LLM SDK 升级税：为什么补丁版本更新实际上是一次伪装的模型发布

我上个季度合作的一个团队在周二凌晨 2:14 向生产环境推送了一个回归错误。值班警报触发了，因为其摘要代理（summarization agent）下游的 JSON 解析器以“尾随逗号错误”拒绝了二十分之一的响应。模型没变。提示词（prompt）没变。评估套件在前一天晚上的通过率为 96.4%，稳稳高于 95% 的准入门槛。改变的只是 package.json 中的一行：模型提供商的 SDK 从 4.6.2 升级到了 4.6.3。补丁更新（Patch bump）。由依赖机器人自动合并。发布说明里写着“内部清理”。

所谓的“内部清理”是一个收紧的 JSON 模式解析器，它删除了一个宽容的后备路径，而这个路径此前一直在默默修复模型工具调用输出中反复出现的尾随逗号怪癖。模型的行为没有改变。但 SDK 对该行为的解释改变了。团队的评估套件从未发现这个回归，因为评估套件运行的 SDK 版本与依赖机器人刚刚推送的版本不同。

这就是 LLM SDK 升级税，它是当今生产环境 AI 中最隐蔽、代价最昂贵的故障模式之一。SDK 不是被动的传输工具。它是你提示词行为的积极参与者，而那些在没有评估的情况下升级 SDK 的团队，实际上是在进行一场伪装的模型发布。

SDK 处于提示词的关键路径上

当工程师谈论“提示词”时，他们通常是指自己编写的字符串。但实际上离开你的进程并到达提供商边缘的字节流包含了几层并非由你的代码创作的内容：

• 当没有提供系统提示词时，SDK 注入的默认系统提示词前缀
• 工具模式（tool schemas）的确切序列化方式（键的顺序、可选字段处理、JSON-Schema 方言、转义规则）
• 多模态内容块的框架结构
• 停止序列（stop sequences）、采样参数和元数据字段的编码
• 将流式响应转回结构化 Python 或 TypeScript 对象的解析规则

其中任何一项都可能导致行为变化。一个收紧的工具模式序列化器可以将你的 additionalProperties: false 从隐式变为显式，模型会将其解读为更严格的契约，并开始拒绝以前可以通过的边缘输入。一个新的系统提示词前缀可以使模型的默认语气变得更加谨慎，以前直接给出答案的代理现在可能会用“我无法确定，但是……”来推诿。流式分块边界的调整可能会以你的累加器（accumulator）未准备好的方式将工具调用拆分到两个事件中。这些都不是模型中的 bug。也不是你提示词里的 bug。它们源于一个错误的假设：SDK 仅仅是一根电线。

今年早些时候的 Anthropic Python SDK 变更日志发布了一个关于查询和表单序列化的内部更改，切换到了索引数组格式。Vercel 的 AI SDK 发布了多个次版本，调整了 Anthropic 工具调用被规范化为其供应商无关形态的方式。OpenAI Python SDK 在一个次版本中更改了 stream_options.include_usage 分块的发射方式，导致下游那些假设每个流只有一个用量事件的累加器必须进行修复。这些更改都没有被标记为行为变化。但对某些人来说，它们全都是行为变化。

为什么 Dependabot 自动合并会掩盖它

大多数团队的默认策略对于普通依赖项是合理的：如果是补丁或次版本更新，CI 通过就自动合并；主版本更新则由人工审核。这一政策建立在一个承重假设之上——即“CI 通过”是行为兼容性的强信号。对于日志库或日期工具，通常确实如此。但对于 LLM SDK，事实并非如此，因为评估套件并不是依赖更新 CI 路径的一部分。

评估套件运行缓慢。需要花钱。会调用真实的模型。因此它通常在每晚运行，或者在发布标签版本时运行，或者在提示词仓库更改时运行。而依赖更新流水线在每个 PR 上运行，耗时四分钟，并针对模拟的（mocked）SDK 响应运行单元测试。这些模拟响应是根据旧版本 SDK 生成的。由于模拟的表面（mocked surface）没有改变，它们在面对新版本时依然能通过。但实际的线路格式和解析逻辑已经变了。在流量进入生产环境之前，回归错误是不可见的。

加载中…