التحكم في مستوى جهد نموذج الاستدلال (Chat Completions)

وصف الواجهة

عند تقديم مطالبة، سيُرجع هذا النموذج ردًا أو أكثر من ردود الإكمال المتوقعة (مع دعم التحكم في مستوى جهد التفكير لنماذج الاستدلال).

مرجع الوثائق الرسمية: OpenAI Reasoning Guides
حالة الواجهة: تم الإصدار (released)

شرح الطلب

طريقة الطلب: POST
عنوان الطلب: https://api.codingplanx.ai/v1/chat/completions

ترويسات الطلب (Headers)

اسم المعامل	مطلوب	النوع	القيمة المثال	الوصف
`Content-Type`	نعم	`string`	`application/json`	تنسيق البيانات
`Accept`	نعم	`string`	`application/json`	تنسيق الاستجابة المقبول
`Authorization`	لا	`string`	`Bearer {{YOUR_API_KEY}}`	بيانات اعتماد المصادقة

معاملات جسم الطلب (Body)

تنسيق البيانات: application/json

اسم المعامل	مطلوب	النوع	الوصف
`model`	نعم	`string`	معرّف النموذج المطلوب استخدامه (مثل `o4-mini` وغيرها).
`messages`	نعم	`array`	قائمة الرسائل الموجودة في المحادثة حتى الآن. تتضمن `role` (مثل user/assistant) و`content` (محتوى الرسالة).
`tools`	نعم	`array`	قائمة بالأدوات (الدوال) التي يمكن للنموذج استدعاؤها. تُستخدم لتزويد النموذج بدوال يمكنه توليد مدخلات JSON لها.
`tool_choice`	نعم	`object`	يتحكم في الدالة التي سيستدعيها النموذج. تشير `none` إلى عدم الاستدعاء، وتشير `auto` إلى الاختيار التلقائي.
`reasoning_effort`	لا	`string`	المعامل الأساسي: يتحكم في مستوى الجهد الذي يبذله نموذج الاستدلال عند توليد الرد (عمق التفكير). القيم الشائعة هي `low` و`medium` و`high`.
`temperature`	لا	`number`	درجة حرارة أخذ العينات، بين 0 و2. القيم الأعلى (مثل 0.8) تجعل المخرجات أكثر عشوائية، والقيم الأقل (مثل 0.2) تجعلها أكثر تركيزًا وحسمًا. يُنصح بتعديل هذا المعامل أو `top_p` فقط، وليس كليهما معًا.
`top_p`	لا	`number`	أخذ عينات النواة. قيمة 0.1 تعني أنه سيتم النظر فقط في الرموز التي تشكل أعلى 10% من الكتلة الاحتمالية. يُنصح بتعديل هذا المعامل أو `temperature` فقط، وليس كليهما معًا.
`n`	لا	`integer`	القيمة الافتراضية هي 1. عدد خيارات إكمال الدردشة التي سيتم توليدها لكل رسالة إدخال.
`stream`	لا	`boolean`	القيمة الافتراضية هي false. عند ضبطه على true، سيتم إرسال زيادات الرسائل الجزئية بصيغة Server-Sent Events (SSE)، مع إنهاء التدفق عبر `data: [DONE]`.
`stop`	لا	`string`	حتى 4 سلاسل نصية يمكن أن تتوقف عندها واجهة API عن توليد المزيد من الرموز.
`max_tokens`	لا	`integer`	الحد الأقصى لعدد الرموز التي يمكن توليدها في إكمال الدردشة. يخضع مجموع طول رموز الإدخال والإخراج لحد طول السياق الخاص بالنموذج.
`presence_penalty`	لا	`number`	رقم بين -2.0 و2.0. القيم الموجبة تعاقب الرموز الجديدة بناءً على ما إذا كانت قد ظهرت مسبقًا، مما يزيد احتمالية التطرق إلى مواضيع جديدة.
`frequency_penalty`	لا	`number`	رقم بين -2.0 و2.0. القيم الموجبة تعاقب الرموز الجديدة بحسب تكرار ظهورها في النص حتى الآن، مما يقلل من تكرار نفس المحتوى.
`logit_bias`	لا	`object`	يقبل كائن JSON يربط معرّفات الرموز بقيم انحياز (من -100 إلى 100) لتعديل احتمال ظهور رموز معينة في الإكمال.
`user`	لا	`string`	معرّف فريد يمثل المستخدم النهائي، ويساعد في المراقبة واكتشاف إساءة الاستخدام.
`response_format`	لا	`object`	يحدد التنسيق الذي يجب أن يخرجه النموذج. على سبيل المثال، `{"type": "json_object"}` لتفعيل وضع JSON.
`seen`	لا	`integer`	ميزة في مرحلة الاختبار (مشابهة لـ seed). عند تحديدها، سيبذل النظام أقصى جهد ممكن لجعل أخذ العينات حتميًا بحيث تعود نفس المعلمات بنفس النتيجة.

مثال الطلب

{
  "model": "o4-mini",
  "max_tokens": 500,
  "messages": [
    {
      "role": "user",
      "content": "مرحبًا، يرجى شرح مبدأ الحوسبة الكمومية بالتفصيل."
    }
  ],
  "temperature": 1.0,
  "stream": false,
  "reasoning_effort": "medium"
}

شرح الاستجابة

معاملات جسم الاستجابة

تنسيق البيانات: application/json

اسم المعامل	النوع	الوصف
`id`	`string`	المعرّف الفريد لهذا الطلب.
`object`	`string`	نوع الكائن، وعادة ما يكون `chat.completion`.
`created`	`integer`	الطابع الزمني لوقت الإنشاء.
`choices`	`array`	قائمة بنتائج الإكمال.
└ `index`	`integer`	فهرس هذا الخيار داخل القائمة.
└ `message`	`object`	كائن الرسالة الذي ولّده النموذج. يتضمن `role` و`content`.
└ `finish_reason`	`string`	سبب توقف التوليد (مثل `stop` أو `length`).
`usage`	`object`	إحصاءات استهلاك الرموز.
└ `prompt_tokens`	`integer`	عدد الرموز المستهلكة في المطالبة.
└ `completion_tokens`	`integer`	عدد الرموز المستهلكة في المخرجات التي ولّدها النموذج.
└ `total_tokens`	`integer`	إجمالي عدد الرموز المستهلكة.

مثال الاستجابة (HTTP 200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
مرحبًا، كيف يمكنني مساعدتك اليوم؟"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

FAQs (الأسئلة الشائعة)

1. ما وظيفة المعامل `reasoning_effort`؟

يُستخدم reasoning_effort للتحكم في مقدار الموارد والوقت الذي يستهلكه نموذج يمتلك قدرات استدلال متقدمة (Reasoning)، مثل نماذج OpenAI من سلسلتي o1/o4، في التفكير الداخلي قبل إعطاء الإجابة النهائية. عادةً ما يدعم ثلاث درجات: low وmedium وhigh. عند ضبطه على high، سيجري النموذج استدلالًا منطقيًا أعمق، وهو مناسب لحل المسائل المعقدة في الرياضيات أو البرمجة؛ لكن زمن الاستجابة سيزداد تبعًا لذلك.

2. لماذا لا أتلقى استجابة JSON قياسية عند تفعيل `stream: true`؟

عند تفعيل البث التدريجي (stream: true)، تستخدم واجهة API بروتوكول Server-Sent Events (SSE) لإرجاع أجزاء من البيانات بشكل مستمر. يتم إرسال كل جزء بصيغة data: {...}، وعند اكتمال الإرسال، يتم إرسال الرسالة data: [DONE]. يحتاج المطور إلى قراءة هذه الأسطر واحدًا تلو الآخر وتحليل سلسلة JSON التي تأتي بعد data: ثم تجميع الرد الكامل.

3. لماذا توصي الوثائق بتعديل واحد فقط من `temperature` و`top_p`؟

كلا المعاملين يُستخدمان للتحكم في عشوائية المخرجات وتنوعها. يقوم temperature بتغيير توزيع الاحتمالات عبر مقياس logits، بينما يقوم top_p (أخذ عينات النواة) بتقييد مجموعة المرشحين عبر استبعاد الكلمات ذات الاحتمالات المنخفضة خارج الكتلة الاحتمالية التراكمية المطلوبة. يؤدي تعديل الاثنين معًا إلى جعل سلوك النموذج أصعب في التنبؤ والتحكم، لذا فإن أفضل ممارسة هي تثبيت أحدهما (غالبًا إبقاؤه على القيمة الافتراضية) وتعديل الآخر فقط لتحقيق مستوى العشوائية المطلوب.

4. ماذا يعني إذا كانت قيمة `finish_reason` هي `"length"`؟

هذا يعني أن رد النموذج قد تم قطعه قسرًا. وعادةً ما يكون السبب أحد أمرين: إما أن عدد الرموز المولّدة بلغ الحد الأقصى المحدد في max_tokens، أو أن مجموع رموز المطالبة (Prompt) والرد الذي ولّده النموذج تجاوز الحد الأقصى لنافذة السياق التي يدعمها النموذج. في هذه الحالة، يُنصح بتقليل سجل المحادثة أو زيادة قيمة max_tokens.

5. كيف أجبر النموذج على إرجاع بيانات بصيغة JSON؟

يمكنك تفعيل وضع JSON عبر تمرير "response_format": {"type": "json_object"} داخل جسم الطلب. مهم جدًا: عند تفعيل هذا الوضع، يجب عليك أيضًا أن تطلب صراحةً من النموذج بلغة طبيعية داخل messages (عادةً في system أو user) أن يُخرج JSON. وإلا فقد يدخل النموذج في حلقة توليد لا نهائية من المسافات الفارغة حتى يصل إلى حد الرموز المسموح.