把现有 OpenAI API 接入点切换到另一个宣称兼容的服务真正的技术风险通常不在“请求发不出去”而在“响应看起来一样、实际结构或语义不同”。迁移前很多人只验证了第一个 Hello World 请求能返回正文却没有验证错误响应、流式事件、工具调用返回、字段缺省这几类最容易在真实流量里出问题的路径。这里给出一套不依赖厂商文档具体描述的验证方法四层兼容性建模、真实响应结构 diff、错误注入实测、契约测试固化。文中代码都是脚手架端点路径、字段名、错误码一律以迁移当天拿到的双方官方文档和线上真实响应为准。本文不预先断言 DeepSeek API 的任何一个具体字段或行为因为那正是迁移方必须在官方文档与真实流量上核实的内容。先把“兼容”拆成四层契约“兼容”不是布尔值。两个服务即使都能成功处理同一类对话补全请求也可能只在某一层兼容接入层base URL、认证头格式、HTTP 方法、路径。请求契约顶层参数名、嵌套对象结构、取值范围、枚举取值、流式开关位。响应契约正文内容放在哪个字段、字段类型、缺省语义、结束原因与用量的结构。行为语义错误码取值范围、限流与重试语义、流式事件边界、工具调用参数编码与回传规则。迁移方案里真正要做的不是把网上的“兼容性对照表”当成事实抄一遍而是逐层用真实请求把新旧两端的行为记录下来做 diff。下面从“如何记录”开始。第一步抓基线把新旧两端的真实响应落盘先写一个最小抓取函数把状态码、响应头、JSON 响应体一起保存import requests def capture(base_url: str, api_key: str, payload: dict) - dict: # 路径与认证方式以双方官方文档为准此处只是演示入口 resp requests.post( f{base_url}/chat/completions, headers{Authorization: fBearer {api_key}}, jsonpayload, timeout60, ) try: body resp.json() except ValueError: body resp.text return { status: resp.status_code, headers: dict(resp.headers), body: body, }保存基线时确认同一个 prompt 在两端的“语义等价”并核对 payload 里每个字段哪些是源服务有而目标服务不接受的哪些枚举取值在目标端会被静默降级而不是报错。这类“请求能成功但语义不同”的差异比 4xx 更危险因为不会触发告警。第二步做结构 diff而不是值 diff模型输出有随机性所以不能比较返回值本身只能比较“键集合 字段类型”。这是整个迁移验证里最关键的一步def diff_schema(source, target, path$): issues [] if isinstance(source, dict) and isinstance(target, dict): for key in sorted(set(source) | set(target)): child f{path}.{key} if key not in target: issues.append((source_only, child)) elif key not in source: issues.append((target_only, child)) else: issues diff_schema(source[key], target[key], child) elif type(source) is not type(target): issues.append((type_mismatch, path, type(source).__name__, type(target).__name__)) return issues结果会有三类source_only源服务有、目标没有。旧代码依赖的字段在目标端可能缺省属于破坏性差异必须逐个处理。target_only目标多出来的字段。宽松解析下通常安全但代码如果把响应整体序列化落库或对响应做严格 schema 校验仍然会造成问题。type_mismatch同一字段类型不同。典型差异是字符串与数字、null 与缺省、数组与单对象。对数组字段不需要对每个元素做 diff取第一个元素递归即可。比较对象应覆盖普通请求、流式请求、工具调用请求、错误响应四类不能只抓一个成功响应就收工。四个必须实测的高风险点第一错误与重试语义。至少用无效凭证和触发限流两种方式各打一次目标服务记录状态码、响应体里的错误码字段、限流相关响应头的名字。然后用这些记录反过来校准重试代码重试条件是按状态码还是按错误码退避是否消费服务端返回的重试等待时间。不校准的后果是目标服务用 429 表达限流而旧重试逻辑只认 5xx限流流量会全部穿透到业务层。第二流式输出。用 requests 的 streamTrue 把原始字节按行存下来先不要解析。核对三件事事件是按空行还是按行边界切分正文增量在哪个字段整个流如何结束。真实业务里最常见的坑是目标服务已经以 200 开始响应业务错误却编码在流中间的某个事件里而不是 HTTP 状态码。第三工具调用。设计一个必然触发工具调用的测试 prompt核对以下行为请求里声明的工具定义 schema 是否被校验返回中的工具调用参数是转义 JSON 字符串还是结构化对象是否可能出现多个候选调用调用结果回传时角色与字段放在哪一层。第四null 与缺省语义。目标服务在“内容为空”和“字段未定义”两种场景下可能一个返回 null、一个直接省略键。旧代码里所有硬编码读取的字段路径都要重新对照真实输出过一遍尤其是消息正文与结束原因这类被业务直接依赖的路径。第三步把兼容性固化成契约测试结构 diff 只给出“一次对比”的结论。要防止目标服务后续升级悄悄破坏兼容性需要把验证放进 CI从源服务多次调用中归纳一份最小契约 schema只包含业务真正使用的字段保存固定 prompt 下的真实响应作为 golden fixture每次对新服务响应做两件事校验它满足最小契约并与 golden 做结构 diff对 target_only 类型的新增字段维护白名单出现白名单之外的键就失败。# tests/test_contract.py import json import os import requests from jsonschema import validate def load_contract_schema(pathcontracts/chat_completion.json): with open(path, encodingutf-8) as f: return json.load(f) def test_response_contract(): base_url os.environ[TARGET_BASE_URL] api_key os.environ[TARGET_API_KEY] payload { model: os.environ[MODEL], messages: [{role: user, content: ping}], } resp requests.post( f{base_url}/chat/completions, headers{Authorization: fBearer {api_key}}, jsonpayload, timeout60, ) assert resp.status_code 200 validate(resp.json(), load_contract_schema())即使 prompt 与采样参数固定两次生成的正文值也不可能相同所以契约测试只对类型和键做断言对正文值一律不比。工具调用与错误响应需要各自独立的 fixture不能共用普通请求的契约。落地手法先收口再灰度最小改动迁移不等于在业务代码里原地替换 base_url。更稳妥的做法是把所有直接 HTTP 调用收敛到一个 client 适配模块请求构造和响应解析各保留一份实现业务侧只依赖这个适配模块暴露的最小数据对象。这样目标服务多出来的字段不会泄漏进业务代码重试与限流逻辑也可以只在一个地方按实测结果调整。灰度顺序建议非流式普通请求 → 流式请求 → 工具调用 → 定时批量任务。每一步都以上一阶段的契约测试通过为前提。最后把一段真实业务流量完整切过去运行一段时间观察错误码分布、超时率、限流触发频次与源服务基线的差异。这里真正值得强调的是任何“官方文档宣称兼容”的说法都只配作为起点。可以进入生产的兼容性证据是真实响应——响应结构 diff 清零或差异全部被评审接受、错误语义测试通过、流式事件结构一致、工具调用端到端行为一致。在这些证据齐全之前最安全的工程假设是目标服务的错误语义与限流行为全部未知宁可保守重试也不要照搬源服务的重试策略。迁移完成后把源服务响应样例、目标服务真实响应样例、差异评审记录三份文件一起归档。下次任何一方服务端升级这三份文件就是回归测试的基准。