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

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

اسم الواجهة: سرد النماذج / إكمالات الدردشة
طريقة الطلب: GET (ملاحظة: وفقًا لتعريف البيانات المقدَّم)
عنوان الطلب：https://api.codingplanx.ai/v1/models
الحالة：منشور (Released)

1. معلمات الطلب

1.1 معلمات Header

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

1.2 معلمات Body

رغم أن التعريف الأصلي هو GET، فإن المعلمات التالية تُمرَّر عادةً عبر JSON Body وفقًا لمنطق العمل.

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

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

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

3. أمثلة الطلب

مثال على طلب ناجح

curl --location --request GET 'https://api.codingplanx.ai/v1/models' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "Hello there, how may I assist you today?"
    }
  ],
  "temperature": 1,
  "top_p": 1,
  "n": 1,
  "stream": false,
  "user": "user-1234"
}'

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

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

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

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

س: كيف ينبغي اختيار temperature وtop_p؟
ج: نوصي بتعديل أحدهما فقط. إذا كنت تريد إجابات أدق وأكثر حتمية، فاخفض temperature (مثل 0.2)؛ وإذا كنت تريد مخرجات أكثر تنوعًا وإبداعًا، فيمكنك رفعها.

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

س: ما المقصود بـ presence_penalty وfrequency_penalty؟
ج:

presence_penalty (عقوبة الوجود): يركّز على معاقبة الموضوعات التي ظهرت بالفعل، ويشجّع النموذج على التطرق إلى مواضيع جديدة.
frequency_penalty (عقوبة التكرار): يركّز على معاقبة الألفاظ التي تكررت بالفعل، لمنع النموذج من تكرار الجملة نفسها خلال وقت قصير.

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