openai 兼容 base url 配置

你拿到一个中转站或自建网关的地址，文档只丢给你一句「把 base_url 换成我们的」，接上去不是 404 就是偶尔超时，换台机器又好了。这篇不解释协议兼容层，只讲工程落地：这个值该写在哪、路径怎么拼、超时重试按什么档设、日志该留哪几个字段、上线前按什么顺序验证。适合已经在写代码、只差把地址配对的人。

你拿到一个中转站或者自建网关的地址，对方文档只丢一句「把 base_url 换成我们的」，照做之后不是 404 就是偶尔超时，同一份代码换台机器又跑通了。这类问题九成不在协议兼容层，而在工程配置：值写在哪、路径拼到哪一层、超时重试按什么档设、日志留哪些字段、上线按什么顺序验证。

这篇不讲模型能力也不讲协议原理，只讲把这个地址接进项目里最不容易翻车的做法。适合已经在写代码、只差把地址配对的人。判断标准给的是通用档位，具体数值请按你自己的延迟基线和站内当时的资料去核对。

这个值到底写在哪：代码、环境变量还是配置文件

最省事的做法往往埋最深的坑：直接把地址写进业务代码。一旦要切环境、切供应商，你得改代码、重新走发布流程。正确做法是把 base_url 当成和密钥同级的运行时配置，通过环境变量或配置中心注入，代码里只留读取逻辑。

• 开发、测试、生产三套地址分开存，别共用一个变量名再靠人肉改
• key 和地址成对切换：换地址通常等于换账户，只改一边大概率鉴权失败
• 前端项目别把地址和 key 一起打进浏览器包，浏览器直连要另做网关转发
• 配置读取失败要快速报错，不要静默回退到官方地址，否则线上流量会悄悄走错路

路径怎么拼：最容易被多写或少写一段的地方

大部分 SDK 会在你给的 base_url 后面自己补版本段和资源路径。你要给的是它期望的那一层，多写一段就 404，少写一段也会 404。自建网关还多一层前缀映射，它到底转发完整路径还是剥掉前缀后的路径，必须和上游约定一致。

1. 打一条最小请求用最短的调用打过去，请求体尽量小，先把连通性跑通再谈业务。
2. 打印实际完整 URL在 HTTP 客户端或 SDK 的钩子里把最终请求的完整 URL 打出来，和文档里的示例逐段比对。
3. 固定两种写法做对照分别在带版本段和不带版本段的情况下各打一次，确认哪一种通、另一种报什么码，把结论写进项目说明。

超时与重试：按档位设，别一个值用到底

很多人只设一个超时值然后用到底，结果连不上和读响应慢被同一个数字卡住。连接超时和整体超时要分开：连不上要快速失败，把时间留给重试或降级；读响应尤其是流式输出，要给足时间，否则会被中途掐断。

• 非流式问答可以重试，但必须带退避与次数上限，别写成死循环
• 已经吐了一部分的流式请求不要重试，重放会重复计费还可能产生重复内容
• 重试只对可安全重放的请求开，带副作用的写操作一律不重试
• 把重试次数和最终失败都记进日志，否则线上问题会被「其实重试成功了」掩盖

具体档位没有万能值，建议先量出自己的延迟分布，再决定分位线。站内有延迟与可用性相关的测试页，可以拿它当基线，到你自己的业务里再上下浮动。所有关于延迟的数字，请到站内实测页核对当时的表现，不要照抄别人的配置。

日志留哪几个字段，以及上线前的验证顺序

换地址期间最怕的是「看起来没报错」。日志里至少要有目标 host、实际请求路径、状态码、耗时、是否发生重试、以及用的是哪把 key 的别名。这几个字段凑齐，一次排查就能定位是路径问题、鉴权问题还是限流问题。

1. 先测连通性发一条最小请求，确认能拿到任何合法响应，哪怕是一个错误码，也说明网络通。
2. 再测鉴权用目标 key 打一次，确认不是 401/403；如果失败，先核对 key 与地址是否配套。
3. 再测流式单独验证流式输出能完整读到结束，中途断开要能区分是超时还是服务端主动结束。
4. 最后压小批量并发用一小批并发看限流与排队表现，确认失败是可重试的类型还是直接被拒。
5. 确认返回来源检查返回内容与响应头，确认确实来自新服务，而不是本地代理或旧缓存兜住的旧结果。

换地址后别只看「没报错」，要确认返回内容确实是新服务给的。