Hướng Dẫn Sử Dụng API GLM-5.1: Chi Tiết Kèm Ví Dụ Code

Tóm tắt

GLM-5.1 có sẵn thông qua API BigModel tại https://open.bigmodel.cn/api/paas/v4/. API này tương thích với OpenAI: cấu trúc điểm cuối tương tự, định dạng yêu cầu tương tự, mẫu truyền dữ liệu tương tự. Bạn cần có tài khoản BigModel, khóa API và tên mô hình glm-5.1. Hướng dẫn này bao gồm xác thực, yêu cầu đầu tiên của bạn, truyền dữ liệu (streaming), gọi công cụ (tool calling) và kiểm thử tích hợp của bạn với Apidog.

Giới thiệu

GLM-5.1 là mô hình tác tử (agentic) hàng đầu của Z.AI, ra mắt vào tháng 4 năm 2026. Nó xếp hạng #1 trên SWE-Bench Pro và vượt trội hơn GLM-5 trên mọi tiêu chuẩn mã hóa chính. Nếu bạn đang xây dựng một trợ lý mã hóa AI, tác tử tự động hoặc bất kỳ ứng dụng nào hưởng lợi từ việc thực thi tác vụ dài hạn, GLM-5.1 rất đáng để tích hợp.

Tin tốt cho các nhà phát triển: API này tương thích với OpenAI. Nếu bạn đã xây dựng trên GPT-4 hoặc Claude, bạn có thể chuyển sang GLM-5.1 bằng cách thay đổi URL cơ sở và tên mô hình. Không cần học SDK mới. Không cần xử lý định dạng phản hồi khác biệt.

Điều kiện tiên quyết

Trước khi thực hiện cuộc gọi đầu tiên, bạn cần:

1. Một tài khoản BigModel tại bigmodel.cn. Đăng ký miễn phí.
2. Một khóa API từ bảng điều khiển BigModel trong phần API Keys.
3. Python 3.8+ hoặc Node.js 18+ (các ví dụ bao gồm cả hai).
4. OpenAI SDK hoặc requests/fetch tiêu chuẩn (API của GLM-5.1 tương thích với OpenAI).

Đặt khóa API của bạn làm biến môi trường:

export BIGMODEL_API_KEY="your_api_key_here"

Không bao giờ mã hóa cứng khóa API trong mã nguồn của bạn.

Xác thực

Mỗi yêu cầu cần một mã thông báo Bearer trong tiêu đề Authorization:

Authorization: Bearer YOUR_API_KEY

Định dạng khóa API của BigModel trông giống xxxxxxxx.xxxxxxxxxxxxxxxx, một chuỗi gồm hai phần được phân tách bằng dấu chấm. Điều này khác với định dạng sk- của OpenAI nhưng hoạt động theo cùng một cách trong tiêu đề.

URL cơ sở

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

Điểm cuối hoàn thành cuộc trò chuyện là:

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

Yêu cầu đầu tiên của bạn

Sử dụng 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
  }'

Sử dụng 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"])

Sử dụng OpenAI SDK (khuyên dùng)

Vì API tương thích với OpenAI, bạn có thể sử dụng OpenAI Python SDK chính thức với URL cơ sở tùy chỉnh:

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)

Đây là cách tiếp cận sạch nhất. OpenAI SDK xử lý việc thử lại, quản lý thời gian chờ và phân tích cú pháp phản hồi. Bạn nhận được tất cả những điều đó miễn phí chỉ bằng cách trỏ nó đến URL cơ sở của BigModel.

Định dạng phản hồi

Cấu trúc phản hồi giống hệt 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
  }
}

Truy cập văn bản phản hồi thông qua result["choices"][0]["message"]["content"].

Trường usage hiển thị số lượng token cho yêu cầu. Theo dõi điều này để giám sát mức tiêu thụ hạn mức của bạn, vì GLM-5.1 tính phí gấp 3 lần hạn mức trong giờ cao điểm (14:00-18:00 UTC+8).

Phản hồi truyền dữ liệu (Streaming)

Đối với các tác vụ tạo mã dài, truyền dữ liệu (streaming) cung cấp cho bạn các token ngay khi chúng đến thay vì phải chờ đợi phản hồi đầy đủ. Điều này rất cần thiết cho bất kỳ ứng dụng nào hướng đến người dùng.

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

Mỗi phân đoạn trong luồng là một delta chỉ chứa các token mới kể từ phân đoạn trước đó. Phân đoạn cuối cùng có finish_reason được đặt thành `"stop"` (hoặc `"length"` nếu bạn đạt đến giới hạn token).

Truyền dữ liệu (Streaming) với các yêu cầu thô

Nếu bạn không muốn sử dụng 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)

Gọi công cụ

GLM-5.1 hỗ trợ gọi công cụ: khả năng yêu cầu thực thi hàm trong cuộc hội thoại. Đây là cơ chế cốt lõi cho các quy trình làm việc tác tử (agentic workflows) nơi mô hình cần chạy mã, tìm kiếm cơ sở dữ liệu, gọi API bên ngoài hoặc thực hiện các hành động trong thế giới thực.

Định nghĩa công cụ

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}")

Xử lý phản hồi gọi công cụ

Khi GLM-5.1 yêu cầu gọi một công cụ, bạn thực thi hàm, sau đó trả về kết quả trong tin nhắn tiếp theo:

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)

Mẫu này mở rộng trực tiếp theo thế mạnh của GLM-5.1 như một mô hình tác tử. Bạn để mô hình quyết định khi nào gọi công cụ, xử lý kết quả và tiếp tục cho đến khi đạt được giải pháp hoặc quyết định đã hoàn thành.

Các tham số chính

Cài đặt khuyến nghị cho các tác vụ mã hóa:

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

Z.AI sử dụng các cài đặt này trong các đánh giá tiêu chuẩn của riêng họ. Để tạo mã có tính xác định, hãy giảm nhiệt độ xuống 0.2-0.4.

Sử dụng GLM-5.1 với trợ lý mã hóa

Kế hoạch Mã hóa của Z.AI cho phép bạn định tuyến Claude Code, Cline, Kilo Code và các trợ lý mã hóa AI khác thông qua GLM-5.1 qua API BigModel. Điều này hữu ích nếu bạn muốn một mô hình mã hóa mạnh mẽ với chi phí thấp hơn so với việc chạy trực tiếp Claude Opus hoặc GPT-5.4.

Thiết lập Claude Code

Trong tệp cấu hình Claude Code của bạn (`~/.claude/settings.json` hoặc tương đương):

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

Thiết lập Cline / Roo Code

Trong cài đặt VS Code của bạn hoặc cấu hình tiện ích mở rộng Cline:

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

Mức tiêu thụ hạn mức

GLM-5.1 sử dụng hệ thống hạn mức của Z.AI thay vì tính phí theo từng token: - Giờ cao điểm (14:00-18:00 UTC+8): 3 lần hạn mức mỗi yêu cầu - Ngoài giờ cao điểm: 2 lần hạn mức mỗi yêu cầu - Giá khuyến mãi đến hết tháng 4 năm 2026: 1 lần trong giờ ngoài cao điểm.

Đối với các tác vụ tác tử nặng, hãy lên lịch các tác vụ chạy dài trong giờ ngoài cao điểm. Một lần chạy tối ưu hóa 600 lần lặp như Z.AI đã trình bày sẽ tốn nhiều hạn mức hơn đáng kể vào giờ cao điểm.

Kiểm thử API GLM-5.1 với Apidog

Kiểm thử tích hợp API tác tử yêu cầu xử lý đúng cách nhiều loại phản hồi: hoàn thành thông thường, các phân đoạn truyền dữ liệu, yêu cầu gọi công cụ, tin nhắn kết quả công cụ và trạng thái lỗi. Kiểm thử tất cả những điều này với API thực sẽ tiêu tốn hạn mức và yêu cầu kết nối trực tiếp.

Smart Mock của Apidog cho phép bạn định nghĩa tất cả các trạng thái phản hồi này và kiểm thử chúng mà không cần truy cập API thực.

Thiết lập điểm cuối giả lập (mock endpoint)

1. Trong Apidog, tạo một điểm cuối mới: POST https://open.bigmodel.cn/api/paas/v4/chat/completions
2. Thêm một Mock Expectation cho phản hồi thành công tiêu chuẩn:

{
  "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. Thêm một expectation thứ hai cho phản hồi gọi công cụ:

{
  "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. Thêm một phản hồi giới hạn tốc độ (HTTP 429):

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

Kiểm thử vòng lặp tác tử hoàn chỉnh

Sử dụng Kịch bản kiểm thử của Apidog để xâu chuỗi nhiều yêu cầu lại với nhau. Đối với kiểm thử vòng lặp tác tử:

1. Bước 1: GỬI (POST) đến /chat/completions với tin nhắn ban đầu của bạn, khẳng định 200 và finish_reason == "tool_calls"
2. Bước 2: GỬI (POST) lại với kết quả công cụ trong mảng tin nhắn, khẳng định 200 và finish_reason == "stop"
3. Bước 3: Trích xuất nội dung cuối cùng và khẳng định nó chứa mã dự kiến

Điều này kiểm thử vòng lặp tác tử hoàn chỉnh mà không tốn bất kỳ hạn mức nào. Bạn cũng có thể kiểm thử xử lý lỗi bằng cách chuyển mock để trả về 429, sau đó xác minh logic thử lại của bạn hoạt động đúng cách.

Đối với các quy trình làm việc tác tử nhiều bước, Kịch bản kiểm thử của Apidog cho phép bạn truyền dữ liệu giữa các bước bằng cách sử dụng các biến, do đó các giá trị request_id hoặc tool_call_id từ bước 1 sẽ tự động chuyển sang bước 2. Điều này phản ánh cách một vòng lặp tác tử thực sự hoạt động và phát hiện lỗi tích hợp trước khi đưa vào sản xuất.

Xử lý lỗi

API trả về các mã trạng thái HTTP tiêu chuẩn:

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")

Đối với các lần chạy tác tử dài, nơi các bước riêng lẻ có thể mất 30-60 giây, hãy luôn đặt thời gian chờ hào phóng (120-300 giây). Mô hình có thể cần thời gian để tạo một tệp mã hoàn chỉnh hoặc phân tích kết quả benchmark phức tạp.

Kết luận

API tương thích với OpenAI của GLM-5.1 có nghĩa là bạn có thể tích hợp nó trong vài phút nếu bạn đã từng làm việc với GPT hoặc Claude. Sự khác biệt chính là điểm cuối (`open.bigmodel.cn`) và hệ thống hạn mức thay vì tính phí theo từng token.

Đối với các ứng dụng tác tử nơi mô hình chạy hàng trăm cuộc gọi công cụ trong một phiên dài, khả năng tối ưu hóa dài hạn của GLM-5.1 là một lợi thế thực sự. Hãy kết hợp nó với việc kiểm thử thích hợp thông qua Smart Mock và Test Scenarios của Apidog để đảm bảo tích hợp của bạn xử lý tất cả các trường hợp biên trước khi nó chạy tự động.

Để biết thêm thông tin cơ bản về GLM-5.1 và cách các điểm chuẩn của nó so sánh, hãy xem tổng quan mô hình GLM-5.1. Để biết thêm về cách xây dựng và kiểm thử quy trình làm việc tác tử AI với Apidog, hãy xem cách bộ nhớ tác tử AI hoạt động.

Câu hỏi thường gặp

API GLM-5.1 có tương thích với OpenAI không?
Có. Định dạng yêu cầu, cấu trúc phản hồi, giao thức truyền dữ liệu (streaming protocol) và định dạng gọi công cụ (tool calling format) đều giống hệt API hoàn thành cuộc trò chuyện của OpenAI. Bạn có thể sử dụng OpenAI Python SDK chính thức hoặc bất kỳ client tương thích OpenAI nào bằng cách đặt URL cơ sở thành https://open.bigmodel.cn/api/paas/v4/.

Tên mô hình cần sử dụng trong các yêu cầu API là gì?
Sử dụng "glm-5.1" làm tên mô hình. Không sử dụng tên có phiên bản đầy đủ; chỉ cần glm-5.1 là được.

Cơ chế định giá API GLM-5.1 hoạt động như thế nào?
API BigModel sử dụng hệ thống hạn mức. GLM-5.1 tiêu thụ hạn mức gấp 3 lần trong giờ cao điểm (14:00-18:00 UTC+8) và gấp 2 lần trong giờ ngoài cao điểm. Đến cuối tháng 4 năm 2026, mức sử dụng ngoài giờ cao điểm được tính phí ở mức 1 lần hạn mức như một mức giá khuyến mãi.

Độ dài ngữ cảnh tối đa là bao nhiêu?
Ngữ cảnh đầu vào 200.000 token. Đầu ra tối đa là 163.840 token. Đối với các lần chạy tác tử dài, hãy đặt max_tokens thành một giá trị lớn (32.768 trở lên) để tránh cắt bớt đầu ra của mô hình giữa chừng tác vụ.

Tôi có thể sử dụng GLM-5.1 cho việc gọi hàm / sử dụng công cụ không?
Có. GLM-5.1 hỗ trợ định dạng gọi công cụ tương tự như API của OpenAI. Định nghĩa công cụ với lược đồ type: "function", truyền chúng vào mảng tools và xử lý các phản hồi finish_reason: "tool_calls" trong vòng lặp tác tử của bạn.

Làm cách nào để kiểm thử các cuộc gọi API GLM-5.1 mà không tốn hạn mức?
Sử dụng Smart Mock của Apidog để định nghĩa các phản hồi giả lập cho từng trạng thái API: thành công, gọi công cụ, giới hạn tốc độ, lỗi. Chạy bộ kiểm thử của bạn với mock trong quá trình phát triển và chỉ sử dụng API thực cho bước xác thực cuối cùng.

Tôi có thể tìm thấy trọng số mô hình GLM-5.1 ở đâu?
Các trọng số mã nguồn mở có sẵn trên HuggingFace tại zai-org/GLM-5.1. Chúng được phát hành theo Giấy phép MIT và hỗ trợ vLLM cũng như SGLang cho suy luận cục bộ.