خروجی ساختاریافته LLM که میشکند: اسکیمای واقعی برای حالت strict چگونه نوشته میشود
جمعبندی: روشن کردن strict روی یک JSON Schema معمولی تقریباً همیشه ۴۰۰ برمیگرداند: همه فیلدها required، additionalProperties:false روی هر آبجکت، و $ref و allOf بلافاصله رد میشوند. این راهنما نشان میدهد چگونه یک اسکیمای آزاد را به نسخه سازگار با strict بازنویسی کنید — با unionهای nullable، سقفهای سخت و چکلیست refusal.

نکته کلیدی: strict: true یک کلید «جدیتر رفتار کن» نیست — یک قرارداد است که فقط زیرمجموعهای از JSON Schema را میپذیرد. همه فیلدها required، روی هر آبجکت additionalProperties: false، و $ref و allOf بلافاصله ممنوع. اگر اسکیما را بدون بازنویسی در حالت strict بفرستید، پاسخ ۴۰۰ است، نه خروجی قابل اعتماد.
در کار روزمره این صحنه تکرار میشود: تیم یک اسکیمای خوشطرح دارد، با فیلدهای اختیاری، $defsهای قابل استفاده مجدد و additionalProperties باز برای سازگاری. بعد کسی "strict": true را به فراخوانی API اضافه میکند و مطمئن است که حالا مدل «به اسکیما احترام میگذارد». نتیجه فوری یک خطای ۴۰۰ با پیام طولانی است، یا بدتر، اسکیمایی پذیرفته میشود که خروجی غیرمنتظره تولید میکند. حالت strict اسکیما را با اغماض تفسیر نمیکند: آن را از نو به گرامری بازنویسی میکند که موتور تولید میتواند حرفبهحرف دنبال کند، و هر چیزی که در آن گرامر جا نشود رد میشود یا نادیده گرفته میشود. شناختن قواعدی که واقعاً برقرارند، قبل از ارسال درخواست، تفاوت بین یک پایپلاین پایدار و یک هفته دیباگ است.
حالت strict = JSON Schema شما به گرامری کامپایل میشود که مدل باید کلمهبهکلمه دنبال کند. هر چیزی که گرامر نمیتواند بیان کند، هنگام ارسال رد میشود یا بیسروصدا نادیده گرفته میشود — و در هر دو حالت مشکل بعد از آن ظاهر میشود که کاربر آن را دیده است.
موتور حالت strict واقعاً چگونه کار میکند
مدلها JSON Schema شما را مثل یک اعتبارسنج سنتی نمیخوانند. وقتی strict: true فعال است، اسکیما به یک گرامر محدودشده تبدیل میشود — یک ماشین حالت متناهی که توکنبهتوکن تصمیم میگیرد کدام ادامهها مجازند. مدل فقط گذارهای مجاز ماشین را تولید میکند؛ هیچ کنترل پس از تولیدی نیست که خروجی را اصلاح کند، درستی ساختاری است.
این معماری همه رفتارهایی را که اسرارآمیز به نظر میرسند توضیح میدهد. اگر فیلدی در required نباشد، ماشین باید تصمیم بگیرد کجا متوقف شود: تنها راهحل امن این است که به مدل اجازه صدور null داده شود، پس اسکیمای مؤثری که به موتور میرسد آن فیلد را همیشه حاضر خواهد داشت. اگر آبجکتی خصوصیات اضافی بپذیرد، ماشین نمیتواند پیشبینی کند چه کلیدهایی ظاهر میشوند، پس هر آبجکت باید سخت بسته شود. هر «ممنوع» در مستندات از یک محدودیت مشخص همین ماشین حالت میآید، نه از یک انتخاب سلیقهای OpenAI.
پیامد دوم مخربتر است: برخی کلیدواژههای JSON Schema (مثل pattern، minLength، maximum) برای اسکیما معتبراند اما توسط گرامر اعمال نمیشوند. اسکیما پذیرفته میشود، پاسخ تمیز میرسد، اما محدودیت هرگز رعایت نشده است. این بیسرصداترین راه خراب کردن پایپلاین است: اعتبارسنجی بعدی در تولید شکست میخورد و هیچ لاگی خطای اسکیما نشان نمیدهد.
سه قاعده غیرقابل مذاکره
اگر فقط وقت درست کردن یک چیز را دارید، همین سه را درست کنید. اکثریت قریب به اتفاق ۴۰۰ها را حل میکنند.
۱. همه فیلدها در required، همیشه. در حالت strict هر کلید اعلامشده در properties باید در required بیاید — حتی اختیاریها. ترفند رسمی برای گفتن «اختیاری» یک union nullable است:
{
"type": "object",
"properties": {
"couponCode": { "type": ["string", "null"] }
},
"required": ["couponCode"],
"additionalProperties": false
}
اینطوری ماشین دقیقاً میداند کِی کلید مجاز است و مدل «کوپنی نیست» را با null بهجای حذف کلید بیان میکند.
۲. additionalProperties: false روی هر آبجکت. نه فقط روی آبجکت ریشه: هر آبجکت تو در تو، بدون استثنا. یک لایه باز کل اسکیمای درخت را نامنطبق میکند.
۳. $ref و allOf ممنوع. نه ارجاع، نه $defs، نه ترکیب. اسکیما باید کامل باز شده باشد، یک درخت یکپارچه و مستقل. if/then/else و oneOf در ریشه هم همان سرنوشت را دارند.
جدول کلیدواژههای ممنوع و بیاثر
| کلیدواژه | نتیجه در حالت strict | جایگزین پیشنهادی |
|---|---|---|
$ref، $defs |
رد با ۴۰۰ | باز شدن کامل اسکیما |
allOf |
رد با ۴۰۰ | ادغام دستی خصوصیات |
if/then/else |
رد با ۴۰۰ | enum + مدیریت سمت کلاینت |
oneOf در ریشه |
مشکل / پاسخ نامنطبق | فقط یک آبجکت ریشه |
فیلد خارج از required |
به همیشهrequired تبدیل میشود | union nullable ["string", "null"] |
pattern، minLength |
اسکیما پذیرفته اما محدودیت نادیده | اعتبارسنجی صریح پس از پاسخ |
maximum، format |
اسکیما پذیرفته اما محدودیت نادیده | بررسی سمت اپلیکیشن |
خطرناکترین سطر، جفت آخر است: اسکیما اعتبارسنجی را رد میکند اما محدودیت وجود ندارد. اگر منطق شما به pattern اعتماد کند، روی شن ساختهاید.
سقفهای سخت که هیچکس نمیخواند
قبل از نوشتن اسکیما، مطمئن شوید داخل این مرزها هستید — عبور از آنها خطاهای عمومی و سختپیگیری تولید میکند:
| محدودیت | سقف |
|---|---|
| مجموع خصوصیات هر اسکیما | ۵۰۰۰ |
| عمق تودرتو | ۱۰ سطح |
| حجم رشته اسکیما | ۱۲۰٬۰۰۰ نویسه |
| مجموع مقادیر enum | ۱۰۰۰ |
اسکیماهایی که خودکار از فریمورکها یا تعریفهای OpenAPI تولید میشوند اغلب بدون آنکه کسی بفهمد از این سقفها عبور میکنند: ۶۰۰۰ خصوصیت مجموع، ۱۲ سطح تودرتو، ۱۵۰۰ مقدار enum پراکنده. پیام خطای API بهندرت میگوید کدام آستانه شکسته شده، پس بهتر است قبل از ارسال خودتان بررسی کنید.
بازنویسی خودکار: اسکریپت make_strict
برای اسکیماهای بزرگ، بازنویسی دستی عملی نیست. این اسکریپت پایتون درخت را پیمایش میکند و سه قاعده را بازگشتی اعمال میکند:
import json
def make_strict(node):
if isinstance(node, dict):
if node.get("type") == "object":
props = node.get("properties", {})
# هر خصوصیت required میشود
node["required"] = list(props.keys())
node["additionalProperties"] = False
# فیلدهای «اختیاری» را باید خودتان از قبل nullable کرده باشید
# حذف چیزهایی که strict نمیپذیرد
for k in ("$ref", "$defs", "allOf", "if", "then", "else"):
node.pop(k, None)
return {k: make_strict(v) for k, v in node.items()}
if isinstance(node, list):
return [make_strict(v) for v in node]
return node
schema = json.load(open("schema.json"))
print(json.dumps(make_strict(schema), indent=2))
دو هشدار. اول: اسکریپت حدس نمیزند کدام فیلدها اختیاری بودند — باید خودتان unionهای nullable را علامت بزنید، ترجیحاً در منبع اسکیما نه در خروجی. دوم: بعد از تبدیل، همیشه یک درخواست آزمایشی اجرا کنید: باز شدن اسکیما میتواند سقف حجم یا خصوصیات را بشکند که قبلاً رعایت میکردید.
مسیر معادل در Anthropic
Anthropic پرچم strict ندارد اما با مکانیزم tool به همان نتیجه میرسد: تعریف ابزار نقش اسکیما را بازی میکند و مدل به شکل آن مقید است. رویکرد عملاً یکسان است:
const tool = {
name: "extract_invoice",
description: "استخراج دادههای فاکتور از متن",
input_schema: {
type: "object",
properties: {
invoiceNumber: { type: "string" },
totalAmount: { type: ["number", "null"] },
lineItems: {
type: "array",
items: {
type: "object",
properties: {
description: { type: "string" },
quantity: { type: "number" }
},
required: ["description", "quantity"],
additionalProperties: false
}
}
},
required: ["invoiceNumber", "totalAmount", "lineItems"],
additionalProperties: false
}
};
// مدل با فراخوانی toolِ منطبق پاسخ میدهد
const response = await anthropic.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 1024,
tools: [tool],
tool_choice: { type: "tool", name: "extract_invoice" },
messages: [{ role: "user", content: invoiceText }]
});
قاعده عملی یکسان است: در Anthropic هم هر آبجکت به required کامل و additionalProperties: false نیاز دارد. تفاوت در کانال پاسخ است — tool_use بهجای محتوای متنی — و اینکه فیلد refusal مختص OpenAI است.
refusal، برش و شکل شکسته: سه خرابی، سه درمان
حتی با اسکیمای بینقص، خروجی میتواند به سه دلیل متمایز شکست بخورد و قاطی کردنشان سریعترین راه از دست دادن یک روز است:
۱. refusal غیر خالی. OpenAI در حالت strict میتواند فیلد refusal را با دلیلی که برای امتناع از درخواست داشته برمیگرداند. این خطای اسکیما نیست — مدل معنایی کار را رد کرده. درمان، بازبینی پرامپت یا سیاست است، نه اسکیما.
۲. برش بهخاطر max_tokens. تولید وسط رشته قطع میشود و JSON بسته نمیشود. در حالت strict اگر پاسخ بیاید منطبق است — اما اگر سقف توکن تمام شود، بریده میرسد. max_tokens را بالا ببرید یا حجم خروجی مورد انتظار را کم کنید. برای سناریوهای تکرارشونده، ترمیم خودکار JSON بریدهشده الگوهای آماده دارد.
۳. شکل شکسته نامنطبق. اسکیما باز بود (خصوصیات اضافی مجاز، فیلدها خارج از required) و strict فعال نبود: مدل JSON معتبر تولید میکند که قرارداد را رعایت نمیکند. درمان، بازنویسی اسکیما مثل همین راهنماست، نه اضافه کردن کنترلهای پس از تولید.
تشخیص درست همیشه از تفکیک این سه حالت شروع میشود: نگاه به فیلد finish_reason، حضور refusal، و مقایسه پاسخ با اسکیمایی که واقعاً ارسال شده.
چکلیست نهایی قبل از انتشار در تولید
| نقطه بررسی | چه چیزی را بررسی کنید |
|---|---|
required کامل |
هر خصوصیت اعلامشده در required هست |
| nullable صریح | فیلدهای اختیاری union ["...", "null"] هستند |
additionalProperties: false |
روی هر آبجکت، نه فقط ریشه |
صفرِ $ref / allOf / if-then-else |
اسکیما کامل باز شده |
| سقفها رعایت شده | ≤ ۵۰۰۰ خصوصیت، ≤ ۱۰ سطح، ≤ ۱۲۰k نویسه |
| محدودیتهای بیاثر منتقل شده | pattern/format سمت اپلیکیشن بررسی میشود |
مدیریت refusal |
کد، امتناع را از خطای اسکیما تفکیک میکند |
| تست با درخواست واقعی | پاسخ آزمایشی قبل از دیپلوی اعتبارسنجی شده |
اگر میخواهید بفهمید چرا additionalProperties: false اینقدر محوری است، تحلیل عمیق کلیدواژه additionalProperties نشان میدهد هر آبجکت باز چگونه فضای تولید را منبسط میکند. برای وارد کردن اسکیما به پایپلاین CI با تستهای خودکار قرارداد، جریان توصیفشده در JSON Schema contract testing رگرسیونهای بیصدا را میبندد. و اگر لازم است از مثالهای JSON موجود اسکیما بسازید، ابزار تبدیل به JSON Schema پلتفرم شما را از داده واقعی شروع میکند — اگرچه برای حالت strict، همچنان باید بازنویسی این راهنما را اعمال کنید.
پرسشهای پرتکرار
چرا مستندات میگوید همه فیلدها باید required باشند، حتی اختیاریها؟
چون ماشین حالت متناهی باید از پیش تصمیم بگیرد کِی هر کلید مجاز است. «اختیاری بودن» با null بیان میشود، نه با غیبت کلید: union nullable راه رسمی گفتن همین است.
اسکیما پذیرفته شده اما pattern کار نمیکند. باگ است؟
نه. در حالت strict، pattern، minLength، maximum و format توسط گرامر تولید اعمال نمیشوند. اسکیما از نظر نحوی معتبر است اما محدودیت وجود ندارد: سمت اپلیکیشن بررسی کنید.
میتوانم $ref استفاده کنم اگر $defs هم اعلام کنم؟
نه، در هر دو حالت ممنوع است. اسکیما باید یک درخت یکپارچه و کامل بازشده باشد. اسکریپتهای بازنویسی خودکار کار باز شدن را انجام میدهند.
تفاوت refusal با خطای اسکیما چیست؟ refusal پاسخی منطبق است که مدل معنایی اعلام میکند نمیخواهد کار را انجام دهد. خطای اسکیما ۴۰۰ هنگام ارسال یا خروجی نامنطبق است. دو مشکل متفاوت با دو درمان متفاوت.
چقدر میتوانم آبجکتها را تودرتو کنم؟ حداکثر ۱۰ سطح تودرتو و ۵۰۰۰ خصوصیت مجموع برای هر اسکیما. اسکیماهای تولیدشده خودکار اغلب از این سقفها عبور میکنند: قبل از ارسال بررسی کنید.
نتیجهگیری
حالت strict گزینهای آرایشی نیست: گذار از «امیدوارم مدل به اسکیما احترام بگذارد» به «گرامر از نظر فیزیکی مانع خروجی نامنطبق میشود» است. بهایش یک زیرمجموعه سختگیرانه از JSON Schema است — required کامل، آبجکتهای بسته، بدون ارجاع — و چند محدودیت که بدون توجه میگذرند اما اعمال نمیشوند. نیمساعت برای بازنویسی با اسکریپت make_strict، علامتگذاری منطقی unionهای nullable، و همیشه تست با یک درخواست واقعی قبل از دیپلوی: پایپلاینی که از این راه میآید، کیفیتی کاملاً متفاوت از پایپلاینهای retry و اصلاح پس از وقوع دارد.