إنشاء إكمالات الدردشة - التحكم في مستوى التفكير في DeepSeek v3.1 (بثّي)

تُستخدم هذه الواجهة لإنشاء محادثات دردشة مع نموذج DeepSeek v3.1. وهي تدعم الإخراج البثّي (SSE) بالإضافة إلى التحكم الدقيق في قدرة النموذج على التفكير العميق (Thinking).

تفاصيل الواجهة

حالة الواجهة: منشورة (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}}`	بيانات اعتماد المصادقة (وعادةً يكون مطلوبًا فعليًا عند الاستدعاء)

(ملاحظة: تم تعطيل ترويسة X-Forwarded-Host حاليًا)

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

Content-Type: application/json

اسم المعامل	مطلوب	النوع	الوصف
`model`	نعم	String	معرّف النموذج المستخدم. مثال: `deepseek-v3-1-250821`
`messages`	نعم	Array of Objects	قائمة رسائل المحادثة.
? `role`	نعم	String	دور مرسل الرسالة (مثل `system`، `user`، `assistant`).
? `content`	نعم	String	المحتوى الفعلي للرسالة.
`max_tokens`	لا	Integer	يحدّد الحد الأقصى لعدد الرموز (tokens) التي يمكن أن ينشئها النموذج في completion واحد. ويظل مجموع رموز الإدخال والإخراج خاضعًا لحد نافذة السياق الخاصة بالنموذج.
`temperature`	لا	Number	درجة حرارة أخذ العينات، بين 0 و2. القيم الأعلى (مثل 0.8) تجعل المخرجات أكثر عشوائية، بينما القيم الأقل (مثل 0.2) تجعلها أكثر تركيزًا وحسمًا.
`stream`	لا	Boolean	إذا تم تعيينه إلى `true`، فسيتم إرسال زيادات الرسالة بشكل بثّي عبر SSE (server-sent events). وينتهي تدفق الرسائل بـ `data: [DONE]`.
`stream_options`	لا	Object	خيارات متعلقة بالإخراج البثّي. لا يمكن تعيين هذا المعامل إلا إذا كانت قيمة `stream` هي `true`.
? `include_usage`	لا	Boolean	إذا تم تعيينه إلى `true`، فسيتم إرسال كتلة إضافية قبل `data: [DONE]` الأخيرة في الرسائل البثّية. ويعرض الحقل `usage` في هذه الكتلة إحصاءات استخدام الرموز (tokens) للطلب بالكامل.
`thinking`	لا	Object	تدعم بعض النماذج ذات قدرات التفكير العميق التحكم في تفعيل هذه القدرة عبر هذا الحقل.
? `type`	لا	String	`enabled`: فرض تفعيل قدرة التفكير العميق.<br>`disabled`: فرض تعطيلها.<br>`auto`: يقرر النموذج تلقائيًا.

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

{
  "model": "deepseek-v3-1-250821",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "temperature": 1.0,
  "stream": true,
  "stream_options": {
    "include_usage": true
  },
  "thinking": {
    "type": "enabled"
  }
}

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

رمز حالة HTTP: 200 OK
Content-Type: application/json

(ملاحظة: عند تعيين stream: true، تكون صيغة الإرجاع تدفق بيانات SSE، وكل data chunk يكون سلسلة JSON بالبنية التالية. فيما يلي البنية القياسية لـ JSON في الوضع غير البثّي، أو بعد تجميع الاستجابة البثّية بالكامل)

اسم الحقل	النوع	الوصف
`id`	String	المعرّف الفريد للطلب.
`object`	String	نوع الكائن، وعادةً ما يكون `chat.completion` أو `chat.completion.chunk`.
`created`	Integer	الطابع الزمني للإنشاء (بالثواني).
`choices`	Array of Objects	قائمة الردود التي أنشأها النموذج.
? `index`	Integer	فهرس هذا الرد داخل قائمة `choices`.
? `message`	Object	كائن الرسالة المُنشأة (وفي الطلبات البثّية يكون عادةً `delta`).
? `role`	String	الدور (وعادةً يكون `assistant`).
? `content`	String	المحتوى الفعلي للرد.
? `finish_reason`	String	سبب توقف التوليد (مثل `stop` أو `length`).
`usage`	Object	إحصاءات استخدام الرموز (Token).
? `prompt_tokens`	Integer	عدد الرموز المستهلكة في prompt.
? `completion_tokens`	Integer	عدد الرموز المستهلكة في المحتوى المُنشأ.
? `total_tokens`	Integer	إجمالي عدد الرموز المستهلكة.

مثال على الاستجابة (JSON)

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

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

س1: كيف يمكنني الحصول على استهلاك الرموز (Usage) في طلبات البثّ (SSE)؟
ج1: تحتاج إلى تعيين stream إلى true في جسم الطلب، مع إعداد stream_options: {"include_usage": true} في الوقت نفسه. عندها سيدفع الخادم كتلة بيانات إضافية قبل إرسال علامة انتهاء SSE وهي data: [DONE]. في هذه الكتلة تكون مصفوفة choices فارغة، لكن حقل usage يحتوي على الإحصاءات الكاملة للرموز.

س2: ما الفرق بين enabled و auto في المعامل thinking؟
ج2:

enabled: يفرض على النموذج إجراء “تفكير عميق (Chain of Thought)” قبل إرجاع الإجابة النهائية. وغالبًا ما يؤدي ذلك إلى نتائج استدلال أفضل، لكنه قد يزيد زمن الاستجابة (تأخير أول رمز) واستهلاك رموز الإخراج.
auto: يترك القرار للنموذج، حيث يحدّد تلقائيًا ما إذا كانت هناك حاجة إلى التفكير العميق بناءً على مدى تعقيد السؤال في messages.

س3: لماذا أعاد الطلب خطأ 401 Unauthorized؟
ج3: يحدث هذا عادةً بسبب فشل المصادقة. يرجى التحقق من أن حقل Authorization في Request Header قد تم تعبئته بالشكل الصحيح وفق الصيغة Bearer {{YOUR_API_KEY}}، والتأكد من أن مفتاح API صالح ولم تنتهِ صلاحيته.

س4: عند تفعيل التفكير العميق thinking، هل سيتم إرجاع محتوى عملية التفكير؟
ج4: وفقًا للتنفيذ القياسي المتوافق مع OpenAI، إذا كانت الاستجابة بثّية، فقد يتم إرجاع محتوى التفكير العميق داخل محددات خاصة (مثل الوسوم <think>...</think>) أو عبر حقول خاصة في chunk. لذا عند تحليل بيانات التدفق في الواجهة الأمامية، انتبه إلى معالجة محتوى التفكير داخل content حتى تتمكن من عرض واجهة “جارٍ التفكير” للمستخدم.

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