> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# GLM Chat Completion API 申请及使用

> GLM API guide - Ace Data Cloud

GLM（النموذج اللغوي العام）هو سلسلة من نماذج اللغة الكبيرة من الجيل الجديد التي أطلقتها شركة زهيبو AI (Zhipu AI / Z.ai)، والتي تتمتع بقدرات قوية في فهم وتوليد اللغة الصينية والإنجليزية، وتظهر أداءً ممتازًا في المهام مثل المشاهد الصينية، وتوليد الشيفرات، والاستدلال، والحوار المتعدد الجولات. تم تحسين نماذج الجيل الجديد مثل GLM-5.3 وGLM-5.2 وGLM-4.7 بشكل كبير في سياقات طويلة، واستدعاء الأدوات، ومهام الشيفرات، ويمكن استخدامها على نطاق واسع في سيناريوهات مثل الأسئلة الذكية، وإنشاء المحتوى، والمساعدة في الشيفرات، وروبوتات خدمة العملاء.

تتناول هذه الوثيقة بشكل رئيسي عملية استخدام واجهة برمجة التطبيقات GLM Chat Completion، حيث يمكنك من خلالها استدعاء نماذج سلسلة GLM بسهولة من خلال واجهة متوافقة مع OpenAI.

## 申请流程

لاستخدام واجهة برمجة التطبيقات GLM Chat Completion، يجب أولاً الذهاب إلى [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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

**يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [لوحة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثيقة الكاملة: [GLM Chat Completion API →](https://platform.acedata.cloud/documents/glm-chat-completions)

## 基本使用

عنوان طلب واجهة برمجة التطبيقات GLM Chat Completion هو `https://api.acedata.cloud/glm/chat/completions`، ويستخدم مصادقة Bearer Token، وجسم الطلب متوافق مع بروتوكول OpenAI Chat Completions.

عند استخدام هذه الواجهة للمرة الأولى، نحتاج على الأقل إلى ملء ثلاثة محتويات:

* `authorization`：اختر Bearer Token مباشرة من القائمة المنسدلة.
* `model`：اختر نموذج GLM الذي تريد استدعاءه، والنماذج المدعومة حاليًا تشمل:
  * `glm-5.3`：أحدث نموذج رائد، يدعم 1M سياق وأقصى 128K مخرجات، مناسب للاستدلال المعقد، والشيفرات، ومهام الوكلاء. الاستدلال مفعل دائمًا، ويمكنك اختيار `reasoning_effort` كـ `low` أو `high` أو `max`.
  * `glm-5.2`：النموذج الرائد من الجيل السابق، ذو قدرة شاملة قوية.
  * `glm-5.1`：نموذج رائد ناضج، مناسب للمهام المعقدة العامة.
  * `glm-4.7`：يظهر أداءً ممتازًا في الاستدلال، واستدعاء الأدوات، ومهام الشيفرات.
  * `glm-4.6`：نموذج حوار عام، يوازن بين الأداء والتكلفة.
  * `glm-3-turbo`：نموذج حوار كلاسيكي، مناسب لمهام توليد النصوص العامة.
* `messages`：مصفوفة الكلمات الدلالية، تحتوي كل رسالة على `role` و `content`، حيث تدعم `role` ثلاثة أدوار: `user` و `assistant` و `system`.

البارامترات الاختيارية الشائعة:

* `max_tokens`：تحديد الحد الأقصى لعدد الرموز في الرد الواحد.
* `temperature`：عشوائية التوليد، بين 0-2، كلما زادت القيمة كانت أكثر تشتتًا.
* `top_p`：معامل أخذ العينات، يتحكم في عتبة الاحتمال التراكمي للرموز المرشحة.
* `n`：عدد الردود المرشحة التي يتم توليدها في مرة واحدة.
* `stream`：هل يتم تفعيل الاستجابة المتدفقة، الافتراضي هو `false`.
* `stop`：تسلسل التوقف المخصص.

إليك مثال بسيط لاستدعاء Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/glm/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "glm-5.2",
    "messages": [
        {"role": "user", "content": "hello"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

بعد الاستدعاء، نجد أن النتيجة المرجعة هي كما يلي:

```json theme={null}
{
  "id": "msg_202604262252030313862701a04e33",
  "model": "glm-5.2",
  "object": "chat.completion",
  "created": 1777215124,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! 👋 How can I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 23,
    "total_tokens": 33
  }
}
```

تفسير الحقول الرئيسية في النتيجة المرجعة كما يلي:

* `id`：معرف فريد لمهمة الحوار هذه.
* `created`：وقت إنشاء مهمة الحوار هذه (طابع زمني Unix، بالثواني).
* `model`：اسم نموذج GLM الذي تم استدعاؤه فعليًا.
* `choices`：قائمة الردود التي أنشأها النموذج. `choices[i].message.content` هو النص المحدد للرد من النموذج، و `finish_reason` يحدد سبب الانتهاء (مثل `stop` أو `length` أو `tool_calls` أو `content_filter` وغيرها).
* `usage`：إحصائيات استخدام الرموز لهذه الطلب، تشمل `prompt_tokens` و `completion_tokens` و `total_tokens`.

## 流式响应

تدعم هذه الواجهة الاستجابة المتدفقة (Server-Sent Events)، وهذا مفيد جدًا لتكامل الويب، حيث يمكن أن يتيح للويب تحقيق تأثير العرض حرفيًا.

إذا كنت ترغب في استجابة متدفقة، قم بتعيين معامل `stream` في جسم الطلب إلى `true`.

كود مثال لاستدعاء Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/glm/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "glm-4.7",
    "messages": [{"role": "user", "content": "hi"}],
    "stream": True
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))
```

تكون النتيجة كما يلي (مقتطف):

```text theme={null}
data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "", "role": "assistant"}, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "مرحبًا! كيف يمكنني"}, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "مساعدتك"}, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "؟"}, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {}, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [], "usage": {"prompt_tokens": 1420, "completion_tokens": 18, "total_tokens": 1438}}

data: [DONE]
```

يمكنك أن ترى أن هناك العديد من `data` في الاستجابة، كل `data` تحتوي على جزء متزايد. `choices[i].delta.content` هو النص الجديد المضاف في الجزء الحالي، يمكنك تجميع هذه الأجزاء لتشكيل رد كامل. عندما يكون محتوى `data` هو `[DONE]`، فهذا يعني أن الاستجابة المتدفقة قد انتهت. آخر جزء يحمل `usage` سيجمع استخدام الرموز لهذه الطلب.

مثال على JavaScript (Node.js):

```javascript theme={null}
const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "glm-4.7",
    messages: [{ role: "user", content: "مرحبًا" }],
    stream: true
  })
};

const response = await fetch("https://api.acedata.cloud/glm/chat/completions", options);
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}
```

مثال على كود Java:

```java theme={null}
JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "glm-4.7");
jsonObject.put("messages", new JSONArray().put(new JSONObject().put("role", "user").put("content", "مرحبًا")));
jsonObject.put("stream", true);
MediaType mediaType = MediaType.parse("application/json; charset=utf-8");
RequestBody body = RequestBody.create(jsonObject.toString(), mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/glm/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
```

يمكنك إعادة كتابة الكود بلغات أخرى بنفس المبدأ.

## محادثة متعددة الجولات

إذا كنت ترغب في تنفيذ وظيفة المحادثة متعددة الجولات، تحتاج إلى وضع المحادثات السابقة في مصفوفة `messages` بالتتابع، مع الحفاظ على ترتيب ظهور `user` و `assistant`.

مثال على كود استدعاء Python:

```python theme={null}
import requests

url = "https://api.acedata.cloud/glm/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "user", "content": "مرحبًا"},
        {"role": "assistant", "content": "مرحبًا! كيف يمكنني مساعدتك اليوم؟"},
        {"role": "user", "content": "ماذا قلت للتو؟"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

من خلال رفع عدة أسئلة، يمكنك بسهولة تنفيذ محادثة متعددة الجولات، ويمكنك الحصول على الردود كما يلي:

```json theme={null}
{
  "id": "msg_20260426225208b95324e9945a48d3",
  "model": "glm-4.7",
  "object": "chat.completion",
  "created": 1777215128,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "لقد قلت: **\"مرحبًا\"** 😊\n\nأخبرني إذا كنت بحاجة إلى أي شيء آخر!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 37,
    "total_tokens": 85
  }
}
```

يمكنك أن ترى أن المعلومات الموجودة في `choices` تتوافق مع الاستخدام الأساسي، حيث يقدم النموذج ردًا بناءً على تاريخ المحادثة الكامل، مما يدعم التفاعل السياقي متعدد الجولات.

## نصوص النظام (System Prompt)

يمكنك إضافة رسالة `role` كـ `system` في بداية `messages` لتقييد دور النموذج أو أسلوبه أو سلوكه:

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "system", "content": "أنت مساعد كتابة محترف باللغة الصينية، يرجى الرد بنبرة مختصرة ومحترفة."},
        {"role": "user", "content": "يرجى تقديم مقدمة عن نموذج GLM في ثلاث جمل."}
    ]
}
```

## استدعاء الأدوات (Function Calling)

يدعم نموذج GLM استدعاء الأدوات المتوافق مع OpenAI، يمكنك من خلال معلمة `tools` إعلان الوظائف القابلة للاستدعاء، وسيقوم النموذج عند الحاجة بإرجاع معلومات استدعاء الوظائف المهيكلة في `choices[i].message.tool_calls`.

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "user", "content": "كيف هو الطقس في بكين اليوم؟"}
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "استعلام عن الطقس في مدينة معينة",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string", "description": "اسم المدينة"}
                    },
                    "required": ["city"]
                }
            }
        }
    ]
}
```

إذا قرر النموذج استدعاء الأداة، ستتغير نتيجة `finish_reason` إلى `tool_calls`، وسيتم تقديم اسم الوظيفة ومعلمات بصيغة JSON في `message.tool_calls`. يمكنك تنفيذ هذه الوظيفة وإرجاع النتيجة كرسالة `role` كـ `tool` إلى النموذج، مما يكمل دورة استدعاء الأداة بالكامل.

## اقتراحات اختيار النموذج

````
| النموذج          | سيناريوهات الاستخدام                               |
| ------------- | -------------------------------------------- |
| `glm-5.3`     | أحدث طراز، 1M سياق، أطول 128K مخرجات، يُوصى به للاستخدام في الاستدلال المعقد، المهام البرمجية ووكيل المهام |
| `glm-5.2`     | الطراز السابق، مناسب للاستدلال المعقد، المهام البرمجية ووكيل المهام                    |
| `glm-5.1`     | طراز ناضج، مناسب للاستدلال المعقد، تحليل الوثائق الطويلة                            |
| `glm-4.7`     | استدعاء الأدوات، توليد الشيفرة، تنسيق الوكلاء وغيرها من المهام                        |
| `glm-4.6`     | خيار متوازن للحوار العام، وإبداع المحتوى                               |
| `glm-3-turbo` | مهام توليد النصوص العامة، في السيناريوهات الحساسة للتكلفة                            |

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

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:

- `400 token_mismatched`：معلمات الطلب مفقودة أو غير صالحة.
- `400 api_not_implemented`：تم استخدام معلمات أو نماذج غير مدعومة.
- `401 invalid_token`：غير مصرح به، رمز Bearer مفقود أو غير صالح.
- `429 too_many_requests`：تم تفعيل حد التكرار، يرجى المحاولة لاحقًا.
- `500 api_error`：خطأ داخلي في الخادم أو الخدمة العلوية غير متاحة مؤقتًا.

### مثال على استجابة الخطأ

```json
{
  "trace_id": "69ea9bcf-c5da-41a3-be97-c80912a08523",
  "error": {
    "code": "api_error",
    "message": "الخدمة غير متاحة مؤقتًا، يرجى المحاولة لاحقًا."
  }
}
````

عند إرجاع `api_error` وكانت الرسالة `الخدمة غير متاحة مؤقتًا، يرجى المحاولة لاحقًا.`، فهذا عادةً ما يشير إلى أن خدمة GLM العلوية غير متاحة مؤقتًا، يُنصح بإعادة المحاولة مع تراجع أسي، أو التبديل إلى نموذج GLM آخر متاح (مثل التبديل مؤقتًا من `glm-5.1` إلى `glm-4.7` أو `glm-4.6`).

## الخاتمة

من خلال هذه الوثيقة، لقد تعرفت على كيفية استخدام واجهة برمجة تطبيقات GLM Chat Completion لاستدعاء نماذج سلسلة GLM من Zhizhu AI، بما في ذلك الاستدعاءات الأساسية، الاستجابات المتدفقة، المحادثات متعددة الجولات، كلمات النظام واستدعاء الأدوات وغيرها من الاستخدامات النموذجية. نأمل أن تساعدك هذه الوثيقة في التوصيل والاستخدام الأفضل لهذه الواجهة. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.