ما هي واجهة برمجة تطبيقات قرارات OpenAI؟

واجهة برمجة تطبيقات قرارات OpenAI هي نقطة نهاية POST /v1/decisions، تعمل على GPT-6 Luna، والتي تأخذ نصوصًا أو صورًا بالإضافة إلى قائمة من الأسئلة وتُرجع إجابات مُحددة النوع بدلاً من النثر: وهي احتمالية محددة، أو اختيار مع احتمالات لكل خيار، أو درجة عبر مستويات مرتبة. تكلف المدخلات 0.10 دولار لكل مليون رمز بدون رسوم على المخرجات أو قراءة أو كتابة ذاكرة التخزين المؤقت، وقد كانت نقطة النهاية في المرحلة التجريبية العامة منذ 2026-10-06، مع تصريح OpenAI بأن التوفر العام (GA) متوقع "في الأسابيع القادمة".

تغطي هذه المقالة ما تُرجعه نقطة النهاية، وتكاليفها، وموقعها مقارنة بالمخرجات المنظمة (Structured Outputs) واستدعاء الدوال (function calling)، وكيفية اختبارها. للحصول على شرح مفصل باستخدام curl و Python و JavaScript، اقرأ مقال كيفية استخدام واجهة برمجة تطبيقات قرارات OpenAI تاليًا؛ وإذا كنت تستخدم بالفعل واجهة برمجة تطبيقات الاستجابات (Responses API)، فإن مقارنة القرارات مقابل الاستجابات توضح نفس المهمة بالطريقتين. سنستخدم خلال هذا المقال Apidog لتخزين المفتاح، وحفظ الطلبات، والتأكد من مصفوفة answers بحيث يؤدي أي تغيير في سلوك النموذج إلى فشل الاختبار بدلاً من توجيه تذكرة بشكل خاطئ.

بنية طلب واستجابة القرارات

ثلاثة حقول للطلب، وثلاثة حقول للاستجابة. لا يوجد id، ولا نص مُولد، ولا شيء للتحليل.

لاحظ ما هو مفقود: لا يوجد temperature، reasoning، stream، store، tools أو text.format. لتلك الأشياء، تحتاج إلى واجهة برمجة تطبيقات الاستجابات. و output_tokens هو 0 في المثال المرجعي الخاص بـ OpenAI، ولهذا السبب لا يحتوي التسعير أدناه على سطر خاص بالمخرجات.

أنواع الأسئلة الثلاثة

يحمل كل سؤال type خاصًا به، ويمكنك مزج الأنواع في إدخال واحد. ضع الأسئلة المستقلة في نفس الطلب؛ أما بالنسبة للقرارات التي تعتمد على إجابة سابقة، فإن دليل OpenAI يوصي بإرسال طلبات منفصلة.

مؤشر: احتمالية نعم/لا

يسأل predicate عما إذا كان شرط ما صحيحًا ويُرجع احتمالية تتراوح من 0 إلى 1 لكونه صحيحًا.

curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "The box arrived crushed and the screen is cracked.",
    "questions": [
      {"type": "predicate", "name": "damaged",
       "instructions": "Is the product described as damaged?"}
    ]
  }'

يُرجع المثال المرجعي لـ OpenAI لهذا الشكل:

{
  "model": "gpt-6-luna",
  "answers": [
    {"type": "predicate", "name": "damaged", "probability": 0.95}
  ],
  "usage": {
    "input_tokens": 42,
    "input_tokens_details": {"cached_tokens":0,"cache_write_tokens":0},
    "output_tokens": 0,
    "output_tokens_details": {"reasoning_tokens":0},
    "total_tokens": 42
  }
}

اختيار: تسمية واحدة من مجموعة غير مرتبة

يضيف choice مصفوفة choices من كائنات {value, description}: من 2 إلى 255 خيارًا فريدًا، حيث value هو سلسلة نصية أو قيمة منطقية (true و "true" متميزان). توصي OpenAI باستخدام خيار احتياطي مثل other عندما لا تغطي الفئات الخاصة بك كل المدخلات.

{
  "model": "gpt-6-luna",
  "input": "I was charged twice for my order.",
  "questions": [
    {"type": "choice", "name": "department",
     "instructions": "Which team should handle this ticket?",
     "choices": [
       {"value":"billing"}, {"value":"technical"},
       {"value":"shipping"}, {"value":"other"}
     ]}
  ]
}

الإجابة التوضيحية للدليل لهذا الإدخال:

{"type": "choice", "name": "department", "choice": "billing",
 "probabilities": [
   {"value":"billing","probability":0.95},
   {"value":"technical","probability":0.02},
   {"value":"shipping","probability":0.01},
   {"value":"other","probability":0.02}
 ],
 "confidence": 0.93}

درجة: موضع على مقياس مرتب

يضيف score مستويات levels، وهي مصفوفة من كائنات {label, description} مرتبة من الأدنى إلى الأعلى. تبدأ الفهارس من 0، وتكون score المرتجعة هي المتوسط المرجح بالاحتمالية لتلك الفهارس، لذا يمكن أن تقع بين المستويات.

{
  "model": "gpt-6-luna",
  "input": "Export fails in Safari but works in Chrome.",
  "questions": [
    {"type": "score", "name": "severity",
     "instructions": "How badly does this bug block the user?",
     "levels": [
       {"label":"Cosmetic"},
       {"label":"Workaround available"},
       {"label":"Fully blocked"}
     ]}
  ]
}

في مثال الدليل، الاحتمالات هي 0.1 و 0.7 و 0.2 عبر المستويات الثلاثة، مما يعطي score بقيمة 1.1 و confidence بقيمة 0.55. تُقرأ 1.1 على أنها "بين المستوى 1 والمستوى 2، قريبة من 1". قاعدة الدليل: choice للفئات غير المرتبة مثل الأقسام؛ score للمستويات المرتبة مثل الشدة.

يمكن أن يظهر نوع إجابة رابع، وهو refusal، لأي سؤال فردي على شكل {"type":"refusal","name":...}. لا يزال بإمكان الأسئلة الأخرى في نفس الطلب الحصول على إجابات، لذا يجب التفريع بناءً على type قبل قراءة أي حقل.

السرعة، كما تصفها OpenAI

تقول OpenAI إن واجهة برمجة تطبيقات القرارات أسرع بحوالي 10 أضعاف من واجهة برمجة تطبيقات الاستجابات؛ وقد صيغت الإعلان على أنها أسرع بما يصل إلى 10 أضعاف من GPT-6 Luna عبر الاستجابات. لا تنشر OpenAI أي رقم مطلق للكمون. أبلغ أحد المطورين في منتدى OpenAI عن استعادة قرارات إدخال الصور في حوالي 0.8 ثانية على اتصال بطيء: وهي حكاية وليست معيارًا. قم بقياس p95 الخاص بك قبل الوعد بأي شيء.

التسعير: 0.10 دولار لكل مليون رمز إدخال، لا شيء آخر

مع gpt-6-luna، تكلف المدخلات 0.10 دولار لكل مليون رمز. تدفع فقط مقابل رموز الإدخال: لا توجد رسوم على قراءة ذاكرة التخزين المؤقت، أو كتابة ذاكرة التخزين المؤقت، أو رموز الإخراج. يحتوي كائن usage على حقلي cached_tokens و cache_write_tokens، ولكن وفقًا لرد في منتدى مطوري OpenAI، لا يوجد تخزين مؤقت على القرارات حتى الآن، لذا توقع 0.

تنطبق مضاعفات اثنان. تُحاسب المدخلات التي تزيد عن 272 ألف رمز بسعر 2x، وهو ما يعادل 0.20 دولار لكل مليون رمز (مستمد من مضاعف السياق الطويل في صفحة التسعير). تضيف المعالجة الإقليمية عبر نقاط نهاية إقامة البيانات في الولايات المتحدة أو الاتحاد الأوروبي 10%. لا يتم توثيق أي مستوى دفعات (Batch)، أو مرن (Flex)، أو سريع (Fast) لنقطة النهاية /v1/decisions، لذا لا تخطط حول خصم موجود فقط في الاستجابات.

إليك الحساب الخاص بعبء عمل توجيه الدعم. تكلفة تذكرة من 500 رمز بثلاثة أسئلة في طلب واحد هي 500 / 1,000,000 × 0.10 دولار = 0.00005 دولار. مليون تذكرة من هذا القبيل تكلف 50 دولارًا. نفس التذكرة عبر واجهة برمجة تطبيقات الاستجابات مع تسمية JSON من 40 رمزًا بسعر 0.50 دولار لكل مليون مخرج تضيف 40 / 1,000,000 × 0.50 دولار = 0.00002 دولار لكل طلب بالإضافة إلى الإدخال، قبل رموز الاستدلال، التي تُحاسب عليها Luna كمخرج في الاستجابات ولا تحاسب عليها القرارات على الإطلاق. الصياغة الصادقة هي "القرارات لا تُحاسب على رموز الإخراج"، وليست نسبة مئوية. للحصول على بطاقة أسعار Luna الكاملة وما يفعله التخزين المؤقت للموجهات في الاستجابات، راجع ما هو GPT-6 Luna.

متى تستخدم القرارات، المخرجات المنظمة، أو استدعاء الدوال

تضع OpenAI الحد الفاصل بنفسها: استخدم المخرجات المنظمة مع واجهة برمجة تطبيقات الاستجابات عندما تحتاج إلى كائن يتبع مخطط JSON الخاص بك، مثل الحقول المستخرجة أو شرح مكتوب، أو استدعاء الدوال عندما تحتاج النموذج لطلب استدعاء أداة مع وسائط. تُستخدم القرارات لتصنيف المحتوى، وتوجيه الطلبات، وتحديد أولويات العمل.

يمكن لتعداد المخرجات المنظمة إرجاع تسمية. لا يمكنه إرجاع توزيع احتمالي أو حقل confidence ما لم تطلب من النموذج كتابة واحد، وعندئذ يكون نصًا مُولدًا، وليس احتمالية مقاسة. تمنحك القرارات أرقامًا يمكنك تحديد عتباتها. تخبرك OpenAI بتعيين هذه العتبات من الأمثلة المصنفة في تطبيقك الخاص، وموازنة تكلفة الإيجابيات الكاذبة مقابل السلبيات الكاذبة، لأنه لا يتم نشر أرقام دقة أو معايرة. هل توازن بين بائع ثانٍ لقرار مُحدد النوع؟ تغطي مقارنة القرارات مقابل Jev السعر والمدخلات وأشكال المخرجات جنبًا إلى جنب.

الصور، وتحذير Base64

يقبل input رسائل المستخدم التي يمزج محتواها أجزاء input_text و input_image، مع detail اختياري من low، high، auto (الاعداد الافتراضي) أو original. يقول الدليل أن الصور يجب أن تكون عناوين URL لبيانات base64 مضمنة؛ ولا يتم دعم عناوين URL المستضافة و file_id. تدرج مرجع API أيضًا عناوين URL المتاحة للجمهور عبر HTTP(S)، بحد أقصى 128 صورة لكل طلب. تعامل مع base64 كمسار موثق واختبر عنوان URL مستضاف قبل الاعتماد عليه.

ضوابط البيانات

تدعم واجهة برمجة تطبيقات القرارات الاحتفاظ بالبيانات صفراً (Zero Data Retention) واستخدام HIPAA للعملاء المؤهلين. يتم دعم إقامة البيانات والمعالجة الإقليمية في الولايات المتحدة وأوروبا (المنطقة الاقتصادية الأوروبية بالإضافة إلى سويسرا) عبر us.api.openai.com و eu.api.openai.com. يمكن الوصول إلى نقطة النهاية من كل منطقة API مدعومة، على الرغم من أن التوفر في منطقة ما لا يعني أن الاستدلال يعمل هناك. يتم الاحتفاظ بسجلات مراقبة الانتهاكات لمدة تصل إلى 30 يومًا افتراضيًا. إذا كنت تقوم بتوجيه رسائل المرضى، فاقرأ دليل الامتثال لـ HIPAA API أولاً.

التوفر: بيتا الآن، وتوفر عام قريباً

انتقلت نقطة النهاية إلى المرحلة التجريبية العامة لجميع المطورين في 2026-10-06 وتقع تحت "Beta APIs" في المرجع. يقول دليل OpenAI أن التوفر العام (GA) متوقع "في الأسابيع القادمة"؛ ولم يتم تحديد موعد. تتطلب أمثلة SDK إصدار Python 3.26.0، أو JavaScript 7.30.0، أو Go 3.73.0، أو Ruby 0.101.0، أو Java 4.78.0 أو أحدث؛ يكون الاستدعاء client.decisions.create(...) في Python و JavaScript. تتيح لك ساحة لعب (Playground) على platform.openai.com/decisions تجربة الأسئلة قبل كتابة التعليمات البرمجية. لا يتم نشر حدود معدل محددة للقرارات؛ تحقق من صفحة حدود مؤسستك. لا توجد فئة مجانية للقرارات؛ للوصول المجاني إلى Luna، راجع منشورنا عن مسارات Luna المجانية.

اختبار استدعاءات القرارات في Apidog

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

قم بتخزين المفتاح مرة واحدة. ضع OPENAI_API_KEY في متغير بيئة Apidog وارجع إليه باستخدام {{OPENAI_API_KEY}} في ترويسة Authorization: Bearer، بحيث لا يظهر المفتاح الحرفي أبدًا في طلب مشترك.

احفظ طلبًا واحدًا لكل نوع سؤال، مع تأكيدات JSONPath: الحالة 200، $.answers[0].type يساوي choice، $.answers[0].choice يساوي billing، $.answers[0].confidence أكبر من 0.8، $.answers[?(@.name=='damaged')].probability أكبر من 0.9، و $.usage.output_tokens يساوي 0، والذي يكتشف مفاجأة في الفواتير قبل أن تكتشفها فاتورتك.

اختر العتبات من مجموعة مصنفة. أنشئ سيناريو اختبار في Apidog يقوم بتشغيل نفس الطلب على ملف CSV لنص التذكرة والقسم المتوقع، ثم عيّن عتبة التوجيه التلقائي حيث تتجاوز تكلفة الإيجابيات الكاذبة تكلفة قائمة المراجعة. قم بتشغيله في CI باستخدام Apidog CLI بحيث يؤدي تغيير النموذج أو الاسم المستعار إلى فشل الاختبار بدلاً من العميل. يغطي الدليل الإرشادي كل خطوة، بما في ذلك محاكاة مصفوفة answers حتى يمكن بناء الواجهة الأمامية قبل أن يصبح الموجه نهائيًا.

الأسئلة الشائعة

هل واجهة برمجة تطبيقات القرارات نموذج جديد؟ لا. إنها نقطة نهاية، POST /v1/decisions، تعمل على GPT-6 Luna. تم إطلاق Luna في 2026-09-22؛ ودخلت نقطة النهاية مرحلة البيتا العامة في 2026-10-06.

كم تكلف واجهة برمجة تطبيقات القرارات؟ 0.10 دولار لكل مليون رمز إدخال بدون رسوم على المخرجات أو قراءة أو كتابة ذاكرة التخزين المؤقت. المدخلات التي تزيد عن 272 ألف رمز تكلفتها مضاعفة، وتضيف المعالجة الإقليمية 10%.

هل تُرجع مخطط JSON الخاص بي؟ لا. تُرجع answers مع حقول probability أو choice أو score. للحصول على مخططك الخاص، استخدم المخرجات المنظمة على واجهة برمجة تطبيقات الاستجابات.

ما مدى دقتها؟ لا تنشر OpenAI أرقام دقة أو معايرة. قم بتعيين العتبات من بياناتك المصنفة الخاصة؛ سيناريو اختبار LLM مدفوع بالبيانات هو الطريقة العملية.

من أين تبدأ

اختر قرار توجيه واحدًا يتخذه تطبيقك اليوم باستخدام تعبير نمطي (regex) أو حلقة توجيه وتحليل، واكتبه كسؤال choice واحد مع خيار احتياطي other، ثم قم بتشغيله على 50 مثالًا مصنفًا. إذا انفصل توزيع الثقة بوضوح، فلديك عتبة واختبار. إذا لم يكن الأمر كذلك، فإن السؤال يحتاج إلى معايير أوضح. لتشغيل هذه التجربة مع الطلبات والتأكيدات المحفوظة، قم بتنزيل Apidog واستورد أمر curl أعلاه.