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

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

عنوان الواجهة: https://api.codingplanx.ai/v1/chat/completions
طريقة الطلب: POST
نوع المحتوى: application/json

معلمات الطلب

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

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

جسم الطلب (Body)

اسم المعلمة	النوع	مطلوب	القيمة الافتراضية	الوصف
model	string	نعم	-	معرّف النموذج المطلوب استخدامه (مثل `gpt-4o`, `gpt-3.5-turbo`).
messages	array	نعم	-	قائمة رسائل المحادثة. يحتوي كل عنصر على `role` (`system`/`user`/`assistant`) و `content`.
temperature	number	لا	1	درجة حرارة أخذ العينات (0-2). كلما زادت أصبحت النتائج أكثر عشوائية، وكلما انخفضت أصبحت أكثر حتمية.
top_p	number	لا	1	أخذ العينات النووي. لا يتم النظر إلا في الرموز الواقعة ضمن أعلى كتلة احتمالية بقيمة top_p. يُنصح عادةً بتعديل أحد `temperature` أو `top_p` فقط.
n	integer	لا	1	عدد خيارات الإكمال التي سيتم توليدها لكل رسالة إدخال.
stream	boolean	لا	false	ما إذا كان سيتم البث التدريجي. هنا يجب ضبطه على `false`.
stop	string/array	لا	null	تسلسلات إيقاف التوليد في API (بحد أقصى 4).
max_tokens	integer	لا	inf	الحد الأقصى لعدد الرموز التي يمكن توليدها، مع التقيد بحد طول السياق الخاص بالنموذج.
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	لا	-	قائمة الأدوات التي يمكن للنموذج استدعاؤها (المدعوم حاليًا هو `function` فقط).
tool_choice	string/obj	لا	auto	التحكم في الوظيفة التي يجب على النموذج استدعاؤها (`none`/`auto`/وظيفة محددة).

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

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

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

أمثلة

مثال طلب (cURL)

curl --location --request POST 'https://api.codingplanx.ai/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "مرحبًا، هل يمكنك أن تعرّف بنفسك؟"
    }
  ],
  "max_tokens": 1000
}'

مثال استجابة

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "مرحبًا! أنا مساعد ذكاء اصطناعي مقدم من CodingPlanX، ويسعدني خدمتك."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 25,
        "total_tokens": 40
    }
}

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

Q1: كيف يمكن تفعيل وضع JSON؟
A1: اضبط "response_format": { "type": "json_object" } داخل جسم الطلب. ملاحظة: عند استخدام وضع JSON، يجب عليك أن توجّه النموذج بوضوح في رسالة system أو user لإخراج JSON، وإلا فقد ينتج النموذج محتوى فارغًا بشكل متكرر إلى ما لا نهاية.

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

Q3: لماذا تكون قيمة finish_reason هي length؟
A3: هذا يعني أن الرد الذي تم توليده قُطع بسبب الوصول إلى حد max_tokens الذي قمت بتعيينه أو بسبب تجاوز الحد الأقصى لطول السياق الذي يدعمه النموذج.

Q4: ما هو Token؟
A4: الـ Token هو الوحدة الأساسية التي يعالج بها النموذج النص. بالنسبة للنص الصيني، يعادل كل حرف صيني تقريبًا 1 إلى 2 Token. تعتمد الفوترة وحدود السياق في API على عدد الـ Tokens.

Q5: ما الفرق بين presence_penalty و frequency_penalty؟
A5: يركّز presence_penalty على “التحدث عن مواضيع جديدة”، أي إنه يفرض عقوبة بمجرد ظهور الكلمة؛ بينما يركّز frequency_penalty على “عدد مرات تكرار الكلمات”، أي كلما تكررت الكلمة أكثر زادت العقوبة.

Q6: إذا أردت الحصول على تأثير الكتابة اللحظية في الوقت الحقيقي، ماذا أفعل؟
A6: يرجى ضبط المعلمة stream على true. لاحظ أن تنسيق الاستجابة في البث التدريجي يختلف عن هذا المستند (غير المتدفق)، إذ يعتمد على Server-Sent Events (SSE).