احصل على مخرجات منظّمة
أرسل JSON Schema كي يعيد النموذج JSON بالشكل الذي تريده، ثم تحقّق منه قبل استخدامه.
أرسل JSON Schema مع الطلب وسيعيد النموذج JSON بهذا الشكل بدلًا من نص حر. استخدمه عندما تريد بيانات، مثل حقول مستخرجة من بريد إلكتروني. واستخدم استدعاء الأدوات عندما تريد أن يطلب النموذج من تطبيقك فعل شيء.
type | ما تحصل عليه |
|---|---|
json_schema | JSON يتبع مخططك. استخدمه افتراضيًا. |
json_object | كائن JSON صالح ما، دون فرض شكل. |
text | نص عادي (الافتراضي). |
يوضع التنسيق في response_format على /v1/chat/completions، وtext.format على /v1/responses، وoutput_config.format على /v1/messages (json_schema فقط).
{
"model": "openai/gpt-6-astra",
"messages": [
{ "role": "user", "content": "Return the city and weather for London." }
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "weather",
"strict": true,
"schema": {
"type": "object",
"properties": {
"city": { "type": "string" },
"weather": { "type": "string" }
},
"required": ["city", "weather"],
"additionalProperties": false
}
}
}
}
يعود JSON كسلسلة نصية في محتوى الرسالة. قبل تحليله، تحقّق من وجود رفض أو محتوى مفقود أو finish_reason غير stop. ثم تحقّق من الكائن بعد تحليله، مثلًا باستخدام Zod. إذا فشل التحقق، أعد المحاولة مرة واحدة مع الخطأ في الموجّه، ثم أعد فشلًا آمنًا. كل إعادة محاولة تُحتسب، وJSON الصالح لا يثبت أن القيم صحيحة.
لا تُسقط Phaseo الحقل response_format أبدًا. فهي توجّه طلب json_schema فقط إلى المزوّدين الذين يدعمون المخرجات المنظّمة، وإذا لم يدعمها أي من مزوّدي النموذج، يفشل الطلب مع 400 validation_error. تشير صفحات النماذج إلى الدعم بـ structured_outputs، وهي علامة قدرة، لا حقل في الطلب.
تحقّق من فهمك
ترسل response_format مع json_schema إلى نموذج لا يدعم مزوّدوه المخرجات المنظّمة. ماذا يحدث؟
طبّق ما تعلّمته
يستخدم محلّل الفواتير لديك json_schema، ومن حين لآخر يفشل الرد في فحص Zod لأن total مفقود. ماذا يجب أن يفعل الكود؟
اعرض الإجابةأخفِ الإجابة
تحقّق أولًا من أن finish_reason هو stop، لأن الإجابة المقطوعة لا يمكن أن تكون صالحة. ثم أعد المحاولة مرة واحدة مع خطأ التحقق في الموجّه، وإذا فشلت مجددًا، فأعد فشلًا آمنًا بدلًا من التخمين. تتبّع حالات الفشل لكل نموذج وإصدار مخطط كي تلاحظ متى يزيد أيّ تغيير منهما الأمر سوءًا.
الخلاصة
json_schema للبيانات التي تحتاجها بشكل ثابت، وتحقّق دائمًا من النتيجة في كودك قبل أن تثق بها.روابط ذات صلة
آخر مراجعة: ١٧ نوفمبر ٢٠٢٦