你原本跑得好好的智能体工作流，某天换了模型或中转线路，就开始报字段错、工具调不动、输出格式对不上，甚至整条链断在中间。问题往往不在「模型变笨了」，而在参数、协议、提示词和工具契约几个环节没跟着调。这篇按排查顺序讲清失效原因和兼容改法，并说明哪些情况下重写反而比修补更省事。
你原本跑得好好的智能体工作流，某天换了模型或换了中转线路，就开始报字段错、工具调不动、输出格式对不上，甚至整条链断在中间。第一反应通常是「模型变笨了」，但多数情况跟能力无关，是参数、协议、提示词和工具契约几个环节没跟着调。
下面按排查顺序讲：先分清跑不动属于哪一类，再逐个环节对差异，最后给可回退、可灰度的兼容改法。也会说清什么情况下重写比修补更省事。判断类结论都有适用范围，别照搬。
先分清是哪一类跑不动
把所有故障混在一起查，是最费时间的做法。先按现象归类：请求直接被拒、工具调用失效、结构化输出格式崩、能跑通但结果质量下降。前两类是协议和参数问题，后两类才更可能涉及提示词和模型风格。归类错了，后面每一步都白做。
| 现象 | 大概率原因 | 先查什么 |
|---|---|---|
| 直接报错（400/401/404） | 鉴权、路径、必填字段或模型名不匹配 | 请求体最小化后逐字段删减对比 |
| 工具调不动 | 函数声明 schema 不被接受或返回结构变了 | 导出工具 schema 逐字段核对 |
| 输出格式崩 | 提示词约束失效或没启用严格模式 | 换工具调用或严格模式约束输出 |
| 能跑但质量差 | 指令遵循风格变化、上下文被截断 | 固定用例对比新旧输出差异 |
- 固定一条最小复现请求把整条工作流砍到只剩一次模型调用加一个工具，确认它单独能跑。跑不通就先修这一条，别拿全链路当试验田。
- 记录报错原文把原始错误响应、请求体、时间点一起存下来。中转线路的报错经常被前端包装过，原始信息才有用。
- 单变量替换一次只换一个变量：模型、线路、提示词、工具声明。换完立刻重跑最小复现请求，确认是哪一步引入的问题。
参数与工具契约的漂移
新模型对必填字段、枚举值、嵌套层级往往更严格。老提示词里那些「差不多就行」的写法，比如漏一个字段、枚举写成中文、少包一层对象，以前被宽容接受，升级后就直接被打回。这不是模型退化，是校验变紧了。
工具调用这块，函数名大小写、参数类型、是否要求 JSON Schema 的完整声明，不同来源的接受范围不一样。换模型前先把工具声明导出成一份对照清单，逐字段过一遍。工具调用相关的常见坑，站内已有排查文章讲得比较细，可以对着看，这里不重复。
- 导出当前所有工具的 schema，存成文件当基线
- 逐字段标注：必填、类型、枚举、是否允许额外字段
- 对新线路跑一组最小工具调用，看返回结构是否一致
- 把不兼容字段改成两端都能接受的写法，实在不行加适配层
- 改动后回归跑一遍固定用例，确认没有引入新问题
如果工具多、字段杂，别指望一次全改对。先改最常被调用的那几个，剩下的按错误率排序处理。判断标准很简单：哪个工具在日志里报错最多，先动哪个。
提示词与输出格式要跟着改
模型升级后指令遵循风格会变。原来写「第一步做 A，第二步做 B」可能被合并成一步，或者某个中间步骤被跳过。表现是流程还在跑，但关键节点没执行。这种情况要把提示词拆细，把必须执行的步骤写成硬性约束，而不是指望模型自己按顺序走。
结构化输出优先用工具调用或严格模式约束，比在提示词里反复强调「请输出 JSON」稳得多。提示词约束属于软约束，模型状态一波动就崩；工具调用和严格模式是硬约束，解析失败会明确报错，不会静默产出错格式。
改提示词前先跑一组固定用例，把新旧版本的输出并排对比。凭感觉判断新版本是好是坏，很容易把偶发波动当成趋势。哪些模型在工具调用和结构化输出上表现更稳，可以到 /rankings 核对当时的评测结果，别只看参数表。
兼容层与切换策略
切换前先确认协议差异：走的是 OpenAI 兼容还是 Anthropic 兼容，字段保留和缺失情况不一样。有的中转线路对某些字段是透传，有的是丢弃，有的是改写。这些差异不看文档看不出来，只能靠实测。
- 摸清协议边界同一份请求分别打主线和备用线，对比返回字段。差异项记下来，作为适配层要处理的清单。
- 加降级路由主模型失败时自动切备用源，避免单点把整条工作流拖死。降级要有超时和重试上限，否则会雪崩。
- 小流量灰度新模型先放一小部分流量，观察错误率和输出质量。指标稳定再逐步放量，出问题一键回滚。
- 保留回滚开关回滚不是换回旧模型就完事，提示词和工具声明也要能一起切回去。配置化，别写死在代码里。
哪些中转线路稳定、响应快，属于会变的动态信息，到 /sites 看当时的检测结果和追踪数据，别拿几个月前的印象做决定。
什么情况下别修，直接换
不是所有失效都值得修。如果工作流依赖长上下文、特定工具调用格式或强推理链路，硬兼容的成本可能高于重写。判断方法：估算改动涉及的提示词、工具声明、适配层和测试用例总量，如果接近重写，就别修了。
还有一种情况是模型换代连能力定位都变了，比如从通用对话变成偏推理或偏多模态。这时候勉强对齐参数只是把问题往后推，早晚还要面对。先明确工作流真正依赖的是哪项能力，再决定是迁就新模型还是换回合适的。
自建部署和调官方 API 的判据不一样。自建要考虑推理环境、量化精度和并发能力，调 API 主要看协议兼容和稳定性。成本怎么算、各家当前什么水平，到 /price-watch 核对当时的数字，别凭记忆估。
最后给一个简单排序：报错类先查协议和参数，工具失效查 schema，格式崩查约束方式，质量下降查提示词和上下文。按这个顺序走，大部分问题能在一轮内定位。定不下来的，先回滚保住线上，再慢慢查。
下一步想确认手上这条线路的兼容情况和稳定性，直接去中转站目录看实测记录，比反复试错快。→常见问题
模型升级后工作流突然全部报错，第一步该查什么？
先固定一条最小请求单独发，确认是鉴权、字段还是模型本身的问题。多数情况是请求体里出现了新模型不接受的字段，或者工具声明的参数类型对不上。把报错原文和请求体放在一起看，比盯着整条工作流猜要快得多。
能不能不改工作流，只换个便宜的模型继续跑？
要看你的工作流对格式和工具调用的依赖有多重。如果只是纯文本问答，换模型多半能直接跑；但只要涉及结构化输出、多步工具调用，通常得跟着调提示词和 schema，否则会在某个节点静默出错，比直接报错更难查。
怎么判断是模型的问题还是中转线路的问题？
同一请求分别打官方通道和你用的中转站，比对返回内容与延迟。也可以到站内工具页先量出延迟基线，再判断是网络抖动还是模型行为变化，两者处理方式完全不同。
