AI 推理模型参数怎么迁移：从 max_tokens 到 max_completion_tokens 的兼容检查

把普通聊天模型切换到推理模型后，最容易被忽略的不是模型名，而是输出上限的语义已经变了。旧请求里的 max_tokens 可能直接不兼容，换成 max_completion_tokens 也不能只做字符串替换：推理 token 会占用同一个上限，原来能完整返回的回答可能变成截断。

一次模型切换为什么会让旧请求失效

线上服务通常把请求参数封装在一个公共结构里。以前所有模型都传 max_tokens，切到推理模型时，接口可能返回参数不支持，或者客户端虽然接受了字段，服务端却按新模型规则拒绝请求。OpenAI 当前的 Chat Completions 参考把 max_tokens 标为弃用，并说明它不兼容 o 系列模型；推荐使用 max_completion_tokens。

这不是简单的参数改名操作。新的上限规则同时覆盖对外返回的可见回答和模型内部隐式执行的推理 token，同样的预算配额下，模型分给内部推理过程的资源越多，留给用户最终可见文字的输出空间就越小。

先把旧参数和新语义分开

可以先把两种请求逻辑拆成两个明确的配置分支，不要在调用前不加判断就直接无条件追加字段：

type GenerationLimit struct {
    LegacyMaxTokens *int
    CompletionLimit *int
}

func buildLimit(model string, n int) map[string]int {
    if strings.HasPrefix(model, "o") {
        return map[string]int{"max_completion_tokens": n}
    }
    return map[string]int{"max_tokens": n}
}

示例只用来演示迁移思路，生产环境的代码最好把模型能力表做成可配置项。不要只靠模型名的字符串前缀做长期判断，不然等服务商更新了新的命名规则，参数选择逻辑会在你完全没感知的情况下失准。

更稳妥的方案是把“模型—参数能力”对应关系放进独立配置，在服务启动自检阶段就主动拦截未知模型。这样后续升级模型版本的时候，你能拿到明确的告警提示，不用等到线上请求偶尔随机失败再排查问题。

预算要按完成结果重新估算

旧系统常用“回答最多 800 token”来解释 max_tokens=800。对推理模型，这个说法不再准确。新的数值更接近完成过程的总预算，至少要同时观察可见输出和推理部分的用量。

迁移落地的时候可以先准备三组测试样本：普通短问答场景、带工具返回结果的中等复杂度任务、需要多步链式推理的长任务。每组都固定输入内容，分别统计总消耗token、用户可见的完成token、如果接口返回明细的话还要单独统计推理token，同时记录每一次请求的结束原因。用真实业务的分布数据调试预算值就好，不用直接把旧参数乘一个看着合理的固定倍数硬套。

if finishReason == "length" {
    metrics.Inc("ai_response_truncated")
    // 记录本次模型、预算和 usage，交给回滚或扩容策略判断
}

如果服务商接口只返回总usage数据，就把它和实际返回的响应长度、请求结束原因一起落地留存。不能光凭返回的文字看起来完整，就断定没有发生预算截断；也不要把模型内部生成的推理token当成用户可见的内容直接拼到返回结果里。

兼容性验收要看四个证据

请求层：字段是否被模型接受

给每个目标对接的模型发一次最小测试请求，记录对应的HTTP状态码、错误类型和模型唯一标识。测试请求能成功不代表返回的语义完全符合预期，但如果请求层直接报错，肯定是你的能力表配置或者参数分支逻辑出了问题，需要优先修正。

结果层：结束原因是否稳定

重点核对正常完成和长度触发截断的请求占比。如果用的是流式响应，还要确认每一次请求的结束事件都正常到达，不能只看前端已经展示出了一部分文字就判定整个请求正常结束。

用量层：预算是否挤压回答

把总token消耗量和用户可见的完成token分开统计，对比迁移前后两个版本的p50、p95耗时和截断率变化。单条请求跑通没法证明预算设置足够覆盖所有场景，至少要把高峰时段的典型输入、最长的业务处理分支都覆盖到。

回滚层：旧模型是否仍可恢复

旧版模型的参数构造逻辑不要直接删掉，但不要让它和新逻辑混在一个没有明确注释的默认值判断里。回滚验收要确认三个点：旧模型的请求仍然可以正常发送、新模型不会再收到旧的参数字段、监控标签可以明确区分新旧两条调用路径。

常见误区与回退边界

第一种误区是把 max_completion_tokens 当成“用户答案字数上限”。它还受推理过程消耗影响，应该和模型、任务复杂度一起调。第二种误区是只检查 HTTP 200，不检查结束原因和 usage。第三种误区是把所有模型都强行改成新字段，忽略仍使用旧接口契约的模型。

上线初期建议给新的调用路径配置独立的监控指标和小流量开关：请求接受率、长度触发结束的占比、平均总token消耗、平均可见token消耗、各类型错误的占比都能单独观测。如果发现截断率或者接口成本超出预期，先切回之前已经验证过的模型-参数组合，再根据之前攒的测试样本调整新的预算数值就好。

相关问题

把预算调大就一定能解决截断吗？

直接把旧max_tokens值原封不动赋值给max_completion_tokens不一定能跑通。输入上下文长度、模型本身的上下文窗口上限、工具返回结果的长度、服务商侧的硬限制都会影响最终可用的配额，先确认到底是哪一层逻辑触达了上限，再针对性调整预算。

普通模型也应该马上改用新字段吗？

参数设置标准要以你对接的目标模型和官方接口文档为准。这次迁移的核心是做好能力匹配和可验证的回退机制，不是全量替换所有旧字段名就完事。

为什么同一个问题每次用量不完全相同？

不同版本的推理路径可能存在差异，采样策略、工具调用逻辑、上下文长度的波动都会改变最终的总token用量。用一组固定的覆盖全场景的样本看整体分布变化，比盯着单次请求的结果调整要靠谱得多。

总结

这次迁移真正要调整的其实是底层的预算模型：从之前只估算用户可见的回答长度，转向同时管理模型内部推理过程和最终输出两部分的配额。把模型能力配置表、请求结束原因统计、usage明细埋点和快速回滚开关一起纳入验收标准，你才能确认这次参数改动是真正的兼容升级，而不是把潜在的截断问题延后到生产环境暴露。