إصلاح استجابات JSON المنظّمة

استخدم هذه الوصفة عندما يحتاج تطبيقك إلى JSON صارم، لكن النماذج تُرجع أحيانًا مخرجات تكاد تكون صالحة، ومع ذلك تتسبب في فشل المحلّل.

​

1. ابدأ بعقد للاستجابة المنظّمة

لا يكون إصلاح الاستجابة مفيدًا إلا إذا كان الطلب يطلب مخرجات منظّمة بالفعل. حالات مناسبة:

• response_format.type = "json_object"
• مخرجات بأسلوب JSON Schema
• بنية كائن ثابتة يستخدمها أكثر من مستدعٍ

لا تفعّل الإصلاح لطلبات النثر المفتوح.

​

2. فعّل الإضافة في المستوى المناسب

يمكنك تفعيل response-healing في ثلاثة مواضع:

1. سياسة الإضافات الافتراضية لمساحة العمل
2. إعداد الإضافات المسبقة في إعداد مُسبق
3. plugins لكل طلب

ترتيب الأولوية:

1. مساحة العمل
2. الإعداد المسبق
3. الطلب

استخدم القيم الافتراضية للإعداد المسبق عندما يتوقع سير العمل JSON منظّمًا باستمرار.

​

3. حدّد شكل مخرجات النموذج

يعمل الإصلاح على نحو أفضل عندما يكون شكل المخرجات المطلوبة محددًا مسبقًا. توصيات:

• كائن واحد بدلًا من كتل متعددة غير مترابطة
• تحديد المفاتيح المطلوبة بوضوح
• استخدام درجة حرارة حتمية متى أمكن
• عدم طلب نص تفسيري إضافي خارج حمولة JSON

​

4. تعرّف على ما يستطيع إصلاح الاستجابة فعله وما لا يستطيع

مسار الإصلاح الحالي حتمي ولا يعمل إلا من دون البث. وتتجاوز طلبات البث الإصلاح بالكامل. يمكنه إصلاح:

• أسوار تعليمات Markdown البرمجية المحيطة بـ JSON
• الفواصل الزائدة في نهاية القوائم
• أقواس الإغلاق الآمنة المفقودة
• مفاتيح الكائنات غير المحاطة بعلامات اقتباس في الكائنات التي يمكن استعادتها بطرق أخرى

إذا كنت تحتاج إلى سياسة أضيق، فاستخدم وضع strict. يستخرج هذا الوضع JSON الصالح مسبقًا فقط من الأسوار أو النص المحيط، ويتجاوز تحويلات الإصلاح النحوي الأوسع. عندما يستخدم الطلب مخرجات بأسلوب JSON Schema، يتحقق الإصلاح أيضًا من الحمولة المستعادة قبل إعادة كتابتها. ويتحقق المدقّق الحالي من القيود الشائعة، مثل:

• المفاتيح المطلوبة
• الأنواع الأساسية للقيم المفردة والحاويات
• التعدادات وقيم const
• حدود المصفوفات وuniqueItems
• أطوال السلاسل والتعابير النمطية والتنسيقات الشائعة مثل email وuri وuuid وdate-time
• حدود الأرقام وmultipleOf
• حدود خصائص الكائن وadditionalProperties: false

ولا يستطيع:

• اختراع حقول دلالية مفقودة
• تخمين قيم الأعمال
• تحويل نثر عشوائي إلى بيانات صالحة

​

5. تحقّق من تشغيل الإضافة فعليًا

عند تشغيل الإصلاح، ينبغي أن تعرض تفاصيل الطلب معلومات عن تنفيذ الإضافة. تحقق من:

• معرّف الإضافة
• ما إذا كانت قد حاولت إجراء تحويل
• ما إذا كانت الحمولة قد تغيّرت
• سبب الفشل عندما تعذرت استعادة الاستجابة
• ما إذا كان الطلب بلا بث عندما توقعت تشغيل الإصلاح

إذا لم تظهر الإضافة، فتحقق من تفعيلها في الطلب أو الإعداد المسبق أو سياسة مساحة العمل.

​

6. ميّز بين مشكلات المحلّل ومشكلات المحتوى

إذا لم يساعد الإصلاح، فحدّد نوع الإخفاق:

1. JSON غير سليم لكنه قريب بنيويًا من الشكل المتوقع
2. JSON صالح وفق المخطط لكن حقوله غير صحيحة
3. نثر بدلًا من JSON
4. مخرجات مبتورة بسبب انخفاض حد الرموز

الحالة الأولى وحدها مناسبة لإصلاح الاستجابة.

​

7. أطلق الميزة تدريجيًا

1. فعّل الإصلاح في إعداد مُسبق واحد ذي مخرجات منظّمة مستقرة
2. راقب بيانات تنفيذ الإضافة الوصفية في السجلات
3. تأكد من مطابقة الحمولات المستعادة للمخطط المتوقع
4. وسّع الإعداد إلى إعدادات مسبقة مشابهة فقط بعد التأكد من سلامة السجلات

​

8. اختر الوضع المناسب

• استخدم safe عندما يستفيد سير العمل من تنظيف نحوي محدود، مثل إزالة الفواصل النهائية أو وضع علامات اقتباس حول المفاتيح غير المحاطة بها.
• استخدم strict عندما ينبغي ألا يقبل سير العمل إلا JSON صالحًا مسبقًا بعد إزالة الأغلفة.
• راجع تفاصيل الطلب لتأكيد الوضع الذي تم تشغيله.

​

أدلة ذات صلة

• استخدام تخزين الاستجابات المؤقت مع الإعدادات المسبقة
• إطلاق الإعدادات المسبقة وتصحيح أخطاء التوجيه
• TypeScript Agent SDK