اعتبارسنجی خروجی هوش مصنوعی با Pydantic؛ JSON کافی نیست

چرا JSON معتبر هنوز می‌تواند غلط باشد؟

دستیار هوشمند ممکن است پاسخ را به شکل JSON تحویل بدهد، اما وجود آکولاد و کلید درست تضمین نمی‌کند شماره سفارش معتبر است یا مبلغ منفی نیست. برای اتصال خروجی مدل به نرم‌افزار، قرارداد داده لازم است: چه فیلدهایی مجازند، هر فیلد چه نوعی دارد و چه محدودیت‌هایی باید رعایت شوند. Pydantic در Python ابزاری برای تعریف و بررسی این قرارداد است. این راهنما درباره دروازه ورود داده به برنامه است؛ از یک پاسخ ظاهراً منظم نباید مستقیماً به ثبت عملیات تجاری برسیم.

دو سطح را جدا کنید. اعتبار ساختاری یعنی فیلد و نوع داده با قرارداد سازگارند. اعتبار معنایی یعنی سفارش وجود دارد، وضعیتش اجازه عملیات می‌دهد و کاربر حق انجام آن را دارد. کتابخانه اعتبارسنجی لایه اول را پوشش می‌دهد؛ لایه دوم به داده معتبر و قواعد کسب‌وکار نیاز دارد. در نمونه، مدل درخواست جمع‌بندی تیکت تعریف می‌کنیم. به‌جای آنکه متن هوش مصنوعی را آزادانه ذخیره کنیم، شناسه مثبت، سطح اولویت محدود و طول عنوان را کنترل می‌کنیم.

قرارداد خروجی را روشن کنید

قرارداد را کوچک نگه دارید و نام فیلدها را مبهم انتخاب نکنید. اگر priority فقط سه مقدار مشخص دارد، همان سه مقدار را در نوع داده نشان دهید. فیلدهای اضافه را رد کنید تا اشتباه تایپی یا خروجی پیش‌بینی‌نشده مخفی نماند. حالت strict در ورودی Python جلوی برخی تبدیل‌های ضمنی را می‌گیرد؛ با این حال، رفتار ورودی JSON برای بعضی نوع‌ها تفاوت دارد و باید مسیر واقعی دریافت داده را تست کنید. هدف پذیرش سخت‌گیرانه بدون فهم قرارداد نیست، بلکه قابل پیش‌بینی کردن مرز برنامه است.

وقتی اعتبارسنجی شکست می‌خورد، خطا را به پیام کوتاه قابل استفاده تبدیل کنید. تمام داده ورودی یا متن مشتری را داخل لاگ خطا نریزید. اگر تصمیم دارید یک بار از مدل اصلاح بخواهید، فقط اشکال قرارداد را بازگردانید و تعداد تلاش را محدود کنید. پس از شکست تکراری، مسیر دستی داشته باشید. اصلاح خودکار بی‌انتها هم هزینه ایجاد می‌کند و هم ممکن است خروجی نادرست را به شکل ظاهراً معتبر درآورد. نتیجه اعتبارسنجی، نسخه قرارداد و شناسه درخواست باید قابل ردیابی باشند.

پیشنهاد تحریریه این است که مجموعه آزمون شامل خروجی درست، فیلد جاافتاده، نوع اشتباه، مقدار مرزی، عنوان بلند و فیلد ناشناخته باشد. علاوه بر این، یک خروجی کاملاً مطابق قرارداد اما با شناسه تیکت ناموجود بسازید؛ این آزمون نشان می‌دهد صحت ساختاری کافی نیست. خروجی مدل را در حالت سایه روی درخواست‌های نمونه ارزیابی کنید و نرخ پذیرش، خطاهای هر فیلد و میزان ارجاع دستی را بسنجید. تغییر قرارداد باید مثل تغییر API نسخه‌بندی شود تا مصرف‌کننده‌ها غافلگیر نشوند.

# python -m pip install "pydantic>=2,<3"
from typing import Literal
from pydantic import BaseModel, ConfigDict, Field, ValidationError

class TicketSummary(BaseModel):
    model_config = ConfigDict(strict=True, extra="forbid")
    ticket_id: int = Field(gt=0)
    priority: Literal["low", "normal", "high"]
    title: str = Field(min_length=5, max_length=120)

valid = '{"ticket_id":42,"priority":"normal","title":"Delivery follow-up"}'
print(TicketSummary.model_validate_json(valid).model_dump())

invalid = '{"ticket_id":-1,"priority":"urgent","title":"x"}'
try:
    TicketSummary.model_validate_json(invalid)
except ValidationError as exc:
    # Do not log the original customer payload.
    print([(e["loc"], e["type"]) for e in exc.errors()])

خروجی سالم باید قابل پیگیری باشد

پس از عبور از قرارداد، مجوز، موجود بودن رکورد و قواعد تغییر وضعیت را در سرویس اصلی بررسی کنید. هر عملیات نوشتنی باید از همان مسیر کنترل‌شده برنامه عبور کند، نه اینکه مدل مستقیم به دیتابیس دسترسی بگیرد. JSON Schema تولیدشده می‌تواند برای مستندسازی و تنظیم بعضی ارائه‌دهندگان مدل مفید باشد، اما پشتیبانی از همه ویژگی‌های آن یکسان نیست. موفقیت این پیاده‌سازی کاهش داده نامعتبر در مرز سیستم و آشکار شدن خطاهاست؛ واقعی بودن پاسخ همچنان نیاز به بررسی جدا دارد.

توضیح‌ها و پیشنهادهای اجرایی این مطلب، تحلیل تحریریه دانشنامه لیان هستند.منابع: Pydantic — Models · Pydantic — Strict mode · Pydantic — JSON Schema

این مطلب بازنویسی تحلیلی دانشنامه لیان بر پایه منبع اصلی است.مشاهده منبع اصلی