failure modes للـstructured output بحسب الـvendor

كل vendor عنده توقيع تقدر تتعرف عليه لما الـstructured output يبوظ. لو إنت عارف التوقيع، بتـtriage أسرع — بدل ما تسأل "إيه اللي غلط في الـprompt؟"، بتسأل "ده فشل Claude، ولا فشل GPT، ولا فشل Gemini؟"، والسؤال ده بيرد على نفسه أول ما تشوف كل واحد فيهم مرتين.

Claude — JSON ملفوف

أكتر failure shape شائع لـClaude على مهام prompt-only JSON هو إنه يلفّ الـJSON الصالح في ```json ... ``` markdown fence. شفت ده في الدرس الأول في الـmodule ده. الـJSON جوّه صح. الـfence لأ.

إزاي تعرفه: JSON.parse(output) بيرمي "Unexpected token `" والموضع بيشير لأول حرف.

إزاي تصلّحه: يا إما استخدم tool-use mode بتاع Anthropic (اللي بيرجّع typed objects، مش نص) أو اعمل pre-process للمخرج:

function stripJsonFence(s: string): string {
  return s.replace(/^```json\s*/, "").replace(/\s*```$/, "").trim();
}

شغّل ده قبل الـparser. خلاص.

GPT-4o-mini — التطوّع الزيادة

لما تطلب من GPT-4o-mini JSON object نضيف عبر الـprompt بس، غالباً بيرجّعه. لما الـprompt يبقى لمهمة مفتوحة أكتر والنموذج يتطوّع بالـstructure، الـstructure غالباً بيكون محاط بنثر: "Here is the JSON object you requested:" قبل الـobject، "Let me know if you need any other fields!" بعده.

إزاي تعرفه: الـparser بيرمي أصل المخرج بشكل الـprompt هو Here is the JSON object you requested:\n{...} والنثر في الأول بيكسر الـparse.

إزاي تصلّحه: استخدم mode بتاع OpenAI response_format: { type: "json_object" }. مع تفعيل الـflag ده، GPT-4o-mini بيقمع النثر خالص. لو ما تقدرش تستخدم الـmode ده (API client أقدم، structured-output مش مدعوم)، نفس حيلة الـpre-processing بتشتغل — اقطع كل حاجة قبل أول { وكل حاجة بعد آخر }.

Gemini 2.5 Flash — التقطّع

توقيع Flash هو التقطّع في النص، زي مثال "products": ["a house blend", "single في الدرس الأول. المخرج بيبدأ كويس، الـschema بيتحترم لأول كام field، وبعدين الـresponse بيقف فجأة. أحياناً في نص الـstring. أحياناً في نص الـarray.

إزاي تعرفه: الـparse بيفشل مش في الأول بس في مكان جوّه، ورسالة الخطأ بتشير لموضع قريب من آخر الـresponse. طول الـresponse مش طبيعي — قريب من power of two (512، 1024، 2048 token).

إزاي تصلّحه: ارفع max_output_tokens الأول، وحاول تاني. لو ما اتصلّحش، اطلع لـGemini Pro لنفس المهمة. لو ما تقدرش تطلع، استخدم أصغر شكل JSON ممكن — سطّح الـarrays، شيل الـoptional fields، اختصر أسامي الـfields. Flash على مهام بـoutput طويل هو الـdefault الغلط.

triage flow عام

لما يحصل failure في structured-output في الـproduction، اسأل بالترتيب ده:

1. هل الـresponse بيبتدي بـ ```json؟ → فشل Claude، اقطع الـfence.
2. هل الـresponse بيبتدي بنثر ("Here is..."، "Sure, ...")؟ → فشل GPT، حوّل لـJSON mode أو اقطع النثر.
3. هل الـresponse بيوقف في نص الـstring أو الـarray؟ → تقطّع Gemini، ارفع حد الـtokens أو اطلع.
4. هل الـJSON صالح بس أنواع الحقول غلط؟ → فشل في تصميم الـschema، مش فشل vendor. النموذج بيعمل اللي إنت قلتله يعمله.

الحالة الرابعة دي هي اللي أغلب الفرق بتفوتها. لو طلبت founded_year: number والنموذج رجّع "founded_year": "2019" (string)، ده الـschema بتاعك soft زيادة. استخدم strict mode بتاع OpenAI، أو tool-use بتاع Anthropic، أو Zod-style runtime validator في جنبك.

الـmodule الجاي: reasoning modes — إمتى تطلب من النموذج يفكّر، وإمتى التفكير بيكلّفك latency بس. :::