تقدم Qwen API منصة Alibaba Cloud Model Studio (Bailian)، ونظام DashScope هو واجهتها الأصلية. توفر المنصة واجهة متوافقة مع OpenAI وأخرى أصلية بـDashScope. لمعظم الفرق، البدء بالواجهة المتوافقة مع OpenAI أسهل: فـSDK وأطر الوكلاء والأدوات الحالية تحتاج عادةً إلى تغيير ثلاثة أشياء فقط: مفتاح API وBase URL واسم الطراز.

لا تكمن المزالق في «هل يعمل الاستدعاء»، بل في منطقة Base URL وصلاحية اسم الطراز وكيفية تحليل البث وأي المعاملات لا تُنسخ من OpenAI كما هي. تشغّل المقالة المسار بأصغر طلب، ثم تضيف استدعاء الأدوات وتشخيص الأخطاء وقائمة الترحيل.

ملاحظة: Qwen وTongyi Qianwen وAlibaba Cloud وBailian (Model Studio) وDashScope أسماء أو علامات تجارية أو منتجات لشركة Alibaba Group والشركات التابعة لها، وهذه المقالة للشرح التقني فقط، ولا توجد علاقة تبعية أو وكالة أو ترخيص مع Alibaba Group. قد تتغير Base URL وأسماء الطرازات وأطوال السياق ومعايير الفوترة، فيُعتمد على وثائق Alibaba Cloud Model Studio الرسمية وأسعار الطرازات داخل الموقع.

أولًا: الاستعداد قبل الربط

تأكد من ثلاثة أشياء قبل البدء:

  • مفتاح API صالح ومطابق للمنطقة المستهدفة.
  • Base URL صحيح، ولا تُخلط عناوين البر الرئيسي والموقع الدولي والبوابة.
  • اسم طراز متاح فعليًا في الوقت الحالي، لا مثالًا منسوخًا من مقالة قديمة.

يُستحسن التحقق من المصادقة والشبكة بـcurl قبل ربط SDK، فيسهل تحديد ما إذا كان الخطأ في المفتاح أم العنوان أم الشيفرة.

ثانيًا: Base URL: اختر المنطقة ثم النطاق

مسار الواجهة المتوافقة مع OpenAI ثابت /compatible-mode/v1، ويُضاف إليه مسار المحادثة /chat/completions. يختلف النطاق حسب المنطقة، والأشكال الشائعة كالتالي:

السيناريو Base URL المتوافق مع OpenAI ملاحظة
البر الرئيسي الصيني (بكين، النطاق المشترك القديم) https://dashscope.aliyuncs.com/compatible-mode/v1 متوافق مع الشيفرة القديمة وما زال متاحًا
سنغافورة (الموقع الدولي) https://dashscope-intl.aliyuncs.com/compatible-mode/v1 حساب ومفتاح الموقع الدولي
فيرجينيا الأمريكية https://dashscope-us.aliyuncs.com/compatible-mode/v1 IPv4 فقط، والقدرات حسب الوثائق
هونغ كونغ الصينية https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 منطقة ومفتاح مستقلان
مساحة عمل مخصصة https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 مفضل للإنتاج، إنتاجية وعزل أفضل
بوابة ZSQH AI https://ai.zhongshangqihang.com/v1 مدخل موحد لعدة طرازات

نقاط أساسية. أولًا، مفتاح API مرتبط بالمنطقة، والاستدعاء عبر منطقة أخرى يعيد عادةً 401 وinvalid_api_key، وهذا يعني عدم تطابق المفتاح مع العنوان لا انتهاء صلاحيته. ثانيًا، حساب البر الرئيسي وحساب الموقع الدولي نظامان منفصلان، ولا تتشارك المفاتيح والفواتير وقوائم الطرازات. ثالثًا، نطاق مساحة العمل المخصص يقبل فقط مفاتيح تلك المساحة، لكن إنتاجيته وعزل حركته أفضل ويناسب الإنتاج؛ أما النطاق المشترك القديم فيسهل التنقل بين المساحات والاختبار السريع.

إذا كان الفريق يستخدم عدة طرازات ولا يريد إدارة المناطق والحصص ومجموعات المفاتيح بنفسه، فيمكنه إنشاء مفتاح موحد في بوابة ZSQH AI واستبدال Base URL بالعنوان في السطر الأخير من الجدول.

ثالثًا: كيف تختار اسم الطراز

تتحدث قائمة طرازات Model Studio بسرعة. بأخذ صفحة الطرازات الرسمية الحالية مثالًا، تضم طرازات توليد النصوص المدرجة qwen3.8-max وqwen3.7-plus وqwen3.8-flash. من التسمية يمكن الفهم التقريبي: max يميل إلى الحد الأعلى للقدرة، وplus إلى التوازن، وflash إلى التأخير والتكلفة المنخفضين؛ ويُعتمد التحديد الدقيق وطول السياق على وثائق الطرازات الرسمية، والأسعار قابلة للتعديل وتُراجع في أسعار الطرازات.

لا تنظر عند الاختيار إلى «الأقوى» وحده. مهام خدمة العملاء والتصنيف الدفعي ومراجعة المحتوى غالبًا تكون أوفر بالمستوى منخفض التأخير؛ وتحليل المستندات الطويلة والوكلاء المعقدون يحتاجان مستوى أعلى. اجعل اسم الطراز بند إعداد لا قيمة مثبتة في الشيفرة، فيسهل التبديل لاحقًا.

هناك مزلقان إضافيان. الصيغ القديمة مثل qwen-max وqwen-plus قد تكون تغيرت، فتأكد من قائمة الطرازات في لوحة التحكم قبل الربط؛ وعند الحاجة إلى قدرات متجهية استخدم سلسلة embedding مثل qwen3.7-text-embedding، فجسم طلبها يختلف عن واجهة المحادثة. ولا يدعم Qwen-Audio بروتوكول التوافق مع OpenAI، بل يحتاج واجهة DashScope الأصلية.

رابعًا: أول استدعاء عبر curl

جهّز متغير البيئة أولًا لتجنب ظهور المفتاح في سجل الأوامر:

export DASHSCOPE_API_KEY="your_key_here"

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [
      {"role": "system", "content": "أنت مساعد تقني موجز."},
      {"role": "user", "content": "اشرح ما هي بوابة API في ثلاث جمل."}
    ],
    "temperature": 0.7
  }'

عند الاستجابة الطبيعية، راجع ثلاثة حقول: choices[0].message.content هو الإجابة، وusage هو الاستخدام، وfinish_reason سبب الانتهاء. إذا عاد 401 فافحص المفتاح والمنطقة؛ وإذا عاد 404 مع ModelNotFound فافحص اسم الطراز وهل هو مفعّل في تلك المنطقة.

خامسًا: الاستدعاء بـPython SDK والإخراج المتدفق

يتطلب OpenAI SDK إصدار 1.0 أو أحدث. بعد توجيه Base URL إلى Model Studio، يكون الاستدعاء مشابهًا لـOpenAI:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

stream = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "اكتب تعريفًا لمنتج لا يتجاوز مئة كلمة."}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

في الإخراج المتدفق، قد تحمل الكتلة الأولى معلومات الدور فقط ويكون content فارغًا، فلا تفترض أن كل كتلة تحتوي نصًا؛ وبعد إضافة stream_options={"include_usage": True} يظهر الاستخدام في الكتلة الأخيرة. في HTTP المباشر تكون الاستجابة بصيغة SSE وتنتهي بـdata: [DONE]. عندما يغلق المستخدم الصفحة، ينبغي للخادم إلغاء طلب المنبع بسرعة لتجنب استمرار التوليد والفوترة.

سادسًا: استدعاء الأدوات وفروق المعاملات

يتبع استدعاء الأدوات صيغة tools وtool_choice في OpenAI. بعد أن يعيد الطراز message.tool_calls، يجب تحليل function.arguments لكل استدعاء بصيغة JSON، وتنفيذ الدالة المحلية، ثم إعادة النتيجة في رسالة بدور role: "tool". في المسارات متعددة الأدوار يجب إرسال tools مع كل دور. وفي بيئة الإنتاج يلزم التحقق من المعاملات والصلاحيات وضبط المهل، ولا يجوز الوثوق الكامل بمعاملات الطراز.

تذكر وثائق التوافق الرسمية حاليًا قيدين على الأدوات: دعمها في بعض الطرازات فقط، وعدم إمكانية استخدام tools مع stream=True مؤقتًا. تتحدث القوائم والقدرات باستمرار، لذا اختبر بالطراز المستهدف قبل الإطلاق؛ وإذا كان العمل يحتاج البث واستدعاء الأدوات معًا، فنظر في واجهة DashScope الأصلية أو اجعل استدعاء الأدوات خطوة غير متدفقة.

عند الترحيل من OpenAI، انتبه إلى فروق المعاملات التالية:

  • messages: يمكن أن يكون messages[0] فقط بدور system؛ ويجب عادةً أن يتناوب user وassistant، وأن تكون الرسالة الأخيرة من user.
  • temperature: النطاق [0, 2)، ولا يُنصح رسميًا بضبطه على 0.
  • top_p: النطاق (0, 1.0).
  • seed: عدد صحيح 64-bit غير موقّع.
  • stop: لا يجوز خلط معرّفات الرموز والنصوص في عناصر المصفوفة.
  • system_fingerprint: يعيد حاليًا سلسلة فارغة.
  • معاملات امتداد مثل enable_search: تُمرر عادةً عبر extra_body، ولا تدعمها كل الطرازات.
  • حقول مثل response_format وfrequency_penalty: لا تضمنها وثائق التوافق، فلا تفترض تطابق سلوكها مع OpenAI.

سابعًا: مقارنة الأخطاء الشائعة

العرض رمز الخطأ الشائع السبب المحتمل المعالجة
401 InvalidApiKey / invalid_api_key مفتاح خاطئ، منطقة غير مطابقة، خلط مفاتيح الخطط تحقق من منطقة المفتاح وBase URL ونوعه
404 ModelNotFound / model_not_found اسم طراز خاطئ، غير متاح في المنطقة، غير مفعّل راجع قائمة الطرازات في لوحة التحكم
404 model_not_supported الطراز لا يدعم وضع التوافق مع OpenAI استخدم واجهة DashScope الأصلية
403 AccessDenied / Workspace.AccessDenied صلاحيات مساحة أو طراز غير كافية افحص تفويض مساحة العمل
403 AllocationQuota.FreeTierOnly نفاد الحصة المجانية اشحن أو عدّل الخطة
429 سلسلة Throttling تجاوز معدل الطلبات أو الرموز أو التزامن خفّض التزامن، أعد المحاولة بتراجع، اطلب حصة
400 Arrearage متأخرات على الحساب اشحن ثم أعد المحاولة
400 Range of input length... المدخل يتجاوز حد السياق اختصر المطالبة أو قسّمها
400 DataInspectionFailed المدخل أو المخرج حجبه أمان المحتوى عدّل المحتوى ثم أعد المحاولة

إعادة المحاولة مفيدة فقط مع 429 و5xx ومهل الشبكة. أما 401 و403 و404 وأخطاء المعاملات فلا تتحسن بالإعادة، بل تهدر الوقت والحصة. سجّل Request ID من الاستجابة وابحث به في سجلات لوحة التحكم، فذلك أسرع من التخمين.

ثامنًا: قائمة التحقق للترحيل من OpenAI

  1. انسخ احتياطيًا المطالبات الحالية ومعاملات الطراز ومجموعة التقييم.
  2. أنشئ مفتاح Qwen مطابقًا للمنطقة المستهدفة، ولا تعِد استخدام مفتاح مزود آخر.
  3. حوّل Base URL واسم الطراز إلى بنود إعداد.
  4. افحص قواعد أدوار messages: system أولًا وuser أخيرًا.
  5. افحص تحليل البث وطريقة إحصاء الاستخدام.
  6. أجرِ اختبار انحدار لاستدعاء الأدوات بأدوات حقيقية.
  7. قارن جودة الإخراج والتأخير والاستخدام على العينة نفسها.
  8. اضبط إعادة المحاولة والمهلة والتزامن، وراقب أسبوعًا قبل التحويل الكامل.
  9. سجّل Request ID في السجلات، واحتفظ بمفتاح تراجع.

تاسعًا: الأسئلة الشائعة

1. هل Qwen API متوافق مع OpenAI؟

معظم واجهات المحادثة الشائعة متوافقة، لكن تبقى فروق في الارتباط الإقليمي وترتيب الأدوار ونطاقات المعاملات وقيود استدعاء الأدوات. تحقق بندًا بندًا وفق وثائق التوافق الرسمية، ولا تفترض تطابق سلوك جميع المعاملات.

2. هل يمكن استخدام مفتاح واحد في البر الرئيسي والموقع الدولي؟

لا. حسابات الموقعين والمفاتيح ونطاقات الربط والفواتير مستقلة. والاستدعاء عبر منطقة أو موقع آخر يعيد عادةً 401 وinvalid_api_key.

3. هل أستخدم النطاق القديم أم نطاق مساحة العمل المخصص؟

للاختبار السريع يمكن استخدام النطاق المشترك القديم؛ وفي الإنتاج يُفضل نطاق مساحة العمل المخصص لإنتاجية وعزل أفضل. المهم أن يتطابق المفتاح مع منطقة النطاق ومساحة العمل.

4. ما سبب model_not_found مع صحة اسم الطراز؟

الأسباب الشائعة عدم توفر الطراز في المنطقة، أو عدم تفعيله، أو اختلاف حالة الأحرف، أو الوصول إلى إصدار موقوف. يُعتمد على قائمة الطرازات الحالية في لوحة التحكم.

5. هل يمكن استخدام tools مع stream؟

تذكر وثائق التوافق الرسمية حاليًا عدم إمكانية استخدامهما معًا، وأن استدعاء الأدوات مدعوم في بعض الطرازات فقط. تتحدث القدرات والقيود مع الطرازات، لذا اختبر بالطراز المستهدف قبل الإطلاق أو استخدم واجهة DashScope الأصلية.

قراءات ذات صلة