GLM API 的接入成本比很多人想象得低：它提供 OpenAI 兼容接口，现有 OpenAI SDK 通常只需要改三处——API Key、Base URL 和模型名。真正的坑不在“能不能调通”，而在模型名是否有效、流式输出怎么处理、工具调用返回什么格式，以及从 OpenAI 迁移时哪些参数不能照搬。
本文用一条最小请求把链路跑通，再补充流式、工具调用、报错排查和迁移清单。所有示例都可以直接替换 Key 后运行。
说明：智谱、GLM、BigModel 是相关权利人的商标，本文仅作技术说明，与智谱无隶属、代理或授权关系。Base URL、模型名、上下文长度与计费口径可能调整，请以智谱开放平台官方文档和站内模型价格为准。
一、接入前准备
开始前确认三样东西：
- 一个可用的 API Key，且类型与要调用的接口匹配。
- 正确的 Base URL，官方直连与网关地址不能混用。
- 一个当前真实可用的模型名，不要照抄旧文章里的示例。
如果是新项目，建议先用 curl 验证鉴权和网络，再接入 SDK。这样出错时容易判断是 Key、地址还是代码问题。
二、Base URL 怎么填
智谱官方 OpenAI 兼容接口的 Base URL 通常写作：
https://open.bigmodel.cn/api/paas/v4
中商起航 AI 网关的 OpenAI 兼容地址是：
https://ai.zhongshangqihang.com/v1
两者都按 OpenAI 的 /chat/completions 路径拼接。注意不要在代码里重复拼接版本段或 /chat/completions，也不要在末尾随意加减斜杠后混用。
| 接入方式 | Base URL 示例 | 适用场景 | 注意事项 |
|---|---|---|---|
| 智谱官方 | https://open.bigmodel.cn/api/paas/v4 |
只用 GLM、要最新功能 | 需官方账号与余额 |
| 中商起航网关 | https://ai.zhongshangqihang.com/v1 |
多模型统一入口、统一账单 | 需在网关创建 Key |
三、模型名怎么选
GLM 系列按能力分为文本、视觉、语音、向量等类别。文本模型里又有不同档位：有的偏向通用对话与 Agent，有的偏向低延迟和高并发，有的支持更长的上下文。以官方文档当前列出的 GLM-5 系列为例，常见写法包括 glm-5.3、glm-5.3-flash、glm-5.2 等，但模型会持续更新，实际可用名称请以控制台和模型价格页为准。
选型时不要只看“最强”。客服问答、批量分类这类任务，用低延迟档位往往更划算；长文档分析、复杂 Agent 再上高配。把模型名做成配置项，而不是写死在代码里，后续切换会轻松很多。
如果任务涉及图片理解，要选择支持视觉输入的模型；涉及向量检索，则使用 embedding 系列。文本、视觉、向量模型的接口路径和参数并不完全相同，不要用同一个请求体硬套。上线前把候选模型放进同一套评测集，比较准确率、延迟和用量，再决定主力与备用。
四、用 curl 跑通第一次调用
先准备环境变量，避免 Key 出现在命令历史里：
export GLM_API_KEY="your_key_here"
curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
-H "Authorization: Bearer $GLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"messages": [
{"role": "system", "content": "你是一名简洁的技术助手。"},
{"role": "user", "content": "用三句话解释什么是 API 网关。"}
],
"temperature": 0.6
}'
返回正常时，重点看三个字段：choices[0].message.content 是回答，usage 是本次用量，finish_reason 表示结束原因。如果返回 401，先查 Key 和请求头；如果返回 1211，先查模型名。
五、用 Python SDK 调用与流式输出
OpenAI SDK 需要 1.0 以上版本。把 Base URL 指向 GLM 后，调用方式与 OpenAI 基本一致：
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url="https://open.bigmodel.cn/api/paas/v4",
)
stream = client.chat.completions.create(
model="glm-5.3",
messages=[{"role": "user", "content": "写一段产品介绍，不超过一百字。"}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
流式输出要注意：首个 chunk 可能只有角色信息，content 为空；不要假设每个 chunk 都有文本。开启思考模式时，推理内容可能出现在 reasoning_content 字段，最终回答仍在 content，两者要分开处理，避免把推理过程直接展示给终端用户。
六、工具调用与参数差异
工具调用沿用 OpenAI 的 tools 和 tool_choice 格式。模型返回 message.tool_calls 后，需要把每个调用的 function.arguments 按 JSON 解析，执行本地函数，再把结果以 tool 角色消息回传。生产环境要做参数校验和超时控制，不能直接信任模型生成的参数。
从 OpenAI 迁移时有几个差异要留意：temperature 的取值范围通常是 0 到 1 之间，传 0 可能不生效；默认值约为 0.6；部分新能力需要通过 extra_body 传参。具体参数以官方 OpenAI 兼容文档为准。
流式场景还要处理客户端断开。用户关闭页面后，服务端应尽快取消上游请求，避免继续生成和计费；如果业务必须完整生成，就把任务转到后台队列，不要依赖前端连接。
七、常见错误对照
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 401 / 1000 | Key 错误、类型不匹配 | 核对 Key 类型与请求头 |
| 1211 | 模型名不存在或未开通 | 查控制台可用模型 |
| 1261 | 输入超过上下文限制 | 压缩提示词或分段 |
| 1302 / 1305 | 账户限流或平台繁忙 | 降并发、退避重试 |
| 1113 | 账户欠费 | 充值后重试 |
| 连接超时 | DNS、代理或网络路径 | 先用 curl 定位网络层 |
重试只对 429、5xx 和网络超时有效。401、1211、1261 这类错误重试不会变好，反而浪费时间和额度。
八、从 OpenAI 迁移的检查清单
- 备份现有提示词、模型参数和评测集。
- 新建 GLM 专用 Key，不要复用其他厂商的 Key。
- 把 Base URL 和模型名改为配置项。
- 用同一批样本对比输出质量、延迟和用量。
- 检查流式解析、工具调用和 JSON 输出是否兼容。
- 调整重试、超时和并发，观察一周再切全量。
九、常见问题（FAQ）
1. GLM API 完全兼容 OpenAI 吗？
大部分常用接口兼容，但仍存在参数范围、思考字段和部分高级能力的差异。建议按官方 OpenAI 兼容文档逐项验证，不要假设所有参数行为一致。
2. Base URL 末尾要不要加斜杠？
官方文档中带斜杠和不带斜杠的写法都出现过，SDK 通常会自动处理。关键是不要重复拼接路径，选一种写法并在项目内统一。
3. 流式输出能拿到推理过程吗？
部分模型在思考模式下会返回 reasoning_content。是否需要展示取决于产品设计，面向终端用户时通常只展示最终回答。
4. 工具调用和 OpenAI 格式一样吗？
工具定义和返回结构基本沿用 OpenAI 格式，但参数细节可能随模型变化。上线前用真实工具做一轮回归测试。
5. 官方和网关的模型名一样吗？
多数情况下沿用同一套模型名，但网关是否开通某个模型、是否支持某个参数，要以网关控制台和模型价格页为准。
