مخارجات LLM المنظمة التي تنهار: كيف تكتب Schema فعليًا لوضع strict
الخلاصة: تفعيل strict على JSON Schema عشوائية يعيد 400 في معظم الحالات: كل الحقول required، additionalProperties:false على كل كائن، و$ref وallOf تُرفض فورًا. يوضح هذا الدليل كيفية إعادة كتابة سكيما متساهلة إلى نسخة متوافقة مع strict — مع union nullable وحدود صارمة وقائمة تحقق لـ refusal.

الخلاصة: strict: true ليس مفتاح «كن أكثر جدية» — إنه عقد يقبل فقط مجموعة فرعية من JSON Schema. كل الحقول required، وadditionalProperties: false على كل كائن، و$ref وallOf ممنوعة فورًا. إذا أرسلت السكيما في وضع strict دون إعادة كتابتها، فالرد هو 400، لا مخرجات موثوقة.
في الممارسة اليومية يتكرر المشهد ذاته: لدى الفريق سكيما مصممة جيدًا، بحقول اختيارية و$defs قابلة لإعادة الاستخدام وadditionalProperties مفتوح من أجل التوافق. ثم يضيف أحدهم "strict": true إلى نداء الـ API واثقًا أن النموذج «سيحترم» السكيما الآن. النتيجة الفورية خطأ 400 برسالة طويلة، أو الأسوأ: سكيما تُقبل لكنها تنتج مخارجات غير متوقعة. وضع strict لا يفسر السكيما بتساهل: إنه يعيد كتابتها من الصفر إلى قواعد نحوية يستطيع محرك التوليد اتباعها حرفًا بحرف، وكل ما لا يتسع في تلك القواعد يُرفض أو يُتجاهل بصمت. فهم القواعد التي تسري فعلًا، قبل إرسال الطلب، هو الفارق بين خط أنابيب مستقيم وأسبوع كامل من التنقيح.
وضع strict = تُجمَّع JSON Schema الخاصة بك إلى قواعد نحوية يجب أن يتبعها النموذج كلمة بكلمة. كل ما لا تستطيع القواعد التعبير عنه يُرفض عند الإرسال أو يُتجاهل بصمت — وفي الحالتين تظهر المشكلة بعد أن يكون المستخدم قد رآها.
كيف يعمل محرك وضع strict فعليًا
النماذج لا تقرأ JSON Schema الخاصة بك كمدقق تقليدي. عند تفعيل strict: true، تتحول السكيما إلى قواعد نحوية مقيدة — آلة حالات منتهية تحكم، رمزًا برمز، على أي استكمالات مسموحة. ينتج النموذج الانتقالات المسموح بها من الآلة فقط؛ لا يوجد تحقق لاحق للإنتاج يصحح المخرجات — الصحة بنيوية.
هذه المعمارية تفسر كل سلوك يبدو غامضًا. إذا لم يكن الحقل ضمن required، على الآلة أن تقرر متى تتوقف: الحل الآمن الوحيد هو منح النموذج حرية إصدار null، وبالتالي فالسكيما الفعلية التي يتلقاها المحرك ستتضمن ذلك الحقل دائمًا. إذا سمح كائنٌ بخصائص إضافية، فالآلة لا تستطيع التنبؤ بالمفاتيح التي ستظهر، لذا يجب أن يُغلق كل كائن بإحكام. كل «ممنوع» في التوثيق ينشأ من قيد ملموس في هذه الآلة، لا من خيار أسلوبي لدى OpenAI.
النتيجة الثانية أخطر: بعض الكلمات المفتاحية في JSON Schema (مثل pattern وminLength وmaximum) صالحة للسكيما لكنها غير مفروضة من القواعد النحوية. تُقبل السكيما، ويرد الرد نظيفًا، لكن القيد لم يُراعَ أبدًا. إنه الطريق الأكثر صمتًا لإفساد خط الأنابيب: يفشل التحقق اللاحق في الإنتاج ولا يُظهر أي سجل خطأ سكيما.
ثلاث قواعد لا يجوز المساومة عليها
إن لم يكن لديك سوى وقت لإصلاح شيء واحد، فأصلح هذه الثلاثة. فهي تحل الغالبية العظمى من أخطاء 400.
1. كل الحقول في required، دائمًا. في وضع strict، يجب أن يظهر كل مفتاح معلن في properties في required — حتى الاختيارية. الحيلة الرسمية للقول «اختياري» هي union nullable:
{
"type": "object",
"properties": {
"couponCode": { "type": ["string", "null"] }
},
"required": ["couponCode"],
"additionalProperties": false
}
بهذا تعرف الآلة بدقة متى يكون المفتاح سليمًا، ويعبر النموذج عن «لا يوجد قسيمة» بقيمة null بدل إسقاط المفتاح.
2. additionalProperties: false على كل كائن. ليس على الكائن الجذر فقط: كل كائن متداخل، دون استثناء. طبقة واحدة مفتوحة تجعل السكيما كلها غير مطابقة.
3. $ref وallOf ممنوعتان. لا مراجع، ولا $defs، ولا تركيب. يجب أن تكون السكيما موسعة بالكامل، شجرة واحدة مستقلة بذاتها. وif/then/else وoneOf في الجذر لهما المصير ذاته.
جدول المصطلحات الممنوعة والعديمة الأثر
| الكلمة المفتاحية | النتيجة في وضع strict | البديل الموصى به |
|---|---|---|
$ref، $defs |
رفض مع 400 | توسيع السكيما بالكامل |
allOf |
رفض مع 400 | دمج الخصائص يدويًا |
if/then/else |
رفض مع 400 | enum + معالجة لدى العميل |
oneOf في الجذر |
مشاكل / رد غير مطابق | كائن جذر واحد فقط |
حقل خارج required |
يتحول إلى إلزامي دائمًا | union nullable ["string", "null"] |
pattern، minLength |
تُقبل السكيما لكن القيد يُتجاهل | تحقق صريح بعد الرد |
maximum، format |
تُقبل السكيما لكن القيد يُتجاهل | فحص لدى التطبيق |
أخطر سطر هو الزوج الأخير: السكيما تجتاز التحقق لكن القيد غير موجود. إذا اعتمد منطقك على pattern، فأنت تبني على الرمل.
الحدود الصارمة التي لا يقرأها أحد
قبل كتابة السكيما، تأكد أنك ضمن هذه الحدود — تجاوزها ينتج أخطاء عامة يصعب تشخيصها:
| القيد | الحد الأقصى |
|---|---|
| مجموع الخصائص لكل سكيما | 5000 |
| عمق التداخل | 10 مستويات |
| حجم نص السكيما | 120,000 حرف |
| مجموع قيم enum | 1000 |
السكيما المولدة آليًا من أطر العمل أو تعريفات OpenAPI كثيرًا ما تتجاوز هذه الحدود دون أن يلاحظها أحد: 6000 خاصية إجمالًا، 12 مستوى تداخل، 1500 قيمة 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 والقطع والشكل المكسور: ثلاثة أعطال، ثلاثة علاجات
حتى مع سكيما مثالية، قد تفشل المخرجات لثلاثة أسباب مختلفة، والخلط بينها أسرع طريق لخسارة يوم:
1. refusal غير فارغ. قد تعيد OpenAI في وضع strict حقل refusal مع سبب رفضها الطلب. هذا ليس خطأ سكيما — النموذج امتنع عن المهمة دلاليًا. العلاج مراجعة البرومبت أو السياسة، لا السكيما.
2. القطع بسبب max_tokens. يتوقف التوليد في منتصف النص ولا يُغلق JSON. في وضع strict، الرد إن وصل فهو مطابق — لكن إن نُفدت ميزانية الرموز وصل مقطوعًا. ارفع max_tokens أو قلص حجم المخرجات المتوقع. وللسيناريوهات المتكررة، الإصلاح الآلي لـ JSON المقطوع يوفر أنماطًا جاهزة.
3. شكل مكسور غير مطابق. كانت السكيما مفتوحة (خصائص إضافية مسموحة، حقول خارج required) ولم يُفعّل strict: ينتج النموذج JSON سليمًا لا يلتزم بالعقد. العلاج إعادة كتابة السكيما كما في هذا الدليل، لا إضافة تحققات لاحقة للإنتاج.
التشخيص الصحيح يبدأ دائمًا بالتفريق بين هذه الحالات الثلاث: النظر إلى حقل finish_reason، ووجود refusal، ومقارنة الرد بالسكيما التي أُرسلت فعلًا.
قائمة التحقق النهائية قبل الإنتاج
| نقطة الفحص | ماذا تفحص |
|---|---|
required كامل |
كل خاصية معلنة موجودة في required |
| nullable صريح | الحقول الاختيارية هي union ["...", "null"] |
additionalProperties: false |
على كل كائن، لا الجذر فقط |
صفر $ref / allOf / if-then-else |
السكيما موسعة بالكامل |
| الحدود محترمة | ≤ 5000 خاصية، ≤ 10 مستويات، ≤ 120k حرف |
| القيود العديمة الأثر منقولة | 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 ردٌ مطابق يعلن فيه النموذج دلاليًا أنه لا يريد تنفيذ المهمة. خطأ السكيما هو 400 عند الإرسال أو مخرجات غير مطابقة. مشكلتان مختلفتان بعلاجين مختلفين.
إلى أي عمق يمكنني تداخل الكائنات؟ 10 مستويات تداخل كحد أقصى و5000 خاصية إجمالًا لكل سكيما. السكيما المولدة آليًا كثيرًا ما تتجاوز هذه الحدود: افحص قبل الإرسال.
الخلاصة
وضع strict ليس خيارًا تجميليًا: إنه الانتقال من «أرجو أن يحترم النموذج السكيما» إلى «القواعد النحوية تمنع فيزيائيًا المخرجات غير المطابقة». ثمنه مجموعة فرعية صارمة من JSON Schema — required كامل، كائنات مغلقة، بلا مراجع — وبعض القيود التي تعبر بلا انتباه لكنها لا تفرض. استثمر نصف ساعة في إعادة الكتابة بسكربت make_strict، وميّز union nullable بعناية، واختبر دائمًا بطلب حقيقي قبل النشر: خط الأنابيب الناتج مختلف جودةً عن الذي يُبنى على إعادة المحاولة والإصلاح بعد وقوع الأعطال.