很多人拿到 Key 之后就卡在填地址这一步：不知道 base_url 到底该写到哪一级，官方地址、兼容站地址、带不带 v1 混着抄，结果一跑就 404 或者连接被拒。这篇不讲协议原理，只给你一个填写口径和一套从报错反推的排查顺序，照着对一遍基本能定位问题出在域名、路径还是客户端自己帮你补了一段。
拿到 Key 之后卡在填地址这一步的人特别多。不是不懂协议，是不知道 base_url 到底该写到哪一级：官方地址、兼容站地址、带不带版本段，全混在一起抄，跑起来不是 404 就是连接被拒。这篇不讲原理，只给一个填写口径和一套从报错反推的排查顺序，照着对一遍，基本能定位问题出在域名、路径，还是客户端自己帮你补了一段。
先记住一句话：多数客户端配置里的 base_url 是前缀，不是完整请求地址。具体端点由 SDK 自己拼上去，你多填一段，它就重复一段。下面分四步走，先分清填的是哪一层，再对照写法，然后把常见错法挨个排掉，最后按报错类型定位。
先分清「接口地址」指的是哪一段
一次请求的完整地址可以拆成三层：站点根域名、版本路径、具体端点。绝大多数客户端只让你填前两层，端点交给 SDK 拼。你要是把三层全塞进配置项，等于告诉它「端点也在这」，它会再拼一次，路径就重了。先把这三层在心里分开，后面填什么都不容易乱。
- 站点根
- 协议加域名，有时带端口，指向服务方入口。
- 版本段
- 形如一个短的版本标识，标明调用的是哪一代接口规范，由服务方文档指定。
- 端点
- 具体功能路径，比如对话、向量、模型列表，由 SDK 或你自己在请求时拼接。
同一个站点有时会同时开放官方风格路径和兼容风格路径，两者不能混着用。选一种从头用到尾，中途换风格最容易出现「半截对半截错」的路径。要比较不同站点的口径和额度，可以先去站内 API 分类页把地址和计费规则一起看一遍，省得来回试。
先对齐站点口径再动手各家兼容地址的写法和限额规则差别不小，先在同一页里横向看一遍，比填完再报错回头查快得多。→填写口径：三行对照着抄
下面这张表是判断标准，不是让你照抄某个具体字符串。用的时候把「填什么」那一列换成你手上站点文档里写的内容，其余判断逻辑通用。
| 使用场景 | 配置项该填到哪一层 | 注意点 |
|---|---|---|
| 官方渠道 | 站点给出的根地址，版本段按官方文档指定写法 | 别自己补结尾斜杠，官方文档怎么写就怎么写 |
| 第三方兼容站 | 以该站文档标注的兼容地址为准，通常已含版本段 | 照抄，不要按官方习惯给它补一段 |
| 自建或反向代理 | 指向你自己的域名 | 确认反代有没有改写路径前缀，改过和没改过填法不同 |
| 本地测试 | 指向本机地址加端口 | 先做最小请求，通了再往后加路径 |
- 先做最小连通性验证配置项只填到域名一级，发一次最简单的请求。通了说明域名和鉴权没问题，再逐段往后加路径。
- 再对齐版本段把客户端实际发出的完整地址打日志打出来，跟文档示例逐字符比。人眼比对最容易漏斜杠，一定要看打出来的字符串。
- 最后固定写法验证通过后把地址写进环境变量，别散落在各个客户端配置里。换机器、换客户端时直接引同一份。
判断标准很简单：最小请求通、加上版本段也通，才算这个地址可用。只通第一步说明路径还没对上，只通第二步而第一步不通，往往是客户端自动补了版本段，说明你填多了。
四种最常见的写错方式
这四种错了之后的报错长得不一样，记一下能省很多时间。共同点是都属于「路径层」问题，别一看见报错就去改 Key 或者换网络。
- 多写端点：把完整请求地址当 base_url 填进去，路径里同一个端点出现两遍，报错通常是 404。
- 漏版本段：客户端不会替你补，路径看着只差一截，同样是 404，但和上一种的路径长度明显不同。
- 结尾斜杠不一致：有的客户端会再拼一层斜杠，路径变成双斜杠，部分网关直接拒掉，报错可能不是 404。
- 协议写错：http 与 https 混用，表现是连接被重置或证书报错，而不是 404，这一类很容易被误判成服务方故障。
还有一种不算填错但很常见的情况：地址填对了，服务方本身不通。这时候怎么改地址都没用。可以先用站内的在线实测工具跑一遍，把「我填错了」和「站本身连不上」这两件事分开，再决定往哪个方向查。
先确认站本身通不通地址排查到后面容易钻牛角尖，先用实测工具确认服务端可达性，能省掉大量无效改配置的时间。→按报错类型反推的排查顺序
顺序很重要：先把报错归类，再往对应方向查，比从域名到 Key 从头试一遍快得多。下面这段顺序按「先排除地址、再排除鉴权、最后排除网络」排列。
- 第一步：看是不是 404是 404 就集中在路径上查，先看实际发出的完整地址里端点是不是出现了两次，再看版本段有没有漏。
- 第二步：看是不是鉴权类 4xx报错里提到鉴权、权限，基本说明地址已经对上了，问题在 Key 或请求头，这时候别再改地址，改了反而把对的改错。
- 第三步：看是不是连接类报错超时、连接被拒、证书错误，优先查协议是 http 还是 https、端口对不对、本地有没有代理拦截。
- 第四步：比对完整地址把实际发出的地址打日志，和文档示例逐字符比一遍，重点看斜杠数量和版本段位置。
- 第五步：区分服务方问题以上都排除后，用中转站真假在线实测确认服务端可达性，避免把服务方故障当成自己填错。
什么时候不适用这套顺序：如果你用的是自建反代，路径被改写过，那 404 更可能出在反代配置而不是客户端填法。这时候直接去看反代有没有剥掉或追加前缀，比在客户端里反复改更快。
减少下次再踩的几条习惯
地址这类问题本身不大，但反复出现很耗时间。把下面几条做成习惯，团队里新人接手时就不用再从头踩一遍。
- 把可用地址写进项目环境变量，不要散落在各个客户端配置里，换人换机器都引同一份。
- 团队维护一张「站点 + 兼容地址 + 已验证时间」的小表，新人直接抄，不用猜。
- 换站点或换客户端的当天就做一次最小连通性验证，别等业务代码写完才发现地址不对。
- 地址变更和 Key 轮换分开管理，两件事混在一起排查时会互相干扰。
- 遇到新的兼容站，先看它文档里的地址写法再配，不要按上一个站点的习惯照搬。
常见问题
openai 兼容接口地址和官方地址能混用吗？
不能。官方地址只对官方服务有效，第三方兼容站的地址是各家自己的域名和路径，两者只能选一个整条链路用到底。混用最典型的表现是地址看着眼熟但一直 404，或者鉴权通过却找不到端点。换供应方时把地址和 Key 一起换掉。
base_url 结尾到底要不要加 /v1？
取决于你用的客户端和站点文档。有的 SDK 会自己补版本段，你再写一遍就会路径重复；有的兼容站把版本段直接写进了它给的地址里。稳妥做法是照抄站点文档里给的那一行，不做任何增删，然后用一次最小请求验证通过。
地址填对了还是不通怎么办？
先把实际发出的完整地址打印出来逐字符比对，确认没有多余路径、斜杠和协议问题；再确认网络层能到（代理、防火墙、证书）；最后才怀疑服务端。用真实中转站在线实测把站点本身的问题排除掉，能省掉大量来回猜的时间。
