ملخص
GLM-5.1 متاح عبر واجهة برمجة تطبيقات BigModel على
https://open.bigmodel.cn/api/paas/v4/.
الواجهة متوافقة مع OpenAI: نفس بنية نقطة النهاية، ونفس تنسيق الطلب، ونفس نمط التدفق.
ستحتاج إلى حساب BigModel، مفتاح API، واسم النموذج glm-5.1.
يغطي هذا الدليل: المصادقة، طلبك الأول، التدفق، استدعاء الأدوات، واختبار التكامل مع Apidog.
مقدمة
GLM-5.1 هو نموذج Z.AI الرائد للوكلاء، تم إصداره في أبريل 2026. يتفوق على GLM-5 في جميع معايير الترميز الرئيسية. إذا كنت تبني مساعد ترميز ذكاء اصطناعي، وكيل مستقل، أو أي تطبيق يعتمد على تنفيذ المهام طويلة الأمد، فإن GLM-5.1 خيار قوي للدمج.
ميزة رئيسية للمطورين: واجهة برمجة التطبيقات متوافقة مع OpenAI. إذا كنت قد استخدمت GPT-4 أو Claude، يمكنك التبديل إلى GLM-5.1 فقط بتغيير عنوان URL الأساسي واسم النموذج. لا حاجة لتعلم SDK أو تنسيقات جديدة.
💡 التحدي الرئيسي مع واجهات برمجة تطبيقات الوكلاء هو الاختبار. من الصعب اختبار نموذج ينفّذ مئات استدعاءات الأدوات على مدار عدة دقائق مقابل API حقيقي دون استنزاف الحصة. تحل سيناريوهات اختبار Apidog هذه المشكلة: يمكنك تحديد تسلسل الطلبات، محاكاة الاستجابات، والتحقق من أن تكاملك يتعامل مع التدفق واستدعاءات الأدوات والأخطاء قبل الإنتاج.
استخدم Apidog لمتابعة قسم الاختبار في هذا الدليل.
المتطلبات الأساسية
قبل إجراء مكالمتك الأولى، تحتاج إلى:
- حساب BigModel على bigmodel.cn (التسجيل مجاني).
- مفتاح API من لوحة تحكم BigModel ضمن "مفاتيح API".
- Python 3.8+ أو Node.js 18+ (كل الأمثلة مغطاة).
- SDK لـ OpenAI أو استخدام مكتبة
requestsأوfetch(لأن API متوافقة مع OpenAI).
قم بتعيين مفتاح API كمتغير بيئة:
export BIGMODEL_API_KEY="your_api_key_here"
لا تقم أبدًا بتضمين مفاتيح API في كودك المصدر.
المصادقة
كل طلب يتطلب رأس Authorization من نوع Bearer:
Authorization: Bearer YOUR_API_KEY
مفتاح API لـ BigModel يكون بالشكل xxxxxxxx.xxxxxxxxxxxxxxxx. يختلف عن صيغة OpenAI (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 (موصى به)
نظرًا لأن API متوافقة مع 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:
{
"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 UTC+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() # بعد انتهاء التدفق
كل جزء هو Delta يحتوي فقط على الرموز المميزة الجديدة. الأخير يحتوي على 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 يدعم استدعاء الأدوات (function calling) بنفس نمط OpenAI، مما يسمح للنموذج بطلب تنفيذ وظائف أثناء المحادثة.
تعريف الأدوات
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}")
معالجة استجابات استدعاء الأدوات
عند طلب استدعاء أداة، نفّذ الوظيفة وأعد النتيجة في الرسالة التالية:
import subprocess
def execute_tool(tool_call):
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):
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":
return message.content
if response.choices[0].finish_reason == "tool_calls":
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)
النمط أعلاه يمكّن النموذج من قيادة التدفق، تنفيذ الأدوات، ومعالجة النتائج تلقائيًا حتى الوصول للحل النهائي.
المعاملات الرئيسية
| المعامل | النوع | الافتراضي | الوصف |
|---|---|---|---|
model |
سلسلة نصية | مطلوب | استخدم "glm-5.1"
|
messages |
مصفوفة | مطلوب | سجل المحادثة |
max_tokens |
عدد صحيح | 1024 | أقصى عدد رموز مميزة للإخراج (حتى 163,840) |
temperature |
عائم | 0.95 | العشوائية: الأقل = أكثر حتمية (0.0-1.0) |
top_p |
عائم | 0.7 | أخذ عينات النواة (توصية Z.AI = 0.7 للترميز) |
stream |
منطقي | خطأ | تفعيل تدفق الاستجابات |
tools |
مصفوفة | لا شيء | تعريف الأدوات لاستدعاء الوظائف |
tool_choice |
سلسلة/كائن | "تلقائي" | "تلقائي"، "لا شيء"، أو أداة محددة |
stop |
سلسلة/مصفوفة | لا شيء | تسلسلات إيقاف مخصصة |
الإعدادات الموصى بها لمهام الترميز:
{
"model": "glm-5.1",
"temperature": 1.0,
"top_p": 0.95,
"max_tokens": 163840 # سياق كامل للمهام الطويلة
}
لإخراج برمجي حتمي: خفض درجة الحرارة إلى 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 UTC+8): 3 أضعاف الحصة لكل طلب.
- خارج أوقات الذروة: 2 أضعاف الحصة لكل طلب.
- حتى أبريل 2026: 1x خارج أوقات الذروة كسعر ترويجي.
للمهام الطويلة، جدولة التنفيذ خارج ساعات الذروة لتقليل الكلفة.
اختبار واجهة برمجة تطبيقات GLM-5.1 باستخدام Apidog
اختبار تكامل واجهة API لوكيل يتطلب التعامل مع أنواع استجابات متعددة: الإكمال العادي، أجزاء التدفق، استدعاء الأدوات، رسائل النتائج، والأخطاء.
الاختبار المباشر يستهلك الحصة ويتطلب اتصال فعلي.
ميزة Smart Mock في Apidog تسمح لك بتعريف كل هذه الحالات واختبارها محليًا.
إعداد نقطة نهاية المحاكاة
- في Apidog، أنشئ نقطة نهاية جديدة:
POST https://open.bigmodel.cn/api/paas/v4/chat/completions - أضف استجابة محاكاة ناجحة:
{
"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
}
}
- أضف استجابة استدعاء أداة:
{
"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
}
}
- أضف استجابة حد المعدل (HTTP 429):
{
"error": {
"message": "Rate limit exceeded. Please retry after 60 seconds.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}
اختبار حلقة الوكيل الكاملة
استخدم سيناريوهات اختبار Apidog لربط طلبات متعددة:
-
الخطوة 1: أرسل POST إلى
/chat/completionsبرسالتك الأولية، تحقق أن الاستجابة200وfinish_reason == "tool_calls". -
الخطوة 2: أرسل POST مع نتيجة الأداة ضمن الـmessages، تحقق من
finish_reason == "stop". - الخطوة 3: استخرج المحتوى النهائي وتأكد أنه يحتوي على الكود المطلوب.
بهذا تختبر حلقة الوكيل بالكامل دون استهلاك الحصة.
اختبر منطق الأخطاء بإرجاع 429 وتحقق من عمل إعادة المحاولة.
لسير عمل وكلاء متعدد الخطوات، استخدم متغيرات Apidog لتمرير القيم بين الخطوات (مثل tool_call_id).
هذا يعكس دورة الوكيل الحقيقية ويكشف أخطاء التكامل مبكرًا.
معالجة الأخطاء
واجهة API ترجع رموز HTTP قياسية:
| الحالة | المعنى | الإجراء |
|---|---|---|
| 200 | نجاح | معالجة الاستجابة بشكل طبيعي |
| 400 | طلب سيء | تحقق من تنسيق الطلب |
| 401 | غير مصرح به | تحقق من مفتاح API |
| 429 | تجاوز الحد الأقصى | أعد المحاولة بعد قيمة رأس Retry-After
|
| 500 | خطأ في الخادم | أعد المحاولة بتكرار تصاعدي (exponential) |
| 503 | الخدمة غير متاحة | أعد المحاولة بتكرار تصاعدي (exponential) |
مثال على منطق إعادة المحاولة:
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 مع تعيين base_url إلى
https://open.bigmodel.cn/api/paas/v4/.
ما هو اسم النموذج في الطلبات؟
استخدم "glm-5.1" فقط.
كيف تتم تسعيرة واجهة GLM-5.1؟
نظام حصص: 3x في الذروة (14:00-18:00 UTC+8)، 2x خارج الذروة، حتى نهاية أبريل 2026: 1x خارج الذروة كسعر ترويجي.
ما هو الحد الأقصى لطول السياق؟
200,000 رمز مميز للسياق. الإخراج حتى 163,840 رمز مميز. للمهام الطويلة، اضبط max_tokens لقيمة كبيرة (32768 أو أعلى).
هل يدعم استدعاء الأدوات/الوظائف؟
نعم. نفس تنسيق OpenAI. عرّف الأدوات بمخطط
type: "function"
ومررها في مصفوفة tools.
كيف أختبر استدعاءات API بدون استهلاك الحصة؟
استخدم Smart Mock في Apidog لتعريف استجابات وهمية لكل حالة. اختبر أثناء التطوير، واستخدم الـAPI الحقيقي فقط للتحقق النهائي.
أين أجد أوزان نموذج GLM-5.1؟
الأوزان متوفرة على HuggingFace في
zai-org/GLM-5.1
بترخيص MIT، وتدعم vLLM وSGLang للاستدلال المحلي.
Top comments (0)