تكلفة ربط GLM API أقل مما يتصور كثيرون: فهي توفر واجهة متوافقة مع OpenAI، ويحتاج OpenAI SDK غالبًا إلى تغيير ثلاثة أشياء فقط: مفتاح API وBase URL واسم الطراز. المزالق الحقيقية ليست في «هل يعمل الاستدعاء»، بل في صلاحية اسم الطراز، وكيفية معالجة البث، وبنسخة استدعاء الأدوات، وأي المعاملات لا يمكن نسخها كما هي عند الترحيل من OpenAI.

تشغّل هذه المقالة المسار بأصغر طلب، ثم تضيف البث واستدعاء الأدوات وتشخيص الأخطاء وقائمة الترحيل. جميع الأمثلة قابلة للتشغيل بعد استبدال المفتاح.

ملاحظة: Zhipu وGLM وBigModel علامات تجارية مملوكة لأصحابها، وهذه المقالة للشرح التقني فقط، ولا توجد بينها وبين Zhipu علاقة تبعية أو وكالة أو ترخيص. قد تتغير Base URL وأسماء الطرازات وأطوال السياق ومعايير الفوترة، فيُعتمد على وثائق منصة Zhipu الرسمية وأسعار الطرازات داخل الموقع.

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

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

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

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

ثانيًا: كيف تكتب Base URL

غالبًا يُكتب Base URL لواجهة Zhipu الرسمية المتوافقة مع OpenAI بالشكل التالي:

https://open.bigmodel.cn/api/paas/v4

وعنوان بوابة ZSQH AI المتوافق مع OpenAI هو:

https://ai.zhongshangqihang.com/v1

يُضاف إلى كليهما مسار OpenAI /chat/completions. لا تكرر مقطع الإصدار أو /chat/completions في الشيفرة، ولا تخلط بين صيغتي الكتابة بإضافة شرطة مائلة أو حذفها في النهاية.

طريقة الربط مثال Base URL السيناريو المناسب ملاحظة
Zhipu الرسمي https://open.bigmodel.cn/api/paas/v4 استخدام GLM وحده والحصول على أحدث الميزات يحتاج حسابًا رسميًا ورصيدًا
بوابة ZSQH https://ai.zhongshangqihang.com/v1 مدخل موحد لعدة طرازات وفاتورة موحدة يتطلب إنشاء مفتاح في البوابة

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

تنقسم سلسلة GLM حسب القدرة إلى النصوص والرؤية والصوت والمتجهات. وداخل طرازات النصوص توجد مستويات مختلفة: بعضها يميل للمحادثة العامة والوكلاء، وبعضها للتأخير المنخفض والتزامن العالي، وبعضها لسياق أطول. بأخذ سلسلة GLM-5 المدرجة حاليًا في الوثائق مثالًا، تشمل الصيغ الشائعة glm-5.3 وglm-5.3-flash وglm-5.2، لكن الطرازات تتحدث باستمرار، والأسماء المتاحة فعليًا تُعتمد على لوحة التحكم وأسعار الطرازات.

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

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

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

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

export GLM_API_KEY="your_key_here"

curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $GLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [
      {"role": "system", "content": "أنت مساعد تقني موجز."},
      {"role": "user", "content": "اشرح ما هي بوابة API في ثلاث جمل."}
    ],
    "temperature": 0.6
  }'

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

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

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

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("GLM_API_KEY"),
    base_url="https://open.bigmodel.cn/api/paas/v4",
)

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

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

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

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

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

عند الترحيل من OpenAI، انتبه إلى فروق عدة: نطاق temperature عادةً بين 0 و1، وقد لا يؤثر تمرير 0؛ والقيمة الافتراضية نحو 0.6؛ وبعض الميزات الجديدة تُمرر عبر extra_body. تُعتمد المعاملات على وثائق التوافق الرسمية مع OpenAI.

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

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

العرض السبب المحتمل المعالجة
401 / 1000 مفتاح خاطئ أو نوع غير مطابق تحقق من نوع المفتاح والترويسة
1211 اسم الطراز غير موجود أو غير مفعّل راجع الطرازات المتاحة في لوحة التحكم
1261 المدخل يتجاوز حد السياق اختصر المطالبة أو قسّمها
1302 / 1305 حد على الحساب أو ازدحام المنصة خفّض التزامن وأعد المحاولة بتراجع
1113 متأخرات على الحساب اشحن ثم أعد المحاولة
مهلة الاتصال DNS أو وكيل أو مسار الشبكة استخدم curl أولًا لتحديد طبقة الشبكة

إعادة المحاولة مفيدة فقط مع 429 و5xx ومهل الشبكة. أما 401 و1211 و1261 فلا تتحسن بالإعادة، بل تهدر الوقت والحصة.

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

  1. انسخ احتياطيًا المطالبات الحالية ومعاملات الطراز ومجموعة التقييم.
  2. أنشئ مفتاحًا خاصًا بـGLM، ولا تعِد استخدام مفتاح مزود آخر.
  3. حوّل Base URL واسم الطراز إلى بنود إعداد.
  4. قارن جودة الإخراج والتأخير والاستخدام على العينة نفسها.
  5. افحص توافق تحليل البث واستدعاء الأدوات وإخراج JSON.
  6. اضبط إعادة المحاولة والمهلة والتزامن، وراقب أسبوعًا قبل التحويل الكامل.

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

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

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

2. هل أضيف شرطة مائلة في نهاية Base URL؟

ظهرت في الوثائق الرسمية صيغتان، بشرطة ودونها، ويتعامل SDK معها عادةً. المهم ألا تكرر المسار، وأن تختار صيغة واحدة وتوحدها في المشروع.

3. هل يمكن الحصول على مسار التفكير في البث؟

تعيد بعض الطرازات reasoning_content في وضع التفكير. يعتمد عرضه على تصميم المنتج، ويُعرض عادةً للمستخدم النهائي الإجابة النهائية فقط.

4. هل استدعاء الأدوات مطابق لصيغة OpenAI؟

تعريف الأدوات وبنية الإرجاع تتبع صيغة OpenAI أساسًا، لكن تفاصيل المعاملات قد تتغير حسب الطراز. أجرِ اختبار انحدار بأدوات حقيقية قبل الإطلاق.

5. هل أسماء الطرازات متطابقة بين الموقع الرسمي والبوابة؟

في معظم الحالات تُستخدم الأسماء نفسها، لكن تفعيل طراز معين أو دعم معامل معين في البوابة يُعتمد على لوحة تحكم البوابة وأسعار الطرازات.

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