GLM 的 OpenAI 兼容层边界：哪些参数它不认

2026-08-25

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

智谱官方的说法是：改 API Key 和 base_url 两处，现有 OpenAI SDK 代码就能跑起来。这句话是对的，但它描述的是「起步成本」，不是「等价性」。官方在同一页里挂了一条警告：某些场景下智谱与 OpenAI 接口仍存在差异。真正会咬人的地方有三类——你在 OpenAI 那边习惯用的一些参数，在智谱全站文档里根本找不到说明；智谱原生有而 OpenAI SDK 形参里没有的字段（thinking、do_sample、reasoning_effort 这些），得靠 extra_body 透传；还有一批同名参数，取值范围和可选项跟 OpenAI 侧的习惯不一样。响应侧同样有边界：finish_reason 的取值比 OpenAI 客户端代码通常处理的要多。把这三类过一遍，迁移基本就不会在半夜炸。

先弄清「兼容」兼容到哪一层

官方 OpenAI 兼容页给的迁移动作只有两步：把 api_key 换成智谱平台申请的 Key，把 base_url 指到 https://open.bigmodel.cn/api/paas/v4/。环境要求写得很具体：Python 3.7.1 或更高版本，OpenAI SDK 版本不低于 1.0.0，官方还专门加了一条警告说旧版本可能存在兼容性问题。

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("ZAI_API_KEY"),
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

官方建议用环境变量而不是硬编码，文档里给的变量名是 ZAI_API_KEY。这一层做完，chat.completions.create、流式迭代 chunk、tools 与 tool_calls 的基本形状都跟 OpenAI 一致，多轮对话、函数调用、图像理解（用 image_url 传 base64 data URL）官方都给了可直接照抄的示例。

所以「兼容」兼容的是调用形状：路径、鉴权头、请求体骨架、响应体骨架。它不承诺参数集合完全一致。下面按三类边界拆。

边界一：OpenAI 有，但智谱文档里查不到的参数

这是最容易出事的一类，因为它不报错在你眼前——你传了一个参数，代码照跑，然后你以为它生效了。

把智谱官方文档全站翻过一遍，frequency_penalty、presence_penalty、logprobs、seed、logit_bias 这几个 OpenAI 侧的常客，在官方文档里没有找到任何相关说明。原生对话补全接口的请求 schema 里也没有列出它们。

response_format 那边同理但更微妙：智谱原生 schema 里 response_format.type 的枚举只列了 text 和 json_object 两个取值，没有找到关于 json_schema 的说明。如果你在 OpenAI 那边用的是带 JSON Schema 的结构化输出，直接平移过来这条路是断的，得退回到 json_object 加提示词约束的写法。

parallel_tool_calls 也值得单说：这个字段在智谱文档里只出现在微调训练数据格式的说明中，对话补全接口的请求 schema 里没有列出它。

我的处理原则很简单：官方文档里没写的参数，就当它不存在。不要因为「传过去没报错」就认为它生效了——服务端忽略未知字段是很常见的行为，而你根本没有办法从返回体里看出来它到底有没有被采纳。真要确认，只能去看官方文档的参数表，或者直接问智谱的技术支持。

边界二：智谱有，但 OpenAI SDK 形参里没有的字段

这一类反过来：智谱原生请求体里有一批字段，OpenAI SDK 的方法签名里没有对应的形参。官方给的解法是 extra_body，兼容页的推理小节直接用这个写法把智谱的原生参数带进请求。

官方在兼容页的推理（thinking）小节里给了完整写法：

response = client.chat.completions.create(
    model='glm-5.2',
    messages=[...],
    stream=True,
    extra_body={
        "thinking": {
            "type": "enabled",
        },
    }
)

需要走 extra_body 这条路的原生字段，从对话补全的官方 schema 里能数出这么几个：

thinking：控制是否开启思维链，官方标注仅部分模型系列支持该参数配置，取值是 enabled / disabled
thinking.clear_thinking：控制是否清除历史对话轮次里的 reasoning_content。官方对 false 的说明写得很硬——要保留历史思考内容，就必须在 messages 中完整、未修改、按原顺序透传历史 reasoning_content，缺失、裁剪、改写或重排会导致效果下降或无法生效
reasoning_effort：控制推理程度，thinking 开启时生效，官方给的枚举是 max / xhigh / high / medium / low / minimal / none（枚举取值以官方文档为准），并且不同模型系列对这些档位的映射规则不同——同一个档位传给不同系列，落到的实际推理强度未必是同一个
do_sample：是否启用采样策略
tool_stream：是否开启流式响应的 Function Calls，官方标注仅部分模型系列支持
request_id 与 user_id：请求唯一标识与终端用户标识，官方对两者都规定了字符长度区间，request_id 未提供时平台会自动生成

request_id 这个字段被低估了。它会原样出现在非流式响应体里，出问题时拿着它去找官方支持，比描述「大概几点钟那次调用」有效得多。这也是 OpenAI 那边没有的东西。

边界三：同名参数，约定不一样

同名不同义比缺失更阴险，因为它一定会跑通，只是行为跟你预期的不一致。

temperature 与 do_sample。 官方兼容页参数表下面挂了一条注意事项，原文说 temperature 参数的区间为 (0,1)，并且 do_sample = False（temperature = 0）在 OpenAI 调用中并不适用。原生 schema 里 temperature 的取值范围写的是 0 到 1、限两位小数（以官方文档为准）。也就是说，你在 OpenAI 那边靠 temperature=0 做确定性输出的习惯，搬到这边不成立——智谱把「不采样」拆成了独立的 do_sample 开关，而这个开关又不是 OpenAI SDK 的标准形参，得走 extra_body。

默认值不要靠记忆。 官方 schema 里 temperature 和 top_p 的默认值按模型系列分别给出，各系列并不相同。这意味着两件事：一是别拿某一个模型的默认值去套另一个；二是对输出稳定性有要求的场景，把这两个参数显式写进请求里，别依赖默认。具体默认值以官方文档当前版本为准。另外官方反复强调，temperature 和 top_p 建议调其中一个，不要同时调。

tool_choice。 智谱原生 schema 对这个字段的描述是：默认 auto 且仅支持 auto。OpenAI 那边常用的强制调用某个具体函数、或者显式禁用工具的写法，在智谱官方文档里没有找到对应说明。依赖「强制走某个工具」这套编排的代码，迁移时要重新设计。

stop。 兼容页的参数表把 stop 写成 string 或 array，而原生 schema 里 stop 是字符串数组并且带条数上限（上限值以官方文档为准）。写成单个字符串的老代码，建议统一改成数组，省得两边表述不一致时踩坑。

tools 不止 function 一类。 原生 schema 里 tools 可以是四类之一：函数调用、知识库检索、网络搜索、MCP 工具（对应官方的 FunctionToolSchema、RetrievalToolSchema、WebSearchToolSchema、MCPToolSchema 四个 schema，取值以官方文档为准）。非流式响应里 assistant 消息的 tool_calls，type 枚举相应给了 function、web_search、retrieval 三个取值；而流式 chunk 的同名字段，schema 里的描述写的是目前支持 function，枚举也只列了 function 这一个（均以官方文档为准）。这个差异值得记一笔：同一份解析逻辑，跑非流式和跑流式面对的取值集合并不一样。从 OpenAI 那边平移过来的解析代码通常默认 type 恒等于 function，用到检索或网络搜索工具时，这个假设就不再成立。

响应侧的边界：finish_reason 和多出来的字段

请求侧对齐了不代表解析代码不会挂。

finish_reason 的取值比你想的多。 官方 schema 的枚举列出了 stop、length、tool_calls、sensitive（内容被安全审核接口拦截）、network_error（模型推理异常）五个取值，字段描述里还提到了 model_context_window_exceeded（超出模型上下文窗口）——描述比枚举多出一个，取值以官方文档为准。一份只 if finish_reason == "stop" 的老代码，遇到 sensitive 会安静地把空内容当成正常结果返回给用户。官方对 sensitive 的措辞是让用户自行判断并决定是否撤回公开内容——这句话的分量，做内容型产品的应该能掂出来。

content_filter 是智谱响应侧多出来的字段。 它是个数组，标注了安全生效环节（assistant 表示模型推理、user 表示用户输入、history 表示历史上下文）和严重程度 level。如果你的解析代码是照着 OpenAI 的响应结构写的，它多半根本不会去读这个数组——字段会安静地落进解析对象的额外字段里，不报错也不提醒。想让安全拦截可追溯，就得主动把它取出来打进日志。

usage 的结构也有差异。 非流式响应的 usage 里除了 prompt_tokens、completion_tokens、total_tokens，还有 prompt_tokens_details.cached_tokens，也就是命中的缓存 token 数量——这是核对账单和验证缓存策略的关键字段，具体怎么用见GLM 上下文缓存怎么才能命中。而流式 chunk 的 usage schema 里，官方只列出了三个基础计数字段，没有列出 prompt_tokens_details。所以想按缓存命中做成本核对的，别只在流式链路上取数。

reasoning_content 在 delta 上。 官方流式示例直接访问 chunk.choices[0].delta.reasoning_content 来打印思维链，这同样是智谱侧多出来的字段。写法上要做好属性不存在的兜底：思维链要开了 thinking 才有，而 thinking 本身官方标注了仅部分模型系列支持，同一段代码换个模型就可能取不到这个属性。官方对该字段的模型支持范围有标注，以官方文档为准。

迁移时按什么顺序检查

给一个可以直接照做的顺序：

先把参数字典打出来。把你现在传给 OpenAI 的全部参数列一遍，逐个去智谱官方文档里搜。搜不到的，删掉或换实现，别抱侥幸。
再处理 extra_body 清单。thinking、do_sample、reasoning_effort、tool_stream、request_id、user_id 这些原生字段，需要哪些就统一收进一个 extra_body 构造函数，别散落在各处。
然后改解析代码。finish_reason 的分支补全，content_filter 做好日志，reasoning_content 做属性兜底。
最后才是模型选型和成本。计费口径和缓存机制是另一条线，可以对照换厂商迁移检查清单逐项过；Key 的管理方式也建议顺手收敛，见API Key 安全管理。

最容易栽的坑，我认为不是上面任何一条具体差异，而是**「跑通了就等于迁移完了」这个错觉**。官方对兼容层的定位写得很清楚，是零学习成本、快速迁移，目标就是让你尽快看到第一个正确响应。但同一页上那条警告也写得明白：某些场景下智谱与 OpenAI 接口仍存在差异。第一个正确响应能验证的只是连通性，验证不了采样行为一致、工具编排能落地、安全拦截被正确处理。真要上生产，把参数字典和响应分支这两张表补齐，比多凑几个 demo 有用得多。遇到报错先按错误码走，可以参考GLM API 报错排查。