تتيح لك المخرجات المنظّمة فرض تنسيق قابل للقراءة آليًا بدلًا من النص الحر.
دعم نقاط النهاية
استخدم المخرجات المنظّمة مع:
/v1/chat/completions باستخدام response_format
/v1/responses باستخدام text.format
- لا يزال بإمكان
/v1/messages إرجاع نص JSON، لكنه لا يستخدم عقد response_format نفسه.
الطلب
الرد
ملاحظات حول العقد
- يجب أن تكون قيمة
response_format.type هي text أو json_object أو json_schema.
- مع
json_schema، أدرج كائن مخطط (response_format.json_schema.schema في حمولة على نمط chat أو text.format.schema في حمولة على نمط Responses).
- تحقّق من JSON على خادمك قبل استخدامه في الأنظمة اللاحقة.
تصميم المخطط
ابدأ بكائن صغير وحدد الحقول المطلوبة صراحةً واستخدم التعدادات للفئات المعروفة. عيّن additionalProperties: false لرفض المفاتيح الإضافية. حافظ على تزامن المخطط المطلوب ومتحقق الخادم وأدِر إصداراتهما معًا.
التحقق من النتيجة
حلّل النتيجة الكاملة وتحقق منها قبل استخدامها لاحقًا. يستخدم مثال TypeScript هذا Zod ويطابق مخطط الطقس أعلاه:
عالج الرفض والمحتوى المفقود والاستجابات المبتورة قبل التحليل. إذا فشل التحقق، اسمح بعدد محدود فقط من المحاولات التصحيحية ثم أعد فشلًا آمنًا. قد تترتب رسوم إضافية على إعادة التوليد. لا يثبت JSON صالح صحة القيم واقعيًا ولا يمنح إذنًا لتنفيذ إجراء.
تتبّع إخفاقات التحقق بحسب النموذج وإصدار المخطط. أعد فحص حالات التقييم عند تغير أي منهما. لاستعادة JSON غير سليم، راجع إصلاح الاستجابة. آخر تعديل في ٢ أكتوبر ٢٠٢٦