OpenAI-compatible API 迁移失败：base_url、/v1、Chat Completions 与 Responses 路径排查

“兼容”描述的是范围，不是无条件互换

先让目标服务明确它支持的接口、模型、流式事件、工具和结构化输出；不要从“兼容”推断全部请求字段或响应对象相同。迁移记录应同时写下调用接口、SDK 版本、模型名、最终 URL、HTTP 状态和脱敏 request ID。这样能区分 URL 拼接错误、认证失败与协议语义不匹配。

先固定最终请求 URL

不要只检查配置里的 base_url 文本。实际打印或断点确认最终请求路径（绝不记录 Authorization），核对 base_url 是否已经包含 /v1，以及 SDK 是否还会追加版本路径。404 应先检查路径与接口是否被目标端声明支持；把模型名错误或权限问题一概归为“base_url 不对”会延误定位。

Chat Completions 与 Responses 不能只替换域名

两种接口的请求和响应模型不同。Chat Completions 常围绕 messages 与 choices；Responses 使用 POST /responses，并以 input、output、status 等对象表达过程和结果。迁移时请求构造、流事件消费者和最终结果读取应一起切换；若保留旧的 choices 解析器，即使 HTTP 成功也会把新响应误判为失败。

认证、模型和调用链逐层最小化

先用一个不含工具、流式或多轮状态的最小文本请求验证认证、模型和返回结构，再一次只加回一个能力。OpenAI API 使用 Bearer 认证；密钥必须保存在服务器或受控密钥管理中，不能放进浏览器、日志或排障截图。对于组织或项目头，按所用凭据与当前官方文档配置，不把某个账户的头部要求泛化到所有兼容服务。

Responses 成功也要检查状态

Responses 文档将请求结果建模为 response 对象，并包含 status、error 与 incomplete_details 等状态信息。应用不应只看 HTTP 2xx 就宣布完成：对于不完整、失败或网络中断，保存可关联的请求 ID 和客户端时间线，再按操作是否幂等决定是否安全重试。不要在未知执行状态下无界重放可能产生副作用的操作。

安全诊断字段：接口类型、最终路径、HTTP 状态、response.status、模型、SDK 版本、x-request-id
严禁记录：Authorization、API key、完整用户输入或未脱敏响应

迁移验收顺序

验收按路径、认证、模型、最小响应、应用解析、流式、工具与多轮状态依次推进。每一步固定前一步证据，失败时回到最近一个成功的最小请求，而不是同时更换 SDK、代理、模型和请求体。供应商支持需要的是时间范围、脱敏请求、模型、SDK 版本和 request ID，而不是密钥。

只改 OPENAI_BASE_URL 就足够吗？

通常不够。还要核对路径版本、目标服务支持的端点、模型名、认证头、参数与响应/流事件结构。

404 一定是模型不存在吗？

不一定。404 也可能是 base_url、/v1 或资源路径重复/遗漏；应先记录最终请求 URL，再检查模型与服务能力。