# لماذا تتعطل مخرجات JSON المنظمة بعد ترحيل واجهة LLM API؟ > تتعطل مخرجات JSON المنظمة غالبًا بعد ترحيل واجهة LLM API لأن البنية القديمة والجديدة تفرضان عقودًا مختلفة. قارن مخططات الطلب وأنماط الاستجابة وسلوك البث وأغلفة استدعاءات الأدوات وحالات الرفض وقواعد التحقق قبل إلقاء اللوم على الموجه. لا يغير الترحيل اسم المضيف فقط. فقد يغير النموذج وتسلسل SDK والكلمات المفتاحية المدعومة في المخطط وترتيب أحداث البث وقيم أخذ العينات الافتراضية وسلوك الأمان والموقع الدقيق للحمولة المولدة. لذلك قد يمثل الطلب الذي يبدو مكافئًا في كود التطبيق عقدًا مختلفًا عند إرساله فعليًا. أسرع طريقة للتشخيص هي حفظ طلب واحد فاشل واستجابته غير المعدلة من كلا المزودين. قارن أجسام HTTP الفعلية، لا كائنات التغليف التي يعرضها SDK. تكشف هذه المقارنة عادة ما إذا كان العطل يحدث قبل التوليد أو أثناءه أو حين يستخرج التطبيق النتيجة ويتحقق منها. ## افصل أخطاء البنية عن أخطاء العقد قد تصف عبارة «تعطل JSON» عدة عيوب مختلفة. يؤدي التعامل معها كمشكلة واحدة إلى تعديلات على الموجه تخفي السبب الحقيقي. * ينتج خطأ البنية نصًا لا يستطيع محلل JSON قراءته. * ينتج خطأ المخطط JSON صالحًا بمفاتيح أو أنواع أو تداخلات أو قيم تعداد خاطئة. * يحدث خطأ الاستخراج عندما تكون البيانات المنظمة الصالحة موجودة في حقل آخر من الاستجابة. * يحدث خطأ البث عند تحليل أجزاء غير مكتملة بوصفها مستندات كاملة. * يستبدل الرفض أو الاقتطاع الكائن المتوقع برسالة أمان أو حمولة غير مكتملة. * يعيد خطأ استدعاء الأداة المعاملات داخل غلاف أداة بينما يتوقع التطبيق نص المساعد. سجل هذه الفئات بصورة منفصلة. يجب ألا يشترك استثناء المحلل وغياب حقل مطلوب وخطأ API من نوع `400` في عداد عام واحد لإعادة المحاولة. ## قارن عقدي الطلب ابدأ بمصفوفة ترحيل حقلًا بحقل. الأسماء المتشابهة لا تعني دائمًا الشيء نفسه. | مجال العقد | البنية القديمة | البنية الجديدة | سؤال الاختبار | |---|---|---|---| | وضع الإخراج | كائن JSON | كائن مقيد بمخطط | هل يضمن البنية فقط أم المخطط كاملًا؟ | | موقع المخطط | معاملات الأداة | تنسيق الاستجابة | هل المخطط مرتبط بحقل الطلب الصحيح؟ | | الصرامة | ضمنية | علامة صريحة | هل يجب تفعيل الوضع الصارم؟ | | الكلمات غير المدعومة | تُتجاهل | تُرفض | هل تُقبل الاتحادات والتنسيقات والقيم الافتراضية والمراجع؟ | | المفاتيح الإضافية | مسموحة | محظورة | هل تُعالج `additionalProperties` بصورة متسقة؟ | | البث | أجزاء نصية | أحداث ذات أنواع | أي حدث يحتوي الكائن المكتمل؟ | | الرفض | نص المساعد | حقل مخصص | هل يستطيع المستخرج التمييز بين الرفض والإخراج؟ | التقط الطلب النهائي بعد تسلسله ومعالجته بواسطة SDK. قد تختفي القيم الافتراضية التي كان العميل القديم يضيفها أثناء الترحيل. وقد يحدث العكس أيضًا، إذ يمكن أن يضيف SDK جديد علامة للوضع الصارم أو يعيد تسمية حقل تنسيق الاستجابة من دون إظهار خطأ واضح في التطبيق. ## صغّر المخطط قبل تعديل الموجه اختبر أصغر مخطط ممكن أولًا. ابدأ بسلسلة نصية مطلوبة واحدة ومن دون تفرعات اختيارية. أضف الأعداد الصحيحة والمصفوفات والكائنات المتداخلة والتعدادات والبنى الشرطية واحدًا تلو الآخر. يعزل ذلك الميزات غير المدعومة أسرع بكثير من إعادة كتابة موجه الإنتاج مرارًا. يمكن أن يكون خط الأساس القابل للنقل مثل الآتي: ```json { "type": "object", "properties": { "decision": { "type": "string", "enum": ["approve", "review", "reject"] }, "reason": { "type": "string" } }, "required": ["decision", "reason"], "additionalProperties": false } ``` إذا نجح هذا المثال، يكون النقل ومسار الفرض الأساسي سليمين. وإذا فشل مخطط الإنتاج بعد إضافة ميزة واحدة، فستكون لديك مسألة توافق محددة بدل مشكلة غامضة في جودة النموذج. ## افحص موضع الحمولة المنظمة غالبًا ما تؤدي عمليات ترحيل المزود إلى تعطيل كود الاستخراج. قد تعيد بنية JSON داخل رسالة المساعد، وتعيده أخرى في خاصية محللة جاهزة، وتعيده ثالثة على شكل معاملات أداة محولة إلى سلسلة. وقد يعرض البث سلسلة من الأحداث ذات الأنواع بدل أجزاء النص العادية. أنشئ نتيجة داخلية موحدة قبل أن ترى بقية أجزاء التطبيق الاستجابة: ```ts type StructuredResult = { data: T | null; raw: unknown; refusal: string | null; finishReason: string | null; validationErrors: string[]; }; ``` احتفظ بـ `raw` خلال فترة الترحيل. فهو الدليل اللازم للتمييز بين عيب في مخرجات النموذج وعيب في المحول. احذف المحتوى الحساس قبل تخزين السجلات وحدد مدة احتفاظ مناسبة لتطبيقك. ## لا تحلل تدفقًا غير مكتمل يظل مستند JSON عادة غير صالح حتى يصل آخر بايت. يؤدي تحليل كل جزء نصي إلى أخطاء متوقعة تبدو كأنها أعطال إنتاج. خزّن الإخراج كاملًا مؤقتًا، أو استخدم محلل JSON تزايديًا يدعمه المزود، أو استهلك حدثًا موثقًا يمثل الاستجابة المنظمة النهائية. يجب أن يغطي اختبار البث أكثر من المسار المثالي: * سلاسل نصية مقسمة بين الأجزاء. * علامات اقتباس مهروبة ومحارف Unicode. * مصفوفات تحتوي عناصر كثيرة. * انقطاع قبل القوس الختامي. * حدث رفض. * كائن نهائي صالح تتبعه بيانات وصفية للاستخدام. * معاملات أداة تصل عبر عدة أجزاء. عامل انقطاع الشبكة كتوليد غير مكتمل، لا كمخرج مشوه من النموذج. قد تكون إعادة المحاولة آمنة لطلب تصنيف للقراءة فقط، لكنها قد لا تكون آمنة إذا كانت النتيجة تطلق أثرًا خارجيًا. ## تحقق مرتين وأصلح بحذر حتى إذا فرض المزود مخططًا، يجب أن يتحقق تطبيقك من النتيجة الموحدة عند حدود الثقة. يحمي ذلك من أخطاء المحول وتراجعات الميزات والافتراضات التي لم يضمنها المزود أصلًا. تسلسل عملي للخطوات هو: 1. تأكد من نجاح طلب HTTP. 2. اكتشف الرفض أو الاقتطاع أو اكتمال استدعاء الأداة بصورة صريحة. 3. استخرج الحمولة المنظمة المكتملة. 4. حللها مرة واحدة. 5. تحقق منها باستخدام إصدار مخطط التطبيق. 6. ارفض القيم المجهولة أو غير الآمنة قبل منطق الأعمال. تجنب حلقة غير محدودة من «إصلاح JSON». قد يغير نموذج الإصلاح المعنى بينما يجعل البنية صالحة. إذا كان الإصلاح مقبولًا، فاقصره على محاولة واحدة ومرر أخطاء التحقق واحتفظ بالمخرج الأصلي، ثم تحقق من الكائن المصلح مجددًا. أما الإجراءات ذات الأثر الكبير فيجب إرسالها للمراجعة. ## أنشئ مجموعة إعادة تشغيل للترحيل قبل تحويل حركة الإنتاج، اجمع مجموعة صغيرة من أشكال الطلبات الحقيقية. أزل البيانات الشخصية أو السرية، ثم أضف حالات تختبر حدود العقد. | مجموعة الحالات | ما يجب تضمينه | شرط النجاح | |---|---|---| | عادية | مدخلات قصيرة شائعة | كائن صالح بالقيم المتوقعة | | حقول اختيارية | حالات بوجود الحقول وغيابها | يطابق سلوك الحقول المطلوبة والاختيارية العقد | | ملتبسة | مدخل متضارب أو ناقص | كائن صالح بحالة عدم يقين مسموحة | | سياق طويل | قريب من الحد المعتاد للتطبيق | لا اقتطاع واستخراج صالح | | عدائية | نص يطلب من النموذج تجاهل المخطط | يبقى المخطط سليمًا | | رفض | طلب غير مسموح أو غير آمن | يُكتشف الرفض دون خلطه بخطأ المحلل | | بث | حدود الأجزاء والانقطاعات | تصل الحمولات المكتملة فقط إلى التحقق | شغّل المزودين بمعاملات ثابتة وسجل معدل الصلاحية والتوافق الدلالي ومعدل الرفض ومعدل الاقتطاع وزمن الاستجابة وعدد مرات إعادة المحاولة. لا يُتوقع دائمًا تطابق دلالي كامل، لكن صلاحية المخطط يجب أن تكون شرطًا صارمًا. ## اعزل التوافق خلف محول لا تدع أنواع استجابات المزود تنتشر في قاعدة الكود كلها. يجب أن يتولى محول صغير بناء الطلب وفحص قدرات المخطط واستخراج الاستجابة وأسباب الإنهاء وحقول الاستخدام وتوحيد الأخطاء. أما بقية التطبيق فيجب أن تستهلك واجهة داخلية واحدة. يمكن لبوابة متوافقة مع OpenAI مثل [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=structured-json-output-after-llm-api-migration) تقليل أعمال التكامل المتكررة عندما يستخدم التطبيق نماذج النص والصورة والفيديو. يفيد التوافق على مستوى النقل، لكنه لا يلغي الاختبار على مستوى النموذج. احتفظ بعلامات قدرات للمخرجات المنظمة والأدوات والبث وميزات المخطط، بدل افتراض أن كل نموذج خلف نقطة نهاية متوافقة يتصرف بالطريقة نفسها. استخدم الإصدارات للمحول والمخطط معًا. عند تغير المخطط، خزّن إصداره مع المخرج حتى تعرف الخدمات اللاحقة أي عقد استلمت. ## استخدم إطلاقًا تدريجيًا بشروط توقف واضحة ابدأ بإعادة التشغيل دون اتصال، ثم حركة الظل، ثم نسبة صغيرة من الحركة الحقيقية. لا تعتمد على النجاح الإجمالي وحده. قد يظل معدل صلاحية 99% غير مقبول إذا تركزت نسبة الفشل الباقية في طلبات الدفع أو الإشراف أو التفويض. حدد شروط التوقف قبل الاختبار: * وصول أي قيمة تعداد غير آمنة إلى منطق الأعمال. * انخفاض معدل صلاحية المخطط عن خط الأساس الحالي. * تحول التعامل مع الرفض إلى حالة ملتبسة. * ارتفاع الاقتطاع فوق الحد المتفق عليه. * رفع إعادة المحاولة التكلفة أو زمن الاستجابة فوق ميزانية التطبيق. * تعذر مطابقة الاستجابات الخام مع المخرجات الموحدة. استخدم إعدادات التوجيه للتراجع بدل نشر كود طارئ متى أمكن. أبقِ المحول القديم متاحًا حتى يمر المسار الجديد بحمل الذروة وفئات المدخلات النادرة. ## الخلاصة تنشأ أعطال JSON المنظمة بعد ترحيل واجهة LLM API عادة من عقود غير متطابقة أو أخطاء استخراج أو منطق بث غير مكتمل، ولا تثبت أن النموذج الجديد عاجز عن اتباع التعليمات. قارن الحمولات الفعلية وصغّر المخطط ووحّد الاستجابات وتحقق عند حدود التطبيق وأعد تشغيل مجموعة ممثلة قبل نقل الحركة. تستطيع واجهة متوافقة تبسيط الترحيل، لكن اختبارات القدرات الصريحة تظل الوسيلة الموثوقة لحماية سلوك الإنتاج. ## FAQ ### لماذا يعمل موجه JSON نفسه مع نموذج ويفشل مع نموذج آخر؟ صياغة الموجه مجرد طبقة واحدة. تختلف النماذج والمزودات في أوضاع JSON الأصلية ودعم المخططات والتقسيم إلى رموز وسلوك الرفض ومدى صرامة الالتزام بالقيود. ### هل وضع JSON هو نفسه فرض JSON Schema؟ لا. قد يضمن وضع JSON صحة البنية النحوية فقط، بينما يفرض المخطط أيضًا المفاتيح والأنواع والحقول المطلوبة، وأحيانًا الخصائص الإضافية. ### هل ينبغي تحليل JSON المتدفق رمزًا بعد رمز؟ عادة لا. خزّن الحمولة المنظمة كاملة مؤقتًا أو استخدم أحداث البث المنظم الموثقة لدى المزود، ثم نفذ التحقق بعد الحدث النهائي. ### هل تلغي واجهة API المتوافقة مع OpenAI أعمال الترحيل؟ يمكنها تقليل تغييرات النقل وSDK، لكن يبقى عليك التحقق من ميزات المخطط الخاصة بالنموذج وأسباب الإنهاء وتنسيقات استدعاء الأدوات وسلوك الأخطاء. ### ماذا ينبغي أن يحدث عند فشل التحقق؟ احتفظ بالاستجابة الخام وصنّف الفشل، ولا تعد المحاولة إلا في الحالات المؤقتة الآمنة، واجعل أي إصلاح حتمي ضمن خطوة تحقق محدودة بدل قبول بيانات مشوهة بصمت. ### ما أسرع اختبار قبل الإنتاج؟ أعد تشغيل مجموعة ثابتة من الطلبات العادية والملتبسة والعدائية والمرفوضة وطويلة السياق والمتدفقة على البنيتين، ثم قارن المخرجات المتحقق منها حقلًا بحقل.