Structured Output: Tables, JSON and Schemas

Get output a program can read: tables and JSON, an output contract with JSON Schema, provider structured-output modes and three-level validation.

بعد از این درس می‌توانی

  • برای یک کار، قالب مناسب خروجی (متن، جدول یا JSON) را با دلیل انتخاب کند.
  • یک JSON Schema ساده با نوع، فیلد الزامی، فهرست مقدار مجاز و null برای مقدار غایب بنویسد.
  • خروجی را در سه سطح نحو، Schema و معنا بررسی کند و برای فقدان داده، رد یا پاسخ ناقص مسیر خطا تعیین کند.
  • میان درخواست متنی JSON، حالت JSON Mode و Structured Outputs تمایز بگذارد و اثر احتمالی قالب بر کار استدلالی را مشروط و آزمون‌پذیر بداند.

چرا این درس مهم است

برگ سبز طبقه‌بندی پیام‌ها را خودکار کرده است: برنامه‌ای خروجی مدل را می‌خواند و پیام را به صف درست می‌فرستد. هفته اول همه‌چیز درست است. هفته دوم برنامه چند بار از کار می‌افتد: یک بار مدل دور JSON سه علامت Markdown گذاشته، یک بار برچسب تازه‌ای ساخته که در فهرست نیست، و یک بار برای پیامی بدون شماره سفارش، شماره سفارش «پیدا کرده» است.

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

مفاهیم کلیدی

یادآوری: قالب خروجی و معیار پذیرش را در درس اول دیدی؛ JSON یعنی قالب متنی داده با جفت‌های «نام: مقدار».

  • `Structured Output` (خروجی ساختاریافته): خروجی با ساختار ماشین‌خوان، مثل JSON یا جدول، که با یک Schema قابل اعتبارسنجی است.
  • `JSON Schema` (شِمای `JSON`): زبان استاندارد برای توصیف شکل مجاز داده JSON: نوع فیلدها، فیلدهای الزامی و مقدارهای مجاز.
  • `Output Contract` (قرارداد خروجی): توافق صریح بین درخواست و برنامه‌ای که خروجی را می‌خواند: چه فیلدهایی، با چه نوع و چه معنایی.
  • `JSON Mode` (حالت `JSON`): تنظیمی که فقط تضمین می‌کند خروجی JSON معتبر باشد، نه اینکه با Schema تو بخواند.
  • `Schema Validation` (اعتبارسنجی با `Schema`): بررسی خودکار اینکه داده با Schema می‌خواند یا نه.
  • `Semantic Validation` (اعتبارسنجی معنایی): بررسی اینکه مقدارها درست و پشتیبانی‌شده‌اند، حتی وقتی شکل درست است.

برچسب دوام: قرارداد خروجی و اعتبارسنجی معنایی [اصل پایدار] هستند؛ JSON Schema [استاندارد] عمومی است، اما زیرمجموعه پشتیبانی‌شده در هر API، JSON Mode و Structured Outputs [ابزار] هستند. قرارداد خروجیِ دستیار ثابت در assistant-io-contract و اجرای عملی در structured-output-n8n آموزش داده می‌شود.

مدل ذهنی

خروجی ساختاریافته را مثل فرم کاغذی با خانه‌های مشخص ببین. Schema همان فرم است: کدام خانه‌ها باید پر شوند، هر خانه چه نوعی دارد، و بعضی خانه‌ها فقط از یک فهرست گزینه پر می‌شوند. فرم خوب یک خانه «نامعلوم» هم دارد تا پرکننده مجبور به حدس نشود.

سه سطح اعتبارسنجی خروجی مدل: خروجی خام مدل اول بررسی می‌شود که `JSON` معتبر است؛ سپس با `Schema` مقایسه می‌شود؛ سپس قاعده‌های معنایی مثل وجود شماره سفارش در پیام بررسی می‌شود؛ شکست هر سطح به تلاش دوباره یا انسان می‌رود و فقط خروجی سالم به برنامه می‌رسد.

سه سطح اعتبارسنجی خروجی مدل

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

گام‌به‌گام

گام ۱: کی متن، کی جدول، کی `JSON`

خواننده خروجیقالب پیشنهادینمونه
انسان، یک بارمتن آزاد با قالب سادهپیش‌نویس ایمیل
انسان که مقایسه می‌کندجدول Markdownمقایسه سه پیشنهاد پخش‌کننده
برنامه یا ورک‌فلوJSON با Schemaبرچسب پیام برای صف پشتیبانی
هر دوJSON برای برنامه، و یک فیلد متنی برای انسانsummary در کنار category

جدول برای انسان خوب است ولی برای برنامه شکننده است: ستون جابه‌جا یا نویسه | در متن کافی است تا خواندنش خراب شود. وقتی برنامه خروجی را می‌خواند، JSON با قرارداد و اعتبارسنجی مناسب اغلب گزینه خوبی است؛ اما سازگاری با محیط مقصد را بررسی کن.

گام ۲: `Schema` بنویس

Schema طبقه‌بندی پیام برگ سبز در assets/ticket-schema.json است. واژه‌های اصلی:

واژهمعنااینجا
typeنوع مقدارcategory رشته است؛ urgent بولی (درست/غلط)
propertiesفیلدهای شیء و Schema هرکدامsrc-jsonschema-objectپنج فیلد
requiredفیلدهایی که باید باشندsrc-jsonschema-objectهر پنج فیلد
additionalProperties: falseفیلد اضافه ممنوعsrc-jsonschema-objectجلوی فیلدهای ساختگی مثل confidence را می‌گیرد
enumفهرست بسته مقدارهای مجازsrc-jsonschema-enumشش برچسب
["string", "null"]مقدار یا «نامعلوم»order_id وقتی در پیام نیست

دو پیش‌فرض JSON Schema را بدان: اگر additionalProperties را نگذاری، فیلد اضافه مجاز است؛ و هر فیلدی که در required نیاید، اختیاری استsrc-jsonschema-object. برای خروجی مدل معمولاً هر دو را صریح می‌بندی.

نکته کلیدی طراحی: order_id الزامی است، ولی می‌تواند null باشد. یعنی مدل باید درباره شماره سفارش تصمیم بگیرد، و راه صادق «نامعلوم» هم دارد. در توضیح (description) همان فیلد هم گفته‌ایم «فقط اگر در پیام آمده باشد».

گام ۳: سه راه گرفتن `JSON`

راهچه تضمینی داردکی
`JSON` در متن درخواست («فقط JSON با این فیلدها برگردان»)هیچ؛ مدل معمولاً رعایت می‌کند، ولی گاهی Markdown، توضیح یا فیلد اضافه می‌گذاردآزمایش سریع، ابزاری که حالت ساختاریافته ندارد
حالت `JSON`فقط JSON معتبر؛ نه مطابقت با Schemasrc-openai-structured-outputsوقتی Schema پشتیبانی نمی‌شود
خروجی ساختاریافته با `Schema`مطابقت با Schema پشتیبانی‌شده در پاسخ عادی و کامل؛ استثناهایی مانند رد یا ناتمام‌بودن را جدا مدیریت کنsrc-openai-structured-outputsهر جا برنامه خروجی را می‌خواند

طبق راهنمای OpenAI، در پاسخ‌های عادی و کامل، Structured Outputs از Schema پشتیبانی‌شده پیروی می‌کند؛ JSON Mode لزوماً قرارداد خاص تو را رعایت نمی‌کند. موارد رد یا خروجی ناتمام باید جدا مدیریت شوند، و همین راهنما Structured Outputs را هر جا ممکن است ترجیح می‌دهد؛ رد درخواست (refusal) هم در این حالت جدا و قابل تشخیص برمی‌گرددsrc-openai-structured-outputs. در نمونه‌های strict همان راهنما همه فیلدها required هستند، additionalProperties برابر false است و مقدار اختیاری با نوع null ساخته می‌شودsrc-openai-structured-outputs؛ همان الگوی Schema این درس.

دو ارائه‌دهنده دیگر:

  • Gemini: زیرمجموعه‌ای از JSON Schema پشتیبانی می‌شود؛ مستندات می‌گوید خروجی از نظر نحوی JSON معتبر است ولی درستی معنایی تضمین نمی‌شود و باید مقدارها را در برنامه‌ات اعتبارسنجی کنی؛ Schemaهای خیلی بزرگ یا تودرتو ممکن است رد شوندsrc-gemini-structured-output.
  • `Ollama`: پارامتر format مقدار "json" یا یک شیء JSON Schema می‌گیرد؛ مستندات پیشنهاد می‌کند Schema را در متن درخواست هم بیاوری، temperature را پایین بگذاری و پاسخ را اعتبارسنجی کنی؛ و طبق همین مستندات در مهر ۱۴۰۵ (اکتبر ۲۰۲۶)، نسخه ابری Ollama خروجی ساختاریافته را پشتیبانی نمی‌کندsrc-ollama-structured-outputs.

گام ۴: اعتبارسنجی سه‌سطحی

حتی با پشتیبانی ساختاری، درستی داده و حالات استثنایی باید بررسی شوند:

  1. `JSON` معتبر؟ اگر از راه «JSON در متن» گرفته‌ای، این اولین شکست رایج است: حصار Markdown، توضیح قبل یا بعد، ویرگول جاافتاده.
  2. مطابق `Schema`؟ فیلد جاافتاده، فیلد اضافه، برچسب خارج از enum، نوع غلط.
  3. درست از نظر معنا؟ Schema نمی‌داند شماره سفارش در پیام بوده یا نه. شکل درست می‌تواند مقدار ساختگی داشته باشد. قاعده‌های معنایی را خودت بنویس: «order_id باید عیناً در پیام باشد»، «اگر category برابر payment است، urgent باید true باشد».

برای هر سطح، تکلیف شکست را تعیین کن (درس سوم): یک بار تلاش دوباره، و بعد صف انسانی. هیچ خروجی شکست‌خورده‌ای نباید بی‌صدا وارد برنامه شود.

گام ۵: وقتی قالب با توان حل مسئله تداخل می‌کند

در مقالهٔ داوری‌شدهٔ Tam و همکاران (۲۰۲۴) بعضی محدودیت‌های قالب در برخی کارهای استدلالی و مدل‌ها به افت عملکرد انجامیده‌اندsrc-tam-format؛ گزارش جدید Nguyen و همکاران (۲۰۲۶) فعلاً preprint است و نقش طراحی آزمایش و نوع محدودیت را بررسی می‌کندsrc-nguyen-constrained. پس نگوییم «JSON همیشه استدلال را خراب می‌کند». برای مسئله پیچیده، دو گزینه را *آزمایش* کن: (الف) نتیجه و شواهد قابل بررسی، سپس تبدیل به قالب، و (ب) خروجی مستقیم ساختاریافته. محاسبهٔ عددی را در صورت نیاز به ابزار قطعی بسپار. الزام ارائهٔ زنجیرهٔ فکر داخلی یا قراردادن reasoning_steps در ابتدای Schema قاعدهٔ عمومی نیست؛ از پاسخ و شاهدِ قابل بررسی استفاده کن.

سه حالت شکست: (۱) متن خام شامل حصار Markdown و مستقیماً قابل JSON.parse نیست؛ (۲) JSON معتبر با مقدار enum نامجاز است؛ (۳) JSON و Schema معتبرند ولی شماره سفارش از متن پشتیبانی نمی‌شود. برای (۱) و (۲) مسیر خطای ساختاری؛ برای (۳) کنترل معنایی مستقل لازم است. پاسخ refusal یا ناتمام را هم از دادهٔ سالم جدا کنsrc-openai-structured-outputs.

مثال‌ها

پیاده‌سازی عملی

ساخت و آزمون قرارداد خروجی. حدود ۲۰ دقیقه.

  1. assets/ticket-schema.json را باز کن و برای هر فیلد یک جمله بنویس که چرا هست و چرا این نوع را دارد.
  2. یک قاعده معنایی دیگر به فهرستت اضافه کن (مثلاً «پیامی که درباره کسر وجه است، urgent درست دارد»).
  3. شش پیام از shared/barg-sabz-tickets.csv انتخاب کن (T01، T04، T06، T10، T11، T12) و برای هرکدام خروجی بگیر یا خروجی‌های آماده را ببین.
  4. هر خروجی را در سه سطح بسنج و نتیجه را در جدول ثبت کن: سطح شکست و علت.
بدون کد

سطح ۱ و ۲ را با یک اعتبارسنج JSON Schema انجام بده (فقط با همین داده ساختگی؛ داده واقعی را در سایت‌های ناشناس نچسبان). سطح ۳ را با چشم: شماره سفارش را در پیام جست‌وجو کن.

با کد

assets/validate_output.py را روی assets/outputs.jsonl اجرا کن (نیاز به pip install jsonschema). سپس قاعده معنایی خودت را به اسکریپت اضافه کن و خروجی‌های خودت را با همان قالب jsonl آزمون کن.

cd assets
python validate_output.py outputs.jsonl
سرویس میزبانی‌شده (در دسترس قانونی)

اگر ابزارت خروجی ساختاریافته با Schema دارد، Schema را آنجا بده؛ اگر فقط حالت JSON دارد، Schema را در متن درخواست بیاور. هر دو را روی همان شش پیام مقایسه کن: کدام سطح‌ها خطا داشتند؟

اجرای محلی

در Ollama، Schema را در format بفرست و در متن درخواست هم بیاورsrc-ollama-structured-outputs:

curl http://localhost:11434/api/chat -d '{
  "model": "<نام-مدل-تو>",
  "messages": [
    {"role": "system", "content": "پیام پشتیبانی را طبق این Schema طبقه‌بندی کن: <متن ticket-schema.json>. order_id فقط اگر در پیام آمده باشد؛ وگرنه null."},
    {"role": "user", "content": "<message>سفارشم رسید ولی یکی از کتاب‌ها اشتباه بود.</message>"}
  ],
  "format": <محتوای ticket-schema.json>,
  "options": {"temperature": 0},
  "stream": false
}'

مدل محلی کوچک ممکن است شکل را رعایت کند ولی در سطح ۳ (معنا) بیشتر خطا کند. این همان دلیلی است که سطح ۳ هیچ‌وقت حذف نمی‌شود.

بدون اجرا / شبیه‌ساز

assets/outputs.jsonl شش خروجی ساختگی با انواع خطا دارد. هر شش را دستی یا با اسکریپت در سه سطح بسنج و با پاسخ‌نامه assets/README.md مقایسه کن.

اشتباه‌های رایج

اشتباهنتیجهکار درست
فقط در متن بنویسی «JSON بده» و مستقیم parse کنیاز کار افتادن برنامه با اولین حصار Markdownخروجی ساختاریافته با Schema یا دست‌کم سطح ۱
فیلد الزامی بدون راه «نامعلوم»مقدار ساختگی برای پرکردن فیلدنوع ["string", "null"] و توضیح فیلد
جاانداختن additionalProperties: falseفیلدهای اضافه ساختگیبستن صریح Schema
برچسب آزاد به‌جای enumبرچسب‌های تازه و ناهمسانفهرست بسته
فکر کنی تضمین Schema یعنی درستیداده خوش‌شکل ولی غلطاعتبارسنجی معنایی
Schema بسیار بزرگ و تودرتورد شدن یا کیفیت کمترSchema کوچک؛ اگر لازم شد، چند گام زنجیره

اشکال‌زدایی

json.loads یا ابزار خواندن JSON خطا می‌دهد.

خروجی حصار Markdown، توضیح اضافه یا JSON ناقص دارد؛ معمولاً در روش «JSON در متن».

خروجی خام را چاپ کن و ببین قبل یا بعد از { چه آمده است.

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

JSON معتبر است ولی اعتبارسنج Schema خطای enum یا required می‌دهد.

ابزار مطابقت با Schema را تضمین نمی‌کند (حالت JSON یا متن)، یا Schema در ابزار پشتیبانی کامل ندارد.

پیام خطای اعتبارسنج نام فیلد را می‌گوید.

برای فیلدهای بسته، enum و مثال؛ در کار خودکار خروجی نامعتبر را رد کن، نه اینکه نزدیک‌ترین برچسب را حدس بزنی.

خروجی از نظر نحو و Schema پذیرفته می‌شود، اما order_id در پیام نیست.

مدل فیلد را با حدس پر کرده است؛ Schema معنا را نمی‌فهمد.

قاعده معنایی «مقدار باید در ورودی باشد».

توضیح فیلد، مثال با null، و قاعده سطح ۳ همیشه فعال.

به‌جای داده، پاسخ رد (refusal) برمی‌گردد.

ارائه‌دهنده درخواست را به دلیل ایمنی رد کرده است.

در ابزارهایی که رد را جدا گزارش می‌کنند، فیلد رد و وضعیت پایان پاسخ را بررسی کنsrc-openai-structured-outputs.

رد ایمنی را بی‌صدا به داده تبدیل نکن؛ علت را ثبت و مورد را برای بررسی انسانی ارجاع بده. تلاش دوبارهٔ خودکار برای دورزدن رد مناسب نیست.

تمرین کوتاه

تمرین · 10 دقیقه

هدف: نوشتن Schema کوچک.

موقعیت (ساختگی): از هر نظر مشتری درباره یک کتاب می‌خواهی این‌ها استخراج شود: امتیاز ۱ تا ۵ اگر مشتری گفته، احساس (مثبت، منفی، خنثی)، اینکه به ارسال اشاره کرده یا نه، و یک خلاصه حداکثر ۸۰ نویسه‌ای.

گام‌ها: Schema را بنویس. برای امتیاز، حالت «گفته نشده» را در نظر بگیر.

معیار پذیرش: همه فیلدها در required؛ additionalProperties: false؛ احساس با enum؛ امتیاز نوع عددی با حد ۱ تا ۵ یا null؛ خلاصه با maxLength.

راه‌حل نمونه
{
  "type": "object",
  "properties": {
    "rating": { "type": ["integer", "null"], "minimum": 1, "maximum": 5 },
    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
    "mentions_shipping": { "type": "boolean" },
    "summary": { "type": "string", "maxLength": 80 }
  },
  "required": ["rating", "sentiment", "mentions_shipping", "summary"],
  "additionalProperties": false
}

قاعده معنایی پیشنهادی: اگر در نظر عددی نیامده، rating باید null باشد.

چالش

تمرین · 30 دقیقه

موقعیت: یک کار از کار خودت انتخاب کن که خروجی‌اش را برنامه، صفحه‌گسترده یا فرد دیگری با قالب ثابت می‌خواند (فرم درخواست، فاکتور، گزارش روزانه، ثبت تماس). نمونه‌ها را ساختگی یا ناشناس‌شده بساز.

  1. قرارداد خروجی را بنویس: فیلدها، نوع، معنا، و رفتار با مقدار نامعلوم.
  2. Schema را بنویس و دست‌کم دو قاعده معنایی که Schema نمی‌تواند بسنجد.
  3. پنج ورودی آزمون بساز، از جمله یکی ناقص و یکی که وسوسه ساختن مقدار دارد.
  4. خروجی‌ها را در سه سطح بسنج (با مدل، یا اگر مدلی نداری، خروجی‌های محتمل را خودت بنویس و بسنج).

خروجی مورد انتظار: فایل Schema، فهرست قاعده‌های معنایی، پنج ورودی آزمون، و جدول نتیجه سه‌سطحی.

معیار پذیرش:

  • Schema بسته است (additionalProperties: false) و فیلدهای بسته enum دارند.
  • هر فیلدی که ممکن است در ورودی نباشد، راه null یا «نامعلوم» دارد.
  • دست‌کم دو قاعده معنایی قابل بررسی نوشته شده است.
  • ورودی ناقص آزموده شده و نتیجه‌اش ثبت شده است.

راهنما: اگر Schema بیش از ده فیلد دارد، فکر کن آیا کار را باید به دو گام زنجیره شکست.

پرسش‌های سنجش

جمع‌بندی

  • وقتی برنامه خروجی را می‌خواند، قرارداد و اعتبارسنجی ساختاری مفید است؛ جدول معمولاً برای انسان و JSON برای برنامه مناسب است، اما صحت معنا جداست.
  • Schema خوب بسته است: required، additionalProperties: false و enum برای فیلدهای بسته.
  • برای مقدار غایب راه null بگذار تا مدل مجبور به حدس نشود.
  • حالت JSON فقط JSON معتبر می‌دهد؛ خروجی ساختاریافته با Schema شکل را تضمین می‌کند، در ابزارهایی که پشتیبانی دارند.
  • شکل درست، درستی معنا را تضمین نمی‌کند؛ قاعده‌های معنایی را خودت بنویس.
  • هر خروجی را در سه سطح بسنج و برای هر شکست، تلاش دوباره یا صف انسانی تعیین کن.

پرسش‌های سنجش

برای هرکدام قالب خروجی را انتخاب کن و یک دلیل بنویس: (الف) مقایسه سه پیشنهاد پخش‌کننده برای جلسه مدیران؛ (ب) برچسب هر پیام برای ارسال خودکار به صف پشتیبانی؛ (ج) پیش‌نویس پاسخ به یک مشتری.

پاسخ نمونه و معیار ارزیابی

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

  • برای صف خودکار JSON همراه Schema را انتخاب می‌کند. (1 امتیاز)
  • برای مقایسه انسانی جدول را با دلیل انتخاب می‌کند. (1 امتیاز)
  • برای متن مشتری قالب انسانی متناسب را انتخاب می‌کند. (1 امتیاز)
  • به تفاوت خوانندهٔ انسانی/ماشینی و لزوم اعتبارسنجی اشاره می‌کند. (1 امتیاز)
  • همه JSON ← JSON برای انسان خوانا نیست؛ وقتی خواننده انسان است، قالب ساده متنی یا جدول بهتر است.

`Schema` یک خروجی را بنویس که از فرم تماس مشتری این‌ها را استخراج کند: موضوع (یکی از سفارش، مرجوعی، سایر)، شماره سفارش اگر هست، و اینکه مشتری خواسته تماس تلفنی گرفته شود یا نه.

پاسخ نمونه و معیار ارزیابی

یک شیء با سه فیلد topic از نوع string و enum سه‌مقداری، order_id از نوع ["string","null"] و wants_call از نوع boolean بساز. هر سه فیلد در required باشند و additionalProperties: false تعیین شود. در description بنویس شماره سفارش تنها اگر در ورودی آمده ثبت شود؛ نبود آن null است. بعد از تولید، مطابقت مقدار شماره سفارش با متن ورودی به‌طور جدا بررسی شود.

  • enum موضوع را با سه مقدار مجاز تعریف می‌کند. (1 امتیاز)
  • order_id را رشته یا null تعریف می‌کند. (1 امتیاز)
  • همه فیلدها را در required و فیلد اضافه را ممنوع می‌کند. (1 امتیاز)
  • قاعدهٔ معنایی تطبیق شماره سفارش با ورودی را مشخص می‌کند. (1 امتیاز)
  • order_id اختیاری بدون null ← فیلد اختیاری ممکن است بی‌صدا جا بیفتد؛ الزامی با null رفتار را صریح و قابل بررسی می‌کند.

سه خروجی مدل برای طبقه‌بندی پیام آمده است. برای هرکدام بگو در کدام سطح (`JSON`، `Schema`، معنا) شکست می‌خورد و چرا.

Schema همان ticket-schema.json درس است. پیام سوم شماره سفارش ندارد.

1) ```json {"category": "payment", "order_id": null, "urgent": true, "summary": "کسر دوباره", "needs_human": true} ```
2) {"category": "refund", "order_id": null, "urgent": false, "summary": "درخواست پس‌گرفتن پول", "needs_human": true}
3) {"category": "order_shipping", "order_id": "51002", "urgent": false, "summary": "لغو سفارش", "needs_human": false}
پاسخ نمونه و معیار ارزیابی

۱) کل متن دارای حصار Markdown را نمی‌توان مستقیماً به‌عنوان یک سند JSON تجزیه کرد؛ اگر محتوای داخل حصار جدا شود، باید دوباره سنجیده شود. ۲) refund خارج از enum تعریف‌شده است و ممکن است فیلد اضافی هم ناقض Schema باشد. ۳) شماره سفارش 51002 در پیام مرجع نیست؛ پس حتی با نحو و ساختار معتبر، اعتبار معنایی رد می‌شود. رد/ناتمام بودن خروجی نیز جدا مدیریت می‌شود.

  • برای مورد ۱ تفاوت متن خام با JSON داخلی را تشخیص می‌دهد. (1 امتیاز)
  • برای مورد ۲ نقض enum یا کلید غیرمجاز را پیدا می‌کند. (1 امتیاز)
  • برای مورد ۳ نبود شاهد شماره سفارش در متن را مشخص می‌کند. (1 امتیاز)
  • برای هر سطح مسیر رد/بازبینی یا کنترل مستقل مناسب می‌گذارد. (1 امتیاز)
  • مورد ۳ درست است ← Schema معنا را نمی‌سنجد؛ مقدار باید با ورودی مقایسه شود.

ابزاری که استفاده می‌کنی فقط «حالت `JSON`» دارد، نه خروجی ساختاریافته با Schema. کدام برنامه درست‌تر است؟

  • حالت JSON کافی است چون شکل خروجی را تضمین می‌کند؛ اعتبارسنجی لازم نیست.
  • حالت JSON را روشن کن، Schema را در متن درخواست بیاور، و هر خروجی را با Schema و قاعده‌های معنایی اعتبارسنجی کن؛ خروجی نامعتبر را رد کن.
  • حالت JSON را خاموش کن و از مدل بخواه جدول Markdown بدهد تا خواناتر باشد.
  • برچسب‌های خارج از فهرست را با نزدیک‌ترین برچسب مجاز عوض کن تا کار متوقف نشود.
پاسخ نمونه و معیار ارزیابی
  • a ← حالت JSON مطابقت با Schema را تضمین نمی‌کند.
  • c ← جدول برای برنامه شکننده‌تر است، نه بهتر.
  • d ← حدس‌زدن برچسب خطا را پنهان می‌کند؛ خروجی نامعتبر را رد کن یا به انسان بسپار.

تیمی می‌گوید: «از وقتی خروجی ساختاریافته با `Schema` را روشن کرده‌ایم، دیگر هیچ اعتبارسنجی لازم نیست.» با یک مثال از کار برگ سبز توضیح بده چرا این درست نیست و حداقل اعتبارسنجی باقی‌مانده چیست.

پاسخ نمونه و معیار ارزیابی

خروجی عادیِ منطبق با Schema ممکن است از نظر معنا غلط باشد: برای پیام بدون شماره سفارش، مقدار ساختگی order_id همچنان می‌تواند رشتهٔ مجاز باشد. باید مقدار استخراج‌شده با متن ورودی تطبیق داده شود، قواعد موضوعی مثل فوریت طبق قرارداد سنجیده شوند و پاسخ رد یا ناتمام پیش از ورود به سیستم شناسایی شود. در وظایف استدلالی پیچیده، روش مستقیم و دو‌مرحله‌ای را بر داده یکسان مقایسه کن؛ افت یا بهبود قطعی فرض نکن.

  • تمایز اعتبار ساختاری و اعتبار معنایی را توضیح می‌دهد. (1 امتیاز)
  • یک نمونه مقدار ساختگی ولی سازگار با Schema می‌آورد. (1 امتیاز)
  • حداقل یک قاعده معنایی مستقل و رفتار با رد/ناتمام را تعیین می‌کند. (1 امتیاز)
  • روش تولید مستقیم و دو‌مرحله‌ای را قابل آزمون و غیرقطعی می‌داند. (1 امتیاز)
  • Schema همه‌چیز را تضمین می‌کند ← حتی مستندات Gemini صریحاً می‌گوید درستی معنایی تضمین نمی‌شود و باید مقدارها را در برنامه بسنجی.

فایل‌های درس

پیام‌های پشتیبانی ساختگی

barg-sabz-tickets.csv

Schema خروجی طبقه‌بندی پیام

ticket-schema.json

شش خروجی ساختگی با انواع خطا

outputs.jsonl

اسکریپت اعتبارسنجی سه‌سطحی

validate_output.py

توضیح دارایی‌ها و پاسخ‌نامه اسکریپت

README.md

ابزارها و جایگزین‌ها

  • ویرایشگر متن — نوشتن Schema و ثبت نتیجه

منابع

JSON Schema: Object JSON Schema استاندارد فنی؛ Draft 2020-12؛ مستند مرجع، نه مقاله پژوهشی

JSON Schema: Enumerated values JSON Schema استاندارد فنی؛ Draft 2020-12؛ مستند مرجع، نه مقاله پژوهشی

Structured model outputs OpenAI مستند رسمی، بدون تاریخ انتشار مشخص؛ بررسی 2026-11-06

Structured output Google مستند رسمی، بدون تاریخ انتشار مشخص؛ بررسی 2026-11-06

Structured outputs Ollama مستند رسمی، بدون تاریخ انتشار مشخص؛ بررسی 2026-11-06

Let Me Speak Freely? A Study On The Impact Of Format Restrictions On Large Language Model Performance Tam et al. / EMNLP Industry Track 2024-11؛ داوری‌شده (EMNLP 2024 Industry Track)

Constrained Decoding: Harmful or Beneficial? Revisiting Its Impact on LLM Performance Nguyen et al. / arXiv 2026-10-26؛ preprint (داوری‌شدن بررسی‌نشده)

Course

From Prompt to Reliable Output