如果你用过 OpenAI Python SDK，接入 GLM 5.2 大约只需要五分钟。该模型通过 Z.ai 的 API 提供服务，完全兼容 OpenAI——也就是说，你只需改现有代码里的两行（base_url 和 model），其他一切都照旧。本指南带你走一遍鉴权、全部可用端点、流式输出、函数调用、JSON 模式，以及如何把完整的 1M token 上下文窗口真正用起来。
前置条件
开始之前，请确保你具备以下条件：
- 一个 Z.ai 账号和 API key（在 api.z.ai 注册）
- Python 3.8 或更高版本
openaiPython 包（pip install openai）- 对发起 HTTP 请求或使用 OpenAI SDK 有基本了解
不需要任何 GLM 专属 SDK。因为 API 表面完全兼容 OpenAI，任何已经支持 OpenAI chat-completions 格式的库或工具，都能直接开箱即用地对接 GLM 5.2。
第 1 步：获取你的 API Key
登录 api.z.ai 的 Z.ai 控制台。在侧边栏找到 API Keys，创建一个新的 secret key，并立即复制——控制台只会完整显示一次。
把 key 存成环境变量，而不是硬编码进代码：
export Z_AI_API_KEY="your-api-key-here"
Windows（PowerShell）下：
$env:Z_AI_API_KEY = "your-api-key-here"
第 2 步：发起你的第一个请求
与 OpenAI API 不同的只有两处：base_url 和 model 名称。其余一切——请求头、请求体结构、响应格式——完全相同。
Base URL： https://api.z.ai/v1
模型名： glm-5.2
下面是一个使用 openai Python 库的最小可运行示例：
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["Z_AI_API_KEY"],
base_url="https://api.z.ai/v1",
)
response = client.chat.completions.create(
model="glm-5.2",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain the Mixture of Experts architecture in two sentences."},
],
)
print(response.choices[0].message.content)
如果你更喜欢原生 HTTP，对应的 curl 命令是：
curl https://api.z.ai/v1/chat/completions \
-H "Authorization: Bearer $Z_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.2",
"messages": [
{"role": "user", "content": "What is GLM 5.2?"}
]
}'
鉴权就是标准的 HTTP Bearer token，没有专有请求头或签名步骤。
第 3 步：启用流式输出
对生产应用来说，流式输出能大幅改善感知延迟。GLM 5.2 吞吐可达 158 tokens/秒，因此流式模式让用户几乎在第一个 token 到达后就能立刻看到输出（TTFT 1.54 秒）。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["Z_AI_API_KEY"],
base_url="https://api.z.ai/v1",
)
stream = client.chat.completions.create(
model="glm-5.2",
messages=[
{"role": "user", "content": "Write a short story about a robot learning to cook."},
],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
print() # newline after stream ends
stream=True 参数会把响应从单个 JSON 对象切换成一系列 server-sent events。每个 chunk 包含一个部分 token，最后的 [DONE] 信号则是空字符串——与 OpenAI 流式 API 的格式一致。
第 4 步：使用函数调用（工具调用）
GLM 5.2 通过 tools 参数支持 OpenAI 格式的函数调用。这让模型能自行决定何时调用某个函数，并返回你可以在客户端执行的结构化参数。
import os, json
from openai import OpenAI
client = OpenAI(
api_key=os.environ["Z_AI_API_KEY"],
base_url="https://api.z.ai/v1",
)
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city name, e.g. Tokyo",
}
},
"required": ["city"],
},
},
}
]
response = client.chat.completions.create(
model="glm-5.2",
messages=[{"role": "user", "content": "What is the weather in Beijing?"}],
tools=tools,
tool_choice="auto",
)
message = response.choices[0].message
if message.tool_calls:
for call in message.tool_calls:
args = json.loads(call.function.arguments)
print(f"Function: {call.function.name}, Args: {args}")
当模型决定调用工具时，message.tool_calls 会带上函数名和一串 JSON 参数。你在自己这边执行函数，把结果以 role: "tool" 追加进对话历史，再发送下一个请求——与 OpenAI API 相同的多轮工具循环。
第 5 步：请求结构化 JSON 输出
对于需要机器可读输出的流水线——分类标签、抽取的实体、结构化报告——请用 JSON 模式。传入 response_format={"type": "json_object"}，并在 system prompt 里指示模型用 JSON 响应：
import os, json
from openai import OpenAI
client = OpenAI(
api_key=os.environ["Z_AI_API_KEY"],
base_url="https://api.z.ai/v1",
)
response = client.chat.completions.create(
model="glm-5.2",
messages=[
{
"role": "system",
"content": "You are a data extraction assistant. Always respond with valid JSON.",
},
{
"role": "user",
"content": "Extract the company name, founding year, and headquarters from: "
"'Anthropic was founded in 2021 and is headquartered in San Francisco.'",
},
],
response_format={"type": "json_object"},
)
data = json.loads(response.choices[0].message.content)
print(data)
# {"company_name": "Anthropic", "founding_year": 2021, "headquarters": "San Francisco"}
JSON 模式保证响应是合法 JSON。但你仍然要告诉模型你期望的 schema——把它写进 system prompt 或用户消息里。
第 6 步：用满 1M token 上下文窗口
GLM 5.2 拥有 1,048,576 token 的上下文窗口——在这个价位上可用的最大窗口之一。输入每百万 token $1.40、缓存命中每百万 $0.26 的价格，让处理超长文档变得很经济。
实用示例——总结一个大型代码库或文档：
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["Z_AI_API_KEY"],
base_url="https://api.z.ai/v1",
)
# Read a large file (e.g., a full codebase or long document)
with open("large_document.txt", "r") as f:
document = f.read()
response = client.chat.completions.create(
model="glm-5.2",
messages=[
{
"role": "system",
"content": "You are a technical analyst. Summarize the following document.",
},
{"role": "user", "content": document},
],
max_tokens=4096,
)
print(response.choices[0].message.content)
按每 1000 token 约 750 个英文单词折算，1M token 大约容纳 75 万词——相当于十部长篇小说、一个大型 monorepo 或一整套法律案卷。对同一份大文档做重复分析时，prompt 缓存能把有效输入成本降到缓存命中时每 M token 仅 $0.26。
第 7 步：列出可用模型
要确认连通性并查看你的 API key 下有哪些模型可用：
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["Z_AI_API_KEY"],
base_url="https://api.z.ai/v1",
)
models = client.models.list()
for m in models.data:
print(m.id)
这会调用 GET /models 并返回模型标识符列表。当你的 key 有权限时，glm-5.2 应该出现在列表中。
API 参考速览
| 属性 | 值 |
|---|---|
| Base URL | https://api.z.ai/v1 |
| 鉴权方式 | Authorization: Bearer <api_key> |
| 主模型名 | glm-5.2 |
| OpenRouter 模型名 | z-ai/glm-5.2 |
| Chat completions 端点 | POST /chat/completions |
| 模型列表端点 | GET /models |
| 流式输出 | stream: true |
| 函数调用 | tools: []（OpenAI 格式） |
| JSON 模式 | response_format: {"type": "json_object"} |
| 最大输出 token | 默认最多 4096；支持更大的值 |
| 上下文窗口 | 1,048,576 tokens |
定价一览
在规模化之前，先理解成本至关重要。作为前沿级模型，GLM 5.2 的定价很有竞争力：
| Token 类型 | 每 1M token 价格 |
|---|---|
| 输入（缓存未命中） | $1.40 |
| 输出 | $4.40 |
| 输入（缓存命中） | $0.26 |
对于反复发送相同 system prompt 或大文档的工作负载，缓存命中能把有效输入成本降低约 81%。一条每天处理 10M 输入 token、缓存命中率 70% 的流水线，费用大约是：(3M × $1.40) + (7M × $0.26) = $4.20 + $1.82 = 每天 $6.02，而不用缓存则是 $14.00/天。
完整的定价拆解及与其他前沿模型的对比，见 GLM 5.2 定价指南。
常见问题排查
| 问题 | 原因 | 解决方法 |
|---|---|---|
401 Unauthorized | API key 缺失或无效 | 检查 Z_AI_API_KEY 环境变量；在控制台重新生成 key |
404 Not Found | base_url 错误或模型名拼写错误 | 严格使用 https://api.z.ai/v1 和 "glm-5.2" |
model_not_found 错误 | 传入了 OpenAI 模型名 | 把 model="gpt-4o" 改成 model="glm-5.2" |
| 流式输出为空 chunk | 在检查 None 之前就消费 delta.content | 打印前加 if delta: 保护 |
| JSON 模式返回散文 | system prompt 缺少 JSON 指令 | 在 system prompt 里加上「respond with valid JSON」 |
| 上下文长度错误 | 输入超过 1,048,576 tokens | 把文档分块，或加一步检索 |
| 首 token 慢 | 网络路由问题，不是模型速度 | 基准 TTFT 为 1.54 秒；更长时间说明是网络延迟 |
常见问题解答
GLM 5.2 能无缝替换 OpenAI API 吗？
就本指南覆盖的端点——chat completions、流式、函数调用和 JSON 模式——而言，可以。把 base_url 改成 https://api.z.ai/v1、model 改成 "glm-5.2" 即可。任何基于 OpenAI SDK 构建的库（LangChain、LlamaIndex、Instructor 等）都能在这两处替换后正常工作。OpenAI 平台特有的功能（Assistants API、微调、embeddings、图像）不适用。
我可以通过 OpenRouter 用 GLM 5.2，而不是直连 Z.ai 吗？
可以。在 OpenRouter 上模型标识符是 z-ai/glm-5.2。把 base_url 设为 https://openrouter.ai/api/v1，用你的 OpenRouter API key。OpenRouter 会在 Z.ai 直连定价上加一点手续费，但它让你不用改集成代码就能在多个供应商之间切换。
怎么处理速率限制？
超过速率限制时 API 会返回 HTTP 429。实现指数退避：重试间隔 1 秒、2 秒、4 秒。openai 库内置了重试支持——给 OpenAI 客户端构造函数传 max_retries=3 即可。
GLM 5.2 支持多模态输入（图像、音频）吗？
不支持。GLM 5.2 是纯文本模型。content 字段不接受图片 URL 或 base64 编码的图片。如果你需要视觉能力，得换别的模型。
最大输出长度是多少？
默认上限是每个请求 4096 个输出 token。你可以请求更高的 max_tokens 值，但很长的单轮输出不一定总能完全满足。做长文生成时，把任务拆成连续的几轮，而不是依赖一次超长输出。
模型可以自托管吗？
可以。GLM 5.2 以 MIT 许可证发布开放权重，Hugging Face 上路径为 THUDM/GLM-5.2。自托管完整的 753B 参数模型需要相当规模的 GPU 基础设施。该模型采用 Mixture of Experts 架构——78 个 transformer 解码器层、每层 256 个专家、每个 token 激活 8 个——意味着每次前向传播只有 40B 参数处于激活状态，推理比同等参数量的稠密模型更高效。
如何从现有 OpenAI 集成迁移？
最小改动就是两行：
# Before
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
response = client.chat.completions.create(model="gpt-4o", ...)
# After
client = OpenAI(
api_key=os.environ["Z_AI_API_KEY"],
base_url="https://api.z.ai/v1",
)
response = client.chat.completions.create(model="glm-5.2", ...)
所有其他参数——messages、temperature、max_tokens、stream、tools、response_format——都保持不变。
下一步
- 探索基准测试： GLM 5.2 在 GPQA Diamond 上得分 89%、SWE-bench Pro 62.1%。在 GLM 5.2 基准拆解 里看它与其他前沿模型的对比。
- 理解架构： 753B 参数 MoE 设计、每 token 40B 激活参数，正是 158 t/s 吞吐的来源。更多内容见 GLM 5.2 概览。
- 细看定价： 缓存命中 $0.26/M tokens 的价格改变了高吞吐流水线的成本结构。看完整定价指南。
- 免代码试用： 想在写任何代码之前先测 GLM 5.2？glm5.app/chat 的聊天界面不需要 API key、零配置。
试试 GLM 5.2——无需 API key：glm5.app/chat。
