保留openai格式的api端点有哪些

很多人换中转站或换模型时，代码一个字没改却报 404，多半是端点路径或请求体字段对不上。这篇不重讲协议，而是按端点把请求方法、路径、必填字段列成对照，再给一套切换前的自检顺序和排错路径，让你判断哪些端点能无缝迁移、哪些要先适配再上。

很多人换中转站或换模型时，代码一个字没改却报 404，第一反应往往是「中转站坏了」。实际排查下来，十有八九是端点路径或请求体字段对不上——对方只实现了对话补全，你去打文本补全；或者返回体里向量那个键名字不一样。这篇不讲协议原理，而是按端点类型把请求方法、路径形态、必填字段列出来，再给一套切换前的自检顺序，让你判断哪些接口能直接换 Base URL 就跑，哪些得先适配再上。

先说结论：兼容 OpenAI 格式不等于每个端点都实现，也不等于字段一字不差。真正能无缝迁移的通常只有一小撮「人人都实现」的端点，其余属于选配。所以动手前最该做的不是改代码，而是先搞清楚对方到底开放了哪些路径、返回体长什么样。

先把端点按功能分几类

兼容 OpenAI 格式的端点大体分八类：对话补全、文本补全、嵌入、图像、语音、文件、批处理、模型列表。这八类里，前两类的路径形态最接近，后面几类各家实现差异会越来越大。看每一类时只需要盯三件事：请求方法是什么、路径后缀长什么样、返回体顶层结构是什么样。

路径形态这一列故意写得模糊，因为各家喜欢在前面加不加前缀、用不用复数，都会影响你拼出来的 URL。正确的做法是到站内的模型资料库和端点对照页面核对当时的实际写法，别凭记忆拼。看到文档没写的端点，不要默认它有——先用最小请求探一下，比事后改代码便宜。

对话类端点：路径之外还要核对哪些字段

对话补全是最常被打的端点，也是「看起来一样、跑起来不一样」重灾区。路径对了只是第一步，请求体里几个字段的取值方式不核对，照样报 400 或返回结构对不上你的解析逻辑。

messages

必须确认是标准角色数组，且角色取值只认那几个固定词，别自己发明

content

区分纯字符串和分块数组两种写法，有的实现只吃其中一种

流式开关

布尔字段名要逐字核对，开启后返回的是事件流而非单个 JSON

长度与采样字段

最大长度、温度、top_p 这类字段名在不同实现里可能只认一种拼法

tools 与结构化输出

属于增强能力，缺了不代表接口坏，但你的代码要能降级

这里最容易踩的坑是 content 的类型。你按分块数组写，对方只认字符串，报错信息可能只说「参数无效」，看不出是类型问题。反过来也一样。切换前把项目里实际用到的字段抄成一张表，逐个到目标端点的返回样例里找，找不到就标记出来，比联调时盲猜快得多。

嵌入、图像、文件与批处理端点

嵌入端点看起来简单，其实有两个必须核对的点：输入是单条还是数组，返回向量放在哪个键下。有的实现只接受单条字符串，你传数组直接报错；有的返回顶层键名字和标准写法差一个字母，你的解析代码就会拿到空值。

• 嵌入：先确认输入形态（单条还是批量），再确认向量所在的键名和维度顺序
• 图像：生成与编辑是两条路径，参数命名差异最大，尺寸和画质类字段尤其爱改
• 语音：转写和合成分开，得确认接受的音频格式和返回的是文本还是二进制
• 文件：先确认对方是否支持上传，再确认删除和查询是否配套
• 批处理：多为选配，先问清楚有没有，别排进第一批迁移计划
• 模型列表：单独看下一节，它是最轻的自检入口

这几类里，文件与批处理属于典型的「锦上添花」。如果你的业务不依赖它们，完全可以先跳过，把对话和嵌入跑通再说。反过来，如果你的检索链路依赖嵌入，那嵌入端点的字段差异必须在上线前解决，不能留到观察期。

模型列表端点是自检的第一站

模型列表通常是最轻的端点：一次 GET，不需要请求体，返回一个模型数组。它的价值不在于列出多少模型，而在于帮你把「网络通不通、密钥对不对、渠道配没配好」这三件事一次性排掉。

要特别注意最后一行：列表能通不等于补全能通。列表只是证明鉴权和网络没问题，补全还会额外受路径、字段、模型可用性影响。所以别把模型列表当唯一验收标准，它只是排查顺序里的第一步。

切换前先做一份字段差异清单

与其在联调时一个个撞，不如切换前花半小时把项目里真正用到的字段列出来，对照目标端点的返回样例，标出差异类型。差异分三类，处理方式完全不同。

• 字段名不同：改配置或加一层映射，别改业务逻辑
• 值类型不同：比如字符串和数组互转，要在适配层里做转换
• 根本不支持：写清降级方案，比如去掉工具调用改走纯文本
• 必填变可选或反过来：影响你的默认值策略，必须标出来
• 返回体顶层结构不同：影响解析入口，通常要包一层适配函数
• 流式和分块的差异：影响你的读取循环，单独列一条

联调排查顺序：从最便宜的动作往上试

排查要讲顺序，先做成本最低、最容易定位问题的动作。上来就开流式、带上全部参数，报错信息会混在一起，你分不清是路径、字段还是密钥的问题。

1. 第一步：打模型列表确认鉴权和网络通。返回空数组就去站内核对渠道配置，别急着改代码。
2. 第二步：发一次非流式最小请求只带必填字段，确认返回体顶层结构。这一步能通，说明路径和鉴权都对。
3. 第三步：逐个加字段把长度、温度、工具调用等字段一个一个加上去，哪一步报错就定位到哪个字段。
4. 第四步：最后才开流式流式对读取方式有要求，放最后验证，避免和前几步的问题混在一起。
5. 第五步：记录每步的证据记下请求路径、状态码、返回体前几行，方便和站内对照表逐条比对。

报错码本身就是线索：404 大概率是路径问题，400 多半是字段或类型不对，401 先别改代码，去看密钥和鉴权头。按这个顺序走，多数问题在第二步就能暴露出来。

多端点并存时怎么留退路

真实项目往往不止挂一个端点，这就要求把「换端点」这件事做成配置，而不是散落在业务代码里。否则每次切换都要全局搜索替换，漏改一处就出线上问题。

路径配置化

把各端点路径收进配置文件或环境变量，业务代码只引用键名

字段映射层

在请求发出前统一做一次字段名和类型的转换，业务层不感知差异

状态码分流

超时和 5xx 处理方式不同，前者可重试，后者更适合直接换端点

观察期

切换后留一段观察期，重点看报错率和响应结构有没有悄悄变

回滚开关

保留切回旧端点的能力，出问题时能一键退回，而不是线上改配置

观察期里最该盯的不是成功率，而是返回结构有没有变化。字段名没变但值类型变了，成功率看不出来，解析却会悄悄出错。这个阶段适合每天跑一遍固定用例，比对返回体的键集合。

什么情况下这套盘点不适用

这套方法有个前提：对方确实提供的是 OpenAI 格式的兼容接口。如果对方用的是自定义协议，或者需要额外的鉴权头、签名参数，照抄标准写法一定不通，这时候该做的是读它自己的文档，而不是套这套清单。

• 对方是自定义协议：字段和路径都不通用，按对方文档来
• 需要额外鉴权头或签名：先解决鉴权，再谈字段差异
• 只做对话不做嵌入和图像：可以整节跳过，别浪费时间核对
• 对延迟极敏感：端点数量不是重点，先去站内测速页面拿到基线
• 对方文档缺失端点说明：先用最小请求探，探不出来别硬上

先探端点，再抄字段；先打列表，再开流式。顺序对了，八成的问题都不用猜。