openai 的 api 接口规范

接第三方模型时，接口文档看着都差不多，真跑起来却总在字段缺失、超时、限流上栽跟头。这篇不重复讲协议兼容层，只从工程落地角度把 OpenAI 接口规范的字段读法、必填与可选项、调用约定讲清楚，再给一套超时、并发、降级和排查的顺序，让你拿到任意一家兼容接口都能自己判断能不能用。

接第三方模型时，接口文档看着都长得差不多，真跑起来却总在字段缺失、超时、限流这几个地方栽跟头。这篇不重复讲协议兼容层怎么做，只从工程落地角度，把 OpenAI 接口规范的字段读法、必填与可选项、调用约定讲清楚，再给一套超时、并发、降级和排查的顺序，让你拿到任意一家兼容接口都能自己判断能不能用。

先明确一点：接口规范约束的是字段名、必填项和返回结构，它管不了模型好不好用。很多时候你调不通，报的错跟模型能力一点关系都没有，纯粹是字段写错了、层级多包了一层，或者把某家的默认值当成了通用契约。所以顺序应该是先读规范、再写代码，而不是先跑通一个 demo 再回头补。

为什么先看规范再写代码

第三方兼容实现经常只覆盖一个子集，你以为标准里有的字段，对方可能压根没实现，或者实现了但语义不同。写代码前先把你要用的字段列出来，一个个去对方文档里确认在不在，比跑起来之后靠报错反推要省事得多。

• 文档里能查到的字段优先用，文档没写的字段一律当不存在处理，不要靠猜
• 如果业务强依赖某个冷门字段，比如某些特殊返回结构，而对方文档没写，这条通道就不适用，别硬接
• 同一套代码要接多家时，把「通用字段」和「通道特有字段」分成两组配置，避免改一家坏另一家
• 规范只是下限，它保证你能发出去请求，不保证返回质量稳定，质量要另做评测

请求里哪些字段是硬性约定

模型标识、消息数组、流式开关属于几乎所有兼容实现都会做的基础项，其它字段按需带就行。消息数组的 role 和 content 结构要严格对齐，role 是系统、用户、助手这几类之一，content 可能是字符串也可能是分块数组，多包一层或者类型不符，是最常见的参数错误来源。

可选字段不传时会走服务端默认值，各家默认值不一样，别把默认值当契约。你要稳定的输出风格，就显式带上温度这类参数；你要控制长度和成本，就显式带最大输出长度。默认值只适合做快速验证，不适合上生产。

响应结构怎么读才不出错

第一步先判断返回是不是流式：非流式是一整个对象，流式是一串分片，两者的解析逻辑不能共用，混用就会出现在流式里找整包字段、或者把分片当完整结果的情况。建议封装成两个独立解析函数，入口按开关分流。

然后关注结束原因字段，它决定你是正常收完还是被截断。被截断就该走降级或续写逻辑，而不是直接把半截结果返回给用户。用量统计字段不一定每家都给，做成本核算前先确认有没有，没有就得靠本地估算，估算口径要和站内页面对齐。

• 先看流式开关，决定用哪套解析逻辑
• 再看结束原因，判断是否截断
• 取内容时按 choices 结构逐层取，不要假设固定层级存在
• 用量字段有就用，没有就本地记，注明是估算值
• 错误返回也是响应，要单独分支处理，别混进正常解析

超时、重试与重试边界

连接超时和读取超时分开设。连接超时管的是握手能不能连上，读取超时管的是发出请求后等多久算放弃。读取超时按任务类型分档，长文本生成和短分类不该用同一个值，否则要么长任务被误杀，要么短任务卡着不动。

1. 分开设置两类超时连接超时设短一点快速失败，读取超时按任务分档；验证方式是造一个慢通道，看是否按预期中断
2. 只对可重试错误重试连接失败、服务端错误可重试；参数错误、鉴权失败重试多少次都没用，直接抛出
3. 带退避和次数上限重试间隔逐步拉长，次数封顶，否则一次抖动会被放大成一轮流量高峰
4. 记录每次重试把重试次数和目标通道写进日志，事后才能判断是通道不稳还是你的参数有问题

重试不是万能药，它只对「可能下一次就成功」的错误有意义。

并发与队列怎么排

并发上限按账号实际额度决定，不要按单机能开多少线程决定。单机线程数只反映你的机器能力，额度反映的是通道允许你打多快，两个数取小的那个才安全。做法是用一个固定大小的队列当缓冲，出口并发固定，队列只做摊平突发，不做无限堆积。

触发限流后按退避节奏降速，同时记录触发时间点，方便判断是额度问题还是账号被风控。这两类现象长得很像，但处理方式完全不同：额度不够可以调并发，风控往往要换通道。区分不了的时候，先按额度处理，再观察是不是反复出现在同一批请求上。

降级路径怎么留

降级顺序建议是：同通道换模型、换通道、返回缓存或兜底文案，每一层都要能单独开关，方便出问题时快速定位是哪一层在起作用。触发条件要写死，比如连续失败几次、或者首字迟迟不来，避免靠感觉切换，不同人对「慢」的判断不一样。

• 同通道换模型：同家的其它模型，字段兼容度最高，优先试
• 换通道：切到另一家中转，注意字段子集可能不同
• 返回缓存：对时效要求不高的场景可用，但要标注是缓存结果
• 兜底文案：最差一层，至少保证业务不崩
• 每一层独立开关，方便单独压测和关闭

日志该记什么才能复盘

每次请求至少记请求标识、目标通道、模型标识、耗时拆分、状态码、是否命中重试。耗时拆分建议分成排队、连接、首字、总时长几段，光看总时长分不清是通道慢还是你自己处理慢。

请求体按隐私要求脱敏后留摘要，别整包落盘；返回只留用量和结束原因。这样体积可控，又足够复盘。排查一个又慢又贵的请求时，靠这几项就能定位是通道慢、重试多，还是输出失控。

请求标识

串起一次请求的所有日志，方便按 ID 捞全链路

耗时拆分

区分排队、连接、首字、总时长，定位瓶颈在哪一段

是否命中重试

判断这次失败是通道抖动还是参数问题

结束原因

判断输出是正常收完还是被截断

接入后的验证顺序

验证要按顺序来，别一上来就测复杂场景。先用最小请求验证连通与鉴权，再验证流式，最后验证工具调用或结构化输出。前一步不过，后面测出来的问题都不可信。

1. 最小请求只带基础必填字段发一次，确认鉴权和连通都正常，失败先查密钥和地址
2. 流式验证打开流式开关，确认分片能正常拼接、结束原因正确，别把半截当完整
3. 扩展能力验证测工具调用或结构化输出，逐字段核对返回是否符合预期
4. 固定样例回归把验证用的样例固定下来，接口规范升级或换通道后重跑一遍对比
5. 测速对照先在站内工具量个基线，和线上日志对照，差太多说明中间还有一层问题

测速和连通性可以先在站内工具里量一个基线，和线上日志对照。如果你测出来的延迟远低于线上日志，那大概率是线上多走了一层你没想到的转发或者重试。各家通道的实测数据和当时的报价，可以到价目与测速页面对照，别拿别人嘴里的印象当依据。