دليل شامل لاستخدام واجهة برمجة التطبيقات GLM-5.1: أمثلة برمجية

ملخص

GLM-5.1 متاح عبر واجهة برمجة تطبيقات BigModel على https://open.bigmodel.cn/api/paas/v4/. واجهة برمجة التطبيقات متوافقة مع OpenAI: نفس بنية نقطة النهاية، ونفس تنسيق الطلب، ونفس نمط التدفق. تحتاج إلى حساب BigModel، ومفتاح API، واسم النموذج glm-5.1. يغطي هذا الدليل المصادقة، وطلبك الأول، والتدفق، واستدعاء الأدوات، واختبار تكاملك مع Apidog.

مقدمة

GLM-5.1 هو نموذج Z.AI الرائد للوكلاء، تم إصداره في أبريل 2026. يحتل المرتبة الأولى في SWE-Bench Pro ويتفوق على GLM-5 في كل معيار ترميز رئيسي. إذا كنت تقوم ببناء مساعد ترميز ذكاء اصطناعي، أو وكيل مستقل، أو أي تطبيق يستفيد من تنفيذ المهام طويلة الأمد، فإن GLM-5.1 يستحق الدمج.

الخبر السار للمطورين: واجهة برمجة التطبيقات متوافقة مع OpenAI. إذا كنت قد بنيت بالفعل على GPT-4 أو Claude، فيمكنك التبديل إلى GLM-5.1 عن طريق تغيير عنوان URL الأساسي واسم النموذج. لا يوجد SDK جديد لتعلمه. لا يوجد تنسيق استجابة مختلف للتعامل معه.

المتطلبات الأساسية

قبل إجراء مكالمتك الأولى، تحتاج إلى:

1. حساب BigModel على bigmodel.cn. التسجيل مجاني.
2. مفتاح API من لوحة تحكم BigModel ضمن "مفاتيح API".
3. Python 3.8+ أو Node.js 18+ (تغطي الأمثلة كليهما).
4. مجموعة تطوير برامج (SDK) لـ OpenAI أو requests/fetch القياسية (واجهة برمجة تطبيقات GLM-5.1 متوافقة مع OpenAI).

قم بتعيين مفتاح API الخاص بك كمتغير بيئة:

export BIGMODEL_API_KEY="your_api_key_here"

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

المصادقة

يتطلب كل طلب رمز Bearer مميزًا في رأس المصادقة (Authorization header):

Authorization: Bearer YOUR_API_KEY

يبدو تنسيق مفتاح API لـ BigModel مثل xxxxxxxx.xxxxxxxxxxxxxxxx، وهو سلسلة من جزأين مفصولين بنقطة. هذا يختلف عن تنسيق OpenAI's sk- ولكنه يعمل بنفس الطريقة في الرأس.

عنوان URL الأساسي

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

نقطة نهاية إكمال الدردشة هي:

POST https://open.bigmodel.cn/api/paas/v4/chat/completions

طلبك الأول

باستخدام curl

curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.1",
    "messages": [
      {
        "role": "user",
        "content": "Write a Python function that finds all prime numbers up to n using the Sieve of Eratosthenes."
      }
    ],
    "max_tokens": 1024,
    "temperature": 0.7
  }'

باستخدام Python (مكتبة requests)

import os
import requests

api_key = os.environ["BIGMODEL_API_KEY"]

response = requests.post(
    "https://open.bigmodel.cn/api/paas/v4/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "model": "glm-5.1",
        "messages": [
            {
                "role": "user",
                "content": "Write a Python function that finds all prime numbers up to n using the Sieve of Eratosthenes."
            }
        ],
        "max_tokens": 1024,
        "temperature": 0.7
    }
)

result = response.json()
print(result["choices"][0]["message"]["content"])

باستخدام OpenAI SDK (موصى به)

نظرًا لأن واجهة برمجة التطبيقات متوافقة مع OpenAI، يمكنك استخدام OpenAI Python SDK الرسمي مع عنوان URL أساسي مخصص:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

response = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Write a Python function that finds all prime numbers up to n using the Sieve of Eratosthenes."
        }
    ],
    max_tokens=1024,
    temperature=0.7
)

print(response.choices[0].message.content)

هذا هو الأسلوب الأكثر نظافة. يتعامل OpenAI SDK مع إعادة المحاولات، وإدارة المهلة، وتحليل الاستجابات. تحصل على كل ذلك مجانًا بمجرد توجيهه إلى عنوان URL الأساسي لـ BigModel.

تنسيق الاستجابة

هيكل الاستجابة مطابق لهيكل OpenAI:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1744000000,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def sieve_of_eratosthenes(n):\n    ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 215,
    "total_tokens": 247
  }
}

يمكن الوصول إلى نص الاستجابة عبر result["choices"][0]["message"]["content"].

يعرض حقل usage عدد الرموز المميزة للطلب. تتبع هذا لمراقبة استهلاك حصتك، حيث يتم احتساب GLM-5.1 بـ 3 أضعاف الحصة خلال ساعات الذروة (14:00-18:00 بالتوقيت العالمي المنسق +8).

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

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

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

stream = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Explain how a B-tree index works in a database, with a code example."
        }
    ],
    stream=True,
    max_tokens=2048
)

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

print()  # newline after streaming completes

كل جزء في التدفق هو دلتا تحتوي فقط على الرموز المميزة الجديدة منذ الجزء الأخير. يحتوي الجزء الأخير على finish_reason مضبوط على "stop" (أو "length" إذا وصلت إلى حد الرموز المميزة).

التدفق باستخدام طلبات خام

إذا كنت تفضل عدم استخدام OpenAI SDK:

import os
import json
import requests

api_key = os.environ["BIGMODEL_API_KEY"]

response = requests.post(
    "https://open.bigmodel.cn/api/paas/v4/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "model": "glm-5.1",
        "messages": [{"role": "user", "content": "Write a merge sort in Python."}],
        "stream": True,
        "max_tokens": 1024
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        line = line.decode("utf-8")
        if line.startswith("data: "):
            data = line[6:]
            if data == "[DONE]":
                break
            chunk = json.loads(data)
            delta = chunk["choices"][0]["delta"]
            if "content" in delta:
                print(delta["content"], end="", flush=True)

استدعاء الأدوات

يدعم GLM-5.1 استدعاء الأدوات: القدرة على طلب تنفيذ وظيفة في منتصف المحادثة. هذه هي الآلية الأساسية لسير عمل الوكلاء حيث يحتاج النموذج إلى تشغيل التعليمات البرمجية، والبحث في قواعد البيانات، واستدعاء واجهات برمجة التطبيقات الخارجية، أو اتخاذ إجراءات في العالم الحقيقي.

تعريف الأدوات

import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "run_python",
            "description": "Execute Python code and return the output. Use this to test, profile, or benchmark code.",
            "parameters": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string",
                        "description": "The Python code to execute"
                    }
                },
                "required": ["code"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Read the contents of a file",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "File path to read"
                    }
                },
                "required": ["path"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Write a function to compute Fibonacci numbers, test it for n=10, and show me the output."
        }
    ],
    tools=tools,
    tool_choice="auto"
)

message = response.choices[0].message
print(f"Finish reason: {response.choices[0].finish_reason}")

if message.tool_calls:
    for tool_call in message.tool_calls:
        print(f"\nTool called: {tool_call.function.name}")
        print(f"Arguments: {tool_call.function.arguments}")

معالجة استجابات استدعاء الأدوات

عندما يطلب GLM-5.1 استدعاء أداة، تقوم بتنفيذ الوظيفة، ثم تعيد النتيجة في الرسالة التالية:

import subprocess

def execute_tool(tool_call):
    """Execute the tool and return the result."""
    name = tool_call.function.name
    args = json.loads(tool_call.function.arguments)

    if name == "run_python":
        result = subprocess.run(
            ["python3", "-c", args["code"]],
            capture_output=True,
            text=True,
            timeout=10
        )
        return result.stdout or result.stderr

    elif name == "read_file":
        try:
            with open(args["path"]) as f:
                return f.read()
        except FileNotFoundError:
            return f"Error: file {args['path']} not found"

    return f"Unknown tool: {name}"


def run_agent_loop(user_message, tools, max_iterations=20):
    """Run a full agent loop with tool calling."""
    messages = [{"role": "user", "content": user_message}]

    for i in range(max_iterations):
        response = client.chat.completions.create(
            model="glm-5.1",
            messages=messages,
            tools=tools,
            tool_choice="auto",
            max_tokens=4096
        )

        message = response.choices[0].message
        messages.append(message.model_dump())

        if response.choices[0].finish_reason == "stop":
            # Model is done
            return message.content

        if response.choices[0].finish_reason == "tool_calls":
            # Execute each tool call and add results
            for tool_call in message.tool_calls:
                tool_result = execute_tool(tool_call)
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": tool_result
                })

    return "Max iterations reached"


result = run_agent_loop(
    "Write a quicksort implementation, test it with a random list of 1000 integers, and report the time.",
    tools
)
print(result)

يتناسب هذا النمط مباشرة مع قوة GLM-5.1 كنموذج وكيل. تترك النموذج يقرر متى يستدعي الأدوات، ويعالج النتائج، ويستمر حتى يصل إلى حل أو يقرر أنه انتهى.

المعاملات الرئيسية

الإعدادات الموصى بها لمهام الترميز:

{
    "model": "glm-5.1",
    "temperature": 1.0,
    "top_p": 0.95,
    "max_tokens": 163840  # full context for long agentic runs
}

تستخدم Z.AI هذه الإعدادات في تقييمات معاييرها الخاصة. لتوليد التعليمات البرمجية الحتمية، اخفض درجة الحرارة إلى 0.2-0.4.

استخدام GLM-5.1 مع مساعدي الترميز

تتيح لك خطة Z.AI للترميز توجيه Claude Code و Cline و Kilo Code وغيرهم من مساعدي الترميز بالذكاء الاصطناعي عبر GLM-5.1 من خلال واجهة برمجة تطبيقات BigModel. هذا مفيد إذا كنت تريد نموذج ترميز قوي بتكلفة أقل من تشغيل Claude Opus أو GPT-5.4 مباشرة.

إعداد Claude Code

في ملف تهيئة Claude Code الخاص بك (~/.claude/settings.json أو ما يعادله):

{
  "model": "glm-5.1",
  "baseURL": "https://open.bigmodel.cn/api/paas/v4/",
  "apiKey": "your_bigmodel_api_key"
}

إعداد Cline / Roo Code

في إعدادات VS Code الخاصة بك أو تهيئة إضافة Cline:

{
  "cline.apiProvider": "openai",
  "cline.openAIBaseURL": "https://open.bigmodel.cn/api/paas/v4/",
  "cline.openAIApiKey": "your_bigmodel_api_key",
  "cline.openAIModelId": "glm-5.1"
}

استهلاك الحصة

يستخدم GLM-5.1 نظام حصص Z.AI بدلاً من الفوترة لكل رمز مميز: - ساعات الذروة (14:00-18:00 بالتوقيت العالمي المنسق +8): 3 أضعاف الحصة لكل طلب - خارج أوقات الذروة: 2 أضعاف الحصة لكل طلب - سعر ترويجي حتى أبريل 2026: 1x خلال خارج أوقات الذروة

لأعباء عمل الوكلاء الثقيلة، قم بجدولة المهام طويلة الأمد لساعات خارج الذروة. يكلف تشغيل تحسين 600 تكرار مثل الذي أظهرته Z.AI حصة أكبر بكثير في أوقات الذروة.

اختبار واجهة برمجة تطبيقات GLM-5.1 باستخدام Apidog

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

تتيح لك ميزة Smart Mock في Apidog تحديد كل حالات الاستجابة هذه واختبارها دون الوصول إلى واجهة برمجة التطبيقات الحقيقية.

إعداد نقطة نهاية المحاكاة

1. في Apidog، قم بإنشاء نقطة نهاية جديدة: POST https://open.bigmodel.cn/api/paas/v4/chat/completions
2. أضف توقع محاكاة لاستجابة نجاح قياسية:

{
  "id": "chatcmpl-test123",
  "object": "chat.completion",
  "created": 1744000000,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def sieve(n): ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 120,
    "total_tokens": 152
  }
}

1. أضف توقعًا ثانيًا لاستجابة استدعاء أداة:

{
  "id": "chatcmpl-tool456",
  "object": "chat.completion",
  "created": 1744000001,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc",
            "type": "function",
            "function": {
              "name": "run_python",
              "arguments": "{\"code\": \"print(2+2)\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 35,
    "total_tokens": 83
  }
}

1. أضف استجابة حد المعدل (HTTP 429):

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

اختبار حلقة الوكيل الكاملة

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

1. الخطوة 1: أرسل POST إلى /chat/completions برسالتك الأولية، وتأكد من استجابة 200 و finish_reason == "tool_calls"
2. الخطوة 2: أرسل POST مرة أخرى مع نتيجة الأداة في مصفوفة الرسائل، وتأكد من استجابة 200 و finish_reason == "stop"
3. الخطوة 3: استخرج المحتوى النهائي وتأكد من أنه يحتوي على التعليمات البرمجية المتوقعة

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

لسير عمل الوكلاء متعدد الخطوات، تتيح لك سيناريوهات اختبار Apidog تمرير البيانات بين الخطوات باستخدام المتغيرات، بحيث تتدفق قيم request_id أو tool_call_id من الخطوة 1 تلقائيًا إلى الخطوة 2. هذا يعكس كيفية عمل حلقة وكيل حقيقية ويكشف أخطاء التكامل قبل الإنتاج.

معالجة الأخطاء

تُرجع واجهة برمجة التطبيقات رموز حالة HTTP القياسية:

import time
import requests

def call_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "https://open.bigmodel.cn/api/paas/v4/chat/completions",
                headers={"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}",
                         "Content-Type": "application/json"},
                json=payload,
                timeout=120
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", 60))
                print(f"Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.Timeout:
            wait = 2 ** attempt
            print(f"Timeout on attempt {attempt + 1}. Retrying in {wait}s...")
            time.sleep(wait)

    raise Exception("Max retries exceeded")

بالنسبة لتشغيل الوكلاء لفترة طويلة حيث يمكن أن تستغرق الخطوات الفردية من 30 إلى 60 ثانية، قم دائمًا بتعيين مهلة سخية (120-300 ثانية). قد يحتاج النموذج إلى وقت لإنشاء ملف تعليمات برمجية كامل أو تحليل نتيجة معيار معقد.

الخلاصة

تعني واجهة برمجة تطبيقات GLM-5.1 المتوافقة مع OpenAI أنه يمكنك دمجها في دقائق إذا كنت قد عملت بالفعل مع GPT أو Claude. الفرق الرئيسي هو نقطة النهاية (open.bigmodel.cn) ونظام الحصص بدلاً من الفوترة لكل رمز مميز.

بالنسبة لتطبيقات الوكلاء حيث يقوم النموذج بتشغيل مئات استدعاءات الأدوات على مدار جلسة طويلة، تعد قدرة GLM-5.1 على تحسين الأفق الطويل ميزة حقيقية. قم بإقرانها بالاختبار المناسب عبر Smart Mock وسيناريوهات الاختبار في Apidog للتأكد من أن تكاملك يتعامل مع جميع الحالات الهامشية قبل تشغيله بدون إشراف.

للحصول على معلومات أساسية حول ماهية GLM-5.1 وكيفية مقارنة معاييره، راجع نظرة عامة على نموذج GLM-5.1. لمزيد من المعلومات حول بناء واختبار سير عمل وكيل الذكاء الاصطناعي باستخدام Apidog، راجع كيف تعمل ذاكرة وكيل الذكاء الاصطناعي.

الأسئلة الشائعة

هل واجهة برمجة تطبيقات GLM-5.1 متوافقة مع OpenAI؟نعم. تنسيق الطلب، وبنية الاستجابة، وبروتوكول التدفق، وتنسيق استدعاء الأدوات كلها مطابقة لواجهة برمجة تطبيقات إكمال الدردشة الخاصة بـ OpenAI. يمكنك استخدام OpenAI Python SDK الرسمي أو أي عميل متوافق مع OpenAI عن طريق تعيين عنوان URL الأساسي إلى https://open.bigmodel.cn/api/paas/v4/.

ما هو اسم النموذج الذي يجب استخدامه في طلبات API؟استخدم "glm-5.1" كاسم للنموذج. لا تستخدم اسمًا كاملاً مُرقّمًا بالإصدار؛ فقط glm-5.1 يعمل.

كيف تعمل تسعيرة واجهة برمجة تطبيقات GLM-5.1؟تستخدم واجهة برمجة تطبيقات BigModel نظام حصص. يستهلك GLM-5.1 3 أضعاف الحصة خلال ساعات الذروة (14:00-18:00 بالتوقيت العالمي المنسق +8) و 2 أضعاف خلال ساعات خارج الذروة. حتى نهاية أبريل 2026، يتم احتساب الاستخدام خارج أوقات الذروة بـ 1x حصة كسعر ترويجي.

ما هو الحد الأقصى لطول السياق؟200,000 رمز مميز لسياق الإدخال. الحد الأقصى للإخراج هو 163,840 رمزًا مميزًا. لتشغيل الوكلاء لفترة طويلة، اضبط max_tokens على قيمة كبيرة (32,768 أو أعلى) لتجنب اقتطاع إخراج النموذج في منتصف المهمة.

هل يمكنني استخدام GLM-5.1 لاستدعاء الوظائف / استخدام الأدوات؟نعم. يدعم GLM-5.1 نفس تنسيق استدعاء الأدوات مثل واجهة برمجة تطبيقات OpenAI. قم بتعريف الأدوات بمخطط type: "function"، وقم بتمريرها في مصفوفة tools، وتعامل مع استجابات finish_reason: "tool_calls" في حلقة وكيلك.

كيف يمكنني اختبار استدعاءات GLM-5.1 API دون استهلاك الحصة؟استخدم Smart Mock في Apidog لتعريف استجابات وهمية لكل حالة من حالات API: النجاح، استدعاءات الأدوات، حدود المعدل، الأخطاء. قم بتشغيل مجموعة الاختبار الخاصة بك مقابل المحاكاة أثناء التطوير واستخدم واجهة برمجة التطبيقات الحقيقية فقط للتحقق النهائي.

أين يمكنني العثور على أوزان نموذج GLM-5.1؟توجد الأوزان مفتوحة المصدر على HuggingFace في zai-org/GLM-5.1. تم إصدارها بموجب ترخيص MIT وتدعم vLLM و SGLang للاستدلال المحلي.