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 OpenAI API path and feature the application actually uses: Responses or Chat Completions input shape, roles and instructions, structured output, tools, streaming events, images, files, embeddings, Batch, moderation, usage fields, request IDs and error handling. The current OpenAI quickstart uses the Responses API, but a migration plan must describe the endpoint your production workload really depends on rather than assuming all text APIs behave alike.
需要清点应用实际使用的每条 OpenAI API 路径与功能：Responses 或 Chat Completions 的输入结构、角色与 Instructions、结构化输出、工具、流式事件、图片、文件、Embedding、Batch、Moderation、用量字段、Request ID 和错误处理。当前 OpenAI Quickstart 采用 Responses API，但迁移计划必须以生产负载实际依赖的端点为准，不能假设所有文本 API 的行为都相同。
Classify workloads by business criticality and feature depth. A stateless summarizer may need only text and token accounting, while an agent can depend on tool-call IDs, approval state, stored conversation objects or server-side tools. Also record data-retention and regional requirements because changing the endpoint or provider can change where application state exists and how long it persists.
还应按业务关键度和功能深度分类。无状态摘要任务可能只依赖文本与 Token 统计，而 Agent 可能依赖 Tool Call ID、审批状态、已存储 Conversation Object 或服务端工具。数据保留与区域要求也要写入清单，因为更换端点或供应商可能改变应用状态存放位置与保留时间。
Freeze representative prompts, tool schemas, sample inputs and expected behaviors in a golden corpus. The new route should be judged against workload acceptance criteria—factual coverage, schema validity, tool selection, safety and latency—rather than exact text equality. Pin the source model snapshot during the comparison so model drift is not mistaken for adapter drift.
把代表性 Prompt、工具 Schema、样例输入与预期行为固化为 Golden Corpus。新路由应根据事实覆盖、Schema 有效性、工具选择、安全性与延迟等工作负载验收标准评判，而不是要求文本逐字相同。比较期间固定源模型 Snapshot，避免把模型漂移误判为 Adapter 漂移。
Compatibility dimensions兼容性维度
| Dimension维度 | Best fit最适合 | Verify before choosing选择前验证 |
|---|---|---|
| Messages and outputMessage 与输出 | 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八步迁移顺序
Move one workload class at a time. The sequence below separates discovery, compatibility work and traffic change so a failed evaluation does not become a production incident.
应一次迁移一个工作负载类别。下面的顺序把现状发现、兼容工作与流量切换分开，避免一次评测失败直接演变为生产事故。
- Inventory endpoints, models, SDK versions, stored state and downstream consumers.
- Classify workloads and define behavioral, operational, accounting and compliance gates.
- Build a feature matrix and identify unsupported or differently modeled capabilities.
- Implement a versioned adapter and preserve provider-native request and response evidence.
- Run the deterministic golden evaluation suite against pinned source and target routes.
- Dual-run sampled, privacy-safe traffic and compare semantics, latency, errors and usage accounting.
- Canary by workload and tenant while monitoring explicit promotion and stop thresholds.
- Exercise rollback under load, then cut over only after the rollback route remains proven.
- 清点端点、模型、SDK 版本、已存储状态及下游消费者。
- 分类工作负载，并定义行为、运营、核算和合规门禁。
- 建立功能矩阵，识别不支持或建模方式不同的能力。
- 实现版本化 Adapter，并保留供应商原生请求与响应证据。
- 针对固定的源路由和目标路由运行确定性 Golden 评测集。
- 双轨运行经过隐私处理的采样流量，比较语义、延迟、错误和用量核算。
- 按工作负载与租户灰度，并监控明确的推进与停止阈值。
- 在负载下演练回滚；只有回滚路径仍被证明有效后才执行切换。
Use an adapter and a versioned route使用适配器与版本化路由
The application should call a stable internal contract rather than a provider object throughout the codebase. A versioned adapter maps authentication, endpoint paths, input items or messages, tool definitions, structured output, streaming events, errors, request IDs and usage to the target foundation. Keep unsupported fields explicit; silently dropping a parameter creates a migration that appears successful while changing behavior.
应用应调用稳定的内部契约，而不是让 Provider Object 散布在整个代码库中。版本化 Adapter 负责映射认证、端点路径、Input Item 或 Message、工具定义、结构化输出、流式事件、错误、Request ID 与用量。对不支持的字段要明确报出；静默丢弃参数会让迁移表面成功，实际行为却已经改变。
Routing policy sits above the adapter and supports shadow execution, canary percentages, tenant allowlists and one-switch rollback without rebuilding the application. Store the route and adapter version with each trace. During dual run, prevent the shadow path from executing real tool side effects or persisting duplicate conversation state.
路由策略位于 Adapter 之上，支持 Shadow Execution、灰度比例、租户白名单和无需重新构建应用的一键回滚。每条 Trace 都应保存路由与 Adapter 版本。双轨运行期间，必须阻止 Shadow 路径执行真实工具副作用或重复持久化会话状态。
Production rule: do not cut over until behavioral, operational, accounting, compliance 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, credential ownership, tenant permissions, idempotency keys and traces across the model migration rather than rebuilding the capability layer at the same time.
迁移改变的是模型 API 路径。QVeris 独立治理外部 API、工具、服务与实时数据的发现和执行。模型迁移期间应保留工具 Schema、凭证归属、租户权限、幂等密钥与 Trace，不要同时重建能力层。
Evaluate tool selection and argument generation on both routes, but execute side effects only on the designated primary. If the target model represents tool calls differently, normalize them at the adapter boundary and retain the provider-native payload for diagnosis. This isolates inference differences without weakening approval, audit or duplicate-prevention controls.
可以在两条路由上评测工具选择和参数生成，但真实副作用只能由指定主路径执行。如果目标模型采用不同的 Tool Call 表示方式，应在 Adapter 边界标准化，并保留供应商原生 Payload 用于诊断。这样既能隔离推理差异，又不会削弱审批、审计或防重复控制。
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。
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.
不能默认认为可以。必须测试每个必需功能与故障路径。
通常不应。比较任务验收、安全、结构定义与工具行为。
直到代表性流量覆盖风险类别且所有发布门禁稳定。