上个月智谱把 GLM-5 正式推上了云端推理服务，我第一时间拿开源版那套代码去对接——结果请求全部悄悄切换到了 GLM-4-Plus，返回质量明显不对。折腾了大半天才发现，云端正式版的 inference endpoint 格式和开源版完全不一样，model name 字段还必须带 -turbo 后缀，不带的话接口不报错但实际跑的是旧模型。这篇把我踩过的坑全部整理出来，从 access token 获取到代码跑通，一篇讲完。

这篇适合谁

• 之前用过 GLM-4 系列 API，想第一时间切到 GLM-5 云端版的开发者
• 已经跑通了 GLM-5 开源版（比如 Ollama 本地部署），现在想用云端推理服务的
• 项目里用 OpenAI SDK 做统一接入，需要把智谱模型加进来的后端同学
• 想搞清楚 GLM-5 云端版到底和开源版有哪些 API 层面差异的

整体流程

1. 在智谱开放平台注册并获取 Access Token
2. 确认 Base URL——云端正式版用的是 /v5/ 路径，不是之前的 /v4/
3. 选对 model name：必须写 glm-5-turbo，不带 -turbo 会无提示地降级到旧版本
4. 跑通基础调用（zhipuai SDK 或 OpenAI 兼容 SDK 二选一）
5. 开启流式输出，验证 streaming 正常

先说结论

对比项	GLM-5 开源版（本地）	GLM-5 云端正式版
Base URL	本地 Ollama 端口	https://open.bigmodel.cn/api/paas/v5/
model name	glm-5	glm-5-turbo（必须带后缀）
Token 获取	不需要	控制台 API Keys 页面
Token 格式	—	JWT 格式（eyJ 开头），GLM-4 起即采用此格式
上下文窗口	取决于本地显存	128K tokens（数据来源：智谱开放平台文档）
认证 Header	无	Authorization: Bearer {token}

第一步：获取 Access Token

登录 open.bigmodel.cn，进控制台找「API Keys」，生成一个新 Key。

# 环境变量里放你的 Key
export ZHIPUAI_API_KEY="eyJhbGciOi..."

智谱从 GLM-4 起就采用 JWT 格式的 API Key（eyJ 开头），GLM-5 沿用了这一格式。如果你之前已经有可用的 JWT 格式 Key，可以直接复用，无需重新生成。

第二步：确认 Base URL

这是我踩的第一个大坑。GLM-4 系列的 base_url 是：

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

GLM-5 云端正式版换成了 /v5/ 路径：

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

如果还用 /v4/ 路径去请求 glm-5-turbo 这个 model name，服务端会返回路径不存在或业务错误码（类似 404 或特定业务错误），而不是连接层面的报错。报错信息可能类似：

# 示意，实际错误码以平台返回为准
Error code: 404 - model not found on this endpoint

注意不要把这类错误误判为网络问题。

第三步：model name 必须带 -turbo 后缀

最坑的地方。我一开始写的是 model="glm-5"，请求正常返回 200，内容也有——但质量明显不对，回答像是 GLM-4 的水平。

后来翻了半天文档才发现：云端正式版的 model name 必须写成 glm-5-turbo。如果你只写 glm-5，接口不报错，但会无提示地降级到 GLM-4-Plus。

# ❌ 错误写法：无提示地降级到旧版本
model = "glm-5"

# ✅ 正确写法
model = "glm-5-turbo"

这个行为挺反直觉的，至少应该返回个 warning 吧。反正我已经在社区提了 issue。

第四步：跑通基础调用

路径 A：用 zhipuai 官方 SDK

import os
from zhipuai import ZhipuAI

client = ZhipuAI(api_key=os.environ.get("ZHIPUAI_API_KEY"))

response = client.chat.completions.create(
    model="glm-5-turbo",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

如果需要传 system prompt，使用 system 参数单独传入（不要放进 messages 数组）：

response = client.chat.completions.create(
    model="glm-5-turbo",
    messages=[{"role": "user", "content": "你好"}],
    system="你是一个专业的代码助手，请用简洁的语言回答问题。"
)
print(response.choices[0].message.content)

注意 zhipuai SDK 要升级到最新版才支持 v5 端点：

pip install --upgrade zhipuai

路径 B：用 OpenAI SDK 兼容接入

如果你项目里已经用了 OpenAI SDK 做统一接入，改两个参数就行：

from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("ZHIPUAI_API_KEY"),
    base_url="https://open.bigmodel.cn/api/paas/v5/"
)

response = client.chat.completions.create(
    model="glm-5-turbo",
    messages=[
        {"role": "system", "content": "你是一个专业的代码助手，请用简洁的语言回答问题。"},
        {"role": "user", "content": "介绍一下你自己"}
    ]
)
print(response.choices[0].message.content)

使用 OpenAI SDK 兼容模式时，system prompt 可以作为 messages 数组中 role: system 的第一条传入（注意：此时 messages 数组中第一条 user 消息仍须在 system 消息之后，详见 FAQ）。

第五步：流式输出

for chunk in client.chat.completions.create(
    model="glm-5-turbo",
    messages=[{"role": "user", "content": "写首诗"}],
    stream=True
):
    print(chunk.choices[0].delta.content or "", end="")

流式这块和 GLM-4 时代没区别，chunk 结构一样。

调用链路一览

graph LR
    A[你的代码] -->|Bearer JWT Token| B{Base URL 选择}
    B -->|/v5/ 路径| C[GLM-5 云端推理集群]
    B -->|/v4/ 路径| D[GLM-4 系列端点 - 不支持 glm-5-turbo]
    C -->|model=glm-5-turbo| E[✅ GLM-5 正式版响应]
    C -->|model=glm-5| F[⚠️ 无提示降级到 GLM-4-Plus]

说明：/v4/ 路径不支持 glm-5-turbo，请求会返回路径不存在或业务错误码，而非正常响应。

不同场景怎么选

场景一：个人项目 / 快速原型

直接用 zhipuai SDK + glm-5-turbo，最省事。128K 上下文够用。具体定价请参考智谱开放平台官方定价页面。

场景二：已有 OpenAI SDK 统一接入层的团队

用 OpenAI 兼容模式，只改 base_url 和 api_key。如果你的接入层本身就支持多个 provider（比如通过 OpenRouter 或者 ofox.io 这类聚合网关统一管理，OpenRouter 按模型收取一定比例加价，ofox 声称 0% 加价对齐官方价格），那连 base_url 都不用改，直接在网关配置里加一个 model mapping 就行。

场景三：需要对比 GLM-5 和其他模型效果

建议本地跑一套 eval benchmark，model name 分别传 glm-5-turbo、glm-4-plus、deepseek-chat，横向对比。我上周测下来 GLM-5 在中文理解任务上提升明显，但英文代码生成还是 DeepSeek 更强一些。

场景四：本地显存够，想省钱

继续用开源版 + Ollama 部署。云端版按 token 计费，长期跑量的话成本会上去。

踩坑记录 / 常见问题 FAQ

Q: 我用了 glm-5 作为 model name，为什么没报错但效果很差？

A: 云端正式版必须写 glm-5-turbo。只写 glm-5 会无提示地降级到 GLM-4-Plus，接口返回 200 但跑的不是 GLM-5。

要确认实际调用的是哪个模型，可以检查响应体中的 model 字段：

response = client.chat.completions.create(
    model="glm-5-turbo",
    messages=[{"role": "user", "content": "你好"}]
)
# 检查实际生效的 model name
print(response.model)

如果返回的 response.model 不是 glm-5-turbo，说明发生了降级，需要检查 model name 拼写和 base_url 是否正确。

Q: 出现 401 Invalid Authorization 怎么排查？

完整报错长这样：

AuthenticationError: Error code: 401 - {'error': {'code': '1113', 'message': 'Invalid Authorization'}}

排查顺序：①确认用的是 JWT 格式 Token（eyJ 开头）②检查有没有多余空格或换行③确认账户没欠费。

Q: messages 第一条必须是 user role？

是的。如果 messages 数组第一条传了 role: system 以外的非 user 消息，或者第一条 user 消息缺失，会报：

status_code: 400, body: {'error': {'code': '1214', 'message': 'messages[0] role must be user'}}

GLM-5 云端版要求 messages 数组中第一条有效的对话消息必须是 role: user。如需传 system prompt，有两种方式：

• 使用 zhipuai SDK 时，通过独立的 system 参数传入（见第四步路径 A 示例）
• 使用 OpenAI 兼容 SDK 时，可将 role: system 放在 messages 数组首位，后面紧跟 role: user 消息（见第四步路径 B 示例）

Q: 429 限速了怎么办？

RateLimitError: Error code: 429 - {'error': {'code': '1302', 'message': 'Rate limit reached'}}

GLM-5 刚上线，免费档限速比较严。要么升级付费套餐提高 QPS，要么做客户端侧的指数退避重试。我目前设的是 retry 3 次，间隔 1s/2s/4s。

Q: 能用 Cursor / Cline 这些工具直接调 GLM-5 吗？

可以。只要工具支持自定义 base_url + model name，填上 https://open.bigmodel.cn/api/paas/v5/ 和 glm-5-turbo 就行。我在 Cline 里测过，正常工作。

小结

GLM-5 云端版和开源版的 API 层差异集中在三个地方：base_url 从 v4 变成 v5、Token 沿用 GLM-4 起的 JWT 格式、model name 必须带 -turbo 后缀。第三点最坑，因为不带后缀不报错只是无提示降级，不注意的话可能跑了好几天都没发现用的是旧模型。

我也不确定智谱后续会不会把 glm-5 这个 model name 直接指向最新版本，目前的行为确实反直觉。先按这篇配置跑起来，后面有更新我再补充。