很多团队迁移 AI 接口时执行方案只有三步替换 Base URL换一把 API Key发送一句“你好”确认能返回。测试成功后全量流量立即切到新上游。真正的问题往往在几小时或几天后才出现普通问答正常结构化输出偶尔破坏 JSON短文本正常长上下文开始截断非流式请求正常流式事件在代理层被缓冲回答看起来通顺业务事实却悄悄变差旧上游已经停用团队才发现回滚配置、模型映射和密钥都没有保留。这类事故的根源通常不是“接口完全不可用”而是把迁移理解成了地址替换。AI 服务迁移至少同时改变四件事HTTP 请求与响应的协议契约、模型对任务的行为表现、延迟与错误分布、运维和回滚路径。一个最小请求返回 200只能证明某个时间点的一条路径可用不能证明真实业务已经可以安全迁移。更稳妥的做法是把迁移设计成一次可观测、可比较、可暂停、可逆转的发布先离线验证协议和任务质量再用影子流量观察候选上游在不影响用户的情况下比较新旧结果随后按用户或租户稳定分桶逐级放量每一级都通过预先写好的门禁失败就自动停止或回滚。本文从这个全新的角度给出一套不依赖特定厂商的 AI 接口迁移方法。文中只把向量引擎的固定地址用作 URL 层级示例。文章不推断其价格、模型列表、并发、延迟、SLA、日志、合规或其他未被资料确认的能力真正迁移时应以服务方当前文档、账号权限和实测结果为准。一、先改目标迁移不是“新接口能调用”而是“业务可以无损切换”如果把成功标准写成“返回 HTTP 200”很多风险都会被测试遗漏。一个响应完全可以是 200同时包含空内容、错误字段、无法解析的工具调用甚至是一段登录页 HTML。反过来一次 429 也不一定代表候选上游不可用它可能是迁移测试没有遵守自己的流量预算。状态码是证据的一部分不是迁移结论。在动配置之前先把“迁移成功”拆成四份契约。第一份是请求契约最终 URL、HTTP 方法、认证方式、模型 ID、消息格式、可选参数、超时、重试和流式开关是否符合预期。第二份是响应契约状态码、Content-Type、JSON 顶层字段、流式事件边界、结束标志、工具调用结构和错误对象能否被现有客户端消费。第三份是行为契约摘要是否完整分类是否稳定检索问答是否忠于证据代码生成是否通过测试结构化输出是否满足 Schema。第四份是运维契约请求能否关联指标能否按新旧上游分组出现异常时能否暂停放量旧路径能否在明确时间内恢复。可以把它写成一张迁移验收表契约核心问题典型证据请求契约发出的是否是候选上游接受的请求脱敏请求快照、最终 URL、模型映射响应契约现有应用能否正确解析返回Schema 校验、流式状态机测试、错误样本行为契约关键任务质量是否守住底线固定评测集、成对比较、人工复核运维契约能否发现、停止并撤销坏变更分组指标、发布门禁、回滚演练只有四份契约都成立迁移才从“接口测试通过”变成“业务切换就绪”。这也是本文和常见配置教程最大的不同我们不从某一个 401、404 或 Base URL 填法出发而是从发布风险出发。二、为什么 AI 迁移比普通 REST API 更难验收普通接口常有确定输出输入订单号预期返回固定字段输入非法参数预期得到特定错误。大模型输出具有波动同一输入可能得到措辞不同但都正确的回答。于是逐字符比较会制造大量误报而只让开发者扫一眼“感觉差不多”又会漏掉真实退化。协议层仍应尽可能确定性测试。例如 JSON 能否解析、必需字段是否存在、工具参数是否满足 Schema、流式事件是否完整、错误对象是否保留类型这些都适合自动断言。语义层则要换一种方法对答案进行分类、打分或成对比较判断它是否满足具体任务标准而不是要求字面完全相同。OpenAI 的评测最佳实践明确强调生成式 AI 存在变化评测应该围绕真实任务设计并结合自动指标与人工判断相较于开放式“写得好不好”分类、评分和成对比较通常更容易形成稳定标准。这个原则同样适用于任何候选 AI 上游不要求被测服务一定来自 OpenAI。因此一个合格的迁移门禁至少包含两条腿协议回归负责发现“程序不能用”任务评测负责发现“程序能用但结果变差”。只测其中一条都会把风险带到生产。三、迁移前先盘点真实流量不要拿一句“你好”代表整个系统真实应用通常不只有一种调用。客服问答可能带长历史消息RAG 会加入检索片段和引用要求代码助手可能携带大段文件工作流会要求 JSONAgent 会请求工具并继续多轮调用。如果只用一句短问题做验证等于用系统中最简单的样本代表所有路径。先从调用端而不是从模型端建立清单。建议至少记录以下维度业务场景问答、摘要、分类、抽取、改写、代码、RAG、工具调用请求形态消息轮数、输入长度、是否流式、是否要求 JSON、是否包含图片或文件风险等级只读建议、对外内容、内部决策、会触发写操作的自动化流量特征高峰时段、请求频率、长尾输入、允许等待时间失败策略可以重试、必须降级、必须人工接管、禁止重复执行当前基线成功率、超时分布、解析失败率、人工反馈和任务得分。不要直接把生产提示词和用户正文导出到个人电脑。评测集应经过权限确认、最小化和脱敏不能合法复用的数据可以让领域人员编写结构相同的合成样本。关键不是复制全部生产数据而是覆盖生产分布中的主要类别和高风险长尾。最终形成的不是一堆随机聊天记录而是一份带标签的“迁移样本册”。每条样本应包含场景、输入模板、允许的变量、预期规则、禁止行为、风险级别和评分方式。发生过的真实故障尤其值得加入因为它们已经证明系统会在这些边界上出问题。四、建立旧上游基线没有对照组就无法判断新上游是否退化很多迁移报告只展示候选上游的数字例如“成功率 99%”“平均耗时两秒”。这些数字没有上下文。若旧上游同一时段的成功率更高、尾延迟更低、任务得分更好候选结果就不一定可接受若网络本身同时抖动只看候选也可能错误归因。基线应在相同样本、相同调用端、相近时间窗口和相同统计口径下采集。至少保留请求总数、协议成功率、应用解析成功率、首字节时间、完整响应时间、取消率、空输出率、任务得分以及每类高风险场景的单独结果。不要只看总体平均值平均值很容易掩盖少量但严重的长尾。Google SRE 的金丝雀发布章节指出候选组需要和控制组比较指标应能归因于正在发布的变化同时还要用绝对健康目标约束系统。套到 AI 迁移上就是既比较“新上游相对旧上游有没有变差”也检查“新上游自己是否越过业务底线”。如果新旧两边都同时变差只做相对比较可能仍显示“差不多”绝对门槛能阻止这种错误放量。建议为每个指标同时写两种门槛gates:protocol_success_rate:absolute_min:由团队依据当前SLO填写max_drop_vs_control:由团队依据风险容忍度填写p95_total_latency:absolute_max_ms:按业务等待预算填写max_increase_vs_control:按业务影响填写task_quality_score:absolute_min:由领域评测定义max_drop_vs_control:由发布负责人批准这里故意不提供一组看似通用的百分比。客服、代码生成和自动执行工具的风险完全不同拿别人的门槛复制过来只会让数字显得专业却不一定保护自己的业务。五、第一阶段用离线回放先把确定性问题挡在生产之外离线回放适合发现请求格式、模型映射、解析器和任务质量的明显问题。流程可以是从迁移样本册选取代表性输入分别调用旧上游和候选上游保存脱敏后的结构化结果再运行协议断言与语义评分。协议断言可以非常具体functionassertResponseContract(result){if(result.httpStatus200||result.httpStatus300){thrownewError(unexpected_status:${result.httpStatus});}if(!result.contentType.includes(application/json)){thrownewError(unexpected_content_type);}if(!Array.isArray(result.body?.choices)){thrownewError(missing_choices);}if(result.body.choices.length0){thrownewError(empty_choices);}}如果应用依赖流式输出还要测试任意网络分片而不是假设一次读取正好得到一个完整事件。一个 UTF-8 字符可能跨两次读取一个 SSE 事件也可能被拆成多段或合并到同一段。迁移测试应随机切分同一字节流确认增量解码器和事件聚合器仍能得到相同最终结果。协议错误在这里被发现远比上线后由用户发现便宜。语义评分则按任务拆开。抽取任务检查字段正确率和缺失率分类任务检查类别RAG 检查回答是否被给定证据支持代码任务运行测试摘要任务检查事实覆盖和臆造面向用户的开放回答可做盲化成对比较。不要把所有任务压成一个总分否则某个高频简单任务会淹没低频高风险任务。离线回放的局限也要写清楚它无法完整复制生产网络、峰值并发、实时上下文和用户行为。因此离线通过只是进入下一阶段的资格不是全量切换的批准。六、第二阶段用影子流量让候选上游“参加考试但不交卷给用户”影子流量的核心是把同一份符合条件的生产请求复制给候选上游但用户仍然只看到旧上游的结果。候选响应被记录、比较和丢弃不参与业务决策。AWS 的MLOps 部署指导把 shadow 定义为新模型与旧模型并行运行、但不影响实际决策的部署方式适合在正式推广前做高保真验证。影子并不等于“所有流量无脑复制”。至少要设置四道保护。第一只复制获得授权的数据。输入可能含代码、客户信息、内部文档或个人数据不能因为测试方便就把它发送到一个尚未完成审批的目的地。第二影子请求必须有独立预算和并发限制不能拖慢主请求。第三候选失败不能阻塞旧上游返回。第四涉及工具调用、发消息、写数据库、创建订单等副作用时影子链路必须禁用真实执行只评估模型提出的工具名称和参数。一个简化的路由伪代码如下asyncfunctionhandle(request){constprimaryPromisecallProvider(control,request);if(isShadowEligible(request)){voidcallProvider(candidate,sanitizeForShadow(request),{timeoutMs:SHADOW_TIMEOUT,toolsMode:record_only}).then(saveShadowResult).catch(saveShadowError);}returnawaitprimaryPromise;}代码里最重要的不是异步语法而是三条边界主路径不等待影子影子输入经过策略判断和脱敏工具只记录不执行。对有状态对话还要把会话上下文版本写入记录避免拿旧上游第 N 轮形成的历史直接评判候选的完整多轮能力。必要时分别设计“单轮兼容性影子”和“候选独立多轮回放”不要混成一个指标。七、比较新旧输出时先比协议再比任务最后才比文风影子阶段最容易走偏的地方是盯着两段回答逐字找差异。大模型措辞不同是正常现象真正应该优先比较的是业务约束。第一层是硬性协议是否成功、是否可解析、必需字段是否完整、工具参数是否满足 Schema、引用格式是否符合约定。第二层是任务正确性事实是否正确、分类是否命中、摘要是否漏掉关键内容、回答是否越过证据边界、代码是否通过测试。第三层才是体验是否冗长、语气是否一致、格式是否便于阅读。建议把评分结果保存为结构化标签而不是一段评语{case_id:rag-042,control:{contract:pass,quality:4},candidate:{contract:pass,quality:3},pairwise_winner:control,failure_tags:[missing_citation],review_status:human_confirmed}对于自动评分先用一小批人工双人复核样本校准。若两位领域人员经常无法达成一致说明评分规则还不够清楚此时扩大自动评测只会放大模糊性。可将“事实错误”“遗漏强制字段”“危险工具参数”等严重问题设为一票否决将文风差异放入非阻断观察项。还要防止评测器偏好某种输出长度、格式或措辞。候选答案和控制答案在人工评审时应随机左右位置并隐藏提供方名称。对自动评测器也应定期加入已知好坏样本检查它是否仍能给出预期排序。评测器本身同样需要版本和回归记录。八、观测字段必须能回答谁、何时、用哪条路、在哪一步变差影子和灰度阶段会同时运行两套路径。若日志里只有“请求成功”和“请求失败”出现波动后仍然无法归因。每条记录至少需要关联以下维度request_id或内部trace_idrelease_id、配置版本与提示词版本route_groupcontrol、shadow、canary 或 full提供方逻辑标识、模型逻辑标识与实际模型 ID场景、风险等级、是否流式、是否工具调用HTTP 状态、应用错误类型、首字节时间、完整时间输入和输出的计量信息协议校验结果、任务评分和回滚原因。OpenTelemetry 的语义约定强调在追踪、指标和日志中采用一致命名从而便于跨组件关联和消费数据。团队可以在此基础上制定自己的 AI 网关字段但应先检查所用约定的稳定状态并固定版本不能把仍在变化的字段名当成永久契约。观测不等于保存全部正文。默认记录结构、长度、哈希、类别、错误码和经过批准的少量样本完整提示词、文件内容、认证头与 API Key 不应进入普通日志。需要人工复核正文时应使用受控样本库、访问审计和明确的保留周期。迁移带来的可观测性改进不能以制造新的敏感数据副本为代价。仪表盘至少按 control 与 candidate 并排展示而不是只画一条混合曲线。进一步按场景、输入长度、区域、客户端版本和是否工具调用切片。总体正常但长上下文明显退化是 AI 迁移中很典型的假阳性只有切片才能把它暴露出来。九、第三阶段灰度放量按稳定对象分桶不要每次请求随机抽签影子通过后候选上游才开始向真实用户返回结果。此时应从低风险、可内部验证的群体开始逐级扩大。Microsoft 的安全部署实践建议采用渐进暴露、阶段健康检查和问题检测机制出现健康异常时应停止发布并启动恢复。灰度分桶应尽量稳定。例如对tenant_id或user_id加盐哈希再映射到发布环。这样同一用户在一段时间内持续命中同一路径便于比较和回滚也避免同一多轮会话在新旧上游之间跳动。functionrouteFor(subjectId,releaseSalt,canaryPercent){constbucketstableHash(${releaseSalt}:${subjectId})%10000;returnbucketcanaryPercent*100?candidate:control;}放量计划不应只写百分比还要写目标群体、观察时间、样本量条件、门禁、审批者和回滚动作。下面只是结构示例不是通用比例建议release:ai-upstream-migration-20260702stages:-name:internalaudience:employees_and_test_tenantstraffic:smallbake_time:defined_by_team-name:low_riskaudience:read_only_low_risk_scenariostraffic:increasedbake_time:defined_by_team-name:broaderaudience:approved_general_scenariostraffic:increased_againbake_time:defined_by_team选择灰度人群时不要只选“最不重要的用户”。样本还要覆盖真实请求类型否则低风险环全是短问答通过后直接扩到长文档和工具调用发布门禁并没有验证关键风险。更好的方式是风险递增与场景覆盖同时设计先让每类任务在内部环境出现再逐渐扩大外部范围。十、放量门禁要在发布前写好不能看到曲线后临时解释发布过程中再讨论“这个错误率算不算严重”很容易受到进度压力影响。门禁应在候选上游接收真实结果之前确定并由业务、研发和运维共同确认。门禁可以分为三类。立即停止项包括认证异常、数据去向不符合策略、工具被错误执行、响应无法解析、严重事实错误或安全规则被突破。阶段暂停项包括候选相对控制组的错误率、尾延迟、任务得分或人工投诉出现显著退化。观察项包括轻微文风变化、非关键格式差异和暂时无法归因的噪声。每个门禁都要配套动作停止继续放量、把新会话切回旧上游、保留受影响会话在原路由、禁用某项功能、进入人工审核或者执行完整回滚。若告警只能通知群聊却不能改变发布状态它还不是完整的发布门禁。Google SRE 的金丝雀方法强调指标既要能反映服务问题也要能归因于候选变化。比如整个集群 CPU 上升可能来自别的任务不适合单独判定 AI 候选失败而候选组应用解析失败率突然上升更直接指向兼容性问题。门禁越多不一定越安全噪声过大的门禁最终会被团队忽略。优先选择与用户结果和发布变化有明确因果关系的指标。十一、回滚不是“把百分比改回零”而是一项必须演练的能力很多方案写着“异常时回滚”却没有回答回滚需要多久、由谁执行、旧凭据是否仍有效、进行中的流式请求怎么办、已经形成的新会话历史能否被旧上游继续消费。直到事故发生才第一次验证回滚通常已经太晚。发布前至少演练一次以下流程冻结放量把新会话路由回控制组决定候选上的进行中请求是等待、取消还是允许完成确认旧上游的配置、模型映射和凭据仍可用验证关键场景恢复记录回滚开始、完成时间和受影响范围保留候选失败样本用于复盘。有状态系统尤其需要“会话黏性”。如果同一对话在候选上游已经产生了工具调用或特有格式直接把下一轮切到旧上游可能造成上下文不兼容。可以选择让已有会话继续留在原路由只把新会话回滚也可以在网关层维护统一的规范消息格式隔离不同上游的私有字段。具体选择取决于业务风险但必须提前决定。工具调用的回滚更复杂模型响应可以撤销路由却不能自动撤销已经发送的邮件、创建的工单或修改的数据。高风险灰度期应保留人工确认、幂等键和补偿操作候选模型不能绕开现有业务授权。任何“自动回滚”都只对可逆的技术状态有效不能替代业务补偿设计。十二、在应用和上游之间增加规范化适配层当多个应用各自直接拼接上游请求时迁移会迅速失控。A 应用把 Base URL 配到版本前缀B 应用保存完整 Endpoint一个客户端认识messages另一个客户端直接透传厂商私有参数模型名、重试和超时散落在环境变量、数据库与前端设置中。此时即使候选上游本身兼容团队也很难证明所有调用端同时兼容更无法用一个开关回滚。更容易治理的结构是在业务应用和外部 AI 服务之间建立一层薄的规范化适配。业务侧只提交内部统一请求例如场景、消息、期望输出类型、风险等级和允许工具适配层负责把逻辑模型名映射为实际上游模型 ID选择目标路由组装上游请求再把不同响应转换成内部统一结果。这里的“薄”很重要它不应该吞掉所有错误并制造另一套含糊协议而应保留原始状态、上游请求 ID、错误类型和可诊断信息。以固定地址为例可以明确区分三个层级而不是都叫“接口地址”服务根地址是https://api.vectorengine.cnOpenAI 兼容前缀是https://api.vectorengine.cn/v1完整 Chat Completions 地址是https://api.vectorengine.cn/v1/chat/completions。适配层配置应保存哪一层取决于它是否会自动追加资源路径关键是最终 URL 必须可观察、可测试不能让应用和网关各追加一次/v1或/chat/completions。内部请求可以采用类似下面的结构{scenario:knowledge_answer,logical_model:general_chat,messages:[{role:user,content:redacted}],output_contract:plain_text_with_citations,risk_level:read_only,release_context:{release_id:ai-upstream-migration-20260702,route_group:canary}}逻辑模型名不等于某家服务的真实模型 ID。它是业务和路由之间的稳定别名业务只声明需要“通用对话”或“结构化抽取”这类已定义能力发布配置再把别名映射到控制组和候选组。这样更换上游时不需要改遍所有仓库也能在同一发布记录中保存新旧映射。映射必须版本化不能在控制台里静默覆盖否则历史请求无法解释回滚也不知道该恢复哪个值。适配层还可以承担参数白名单。业务提交的温度、最大输出、工具和响应格式只有经过当前路由声明支持的部分才会被发送未支持参数应明确拒绝或记录降级不能悄悄丢弃。静默丢弃最危险调用表面成功行为却已经改变排查时又没有任何证据说明差异来自适配器。错误也应规范化但不抹平。内部可以统一为authentication_failed、rate_limited、upstream_timeout、response_contract_failed等类别同时保留脱敏后的原始 HTTP 状态和上游错误码。应用依据统一类别决定是否重试、降级或人工接管工程师仍能沿着原始证据定位。不要把所有异常包装成 200 和一段“模型繁忙”这会让监控失真也可能让调用方把失败文本当成正常答案写入数据库。规范化适配层的价值不是“再造一个万能 AI 平台”而是把迁移必需的路由、映射、观测和回滚集中到一个边界。它本身同样需要高可用、权限控制和回归测试如果团队只有一个简单应用没必要为了架构图漂亮而引入复杂网关。但当多个调用方需要同时迁移时一个克制的适配层通常比在每个项目里复制灰度逻辑更容易审计。十三、用故障注入验证门禁不要等真实事故替你测试回滚健康曲线全绿只能证明测试期间没有被观察到的异常不能证明门禁真的会在异常时动作。发布前应主动制造一组可控故障验证从信号产生到停止放量、切回控制组的完整链路。故障注入不需要一开始就做复杂混沌工程先从不会伤害真实用户的预发布环境和内部灰度环开始。第一类是协议故障。让候选模拟返回 HTML、缺少必需字段的 JSON、错误Content-Type、被截断的流式事件和未知结束原因确认解析器会把它标记为契约失败而不是输出空白或无限等待。第二类是网络故障。注入连接超时、首字节超时、读取中断和短暂 5xx确认超时预算分阶段生效重试不会把请求风暴放大。第三类是行为故障。准备明确错误、缺少引用、违反 Schema 或提出危险工具参数的候选结果确认质量门禁和人工审核能拦住它们。重试策略尤其需要单独验证。只读、无副作用的生成请求在满足预算时可能允许有限重试会触发工具或写操作的请求则必须使用幂等键并把“模型生成工具参数”和“业务系统执行操作”分成两个步骤。网络在响应返回前中断并不能证明上游没有执行。若客户端自动重放同一写操作可能创建两张工单或发送两次消息。迁移适配层不能为了提高表面成功率而绕过业务幂等性。故障注入还应覆盖控制组与候选组共享的依赖。例如两条路由经过同一个出口代理代理异常会让两边同时失败如果自动判定只比较候选相对控制组它们可能看起来“同样正常”。因此门禁必须同时包含相对差异和绝对健康条件。候选与控制组共用缓存时影子流量也可能改变缓存命中率或消耗共享配额导致对照实验相互污染。测试记录应明确哪些依赖隔离、哪些共享以及共享会怎样影响判断。一次回滚演练应产生可核验的时间线故障在何时注入哪个指标首先越过阈值发布系统何时停止扩大流量谁收到通知路由何时恢复进行中请求如何处理关键业务探针何时重新通过。只有时间线闭环团队才能知道“自动回滚”究竟用了几十秒、几分钟还是实际上卡在人工审批里。演练完成后不要只删掉故障开关。把触发过的样本、指标查询、告警截图、路由变更和恢复验证保存到发布记录并把此前未覆盖的故障加入固定回归集。若某个告警没有触发先修正观测或门禁若告警触发但无法自动停止就明确升级责任人和人工步骤。演练发现问题正是它的价值而不是发布失败。对于无法在生产复制的高风险故障可在隔离环境中验证机制在生产只验证安全的路由暂停和控制组恢复。故障注入本身也属于变更必须设定影响范围、终止条件和负责人。目标是证明保护装置有效而不是用一场不受控实验制造新的事故。十四、一个可落地的七步迁移顺序把前面的原则压缩成执行清单可以按以下顺序推进。第一步冻结现状。记录旧上游配置、模型映射、调用场景、指标口径和当前基线确认旧路径可继续使用。第二步定义契约。分别写出请求、响应、行为和运维契约明确阻断项与非阻断项。第三步准备评测集。覆盖主流场景、高风险路径、长尾输入和历史故障完成数据授权与脱敏。第四步离线回放。先跑协议回归再跑任务评测失败样本进入固定回归集。第五步影子验证。候选响应不影响用户、不执行工具按 control/candidate 并排观测。第六步渐进灰度。稳定分桶逐级扩大每级都满足样本量、观察时间和门禁。第七步全量后继续观察。保留控制能力和回滚窗口把灰度中新发现的样本加入持续评测而不是切完当天就删除全部迁移设施。发布负责人可以用下面这份核对表签字最终请求 URL、认证、模型 ID 和请求体已经脱敏核对非流式、流式、JSON、长上下文和工具场景按实际使用完成测试评测集包含真实分布与历史故障不只有演示问题新旧上游在相同口径下完成协议和任务比较影子流量不会阻塞主链路也不会执行真实副作用日志不包含完整密钥、认证头和未经批准的用户正文灰度按用户或租户稳定分桶多轮会话不会随机跳路由每个阶段都有明确门禁、观察时间、负责人和停止动作旧配置、旧凭据和旧模型映射仍可用于回滚已经实际演练回滚而不是只在文档里写了“支持回滚”全量后仍保留持续评测、异常样本回收和复盘机制。十五、别让一次迁移只产生一份“成功截图”一次成熟的 AI 接口迁移最终应该沉淀四类长期资产一份请求与响应契约防止客户端和网关悄悄漂移一套按业务场景组织的评测集用于后续模型、提示词和供应商变更一个能区分路由、版本和任务的观测面板一份经过演练的灰度与回滚手册。这些资产的价值远高于某次测试返回的 200。下一次更换模型、调整提示词、升级 SDK、修改代理或切换上游时团队不必重新凭感觉判断而是复用同一套证据链。迁移也不再是一场全量豪赌而是一系列小范围、可验证、随时能停下来的决策。还应为每次迁移保留一份简短的决策记录为什么要变更候选方案解决什么问题哪些场景明确不在本次范围谁批准门槛证据存放在哪里何时关闭旧路径。半年后回看时团队需要知道当时是在什么约束下作出选择而不是只看到最终配置。决策记录也能防止临时需求不断混入同一次发布新增模型、重写提示词、替换代理和调整业务逻辑如果同时发生即使结果变好也很难判断改进来自哪里。一次迁移尽量只验证一组相关变化其余变化进入下一轮这会让评测、灰度和复盘都更可信。真正可靠的兼容不是“字段名字看起来一样”而是经过真实任务证明请求能够送达响应能够解析结果守住业务底线异常能够被看见坏变更能够被撤回。做到这一步改 Base URL 才是迁移中最简单、也最不值得庆祝的那一行。参考资料Google SRE WorkbookCanarying ReleasesAWS Prescriptive GuidanceDeployment strategies for ML workloadsOpenAI DevelopersEvaluation best practicesMicrosoft Azure Well-Architected FrameworkSafe deployment practicesOpenTelemetrySemantic ConventionsRFC EditorRFC 9110 — HTTP Semantics相关接入资料
