DEV Community

Cover image for كيفية استخدام Qwen 3.7 API؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام Qwen 3.7 API؟

أصدر فريق Qwen التابع لـ Alibaba نموذج Qwen3.7-Max-Preview في منتصف مايو 2026، وبدأ السؤال العملي للمطورين مباشرة: كيف أستدعيه من الكود؟ النموذج مخصص للاستنتاج، ويدعم نافذة سياق بحجم مليون رمز، مع تتبع صريح لسلسلة التفكير، ما يجعله مناسبًا للوكلاء، وتحليل المستندات الطويلة، وتوليد الكود. لكن لأنه إصدار Preview، فالوصول مقيد، وواجهة API ما زالت في طور الاستقرار، لذلك تحتاج إلى التحقق من معرف النموذج ونقطة النهاية قبل الاعتماد عليه في الإنتاج.

جرّب Apidog اليوم

الخلاصة

Qwen3.7-Max-Preview هو نموذج الاستنتاج الرائد من Alibaba، صدر كمعاينة في 14 مايو 2026، مع نافذة سياق بحجم مليون رمز. أثناء فترة المعاينة، أسهل طريقة للتجربة هي Qwen Chat على chat.qwen.ai. أما التكامل البرمجي فيتم عادة عبر Alibaba Cloud Model Studio أو DashScope باستخدام نقطة نهاية متوافقة مع OpenAI: تضبط base_url، تمرر مفتاح API كـ Bearer token، ثم تستدعي /chat/completions.

بما أن مستوى 3.7 ما زال Preview، تحقق دائمًا من معرف النموذج ونقطة النهاية في الوثائق الرسمية قبل التشغيل. يمكنك استخدام Apidog لاختبار الطلبات ومحاكاة نقطة النهاية أثناء انتظار توفر API أو استقرارها.

كيفية الوصول إلى Qwen 3.7 الآن

تتوفر نماذج Qwen عبر أكثر من واجهة، وليس بالضرورة أن تتوفر جميعها في الوقت نفسه. اعتبارًا من أواخر مايو 2026، هذا هو المسار العملي للوصول.

1. Qwen Chat

استخدم chat.qwen.ai إذا أردت تجربة النموذج بسرعة بدون كود.

الخطوات:

  1. سجّل الدخول بحساب Qwen مجاني.
  2. اختر qwen3.7-max-preview من محدد النماذج.
  3. فعّل Thinking Mode إذا أردت رؤية تتبع الاستنتاج.
  4. اختبر المطالبات قبل نقلها إلى الكود.

هذه الطريقة مناسبة لتقييم النموذج وضبط المطالبات، لكنها ليست API ولا تصلح للتكامل المباشر داخل تطبيقك.

2. Alibaba Cloud Model Studio / DashScope

هذا هو المسار المناسب للتكامل البرمجي. يعرض Model Studio نماذج Qwen عبر نقطة نهاية متوافقة مع OpenAI، لذلك يمكنك استخدام OpenAI SDK مع تغيير base_url والمفتاح فقط.

النماذج الأقدم مثل qwen3.6-max-preview وعائلة qwen-max متوفرة عبر Model Studio. قد لا يكون qwen3.7-max-preview متاحًا كـ API عامة عند قراءتك لهذا المقال، لأن Qwen عادة يفتح الوصول البرمجي بعد فترة من معاينة الدردشة.

واجهة Alibaba Cloud Model Studio

3. النمط المتوافق مع OpenAI

النمط المتوقع لطلب Qwen عبر Model Studio هو:

POST {base_url}/chat/completions
Authorization: Bearer {DASHSCOPE_API_KEY}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

مع جسم طلب يحتوي على:

{
  "model": "qwen3.7-max-preview",
  "messages": [
    {
      "role": "user",
      "content": "اكتب ملخصًا تقنيًا قصيرًا عن..."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

تعامل مع وثائق Qwen الرسمية وقائمة نماذج Model Studio كمصدر موثوق لمعرف النموذج ونقطة النهاية. وإذا أردت التجربة مجانًا أثناء انتظار API، راجع دليلنا حول كيفية استخدام Qwen 3.7 مجانًا.

طرق الوصول في لمحة

الطريقة الوصول إلى API التكلفة الأفضل لـ
Qwen Chat (chat.qwen.ai) لا مجاني، محدود المعدل التقييم السريع واختبار المطالبات
Alibaba Cloud Model Studio / DashScope نعم، متوافق مع OpenAI الدفع حسب الرمز التكامل البرمجي والإنتاج
Qwen على Hugging Face الأوزان عند الإصدار مجاني مع استضافة ذاتية النماذج مفتوحة الوزن، وليس Max Preview
بوابات الطرف الثالث يختلف يختلف توجيه الطلبات بين عدة نماذج

ملاحظة مهمة: نماذج Qwen مفتوحة الوزن قد تصل إلى Hugging Face، لكن مستوى Max-Preview خاص ومغلق، لذلك لا تتوقع توفر أوزان قابلة للتنزيل لـ qwen3.7-max-preview.

الحصول على مفتاح API لـ Qwen 3.7

يتم الوصول إلى API عبر حساب Alibaba Cloud.

الخطوات العملية:

  1. أنشئ حساب Alibaba Cloud.
  2. افتح لوحة Model Studio: 
   modelstudio.console.alibabacloud.com
Enter fullscreen mode Exit fullscreen mode
  1. فعّل Model Studio لحسابك والمنطقة المطلوبة.
  2. افتح قسم مفاتيح API.
  3. أنشئ مفتاحًا جديدًا.
  4. انسخ المفتاح مرة واحدة واحفظه كسر.

تبدو المفاتيح عادة مثل:

sk-xxxxxxxxxxxxxxxx
Enter fullscreen mode Exit fullscreen mode

انتبه إلى أن المفاتيح مرتبطة بالمنطقة. مفتاح خاص بنقطة نهاية سنغافورة لن يعمل بالضرورة ضد نقطة نهاية بكين.

اختيار عنوان URL الأساسي حسب المنطقة

المنطقة عنوان URL الأساسي
سنغافورة https://dashscope-intl.aliyuncs.com/compatible-mode/v1
الولايات المتحدة، فرجينيا https://dashscope-us.aliyuncs.com/compatible-mode/v1
بكين، الصين https://dashscope.aliyuncs.com/compatible-mode/v1

لا تضع المفتاح مباشرة داخل الكود. استخدم متغير بيئة.

# macOS / Linux
export DASHSCOPE_API_KEY="sk-your-key-here"

# Windows PowerShell
setx DASHSCOPE_API_KEY "sk-your-key-here"
Enter fullscreen mode Exit fullscreen mode

ثم اقرأه داخل التطبيق وقت التشغيل. هذا يمنع تسريب المفتاح في Git ويسهل تدويره لاحقًا. ينطبق النمط نفسه على واجهات نماذج أخرى مثل واجهة برمجة تطبيقات Gemini 3.5.

طلبك الأول: Python و curl و JavaScript

نقطة نهاية Qwen على Model Studio متوافقة مع OpenAI. يمكنك إما استخدام OpenAI SDK أو إرسال HTTP خام.

ملاحظة: استخدم qwen3.7-max-preview هنا كمعرف للنموذج في المعاينة. قد تختلف السلسلة المطلوبة في API أثناء فترة Preview، وقد يكون المتاح لديك هو مستوى أقدم مثل qwen3.6-max-preview. تحقق من قائمة نماذج Model Studio قبل التشغيل.

Python مع OpenAI SDK

ثبّت الحزمة:

pip install openai
Enter fullscreen mode Exit fullscreen mode

ثم أرسل الطلب:

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="qwen3.7-max-preview",
    messages=[
        {"role": "system", "content": "أنت مساعد برمجة دقيق."},
        {"role": "user", "content": "اكتب دالة بايثون تعكس قائمة مرتبطة."},
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

هيكل الطلب يعتمد على مصفوفة messages:

  • system: يحدد سلوك النموذج.
  • user: يحتوي على طلب المستخدم.
  • الاستجابة النصية موجودة في: 
  response.choices[0].message.content
Enter fullscreen mode Exit fullscreen mode

curl

استخدم curl للتحقق السريع من المفتاح ونقطة النهاية قبل كتابة كود التطبيق:

curl 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen3.7-max-preview",
    "messages": [
      {
        "role": "user",
        "content": "اشرح مفهوم الـ Idempotency في واجهات برمجة تطبيقات REST في جملتين."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

إذا كان المفتاح ومعرف النموذج صحيحين، ستحصل على JSON يحتوي على الإكمال. إذا ظهر خطأ، راجع كود الحالة ورسالة الخطأ.

JavaScript / Node.js

ثبّت SDK:

npm install openai
Enter fullscreen mode Exit fullscreen mode

ثم استخدمه بهذا الشكل:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
});

const response = await client.chat.completions.create({
  model: "qwen3.7-max-preview",
  messages: [
    {
      role: "user",
      content: "اذكر ثلاثة مفاضلات لـ GraphQL مقارنة بـ REST.",
    },
  ],
});

console.log(response.choices[0].message.content);
Enter fullscreen mode Exit fullscreen mode

الميزة هنا أن شكل الطلب واحد تقريبًا عبر Python وNode وHTTP الخام.

الاستجابات المتدفقة

في التطبيقات التي تواجه المستخدم، لا تنتظر اكتمال الاستجابة كاملة. استخدم Streaming لعرض الرموز فور توليدها.

في Python:

stream = client.chat.completions.create(
    model="qwen3.7-max-preview",
    messages=[
        {"role": "user", "content": "لخص نظرية CAP."},
    ],
    stream=True,
)

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

في Node.js:

const stream = await client.chat.completions.create({
  model: "qwen3.7-max-preview",
  messages: [
    {
      role: "user",
      content: "لخص نظرية CAP.",
    },
  ],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}
Enter fullscreen mode Exit fullscreen mode

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

معامل الاستنتاج والتفكير

Qwen3.7-Max-Preview نموذج استنتاجي. يمكنه إنتاج تتبع تفكير داخل كتل مثل:

<think>
...
</think>
Enter fullscreen mode Exit fullscreen mode

هذا مفيد عند حل مسائل متعددة الخطوات أو تحليل كود معقد. لكنه يضيف تكلفة زمنية وتكلفة رموز.

في نماذج Qwen الحديثة عبر DashScope، يتم التحكم غالبًا في سلوك التفكير باستخدام معامل مثل enable_thinking. تحقق من الاسم الصحيح في مرجع API الحالي قبل الاعتماد عليه.

مثال مفاهيمي:

response = client.chat.completions.create(
    model="qwen3.7-max-preview",
    messages=[
        {
            "role": "user",
            "content": (
                "يغادر قطار في الساعة 2 ظهرًا بمتوسط سرعة 60 ميلاً في الساعة. "
                "يغادر قطار ثانٍ في الساعة 3 ظهرًا بسرعة 75 ميلاً في الساعة على نفس المسار. "
                "متى يلحق القطار الثاني بالأول؟"
            ),
        },
    ],
    extra_body={
        "enable_thinking": True
    },
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

استخدم التفكير بهذه القواعد:

  • فعّله للمسائل متعددة الخطوات، التخطيط، التحليل، وتصحيح الكود.
  • عطّله للمهام البسيطة مثل التنسيق أو التصنيف السريع.
  • قرر هل ستعرض محتوى <think> للمستخدم أم ستزيله وتعرض الإجابة النهائية فقط.
  • راقب عدد الرموز لأن تتبع التفكير يُحسب ضمن الإخراج.

إذا كنت تقارن الجودة والتكلفة مع نماذج أخرى، راجع مقارنة Qwen 3.7 مقابل GPT-5.5 مقابل Opus 4.7. وإذا كنت تستخدم النموذج داخل وكلاء، فاقرأ أيضًا كيفية تقليل تكاليف رموز الوكيل.

معالجة الأخطاء وحدود المعدل

تعامل مع أخطاء API صراحة بدلًا من ترك التطبيق يفشل بصمت.

حالة HTTP المعنى ما يجب فعله
400 طلب غير صالح، JSON خاطئ، أو معامل غير مدعوم أصلح جسم الطلب وتحقق من أسماء الحقول
401 مفتاح API مفقود أو غير صالح تحقق من المفتاح ومن مطابقته للمنطقة
403 لا تملك وصولًا إلى النموذج تأكد من تفعيل الحساب أو صلاحية الوصول للمعاينة
404 النموذج غير موجود تحقق من معرف النموذج والمنطقة
429 تجاوز حد المعدل أو الحصة استخدم تراجعًا أسيًا وأعد المحاولة
500 / 503 خطأ من الخادم أعد المحاولة مع تراجع أسي

نماذج Preview قد تعيد 403 أو 404 أكثر من النماذج المستقرة، لأن الوصول مقيد والمعرفات قد تتغير. في هذه الحالة، غالبًا المشكلة ليست في الكود بل في الصلاحية أو اسم النموذج.

مثال Python للتعامل مع إعادة المحاولة:

import os
import time
from openai import OpenAI, RateLimitError, APIStatusError

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

def ask_qwen(prompt, max_retries=4):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="qwen3.7-max-preview",
                messages=[
                    {
                        "role": "user",
                        "content": prompt,
                    }
                ],
            )
            return response.choices[0].message.content

        except RateLimitError:
            wait = 2 ** attempt
            print(f"تم تجاوز حد المعدل. إعادة المحاولة في {wait} ثوانٍ...")
            time.sleep(wait)

        except APIStatusError as e:
            print(f"خطأ API {e.status_code}: {e.message}")
            raise

    raise RuntimeError("فشل الطلب بعد عدة محاولات")
Enter fullscreen mode Exit fullscreen mode

القاعدة العملية:

  • أعد المحاولة عند 429 و5xx.
  • افشل بسرعة عند 400 و401 و403 و404.
  • لا تعيد إرسال طلبات غير صالحة لأنها لن تنجح بمجرد الانتظار.

اختبار ومحاكاة واجهة Qwen باستخدام Apidog

عندما يكون النموذج في وضع Preview، يصبح الاختبار المباشر مرهقًا: وصول مقيد، معرف نموذج قد يتغير، وحدود معدل ضيقة. بدلًا من تشغيل التطبيق كاملًا وقراءة السجلات، استخدم أداة API لإرسال الطلبات وحفظها وإعادة تشغيلها.

Apidog مناسب لهذه الدورة.

اختبار واجهة API في Apidog

سير عمل عملي

  1. أنشئ مشروعًا جديدًا في Apidog.
  2. أضف طلبًا: 
   POST https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode
  1. أضف الهيدر: 
   Authorization: Bearer {{DASHSCOPE_API_KEY}}
   Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode
  1. أضف جسم الطلب: 
   {
     "model": "qwen3.7-max-preview",
     "messages": [
       {
         "role": "user",
         "content": "اشرح الفرق بين REST وGraphQL باختصار."
       }
     ]
   }
Enter fullscreen mode Exit fullscreen mode
  1. خزّن المفتاح كمتغير بيئة داخل Apidog بدلًا من وضعه في الطلب مباشرة.
  2. نفّذ الطلب واحفظ الاستجابة.
  3. أنشئ حالات اختبار مختلفة للمطالبات، والتدفق، والأخطاء المتوقعة.

محاكاة نقطة النهاية أثناء التطوير

أهم استخدام أثناء فترة Preview هو Mocking. يمكنك إنشاء خادم محاكاة في Apidog يعيد استجابات واقعية بناءً على مخطط API بدون مفتاح وبدون حدود معدل.

هذا مفيد عندما:

  • لا تملك وصولًا بعد إلى qwen3.7-max-preview.
  • نقطة النهاية غير مستقرة.
  • فريق الواجهة الأمامية يحتاج إلى التطوير قبل توفر API.
  • تريد اختبار حالات الخطأ مثل 429 أو 403.

عندما تصبح API الحقيقية جاهزة، غيّر base_url من خادم المحاكاة إلى DashScope، واترك شكل الطلب كما هو. لمعرفة المزيد عن سير العمل المعتمد على المخطط، راجع دليل الوضع المعتمد على المواصفات في Apidog.

ينطبق النمط نفسه على نماذج أخرى مثل Qwen وGemini وواجهة برمجة تطبيقات ERNIE 5.1.

الخلاصة

استدعاء Qwen 3.7 من الكود مباشر إذا كان لديك مفتاح API، ونقطة نهاية صحيحة، ومعرف نموذج متاح لحسابك. الجزء الصعب هو أن النموذج ما زال في وضع Preview، لذلك يجب أن تبني التكامل بطريقة قابلة للتغيير: اجعل model وbase_url إعدادات خارجية، استخدم متغيرات بيئة للمفاتيح، أضف معالجة أخطاء واضحة، واختبر الطلبات خارج تطبيقك قبل دمجها.

يمكنك تنزيل Apidog لتصميم نقطة نهاية Qwen، إرسال طلبات اختبار، حفظ السيناريوهات، ومحاكاة API أثناء التطوير.

Top comments (0)