وثائق واجهة برمجة تطبيقات إكمال الدردشة (Chat Completions)

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

1. معلومات الواجهة

اسم الواجهة: الاختبار الرسمي N
طريقة الطلب: POST
عنوان الطلب: https://api.codingplanx.ai/v1/chat/completions
نوع المحتوى: application/json
طريقة المصادقة: Bearer {{YOUR_API_KEY}}

2. رؤوس الطلب (Headers)

اسم المعلمة	مطلوب	النوع	الوصف	المثال
Content-Type	نعم	string	معرّف نوع الوسائط	`application/json`
Accept	نعم	string	تنسيق الاستجابة الذي يقبله العميل	`application/json`
Authorization	لا	string	رمز الوصول إلى API	`Bearer sk-xxxxxx`

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

اسم المعلمة	مطلوب	النوع	الوصف
model	نعم	string	معرّف النموذج المراد استخدامه (مثل `gpt-4o`, `gpt-3.5-turbo`).
messages	نعم	array	قائمة رسائل المحادثة. يحتوي كل كائن على `role` (`system` / `user` / `assistant`) و`content`.
tools	نعم	array	قائمة بالأدوات التي يمكن للنموذج استدعاؤها. حاليًا يتم دعم الدوال فقط.
tool_choice	نعم	object	يتحكم في الدالة التي يجب على النموذج استدعاؤها. القيم الممكنة: `none` (بدون استدعاء)، `auto` (تلقائي)، أو تحديد دالة معيّنة.
temperature	لا	number	درجة حرارة أخذ العينات (0-2). كلما ارتفعت زادت العشوائية، وكلما انخفضت زادت الحتمية. يُنصح عادةً بالاختيار بين هذا و`top_p`.
top_p	لا	number	أخذ العينات بالنواة (nucleus sampling). مثلًا، `0.1` تعني النظر فقط في الرموز التي تشكل أعلى 10% من الكتلة الاحتمالية.
n	لا	integer	القيمة الافتراضية هي 1. عدد الردود التي سيتم توليدها لكل رسالة إدخال.
stream	لا	boolean	القيمة الافتراضية هي `false`. إذا كانت `true`، فسيتم إرسال الرموز بشكل تدريجي مثل ChatGPT.
stop	لا	string	تسلسل الإيقاف. يتوقف التوليد عندما يصادف النموذج هذه الأحرف.
max_tokens	لا	integer	الحد الأقصى لعدد الرموز التي سيتم توليدها. القيمة الافتراضية هي `inf`.
presence_penalty	لا	number	بين `-2.0` و`2.0`. يعاقب الموضوعات التي ظهرت مسبقًا لزيادة احتمال التحدث عن موضوعات جديدة.
frequency_penalty	لا	number	بين `-2.0` و`2.0`. يعاقب الكلمات المتكررة.
logit_bias	لا	object	يعدّل احتمال ظهور رموز معيّنة.
user	لا	string	معرّف المستخدم النهائي، ويُستخدم لاكتشاف إساءة الاستخدام.
response_format	لا	object	يحدد تنسيق الإرجاع. على سبيل المثال، `{ "type": "json_object" }` يمكنه تفعيل وضع JSON.
seen	لا	integer	ميزة في المرحلة التجريبية. تحدد قيمة Seed لمحاولة تحقيق مخرجات حتمية.

4. معلمات الاستجابة (Response Body)

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

5. أمثلة (Example)

مثال على الطلب

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "من أنت؟"
        }
    ],
    "n": 1,
    "max_tokens": 100,
    "temperature": 0.8,
    "stream": false
}

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

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

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

س: لماذا يظهر خطأ عند تعيين response_format: { "type": "json_object" }؟
ج: عند استخدام وضع JSON، يجب عليك توضيح ذلك صراحةً داخل messages من خلال رسالة نظام أو رسالة مستخدم تطلب من النموذج الإرجاع بصيغة JSON (مثل: "الرجاء الرد بصيغة JSON"). وإلا فقد يتعذر على النموذج إنشاء JSON صالح، مما قد يؤدي إلى التوقف أو ظهور خطأ.

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

س: كيف أستقبل البيانات عند تعيين stream: true؟
ج: عند تفعيل البث، سيرسل الخادم سلسلة من أحداث Server-Sent Events (SSE). يحتوي جزء البيانات في كل حدث على كائن JSON، وفي النهاية سيتم إرسال data: [DONE]. ستحتاج إلى استخدام مكتبة لمعالجة البث (مثل response.iter_lines() في Python) للتعامل مع البيانات سطرًا بسطر.

س: كيف يتم حساب استهلاك الـ Token؟
ج: بالنسبة للإنجليزية، يعادل 1 Token تقريبًا 4 أحرف أو 0.75 كلمة؛ أما بالنسبة للصينية، فقد يقابل الحرف الواحد من 1 إلى 2 Token. ويظل الاستهلاك النهائي معتمدًا على الحقل usage في جسم الاستجابة.

س: ماذا يعني finish_reason: "length"؟
ج: هذا يعني أن المحتوى الذي تم توليده تجاوز الحد الذي حددته في max_tokens، أو أنه وصل إلى الحد الأقصى لطول السياق الخاص بالنموذج، مما أدى إلى قطع المحتوى.

س: هل تدعم الواجهة استدعاء الدوال (Function Calling)؟
ج: نعم، مدعوم. يمكنك تعريف نماذج الدوال من خلال المعلمة tools، وسيُرجع النموذج tool_calls داخل choices[0].message بدلًا من content العادي.