6 篇博文 含有标签「versioning」

当你为人类开发人员弃用一个 API 时，你会为此举行一整套“仪式”。你提升版本号，在 OpenAPI 规范中添加 deprecated: true，发送 Sunset HTTP 响应头，向开发人员邮件列表发送邮件，发布变更日志，并给人们六个月的时间进行迁移。信号到达阅读它的开发人员，他们提交工单，并在旧路径消失之前更新他们的客户端。

现在，将同样的弃用通知指向一个智能体。调用你工具的模型不会阅读你的变更日志，它不会订阅你的邮件列表。它永远看不到 Sunset 响应头，除非你刻意将其放在模型会查看的地方，即便如此，它也没有可靠的习惯去据此行动。你精心编写的弃用通知落入了一个没有读者的信箱。智能体会一直调用工具的旧形式，直到该形式彻底消失，然后它就会失败——通常是静默失败，通常是在生产环境中，通常是在凌晨 2 点。

这就是为智能体而非人类构建工具时所存在的隐性不对称。我们在 API 演进的二十年里建立的每一项准则，都假设在弃用和迁移之间坐着一个人类。把人类拿掉，整个机制就会失效。

你完美地执行了弃用指南。提前六个月发布公告邮件。包含四种语言代码示例的迁移指南。在每个 v1 响应中添加了 Sunset 响应头。开发者仪表板上的横幅。两封提醒邮件。然后你关闭了 v1 —— 但结果并非指南所承诺的安静切换，你的错误率直线飙升并维持在高位。流量没有迁移。它只是不断涌入、失败并重试，且容量比以前更高，因为每一次失败都触发了另一次尝试。

指南之所以失败，并不是因为你执行得不好。它的失败是因为它假设另一端是一个人类 —— 一个会阅读邮件、浏览变更日志并在截止日期前提交 Jira 任务进行迁移的人。你很大一部分流量背后已经没有这样的人了。它来自智能体 (Agent)，它们对你 API 的认知被冻结在系统提示词、工具 schema 以及散布在成千上万个你看不见也永远无法触达的代码库中的模型训练数据里。你的停用通知是写给读者看的。而你的最大客户端是一个 Prompt。

一个平台团队对他们的摘要服务的系统提示词（system prompt）进行了一行细微的调整。没有代码审查，没有迁移指南，没有版本更新——这“仅仅是一个提示词”。两周后，法律产品团队发现他们的合规自动脱敏功能一直在静默地泄露姓名。调查耗费了一个冲刺（sprint）。修复很简单。损害的是信任。

这是 AI 变更日志问题的缩影。行为现在是你系统的一等输出（first-class output），当提示词、模型、检索器或工具模式（tool schemas）发生变化时，行为也会随之改变——而这些变化都不会出现在消费方应用的 git diff 中。如果团队像对待后端部署那样对待 AI 更新，认为在 #releases 频道发一条 Slack 消息就足够了，那么他们最终会重蹈 2010 年代早期那种“我们先上线，稍后再告诉 QA”工作流的覆辙。

你的 /v1/summarize 端点在 18 个月里运行得非常完美。然后你升级了底层模型。输出格式没变，JSON schema 完全一致。但你的下游消费者开始提交 bug：摘要“太随意了”，要点“详细得诡异”，边界情况下的拒绝响应“变得不同”。从传统意义上讲，一切都没坏；但在 AI 的语境下，一切都坏了。

这是 REST 和 GraphQL 从未被设计用来解决的版本控制问题。传统的 API 合约假设确定性：相同的输入总是产生相同的输出。而 AI 端点的合约是概率性的——它包括语气、推理风格、输出长度分布以及拒绝阈值，当你更换或更新底层模型时，所有这些都可能发生漂移。对于以数据库为支撑的 API 有效的技术，对于以 AI 为支撑的 API 是必要但不充分的。

你上周二发布了一个智能体。代码库没有任何改动。到了周四，它开始拒绝之前已经可靠处理了好几周的工具调用。你的 git 日志是干净的，测试全部通过，CI 流水线一片绿色。但智能体坏了——而且你没有可以回滚的版本，因为真正发生变化的东西根本不在你的代码仓库中。

这就是智能体版本控制的核心悖论：你追踪的制品（代码、配置、提示词）是必要的，但不足以定义你的智能体实际做了什么。行为是从代码、模型权重、工具 API 和运行时上下文的交叉中涌现出来的——其中任何一个都可以在版本控制系统中不留痕迹地发生变化。

2023 年，斯坦福大学和加州大学伯克利分校的研究团队做了一项受控实验：他们在 3 月和 6 月分别向 GPT-4 提交了完全相同的提示词，任务非常基础——判断一个数字是否为质数。3 月时，GPT-4 的准确率为 84%。到了 6 月，使用完全相同的 API 端点和完全相同的模型别名，准确率已跌至 51%。没有变更日志，没有通知，没有传统意义上的破坏性变更。

这项实验清晰地揭示了一个在多服务架构中部署 LLM 的团队迟早都会遇到的问题：模型别名不是稳定的契约。当你的下游支付处理器、推荐引擎或合规系统依赖 LLM 生成的结构化 JSON 时，你就建立了一个隐式的 API 契约——而隐式契约会悄无声息地崩溃。