إنشاء إكمالات الدردشة (متدفق)

مرجع الوثائق الرسمية: OpenAI Chat Create

وصف الواجهة

عند تقديم موجّه (Prompt)، سيُرجع النموذج محتوى دردشة مُكمَّلًا واحدًا أو أكثر بشكل متوقع. تدعم هذه الواجهة كلًا من الاستجابة القياسية والاستجابة المتدفقة (SSE)، كما يمكنها أيضًا إرجاع احتمالات الرموز البديلة لكل موضع.

شرح الطلب

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

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

اسم المعامل	مطلوب	النوع	المثال	الوصف
`Content-Type`	نعم	string	`application/json`	تنسيق البيانات
`Accept`	نعم	string	`application/json`	تنسيق البيانات المستقبَلة
`Authorization`	لا*	string	`Bearer {{YOUR_API_KEY}}`	رمز المصادقة (عادةً ما يكون مطلوبًا في الاستدعاء الفعلي)
`X-Forwarded-Host`	لا	string	`localhost:5173`	اسم مضيف الوكيل (غالبًا لا حاجة لتمريره يدويًا)

جسم الطلب (Request Body)

اسم المعامل	النوع	مطلوب	الوصف
`model`	string	نعم	معرّف النموذج المراد استخدامه. راجع جدول توافق نقطة نهاية النماذج لمعرفة قائمة النماذج المدعومة.
`messages`	array	نعم	قائمة الرسائل الموجودة في المحادثة حتى الآن. تحتوي على الحقلين `role` و`content`.
`tools`	array	نعم	قائمة الأدوات التي يمكن للنموذج استدعاؤها. حاليًا يتم دعم الدوال فقط كأدوات.
`tool_choice`	object	نعم	يتحكم في الدالة التي سيستدعيها النموذج، إن وجدت. تشير القيمة `none` إلى عدم الاستدعاء، و`auto` إلى الاختيار التلقائي، أو يمكن فرض استدعاء دالة محددة.
`extra_body`	object	نعم	معلمات إضافية. تتضمن `enable_thinking` (boolean)، وتحدد ما إذا كان سيتم تفعيل وضع التفكير أم لا (يتطلب دعمًا من النموذج).
`temperature`	integer/float	لا	درجة حرارة أخذ العينات، بين 0 و2. القيم الأعلى (مثل 0.8) تجعل المخرجات أكثر عشوائية، والقيم الأقل (مثل 0.2) تجعلها أكثر تركيزًا وثباتًا. يُنصح بتعديل هذا المعامل أو `top_p`، ولكن ليس كليهما في الوقت نفسه.
`top_p`	integer/float	لا	معامل أخذ العينات بالنواة. تعني القيمة 0.1 أنه سيتم النظر فقط في الرموز التي تُشكّل أعلى 10% من الكتلة الاحتمالية. يُنصح بتعديل هذا المعامل أو `temperature`، ولكن ليس كليهما في الوقت نفسه.
`n`	integer	لا	عدد خيارات إكمال الدردشة التي سيتم إنشاؤها لكل رسالة إدخال. القيمة الافتراضية هي 1.
`stream`	boolean	لا	ما إذا كان سيتم تفعيل الإخراج المتدفق. إذا تم ضبطه على `true`، فسيتم إرسال زيادات الرسائل الجزئية بصيغة Server-Sent Events (SSE)، وسينتهي التدفق عند رسالة `data: [DONE]`.
`stop`	string/array	لا	تسلسل يوقف عنده الـ API توليد المزيد من الرموز (بحد أقصى 4). القيمة الافتراضية هي null.
`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. ملاحظة: عند استخدامه، يجب توجيه النموذج داخل الرسائل لإنتاج JSON، وإلا فقد يؤدي ذلك إلى تدفق لا نهائي من المسافات الفارغة.
`seen`	integer	لا	يحدد بذرة (Seed) لأخذ عينات حتمية (ميزة Beta).

مثال الطلب

{
  "model": "gpt-5-mini",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "system",
      "content": "أنت مساعد مفيد."
    },
    {
      "role": "user",
      "content": "مرحبًا"
    }
  ],
  "temperature": 1.0,
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

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

Content-Type: application/json (غير متدفق) أو text/event-stream (عند التفعيل المتدفق باستخدام stream: true)

معاملات الاستجابة (البنية غير المتدفقة)

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

مثال الاستجابة (غير متدفقة / نتيجة متدفقة مجمّعة)

{
    "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
    }
}

(ملاحظة: إذا تم تحديد stream: true في الطلب، فسيكون جسم الاستجابة عبارة عن تدفق أحداث SSE مفصولة بأسطر، ويبدأ كل سطر بـ data: {...}، وينتهي أخيرًا بـ data: [DONE].)

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

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

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

س3: هل يمكن تعديل temperature وtop_p في الوقت نفسه؟
ج: توصي الوثائق الرسمية بشدة بعدم تعديل هذين المعاملين معًا. كلاهما يُستخدم للتحكم في عشوائية خرج النموذج. إذا كنت تريد مخرجات أكثر استقرارًا وقابلية للتوقع، فقم بتقليل temperature أو تقليص top_p؛ وإذا كنت تريد إجابات أكثر إبداعًا، فقم برفع أحدهما. تعديل كليهما معًا قد يؤدي إلى نتائج يصعب توقعها.

س4: ما وظيفة extra_body.enable_thinking ضمن المعاملات؟
ج: هذا معامل توسعة خاص بهذه الواجهة. عند تمرير {"enable_thinking": true}، وإذا كان النموذج المستخدم في الخلفية يدعم “وضع التفكير (Thinking Mode / CoT)” (مثل بعض النماذج الكبيرة المعززة للاستدلال)، فسيتم تفعيل عملية التفكير العميق. وإذا لم يكن النموذج يدعم ذلك، فعادةً ما يتم تجاهل هذا المعامل.

س5: لماذا تكون قيمة finish_reason في الاستجابة هي length بدلًا من stop؟
ج: إرجاع finish_reason بالقيمة length يعني أن النموذج لم يُكمل الرد بالكامل وتم قطعه قسرًا. يحدث هذا عادةً لأن قيمة max_tokens التي حددتها صغيرة جدًا، أو لأن مجموع عدد الرموز في الإدخال والمخرجات تجاوز الحد الأقصى لنافذة السياق التي يسمح بها النموذج الحالي. جرّب زيادة قيمة max_tokens.