Migrate From OpenAI API
Preserve Behavior, Keep Rollback Ready
迁移 OpenAI API：保持行为一致，随时可以回滚
API-shape compatibility is only the first checkpoint. A safe migration proves tool behavior, structured output, streams, errors, usage, data terms, latency and quality under real workloads.
API 形状兼容只是第一道检查。安全迁移必须用真实负载验证工具、结构化输出、流、错误、用量、数据条款、延迟与质量。
TL;DR
Find endpoints, SDK versions, models, prompts, tools, streams, files and batch jobs.
Compare behavior and constraints by feature, not by marketing label.
Normalize only what the application contract requires and preserve native fields.
Shift one workload gradually while measuring semantic and operational differences.
找出端点、SDK 版本、模型、提示词、工具、流、文件与批处理 Job。
按功能行为与约束比较，而不是按营销标签比较。
只标准化应用契约所需内容，并保留原生字段。
逐步迁移一个负载，同时测量语义与运营差异。
Migration scope is larger than the endpoint 迁移范围不止端点
Catalog every API path and feature actually used: response format, tools, streaming, images, files, embeddings, batch, moderation, usage fields and error handling. Classify workloads by business criticality.
清点实际使用的每条 API 路径与功能：响应格式、工具、流、图片、文件、Embedding、批处理、审核、用量字段与错误处理，并按业务关键度分类。
Freeze representative prompts and expected behaviors in a golden corpus. The new route must be judged against workload acceptance criteria rather than exact text equality.
把代表性提示词与预期行为固化为 Golden Corpus。新路由应按工作负载验收标准评判，而不是要求文本完全相同。
Compatibility dimensions 兼容性维度
| Dimension 维度 | Best fit 最适合 | Verify before choosing 选择前验证 |
|---|---|---|
| Messages and output Message 与输出 | Core text workloads with stable input and output contracts. 输入输出契约稳定的核心文本负载。 | Roles, instruction precedence, stop behavior and structured output. 角色、指令优先级、停止行为与结构化输出。 |
| Tools and streams 工具与流 | Agents or interactive applications. 智能体或交互应用。 | Tool schema, call IDs, parallelism, chunk ordering and termination. 工具结构定义、调用 ID、并行、Chunk 顺序与终止。 |
| Errors and retries 错误与重试 | Production reliability paths. 生产可靠性路径。 | Codes, retry hints, timeout ownership, idempotency and cancellation. Code、重试提示、超时归属、幂等与取消。 |
| Usage and terms 用量与条款 | Cost, audit and compliance owners. 成本、审计与合规负责人。 | Units, cached usage, tools, retention, regions, support and billing. 单位、缓存用量、工具、保留、区域、支持与账单。 |
Release gates 发布门禁
Golden tasks meet quality, safety and tool correctness thresholds.
Latency, throughput, cancellation, retries and alerts satisfy SLOs.
Usage can be reconciled to provider evidence and invoices.
Old route, configuration and data dependencies remain ready during canary.
Golden Task 达到质量、安全与工具正确性阈值。
延迟、吞吐、取消、重试与告警满足 SLO。
用量可与供应商证据及账单对账。
灰度期间旧路由、配置与数据依赖保持可用。
Eight-step migration sequence 八步迁移顺序
- Inventory and classify every workload before changing the client.
- Build the matrix, adapter and deterministic golden evaluation suite.
- Dual-run sampled traffic and review semantic and accounting differences.
- Canary by workload, monitor gates and exercise rollback before cutover.
- 更改客户端前清点并分类所有负载。
- 建立矩阵、适配器与确定性 Golden 评测集。
- 双轨运行采样流量，并检查语义与核算差异。
- 按负载灰度、监控门禁，并在切换前演练回滚。
Use an adapter and a versioned route 使用适配器与版本化路由
The application calls a stable internal contract. A versioned adapter maps authentication, paths, parameters, tools, streams, errors and usage to the target foundation. Routing policy supports dual run, canary percentages and one-switch rollback without rebuilding the application.
应用调用稳定内部契约。版本化适配器将认证、路径、参数、工具、流、错误与用量映射到目标基础。路由策略支持双轨、灰度比例与无需重建应用的一键回滚。
Production rule: do not cut over until behavioral, operational, accounting and rollback gates all pass.
生产规则：行为、运营、核算与回滚门禁未全部通过前，不得切换。
Migrate inference without mixing tool access 迁移推理时不要混合工具访问
The migration changes the model API path. QVeris independently governs discovery and execution of external APIs, tools, services and live data. Preserve tool schemas, credentials, idempotency and traces across the model migration.
迁移改变模型 API 路径。QVeris 独立治理外部 API、工具、服务与实时数据的发现和执行。模型迁移期间应保留工具结构定义、凭证、幂等与调用链。
Move one reversible configuration boundary 迁移一个可逆配置边界
Start by moving only the client construction behind environment-owned configuration. Do not simultaneously rename models, change prompts, enable routing, and alter retries; those changes make regressions impossible to attribute.
第一步只把 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"]
- Run golden prompts through old and new endpoints with the same model contract.
- Compare accepted quality, latency, errors, tool behavior, usage, and total cost.
- Canary by workload or tenant and keep the previous URL, key reference, and alias map ready.
- 用相同模型契约让 Golden 提示词同时通过新旧端点。
- 比较合格质量、延迟、错误、工具行为、用量与总成本。
- 按工作负载或租户灰度，并保留旧 URL、密钥 Reference 与别名 Map。
Verified implementation reference: OpenAI Python library.
实施参考已根据官方资料核验：OpenAI Python library。
Define the Production Contract for migration from the OpenAI API定义从 OpenAI API 迁移的生产契约
For Migrate From OpenAI API, protocol similarity lowers integration effort, but it does not guarantee behavioral parity. Put a versioned application contract between product code and the provider path so change remains testable and reversible.
针对“迁移 OpenAI API”，协议相似可以降低集成工作量，却不能保证行为等价。应在产品代码与供应商路径之间建立版本化应用契约，让变更保持可测试、可回滚。
Document messages and roles, model IDs, sampling parameters, streaming, structured output, tools, embeddings, files, batch jobs, moderation, usage, and error handling. Mark each item as required, optional, provider-native, or unsupported, and assign an owner for any transformation that changes its meaning.
记录消息与角色、模型 ID、采样参数、流式、结构化输出、工具、Embedding、文件、批处理、Moderation、用量和错误处理。把每一项标记为必需、可选、供应商原生或不支持，并为任何改变语义的转换明确负责人。
To validate Migrate From OpenAI API, create fixtures for short and long prompts, Unicode, streaming, JSON schema, parallel tools, refusals, cancellation, malformed input, and rate limits. Check required fields and event order instead of accepting one plausible text answer.
验证“迁移 OpenAI API”时，为短与长提示词、Unicode、流式、JSON Schema、并行工具、拒绝、取消、畸形输入和限流建立 Fixture，检查必需字段与事件顺序，而不是接受一个看似合理的文本答案。
When operating Migrate From OpenAI API, trace internal request ID, resolved model and provider, model version, transformations, retries, latency, token classes, cost source, policy result, and output validation. Redact secrets without deleting the context needed to reproduce failure.
运营“迁移 OpenAI API”时，追踪内部请求 ID、解析后的模型与供应商、模型版本、转换、重试、延迟、Token 类别、成本来源、策略结果和输出校验，在脱敏密钥的同时保留复现失败所需上下文。
Before rolling out Migrate From OpenAI API, shadow representative traffic, classify semantic differences, canary by reversible workload, monitor task completion and tail behavior, and keep the previous route available until rollback and return-to-primary have been rehearsed.
上线“迁移 OpenAI API”前，运行代表性影子流量，分类语义差异，按可逆工作负载进行金丝雀发布，监控任务完成与长尾行为，并在演练回滚和恢复主路径之前保留原有路由。
FAQ
Not automatically. Test every required feature and failure path.
Usually no. Compare task acceptance, safety, schema and tool behavior.
Until representative traffic covers risk classes and all release gates are stable.
不能默认认为可以。必须测试每个必需功能与故障路径。
通常不应。比较任务验收、安全、结构定义与工具行为。
直到代表性流量覆盖风险类别且所有发布门禁稳定。