إنشاء إكمالات الدردشة (qwen-mt-turbo)

عند إعطاء هذا النموذج مُدخلًا (Prompt)، فإنه سيُرجع إكمالًا متوقعًا واحدًا أو أكثر (Completion)، ويمكنه أيضًا إرجاع احتمالات الرموز البديلة (Tokens) في كل موضع. تُستخدم هذه الواجهة أساسًا لإجراء المحادثة مع النموذج ومعالجة مهام اللغة الطبيعية مثل الترجمة الآلية.

المرجع الرسمي: Alibaba Cloud Bailian - نموذج الترجمة الآلية

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

بروتوكول الطلب: HTTP/HTTPS
طريقة الطلب: POST
مسار الطلب: https://api.codingplanx.ai/v1/chat/completions

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

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

معاملات الطلب (Request Body)

صيغة جسم الطلب هي application/json.

اسم المعامل	مطلوب	النوع	الوصف
model	نعم	string	معرّف النموذج المراد استخدامه. مثال: `qwen-mt-turbo`.
messages	نعم	array	قائمة الرسائل التي يتضمنها الحوار حتى الآن. تحتوي على الحقلين `role` و `content`.
? role	لا	string	دور مُرسل الرسالة، مثل `user` أو `assistant` أو `system`.
? content	لا	string	محتوى الرسالة.
tools	نعم	array	قائمة الأدوات التي يمكن للنموذج استدعاؤها. حاليًا لا يتم دعم إلا الوظائف (functions) كأدوات. تُستخدم لتزويد النموذج بوظائف يمكنه توليد مُدخلات JSON لها.
tool_choice	نعم	object	يتحكم في الوظيفة التي سيستدعيها النموذج (إن وُجدت). تشير `none` إلى عدم الاستدعاء، وتشير `auto` إلى أن النموذج يختار بنفسه. كما يمكن فرض استدعاء وظيفة محددة عبر `{"type": "function", "function": {"name": "my_function"}}`.
temperature	لا	integer	درجة حرارة أخذ العينات، بين 0 و 2. القيم الأعلى (مثل 0.8) تجعل المخرجات أكثر عشوائية، والقيم الأقل (مثل 0.2) تجعلها أكثر تركيزًا وحتمية. يُنصح بتعديل هذا الحقل أو `top_p`، لكن ليس كليهما معًا.
top_p	لا	integer	معامل أخذ العينات بالنواة (Nucleus Sampling). القيمة 0.1 تعني النظر فقط في الرموز التي تكوّن أعلى 10% من الكتلة الاحتمالية. يُنصح بتعديل هذا الحقل أو `temperature`، لكن ليس كليهما معًا.
n	لا	integer	عدد خيارات إكمال الدردشة التي سيتم إنشاؤها لكل رسالة إدخال. القيمة الافتراضية هي 1.
stream	لا	boolean	ما إذا كان سيتم تفعيل الإخراج المتدفق. إذا كانت القيمة `true`، فسيتم إرسال زيادات جزئية من الرسائل عبر Server-Sent Events (SSE)، وعند الانتهاء سيتم إرسال `data: [DONE]`. القيمة الافتراضية هي `false`.
stop	لا	string	تسلسل يجعل الـ API يتوقف عن توليد المزيد من الرموز (بحد أقصى 4).
max_tokens	لا	integer	الحد الأقصى لعدد الرموز التي يمكن توليدها في إكمال الدردشة. يخضع مجموع طول الإدخال والمخرجات لحد طول السياق الخاص بالنموذج.
presence_penalty	لا	number	رقم بين -2.0 و 2.0. القيم الموجبة تُعاقب الرموز وفقًا لما إذا كانت قد ظهرت مسبقًا في النص، مما يزيد احتمال التطرق إلى موضوعات جديدة.
frequency_penalty	لا	number	رقم بين -2.0 و 2.0. القيم الموجبة تُعاقب الرموز وفقًا لتكرار ظهورها الحالي في النص، مما يقلل احتمال تكرار السطور نفسها.
logit_bias	لا	object/null	يغيّر احتمال ظهور رموز محددة في الإكمال. يقبل كائن JSON يربط معرّفات الرموز بقيم انحياز تتراوح بين -100 و 100.
user	لا	string	معرّف فريد يمثّل المستخدم النهائي لديك، ويمكن أن يساعد في المراقبة واكتشاف إساءة الاستخدام.
response_format	لا	object	كائن يحدد التنسيق الذي يجب أن يخرج به النموذج. سيؤدي استخدام `{"type": "json_object"}` إلى تفعيل وضع JSON. ملاحظة: عند استخدامه يجب توجيه النموذج داخل الرسائل لتوليد JSON.
seen	لا	integer	ميزة في المرحلة التجريبية. تُستخدم كبذرة (seed) لأخذ عينات حتمية. يجب أن يؤدي تكرار الطلب باستخدام نفس البذرة ونفس المعاملات إلى النتيجة نفسها.

مثال طلب (سيناريو الترجمة الآلية)

{
  "model": "qwen-mt-turbo",
  "messages": [
    {
      "role": "user",
      "content": "看完这个视频我没有笑"
    }
  ],
  "translation_options": {
    "source_lang": "auto",
    "target_lang": "English"
  }
}

(ملاحظة: translation_options هو معامل موسّع خاص بنموذج الترجمة qwen-mt-turbo)

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

صيغة الإرجاع هي application/json.

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

مثال استجابة (200 OK)

{
    "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. ما السيناريوهات الرئيسية التي يُستخدم فيها نموذج `qwen-mt-turbo`؟

يُعد qwen-mt-turbo نموذجًا مُحسّنًا بعمق للترجمة الآلية (Machine Translation). وعلى الرغم من أنه يستخدم واجهة Chat Completions القياسية، فإن تمرير النص المطلوب ترجمته مع إعداد لغة المصدر واللغة الهدف يتيح له تقديم نتائج ترجمة عالية الجودة جدًا.

2. كيف يمكن تنفيذ تأثير الكتابة المتدرجة (الإخراج المتدفق)؟

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

3. لماذا أتلقى الخطأ `401 Unauthorized`؟

يُرجى التحقق من الحقل Authorization في رؤوس الطلب. تأكد من أن تنسيقه هو Bearer <your_API_KEY> (لاحظ وجود مسافة بين Bearer و API Key)، وأن مفتاح الـ API لا يزال صالحًا ولديه صلاحية استدعاء هذا النموذج.

4. كيف ينبغي ضبط `temperature` و `top_p`؟

يُستخدم هذان المعاملان للتحكم في عشوائية مخرجات النموذج. توصي الوثائق الرسمية بتعديل واحد فقط منهما مع إبقاء الآخر على القيمة الافتراضية. إذا كنت تريد أن تكون نتائج الترجمة أو السؤال والجواب أكثر دقة وثباتًا، فيُنصح بخفض temperature (مثل 0.1 - 0.2)؛ أما إذا كنت تريد مخرجات أكثر إبداعًا، فيمكنك رفعها (مثل 0.8).

5. هل `translation_options` مطلوب في مثال الطلب؟

هذا إعداد موسّع تدعمه نماذج الترجمة المتخصصة مثل qwen-mt-turbo، ويُستخدم لتحديد لغة المصدر (source_lang) واللغة الهدف (target_lang) بشكل صريح. ورغم أنه يمكن استخدام content داخل messages بصياغة طبيعية لطلب الترجمة من النموذج، فإن استخدام translation_options يجعل تعليمات الترجمة أوضح ويمنح نتائج أكثر استقرارًا. وإذا كنت تستخدمه لمحادثة أساسية غير متعلقة بالترجمة، فيمكن عدم تمريره.