假设配置文件里写着 API_BASE_URL=https://api.vsoui.com/v1,业务代码里写着 ${API_BASE_URL}/v1/chat/completions。分开看,两行都挺眼熟。拼在一起,问题就出来了:
https://api.vsoui.com/v1/v1/chat/completions
如果网关没有这条路由,请求就可能收到 404。这时候换模型名,只会带着新模型再走一遍同样的错路。
先把最终地址打印出来
如果服务商文档给的接口前缀已经以 /v1 结尾,手写 Chat Completions 请求时,只需要再拼上 /chat/completions。下面这两行可以直接在终端里跑,不需要 Key:
API_BASE_URL='https://api.vsoui.com/v1'
printf '%s\n' "${API_BASE_URL%/}/chat/completions"
这里的 ${API_BASE_URL%/} 会去掉前缀末尾的一个斜杠。对照文档时,要看的是配置和业务代码拼出来的完整 URL。如果你用 SDK,也看一下实际发出的请求路径,有些客户端会自行追加接口路径。
地址对了,再看响应正文
我喜欢把项目先放到一边,用同一个 Key、同一个模型发一条最短的消息。下面这段适用于装有 Python 3 和 curl 的 macOS,在 zsh 终端里直接粘贴即可。模型 ID 从自己账号的可用模型列表复制。
(
read -rs 'api_key?输入 API Key(输入时隐藏):'
printf '\n'
read -r 'model_id?输入模型 ID:'
python3 -c '
import json, sys
print(json.dumps({
"model": sys.argv[1],
"messages": [{"role": "user", "content": "请只回复 OK"}]
}))
' "$model_id" | curl --silent --show-error --max-time 30 \
--header "Authorization: Bearer $api_key" \
--header 'Content-Type: application/json' \
--data-binary @- \
--write-out '\nHTTP %{http_code}\nURL %{url_effective}\n' \
'https://api.vsoui.com/v1/chat/completions'
)
最后的 --write-out 会把状态码和 URL 放在响应正文下面。同样看到 404,正文不同,下一步要查的地方也不同:
| 终端里看到什么 | 接下来查哪里 |
|---|---|
URL 出现 /v1/v1/ | 回到拼接 URL 的那一行,看看版本前缀加了几次。 |
URL 正确,JSON 里有 model_not_found | 核对模型 ID 的完整拼写,以及当前 Key 能访问的模型。 |
| 正文是整页 HTML | 看页面标题。如果是网站的 404 页面,核对请求域名和反向代理的路由。 |
HTTP 200,且 choices[0].message.content 有回复 | 保留这组能跑通的配置,与项目运行时读取的地址、模型名逐项对照。 |
还有个容易漏掉的细节:终端请求成功,改完项目的 .env 却仍然报错。这时可以在服务端临时打印当前进程读到的接口前缀和模型名,确认进程已经加载新配置。打印这两个字段就够了,Key 和完整请求头留在日志之外。
文里用的是我维护的维索 API。为了方便对照,我把接口前缀、cURL 和 SDK 示例放在了同一页。使用其他兼容服务时,换成对应的地址和模型 ID,也可以按上面的顺序排查。维索 API 接入示例