openai 兼容的 api 接口

你已经拿到一个 key 和一段 base_url，模型也能调通，但真接进项目就开始出问题：换一家中转站返回少一个字段、超时设多少没底、并发一上去就限流、日志里看不出这次请求慢在哪。这篇不讲协议原理，只给工程落地时的对照表和排查顺序，帮你把「能调通」推到「敢上线」。

你手里已经有一个 key 和一段 base_url，模型也调通了，但真接进项目就开始出问题：换一家中转站返回少一个字段、超时设多少没底、并发一上去就限流、日志里看不出这次请求慢在哪。这篇不讲协议原理，只给工程落地时的对照表和排查顺序，帮你把「能调通」推到「敢上线」。

下面所有涉及具体数字的地方——各家站点的额度、延迟、稳定性记录——都不在这里写死，你到站内对应页面看当时的数字更靠谱。代码示例只讲结构和判断依据，参数值请你按自己线路实测再填。

先分清哪些字段是硬契约，哪些是软实现

很多人把 OpenAI 兼容接口当成一套完整标准，其实是「请求侧高度统一、响应侧各写各的」。请求侧那几个必填项和响应侧取内容的位置，改了就报错，这是硬契约；而 usage、finish_reason、id、created 这类元信息属于软实现，不同中转站缺哪个都不一定影响你跑通。分不清这两类，就会在无关紧要的字段上死磕。

判断一个站是否可用，最省事的办法是写一个最小探针请求，把响应原样存下来逐字段比对。满足三条就算可用：能取到内容、能判断是否结束、能拿到用量。缺用量统计的站别急着放弃，很多只是没透传，你到站内的接口测速与对齐页面核对口径即可。

1. 发一次最小请求只给必填字段，不带任何扩展参数，把完整响应文本落盘保存。
2. 逐字段打勾对照上面的表，把每个字段标成有值、为空、不存在三种状态。
3. 换站重复把同一段探针代码指向第二家站点，比较两份结果，差异点就是你要写兼容分支的地方。

接中转站时最容易踩的适配差异

同一段代码在 A 站正常、B 站报错，八成不是网络问题，而是可选字段被拒或者必填字段没给。定位方法是二分：先发最小请求，如果通了，再逐个把字段加回去，加到哪个报错就是哪个字段的问题。别一上来就怀疑密钥或者额度，那种情况通常报错信息更直接。

• 流式与非流式的取值位置不一样，切换时最容易读到空内容，两条路径都要写探针，不能只测一种。
• 模型名不要硬编码在业务代码里，放进配置或环境变量，换站时只改一处，省得满项目搜字符串。
• 参数里那些「可有可无」的扩展项，换站前先确认对方接不接，不接就整段注释掉再发。
• 错误响应结构各站不同，别直接按某一家去解析错误码，先看原始响应体再决定怎么抓。

还有一类差异是超时语义：有的站在服务端提前掐断连接，你这边看起来像网络故障，其实是它自己的限制。遇到这种先看响应头和返回体，再判断是自己的读取超时设短了，还是对面主动结束了。

超时、并发、重试三件事要一起定

这三件事分开调永远调不好。超时分三档更实用：连接超时管建连，读取超时管拿到第一个字节之后，整体超时兜住整个请求。流式请求的读取超时要按「两次数据之间的间隔」算，而不是按总时长算，否则一个长回答会被你自己的超时先掐断。

并发数是上限，不是目标。按你账号的额度分档排队，超出的进队列，而不是直接放大重试次数。重试一定带退避，并且设总次数上限，不然限流时会雪崩。

阈值从哪来？先自己跑一次接口测速，量出这条线路的延迟基线，后面所有超时和并发都拿这个基线当参照。别人的经验数字对你没用，因为线路和时段都不一样；站内的测速记录页可以当对照，但仍以你自己的实测为准。

排查顺序

1. 看是哪一个超时连接失败、首字节迟迟不来、整体超时，三种日志写法要能区分开。
2. 看是否被限流限流通常有明确的返回结构或状态码，先确认再降并发，不要盲目降。
3. 再动重试前两步都没问题还偶发失败，才考虑加退避重试，且必须设上限。

降级与日志：出问题时能自证

降级不是「出错了就换一个」，而是一条有顺序的路径：同站换模型 → 换备用站 → 返回兜底结果。每一步都要在响应里标记实际走了哪条路，否则事后复盘你根本不知道用户那次到底命中哪个分支。这个标记成本很低，价值很高。

最后补一条前提：每次调用尽量做成幂等的，重试不会产生重复副作用。做不到幂等就别轻易开自动降级，否则失败一次重试一次，业务侧会收到重复结果。这条比任何超时参数都重要。

能把故障讲清楚的那套日志，比多接两家备用站更能救命。