用三句话先说明白人会照旧说明书办事模型也一样。它见过的文档、缓存里的接口描述、网页上没刷新的说明、向量库里还没更新的片段都可能比真实系统更旧。于是系统已经升级了它还在用老地址、老字段名、老例子去调用。给人改流程可以发邮件、约下周再切换给 API 改接口没有这种「大家一起听一场会」的机会。调用方五花八门服务器上的代码、浏览器、命令行、还有「模型根据提示词自动拼出来的请求」。如果接口不标版本、只在原地址上悄悄改含义就很容易出现线上已经是新规则模型脑子里还是旧规则报错东一块西一块很难想到根因是「文档和代码对不上」。本篇讲怎么少踩这个坑用网址里的版本号划清界限小改动尽量别弄坏老用户大改动开新地址用标准响应头告诉机器「这条接口快不用了」发布时代码、文档、工具描述、向量库尽量同一班车更新。本篇在系列里的位置前面三篇分别讲了能力怎么暴露、契约怎么定死、响应怎么方便模型读。这一篇讲API 怎么像产品一样升级以及LLM 场景下常见的「契约漂移」怎么缓解。摘要做法一览对外接口建议在网址里写主版本例如/v1/、/v2/让人和机器一眼知道「这是哪一版整套约定」。在同一版里尽量只做加字段、加可选参数这类老客户端还能用的改动要改到老客户端一定会坏时用新路径发布不要偷偷改旧路径。旧版接口可以在响应里带上Deprecation、Sunset、Link等标准头含义见下文让监控和客户端能自动知道「该迁移了」。这些名字来自 RFC生产环境请以你们选定的规范为准。发版时把实现、OpenAPI、工具 JSON、迁移说明、文档/向量库绑在一起更新。关键词API 生命周期路径版本向后兼容破坏性变更契约漂移DeprecationSunsetRFC 8594RFC 8288RFC 9745OpenAPILLM 工具定义示例代码面向 LLM 的程序设计 4API 版本化与演进示例代码1 问题从哪来1.1 「消费者」不只是你们自己的代码只要东西进了模型或进了检索库都可能影响它怎么调你的 API例如各种文档Swagger、导出的openapi.json、Wiki、PDF、被切成小块放进向量库的说明。模型侧带着的内容系统提示词里的 JSON 例子、Agent 里写死的工具说明、聊天里用户贴过的旧请求。模型当场编出来的调用根据上面这些材料现拼的 URL 和字段没人保证和线上最新版一致。所以要解决的不只是「版本号写什么字符串」而是很多份、很旧的副本里到底该信哪一版换版本时能不能被看见、能报警、能回退。1.2 三种常见翻车名字没变意思变了地址和字段名都和以前一样但含义或默认值改了旧提示词生成的请求以前能过现在 silently 错。只升了一半规范已经是 v2工具描述或向量库里还是 v1模型两套字段混着用。嘴上说不让用系统不知道没有机器可读的「下线时间」网关没法按旧流量做告警业务也没法排期。2 版本怎么放——优先写在网址里2.1 为什么 LLM 场景更推荐/v1/这种「路径版本」版本可以放在网址、HTTP 头、子域名等地方。对Agent 文档来说写在路径里每个示例 URL 都带着版本人眼扫、搜文档、模型复述地址时最不容易丢。只写在头里用curl或生成代码时容易忘带日志里若只看 URL看不见版本排障麻烦。头更适合做小开关、小特性不太适合单独承担「整包换一代契约」除非你们中间件能保证每个请求都自动带头。本系列 demo 用/v1/、/v2/就是取「一眼能看见」。2.2 同一个/vN/里面改动分三类安全扩展加可选字段、响应多几个键、枚举只加不删同时想想下游有没有写死switch。结果会变、但 JSON 形状可能没变排序、默认每页条数、筛选规则变了——用户会觉得「怎么和以前不一样」。这类别悄悄上线最好用公告、功能开关、或新参数显式打开。老客户端一定会挂的改法删字段、改类型、改必填、改名——应当新开/vN1/旧版在约定期内只修严重问题和安全补丁。3 「兼容」别靠嘴说要能检查评审时少说「这次兼容」多说下面三类里到底满足哪条表格第三列是容易忽略的细节。说法白话含义实际影响记住这一条就够语法 / Schema 兼容老客户端按老样子发 JSON服务端还认若服务端禁止多出来的字段新客户端给旧服务端发新字段常会422。所以「同一路径上随便加必填/新键」往往要配合新路径或先放宽、再收紧的步骤。语义兼容字段意思、单位、业务规则没变或可说成「只收更窄、规则更严」不能只看「名字没改」要用例子、监控、回归证明。行为兼容分页、排序、默认条数、去重规则一样或有明确开关这类改动经常骗过 JSON Schema但会让 Agent输出变来变去。枚举和可选字段在同一路径上「枚举多几个值」「可选改成必填」常常是 breaking非做不可时想想默认值、分阶段拒绝、或新路径。4 告诉机器「这条接口要退休了」——几个响应头下面这些头不改变「这次请求业务上算不算成功」但告诉客户端和平台以后别依赖它了该迁到哪。头白话参考Sunset打算哪天起这条地址不再用HTTP 日期格式RFC 8594Deprecation已经不建议用请迁走写法 RFC 9745 有规定常和Sunset一起出现RFC 9745Link可带relsuccessor-version等指向下一代地址RFC 8288 等实务提醒短Sunset是计划不是法务合同日期还可能改。但没有它自动化很难统一喊「要下线了」。Deprecation历史上写法不统一新项目应在网关层定一种写法并写进规范demo 为可读性做了简化上生产前与你们选定的 RFC/中间件对齐。404、5xx上乱挂下线头容易误解成「资源没了还是版本没了」。常见做法成功响应和专门设计的迁移类 4xx里带头纯参数错误可不带。5 发布时代码和文档「同一班车」一次发布尽量把下面这些绑在一起同一工单或同一流水线代码、openapi.json、工具用的 JSON如果有、迁移说明、文档/向量库里相关段落和示例 URL。对照表旧字段名 → 新字段名单位有没有变例如字数包不包括空格附最小Before/After例子。CI 里对比 OpenAPI检出 breaking 变更时没升路径版本就别合并。工具名若用xxx_v2这种后缀减少混用要和 OpenAPI同源避免名和路径两套故事。RAG旧版文档标停更日期或从索引拿掉正文链到新版否则检索会把过期说明当真理喂给模型。6 上线之后看什么流量按路径或你们用的版本头看v1 / v2 占比和错误率快 Sunset 时给v1 占比设告警。契约测试至少保证一类典型客户端升级后不会在静默中踩雷。文档Sunset 等词别自己重新定义链到 RFC 内部废弃政策提前多久、谁批、是否410 Gone。7 LLM 特有风险一表读完现象可以怎么做提示词里写死了 v1 例子发 v2 时同步发迁移片段或更新工具列表重要环境用配置中心统一下发模型混用 v1/v2 字段路径分版本工具定义和 OpenAPI 同版本错误里写清该用哪版或文档链接错误体专题可再写向量库很旧文档与 API同一张生命周期表废弃接口的 chunk 打deprecated: true方便过滤8 Demo 在演示什么一个进程里同时提供两套接口都对同一批假文档做「截断摘要」——业务相同只为对比契约差异。共同点按长度截断字符串。v2 在formatbullets时会多一步「项目符号分行」表示新版本多了一点行为。POST /v1/summarize-document老字段名成功时响应带头Deprecation、Sunset、Link指向 v2。细节见README_完整方案.md。POST /v2/summarize-document新字段名可选参数演示「响应里多带可选字段」。GET /api-versions返回 JSON里面有字段对照和端点方便 Agent结构化读迁移说明。main.py依次打/api-versions、v1、v2方便本地对照响应头和 body。先uvicorn server_api:app --reload --host 127.0.0.1 --port 8313再在项目目录运行python main.py。启动服务后再在另外一个terminal中运行python main.pyterminal中返回 GET /api-versions {supported: [v1, v2], default_recommended: v2, migration: {v1_to_v2_request: {doc_id: document_id, max_words: max_length}, v1_to_v2_response: {summary_text: summary, approx_word_count: word_count}, v1_sunset_hint: See HTTP Sunset header on v1 responses (demo uses fixed date).}, endpoints: {v1_summarize: POST /v1/summarize-document, v2_summarize: POST /v2/summarize-document}} POST /v1/summarize-document注意响应头 Deprecation / Sunset / Link deprecation: true sunset: Wed, 01 Jan 2027 00:00:00 GMT link: /v2/summarize-document; relsuccessor-version body: {summary_text: 人工智能在自然语言处理领域取得显著进展。大语言模型能够完成 摘要、问答、翻译等任务。企业可将 LLM 与内部 API 结合构建智能客服与数据分析应用。, approx_word_count: 75} POST /v2/summarize-documentinclude_metadatatrue {summary: 人工智能在自然语言处理领域取得显著进展。大语言模型能够完成摘要、问答、翻译等任务。企业可将 LLM 与内部 API 结合构建智能客服与数据分析应用。, word_count: 75, format: plain, api_version: v2, document_id_echo: doc_001}9 完整代码与文档运行与架构demo/README_运行与架构.md完整方案demo/README_完整方案.md在demo/目录安装依赖后执行uvicorn server_api:app --reload --port 8313再运行python main.py