迁移 OpenAI API
保持行为一致，随时可以回滚迁移 OpenAI API
安全且可回滚
API 形状兼容只是第一道检查。安全迁移必须用真实负载验证工具、结构化输出、流、错误、用量、数据条款、延迟与质量。
速览
找出端点、SDK 版本、模型、提示词、工具、流、文件与批处理 Job。
按功能行为与约束比较，而不是按营销标签比较。
只标准化应用契约所需内容，并保留原生字段。
逐步迁移一个负载，同时测量语义与运营差异。
迁移范围不止端点
需要清点应用实际使用的每条 OpenAI API 路径与功能：Responses 或 Chat Completions 的输入结构、角色与 Instructions、结构化输出、工具、流式事件、图片、文件、Embedding、Batch、Moderation、用量字段、Request ID 和错误处理。当前 OpenAI Quickstart 采用 Responses API，但迁移计划必须以生产负载实际依赖的端点为准，不能假设所有文本 API 的行为都相同。
还应按业务关键度和功能深度分类。无状态摘要任务可能只依赖文本与 Token 统计，而 Agent 可能依赖 Tool Call ID、审批状态、已存储 Conversation Object 或服务端工具。数据保留与区域要求也要写入清单，因为更换端点或供应商可能改变应用状态存放位置与保留时间。
把代表性 Prompt、工具 Schema、样例输入与预期行为固化为 Golden Corpus。新路由应根据事实覆盖、Schema 有效性、工具选择、安全性与延迟等工作负载验收标准评判，而不是要求文本逐字相同。比较期间固定源模型 Snapshot，避免把模型漂移误判为 Adapter 漂移。
兼容性维度
| 维度 | 最适合 | 选择前验证 |
|---|---|---|
| Message 与输出 | 输入输出契约稳定的核心文本负载。 | 角色、指令优先级、停止行为与结构化输出。 |
| 工具与流 | 智能体或交互应用。 | 工具结构定义、调用 ID、并行、Chunk 顺序与终止。 |
| 错误与重试 | 生产可靠性路径。 | Code、重试提示、超时归属、幂等与取消。 |
| 用量与条款 | 成本、审计与合规负责人。 | 单位、缓存用量、工具、保留、区域、支持与账单。 |
发布门禁
Golden Task 达到质量、安全与工具正确性阈值。
延迟、吞吐、取消、重试与告警满足 SLO。
用量可与供应商证据及账单对账。
灰度期间旧路由、配置与数据依赖保持可用。
八步迁移顺序
应一次迁移一个工作负载类别。下面的顺序把现状发现、兼容工作与流量切换分开，避免一次评测失败直接演变为生产事故。
- 清点端点、模型、SDK 版本、已存储状态及下游消费者。
- 分类工作负载，并定义行为、运营、核算和合规门禁。
- 建立功能矩阵，识别不支持或建模方式不同的能力。
- 实现版本化 Adapter，并保留供应商原生请求与响应证据。
- 针对固定的源路由和目标路由运行确定性 Golden 评测集。
- 双轨运行经过隐私处理的采样流量，比较语义、延迟、错误和用量核算。
- 按工作负载与租户灰度，并监控明确的推进与停止阈值。
- 在负载下演练回滚；只有回滚路径仍被证明有效后才执行切换。
使用适配器与版本化路由
应用应调用稳定的内部契约，而不是让 Provider Object 散布在整个代码库中。版本化 Adapter 负责映射认证、端点路径、Input Item 或 Message、工具定义、结构化输出、流式事件、错误、Request ID 与用量。对不支持的字段要明确报出；静默丢弃参数会让迁移表面成功，实际行为却已经改变。
路由策略位于 Adapter 之上，支持 Shadow Execution、灰度比例、租户白名单和无需重新构建应用的一键回滚。每条 Trace 都应保存路由与 Adapter 版本。双轨运行期间，必须阻止 Shadow 路径执行真实工具副作用或重复持久化会话状态。
生产规则：行为、运营、核算、合规与回滚门禁未全部通过前，不得切换。
迁移推理时不要混合工具访问
迁移改变的是模型 API 路径。QVeris 独立治理外部 API、工具、服务与实时数据的发现和执行。模型迁移期间应保留工具 Schema、凭证归属、租户权限、幂等密钥与 Trace，不要同时重建能力层。
可以在两条路由上评测工具选择和参数生成，但真实副作用只能由指定主路径执行。如果目标模型采用不同的 Tool Call 表示方式，应在 Adapter 边界标准化，并保留供应商原生 Payload 用于诊断。这样既能隔离推理差异，又不会削弱审批、审计或防重复控制。
迁移一个可逆配置边界
第一步只把 Client Construction 移到环境配置边界之后。不要同时重命名模型、修改提示词、启用路由并改变重试，否则回归问题无法归因。
from openai import OpenAI
import os
def build_client() -> OpenAI:
return OpenAI(
api_key=os.environ["LLM_API_KEY"],
base_url=os.environ.get("LLM_BASE_URL", "https://api.openai.com/v1"),
timeout=float(os.environ.get("LLM_TIMEOUT_SECONDS", "30")),
max_retries=0,
)
MODEL_ALIASES = {
"support-fast": os.environ["SUPPORT_FAST_MODEL"],
"support-quality": os.environ["SUPPORT_QUALITY_MODEL"],
}
client = build_client()
model = MODEL_ALIASES["support-fast"]- 用相同模型契约让 Golden 提示词同时通过新旧端点。
- 比较合格质量、延迟、错误、工具行为、用量与总成本。
- 按工作负载或租户灰度，并保留旧 URL、密钥 Reference 与别名 Map。
实施参考已根据官方资料核验：OpenAI Python library。
FAQ
不能默认认为可以。必须测试每个必需功能与故障路径。
通常不应。比较任务验收、安全、结构定义与工具行为。
直到代表性流量覆盖风险类别且所有发布门禁稳定。