写应用代码之前，先用 curl 验证第一次 /chat/completions 调用

接入一个新的 LLM API 聚合站时，最先出问题的往往不是业务逻辑，而是鉴权头、base URL 拼写、模型名大小写这类细节。如果一上来就写应用代码，报错会同时来自网络、SDK 封装和你的业务逻辑，很难定位。先用 curl 把这层跑通，能把「接入问题」和「应用层 bug」分开。

先准备三个环境变量

把 key 和 base URL 放进环境变量，后面所有命令复用，避免每次手打出错。

export API_BASE="https://你的聚合站域名/v1"
export API_KEY="sk-你的key"

注意 base URL 通常要带 /v1 这一段，具体以文档里的接口地址为准。很多人第一次调不通，就是把 /v1 漏了或者重复写了。

第一步：确认鉴权能过

先用最小的请求体，只看两件事——HTTP 状态码和返回的 JSON 结构。

curl -sS -w '\nHTTP %{http_code}\n' "$API_BASE/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "模型名",
    "messages": [{"role": "user", "content": "ping"}]
  }'

-w 把状态码打在最后，方便一眼判断：

• 200：鉴权通过，继续下一步。
• 401 / 403：key 本身有问题——多复制了空格、key 已失效、或者没带 Bearer 前缀。
• 404：多半是路径拼错，检查 /v1 和 /chat/completions 是否完整。
• 400：鉴权已经过了，问题在请求体，通常是模型名写错或 JSON 不合法。

想看得更清楚，可以给 curl 加上 -i 打印响应头，或者把响应体交给 jq 格式化。

第二步：确认模型名的解析

聚合站会把你的模型名映射到实际提供方。同一个模型可能支持多种写法（例如带或不带提供方前缀的别名），但解析失败时的报错信息往往很含糊。

用同一个 key，把 model 字段换成你要用的名字再跑一次上面的命令。判断依据：

• 返回正常：这个名字被解析到了，可以写进代码。
• 返回模型不存在/不支持类的错误：这个名字不在这家站的映射表里，换一个别名再试。

建议把你要用的每个模型都用 curl 单独确认一次，而不是只测一个就认为「全都能用」。模型清单和可用别名以该站文档为准，不要凭记忆猜。

这一步还能顺手区分两类错误：如果换模型名后错误类型变了（从鉴权错误变成模型错误），说明 key 是好的；如果一直是同一个鉴权错误，就回到第一步。

第三步：确认流式输出

应用里最常用的就是流式。流式的问题在于：即使返回 200，也可能中途断开，或者格式和预期不同。用 -N 关掉 curl 的缓冲，直接看原始分块输出。

curl -sS -N "$API_BASE/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "模型名",
    "messages": [{"role": "user", "content": "数到十"}],
    "stream": true
  }'

正常时你会看到一串 data: 开头的行，最后以 data: [DONE] 之类的终止标记收尾（具体格式以文档为例）。要观察的点：

• 内容是不是逐块返回，而不是等很久后一次性吐出。
• 分片是不是以预期的分隔方式出现，应用里的解析逻辑要跟这个格式对齐。
• 结尾有没有明确的终止信号，否则你的流式循环可能挂住。

如果普通调用能过、流式调用卡住或报错，问题基本在服务端对该模型的流式支持或你的网络链路上，而不在你的应用代码里。

常见坑位的快速对照

• 少写 Bearer 前缀：鉴权失败最常见的原因之一，注意 Authorization: Bearer $API_KEY 中间有个空格。
• JSON 用了单引号包裹但内部又是单引号：shell 会提前截断。统一用外层单引号、内层双引号。
• 换行和空格：-d 里的 JSON 可以多行，但要确保没有尾随逗号。
• key 泄露：不要把真实 key 贴进聊天记录或提交进仓库；用环境变量，测完及时清理终端历史。

这套顺序为什么有效

三个步骤各自只验证一件事：第一步只验证「key + 路径」，第二步只验证「模型名映射」，第三步只验证「流式形状」。每步失败时，可能的原因被压缩到很小范围。

等你把这三步跑通，再装 SDK、写重试、接业务，出错时就基本可以断定是应用层的问题——因为底层链路已经被 curl 独立验证过了。这不是多此一举，而是把调试成本从「翻 SDK 源码」换成「改一行命令」。