SDK 与框架迁移清单

从官方服务或其他网关迁移已有应用。

迁移应先核对应用实际发送的 HTTP 请求，而不是只看所用 SDK 的名字。本站 Python / TypeScript 示例固定依赖版本，便于复现；其他 SDK 版本的默认重试、参数和资源调用需要重新确认。

配置或行为	迁移时处理
Base URL	OpenAI SDK 示例包含 /v1；原生 Claude / Gemini 示例使用根地址并自行拼协议路径
凭据	使用目标部署的 API 令牌；不要把原供应商密钥直接当作网关令牌
模型名	使用部署给出的完整 ID，包含必要前缀；不要默认官方模型别名存在
请求与输出	同协议保留结构；Chat、Responses、Claude、Gemini 之间切换时一起改解析与历史格式
自动重试	查明 SDK、业务队列和网关的重试层，控制总次数和重复执行
扩展参数	tools、JSON Schema、图片、reasoning、store 等逐项验证
内置资源调用	Files、Vector Stores、Batch、Conversations 等先查支持范围
状态与路由	保存响应 ID、压缩密文、签名和媒体任务不能假设跨渠道可迁移

​

建议迁移顺序

1. 保留当前可用配置，使用隔离的测试配置接入目标部署。
2. 先跑快速开始，确认模型、URL 和权限。
3. 使用业务真实协议的最小调用，再验证流式、工具、结构化输出和多模态。
4. 检查框架在启动、检索、上传、记忆管理和重试时是否额外调用资源接口。
5. 对比代表性业务样本的输出质量、延迟、失败行为和资源使用，再小流量切换。

​

常见框架设置差异

某些客户端要求根地址，另一些会自行追加 /v1 或完整端点。不要直接把本页 SDK 的地址复制到所有客户端；观察最终请求路径。LangChain、LlamaIndex、AI SDK 等框架的 provider 配置也不保证所有功能由同一个 Base URL 控制，应核对所安装版本的官方说明和实际请求。

HTTP 接口不存在时，不要通过增加重试解决。需要服务端记忆时可以先采用显式历史；需要知识检索时可采用应用侧 RAG。

生产验收 · 排障

Read in English

模型路由 · 限流与重试 · 请求观测 · AI SDK