是 SDK、适配层还是聚合站：用一条裸 curl 基准线定位故障层

调用失败时最常见的误区是：直接在业务代码里加日志、改 SDK 版本、或者换一个模型重试。这些动作都在客户端栈的高层进行，反而掩盖了问题真正所在的那一层。一个更可靠的做法是：把这次调用剥到最底层——一条裸 curl 请求——然后逐层往回加，看问题从哪一层开始出现。

先明确客户端栈有哪几层

一次典型的 LLM 调用经过的层次大致是：

• 业务代码（你的 prompt 拼接、参数组装）
• 模型 SDK 或官方客户端库（负责鉴权、序列化、重试、流式解析）
• 适配层（如果你用了统一接口封装、OpenAI 兼容层、自建网关或代理）
• 网络与传输（DNS、TLS、HTTP/2、代理、超时）
• 聚合站或上游服务（网关鉴权、路由、模型转发、计费）

任何一层都可能出问题，但报错信息通常由最上层抛出，因此具有误导性。裸 curl 的价值在于：它跳过前三层，直接验证最后两层。

第一步：构造最小可复现的裸请求

从失败的调用中提取四样东西：请求地址（base URL + 路径）、鉴权头、请求体、以及内容类型。然后用 curl 原样发出：

curl -sS -i https://<你的接入地址>/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<模型名>","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'

几个细节值得注意：

• 用 -i 或 -v 保留响应头和状态码，它们是判读的关键。
• -sS 让 curl 静默但保留错误输出，避免把网络错误吞掉。
• 请求体用最小化内容（一条短消息、小 max_tokens），排除参数过长导致的干扰。
• 如果模型名、路径来自配置文件或环境变量，请手工确认它们的实际取值，而不是凭印象填写。

第二步：读状态码，而不是读报错文案

状态码是把问题分层的最快线索：

• 连接阶段就失败（curl 报 could not resolve host、connection refused、SSL 握手失败、超时且无响应头）：问题在网络、DNS、代理或地址配置，与模型服务无关。
• 401 / 403：鉴权层。检查 key 是否被正确读取、是否带了多余空格或换行、请求头格式是否为 Bearer。
• 404：路径或模型名不匹配。常见于适配层把 base URL 拼错，或模型标识符与网关支持的名称不一致。
• 400 / 422：请求体结构问题。多半是参数名、字段类型或必填项不符合该接口约定，也可能来自适配层的字段转换错误。
• 429：请求频率或额度限制，属于服务侧策略，而非代码缺陷。
• 5xx：服务侧或网关转发异常。此时裸 curl 复现即为有效证据。

如果裸 curl 返回 200 且内容正常，说明鉴权、网络、路径、模型名、请求体结构都没有问题——故障大概率在 SDK 或适配层。

第三步：逐层加回，锁定起始层

裸 curl 通过后，按相反顺序把层次加回去，每一步只增加一层：

1. 加回适配层：用你自建网关或统一接口的地址发同样的裸请求。若此处失败，问题在适配层的路由、字段映射或鉴权透传。
2. 加回 SDK 的最小示例：用官方 SDK 或客户端库写一个十行以内的脚本，打印实际发出的 URL、请求头和请求体。很多 SDK 支持调试日志或拦截器，可用来对比它与裸请求的差异。
3. 加回业务代码：最后才回到真实业务路径，逐步缩小到具体参数或调用方式。

关键判据是：哪一层第一次出现与裸 curl 不同的行为。差异点就是故障层。

第四步：常见差异点清单

逐层对比时，以下几类差异最容易导致“裸 curl 能通、代码不通”：

• 鉴权方式不同：SDK 可能自动读取环境变量、追加额外头部，或在适配层被改写为其他形式的凭证。
• base URL 拼接规则不同：有的 SDK 会自动补 /v1，有的不会，双重拼接会得到 404。
• 默认参数注入：SDK 可能默认带上流式、工具调用、响应格式等参数，触发服务端不支持的组合。
• 序列化差异：空值、数字类型、嵌套结构在不同序列化器下可能变成非法字段。
• 重试与超时：SDK 的自动重试会把一次失败放大成多次请求，日志里看到的错误可能不是根因。
• 代理与环境变量：系统代理设置对 curl 和 SDK 的生效方式可能不同。

第五步：把结论写成可提报的证据

定位完成后，提报内容应包含：裸 curl 命令（脱敏）、状态码与响应头、响应体关键字段、以及逐层加回时第一次失败的层次。这样的描述能让对方在几分钟内判断问题归属，而不是来回追问“你用的什么客户端”。

需要强调的是，裸 curl 能证明的只是“在这一时刻、这个地址、这组参数下，服务侧的响应是什么”。它不能证明服务在所有情况下都正常，也不能替代对业务代码的审查。它的作用是划出一条明确的基准线，让讨论从“调用失败”收敛到“哪一层与基准线不一致”。

小结

把失败调用剥成一条裸请求，本质上是建立一个最小对照实验：先确认服务侧可达且响应正确，再逐层加回客户端栈，找到第一个偏离基准的层次。这个方法不依赖具体 SDK，也不依赖对服务内部的了解，适用于任何基于 HTTP 的模型调用。