خروجی مدلهای هوش مصنوعی همیشه قابل اعتماد نیست. یک پاسخ ممکن است فیلد اجباری نداشته باشد، عدد را به شکل متن برگرداند، مقدار خارج از محدوده تولید کند یا ساختار JSON مورد انتظار را بشکند. اگر این پاسخ مستقیماً وارد API، دیتابیس یا یک workflow اتوماسیون شود، یک خطای کوچک میتواند به اجرای عملیات اشتباه، ثبت دادهٔ ناقص یا زنجیرهای از خطاها منجر شود.

Pydantic یک کتابخانهٔ پایتون برای تعریف مدلهای typed و تبدیل و اعتبارسنجی داده است. در کنار JSON Schema، این ابزار به تیم اجازه میدهد قرارداد خروجی مدل را صریح کند، ورودی نامطمئن را بررسی کند و فقط دادهای را به مرحلهٔ بعد تحویل دهد که با نوعها و محدودیتهای مورد انتظار سازگار است. مزیت Pydantic این است که قرارداد در کد قابل اجرا و قابل تست باقی میماند.
چرا خروجی AI باید قرارداد داشته باشد؟
مدل زبانی متن تولید میکند، نه تضمین یک پاسخ معتبر برای سیستم شما. حتی وقتی prompt دقیق است، ممکن است کلید priority حذف شود، amount بهجای عدد به شکل رشته بیاید، ایمیل قالب نادرست داشته باشد یا مدل در کنار JSON توضیح اضافی بنویسد. این تفاوت میان «پاسخ قابل خواندن برای انسان» و «دادهٔ قابل مصرف برای نرمافزار» است.
قرارداد typed مرز بین مدل AI و سیستم عملیاتی را مشخص میکند. در این مرز، پاسخ خام باید ابتدا parse شود، سپس با مدل بررسی شود و در صورت موفقیت به یک شیء معتبر تبدیل شود. خطا نیز باید بهصورت ساختاریافته ثبت شود تا مشخص باشد کدام فیلد ناقص، کدام نوع اشتباه و کدام مقدار خارج از محدوده بوده است.
ساخت مدل خروجی با Pydantic
در Pydantic، مدل معمولاً از BaseModel ارث میبرد و فیلدها با annotation تعریف میشوند. برای نمونه، یک پاسخ دستهبندی تیکت میتواند شامل شناسهٔ تیکت، اولویت، خلاصه و فهرست اقدامها باشد. فیلدهای اجباری، نوع داده و مقدار پیشفرض در همان مدل ثبت میشوند و این مدل به مستندات JSON Schema نیز تبدیلپذیر است. با Pydantic میتوان این تعریف را کنار تستهای واحد نگه داشت و هر تغییر قرارداد را قابل مشاهده کرد.
برای محدودیتهای دقیقتر از Field استفاده کنید: حداقل و حداکثر عدد، طول متن، الگوی رشته و مقدارهای مجاز. اگر یک فیلد فقط باید یکی از low، normal یا high باشد، Enum یا Literal از یک توضیح متنی در prompt مطمئنتر است. همچنین برای دادهٔ حساس، خروجی خطا را طوری ثبت کنید که متن کامل درخواست یا اطلاعات خصوصی در لاگ باقی نماند.
اعتبارسنجی مستقیم JSON با model_validate_json
وقتی پاسخ مدل یک JSON string است، model_validate_json() مسیر مناسبی برای اعتبارسنجی مستقیم است. این روش JSON را parse میکند و آن را با تعریف مدل تطبیق میدهد؛ در صورت موفقیت، برنامه یک نمونهٔ معتبر از مدل دریافت میکند و در صورت شکست، ValidationError جزئیات خطا را ارائه میدهد. اگر پاسخ شامل markdown fence یا متن اضافی باشد، بهتر است پیش از اعتبارسنجی آن را رد کنید یا یک مرحلهٔ استخراج JSON با قواعد مشخص داشته باشید؛ حذف بیقاعدهٔ متن میتواند دادهٔ جعلی را معتبر جلوه دهد.
در مسیر production، خطاها را به چند گروه جدا کنید: JSON نامعتبر، فیلد ناقص، نوع اشتباه و مقدار نامعتبر. این تفکیک به شما میگوید چه زمانی retry با prompt اصلاحی منطقی است و چه زمانی باید workflow متوقف و برای بررسی انسانی ارسال شود. retry نامحدود هم هزینه را بالا میبرد و هم ممکن است یک پاسخ نادرست را بارها به سیستم نزدیک کند.
JSON Schema برای هماهنگی بین سرویسها
مدل Pydantic میتواند JSON Schema تولید کند. Schema یک قرارداد قابل اشتراک میان سرویس تولیدکننده، validator، مستندات API و تستهاست. از آن میتوان برای بررسی شکل کلی داده، ساخت نمونهٔ ورودی، هماهنگکردن تیمها و حتی کنترل خروجی structured مدل استفاده کرد. Schema جایگزین اعتبارسنجی نهایی در کد نیست، اما زبان مشترکی برای مرز سرویسها میسازد.
اگر قرارداد تغییر کرد، نسخهٔ schema را مدیریت کنید. افزودن فیلد اختیاری معمولاً تغییر کمخطرتری از حذف یا تغییر نوع یک فیلد اجباری است. تستهای regression باید پاسخهای قدیمی، فیلد اضافه، فیلد ناقص و مقدارهای مرزی را پوشش دهند تا تغییر مدل یا prompt باعث شکستن ناگهانی اتوماسیون نشود.
retry، توقف و بررسی انسانی
هر خطای validation قابل retry نیست. اگر JSON ناقص است و مدل میتواند با ذکر فیلدهای missing آن را اصلاح کند، یک retry محدود با prompt اصلاحی انجام دهید. اگر مقدار از محدوده خارج است، اطلاعات مورد نیاز وجود ندارد یا چند retry پشتسرهم شکست خورد، workflow را متوقف کنید. برای تصمیمهای حساس مانند پرداخت، تغییر دسترسی، حذف داده یا ارسال پیام، تأیید انسانی باید بخشی از طراحی باشد.
در لاگ، شناسهٔ اجرای workflow، نسخهٔ مدل، نسخهٔ schema، نوع خطا و تعداد retry را ثبت کنید. متن کامل دادهٔ کاربر یا پاسخ مدل را فقط در صورت نیاز و با حذف اطلاعات حساس نگه دارید. این اطلاعات برای عیبیابی و مقایسهٔ نسخهها ارزشمند است و نشان میدهد کدام مرحله دادهٔ نامعتبر را متوقف کرده است.
یک الگوی عملی برای اتوماسیون امن
مسیر پیشنهادی چنین است: prompt ساختاریافته تولید میشود؛ پاسخ خام دریافت میشود؛ JSON بهصورت مستقیم parse و با Pydantic validate میشود؛ خطا بر اساس نوع طبقهبندی میشود؛ در صورت نیاز فقط یک یا دو retry محدود انجام میشود؛ و بعد از موفقیت، فقط model_dump() یا دادهٔ معادل مدل معتبر به API، دیتابیس یا صف تحویل داده میشود. هیچ مرحلهٔ بعدی نباید به متن خام مدل دسترسی داشته باشد.
این طراحی، مدل AI را به یک تولیدکنندهٔ پیشنهاد تبدیل میکند، نه یک عامل دارای دسترسی مستقیم. در نتیجه میتوان ورودی، خروجی، نسخهٔ قرارداد و تصمیم توقف را مشاهده و آزمون کرد. برای پروژههای واقعی، از یک نمونهٔ کوچک شروع کنید: یک مدل خروجی، چند پاسخ موفق، چند پاسخ ناقص و چند مقدار مرزی بسازید و سپس معیارهای retry و بررسی انسانی را مشخص کنید.
جمعبندی
در عمل، Pydantic باید مرز رسمی میان پاسخ مدل و عملیات بعدی باشد: پاسخ خام را نگه دارید، آن را با Pydantic بررسی کنید و فقط نمونهٔ معتبر Pydantic را به مرحلهٔ اجرا بدهید.
Pydantic و JSON Schema کمک میکنند خروجی مدلهای AI از یک متن غیرقابل پیشبینی به دادهای با قرارداد روشن تبدیل شود. تعریف نوعها و محدودیتها، استفاده از model_validate_json()، طبقهبندی ValidationError، retry محدود و تحویل فقط مدل معتبر، پایهٔ یک workflow قابل اعتماد است. پیش از اتصال خروجی AI به عملیات واقعی، تست regression، ثبت نسخهٔ schema و مسیر بازگشت را آماده کنید.
برای جزئیات مدلها و روشهای اعتبارسنجی، مستندات رسمی Pydantic را ببینید. برای هماهنگی داخلی تیم نیز مجله فناوری تکتاز مطالب آموزشی بیشتری دارد.
مطالب مرتبط
همه مطالب مقالات آموزشیمقالات آموزشیPython ۳.۱۶ آلفا ۲؛ قابلیتهای تازه را چطور امن آزمایش کنیم؟
مقالات آموزشیAndroid Studio Rabbit ۲ و نسل تازهٔ توسعهٔ عاملمحور اندروید
مقالات آموزشیقابلیتهای جدید DevTools در Chrome ۱۵۳ و ۱۵۴؛ راهنمای کاربردی برای توسعهدهندهها
مقالات آموزشیامنیت وبهوک ووکامرس؛ راهنمای اعتبارسنجی و پایش
مقالات آموزشیWindows ۱۱؛ آپدیت اکتبر و تفاوت 26H1 و 26H2 برای مدیران
مقالات آموزشیiframeهای واکنشگرا در Chrome ۱۵۴؛ راهنمای کاربردی برای توسعه وب














