模型报“不可用”？先检查API端点是否填对

一、高频误解：报“不可用”不等于模型挂了

接入大模型 API 时，下面这些场景几乎人人都遇到过：

• 模型列表接口里明明返回了这个模型，一发起对话调用就失败；
• 同一个模型，在某个客户端里配置后一切正常，换一个工具就提示不可用；
• API Key 校验通过、账户余额充足，错误信息却是 model unavailable；
• 一份接入文档让填 /v1/messages，另一个工具的配置页却写着 /v1/chat/completions，不知道该听谁的。

很多人的第一反应是“模型下线了”“服务出故障了”，于是反复重试、更换密钥、切换区域，折腾半天毫无进展。但在排除服务端因素之后，你会发现相当一部分案例的根因非常朴素：端点填错了。

端点（endpoint）是调用链上的“门牌号”。门牌号错了，服务再正常也送达不了。而端点错误的麻烦之处在于：它抛出的报错往往语义模糊，极易被误读为“模型不可用”。

二、一次成功的调用，需要同时满足三个条件

很多人以为调通大模型 API 就是“选一个模型名”的事，实际上一次请求至少要同时满足三件事：

1. 模型名正确：该模型确实在目标服务上开放可用
2. 端点正确：请求打到了支持该模型、该能力的路径上
3. 请求格式正确：请求体结构、字段、鉴权方式符合该端点的约定

三者是“与”的关系，任何一处出错，整条调用链都会失败。更麻烦的是错误之间的“交叉污染”：

• 模型名是对的，但端点不支持你提交的请求格式；
• 端点是对的，但请求体写成了另一套接口的格式；
• 工具内置的是通用对话 SDK，却被强行指向了某厂商的原生接口；
• 工具要求填 Base URL，你却填了完整 endpoint，导致路径被重复拼接。

这些错误最终在客户端呈现出来的，可能就是 model unavailable、unsupported endpoint、invalid request body、404 not found 这类报错。于是“模型挂了”的错觉就产生了——其实模型好好的，只是你走错了门。

三、三类常见端点，到底差在哪

当前主流大模型服务的接入层，常见的对话类接口路径主要有三种。它们看起来都和“聊天”“生成回复”有关，但并不是同一套协议，也不能混用。

1. /v1/chat/completions：事实上的通用标准

这是最早被大规模普及、也被最广泛兼容的对话补全接口形态，核心是以 messages 数组组织对话上下文。由于出现早、使用面广，大量客户端、网关、代理服务和本地开发工具都是围绕它实现的。当一个工具宣称“支持通用格式的对话接口”或“兼容模式接入”时，绝大多数指的就是这一套。

如果你不确定该填哪个，先按这个方向配置，成功率最高。 目前主流模型服务平台——包括百度智能云这类一站式平台——普遍提供与该格式兼容的接入点，方便存量工具平滑迁移。

2. /v1/responses：较新的接口形态

这是近年新引入的接口形态，定位与对话补全不同，面向更结构化的调用组织方式。使用时要注意两点：一是它并非所有网关和中转服务都已实现，随意填写很可能直接得到 404；二是只有当工具文档里明确出现这个路径、明确声明对接该形态时，才应该使用它。多数存量工具并不认识它，不要靠猜。

3. /v1/messages：部分厂商的原生消息接口

某些模型厂商的原生 SDK 与官方接入文档采用这套消息接口。它与通用对话补全格式并不互通，差异体现在多个层面：

• 鉴权方式：部分原生接口使用自定义的密钥请求头和版本声明头，而不是常见的 Bearer Token 方式；
• 请求体结构：系统提示词的位置、必填与可选字段的约定都不同，某些在通用格式里可省略的参数在这里是必填的；
• 流式返回：流式输出的事件结构自成一套，混用会导致客户端解析失败，或表现为“请求发出去了却没有响应”。

因此，这类路径只应配合对应厂商的原生 SDK，或明确要求该路径的工具使用，不能拿通用客户端直接对接。

一张表看懂适用场景

接口路径	定位	典型适用场景	生态兼容度
/v1/chat/completions	通用对话补全，事实标准	绝大多数兼容型客户端、网关、中转服务	最广
/v1/responses	较新的响应式接口	明确声明支持该形态的新工具	较窄
/v1/messages	部分厂商原生消息接口	对应厂商原生 SDK、官方文档指定场景	限定场景

四、端点错误为什么“伪装”成模型不可用

理解了三套接口的差异，再看报错就能对上号了。常见报错与真实根因的对应关系大致如下：

报错现象	更可能的根因
404 not found	路径不存在：漏写或多写了 /v1、网关未实现该路径、路径被重复拼接
400 invalid request body	端点选对了，但请求体是另一套接口的格式
model not found / unavailable	模型名没有注册在这个端点下，或该端点不提供此模型
401 / 403	鉴权头风格与端点要求不一致，密钥本身可能没问题

可以看到，这些报错没有一条直接说“你的端点填错了”。服务端只能如实报告“这个路径下没有你要的东西”，至于为什么没有，需要调用方自己判断。这正是端点错误总是被误诊为“模型不可用”的根本原因。

五、如何快速判断该填哪个端点

按下面的优先级排查，基本不会走弯路：

1. 先看工具文档的关键词。文档里出现“兼容格式”“通用对话接口”字样，选 /v1/chat/completions；明确写出 /v1/responses，按文档填；明确写出 /v1/messages 或要求使用厂商原生 SDK，同样按文档填。
2. 看 SDK 的来源。工具内置的是模型厂商官方 SDK，就用对应原生路径；内置的是通用对话 SDK，就走通用补全路径。
3. 用鉴权方式反推。如果工具构造的请求头是自定义密钥头加版本声明头，它对应的是原生接口；如果是标准 Bearer 方式，大概率对应通用补全接口。
4. 完全不确定时，先试 /v1/chat/completions，不行再试原生路径，最后才考虑较新的接口形态。

更口语化的版本：

兼容型/通用型工具        → /v1/chat/completions
明确要求新形态接口的工具  → /v1/responses
厂商原生 SDK 或指定工具   → /v1/messages

六、典型踩坑清单

除了选错接口形态，配置环节还有几个高频坑，逐条核对能省掉大量排查时间：

1. Base URL 与完整 endpoint 混填。这是第一大坑。有的工具要求填 https://host，由工具自己拼接路径；有的要求填到 /v1 为止；还有的要求填完整路径。三种约定并存，直接复制粘贴就容易出错。
2. 结尾斜杠与重复拼接。Base URL 末尾多了斜杠，拼出来变成 //v1/...；或工具自动补路径时，你手填的路径又叠了一层。
3. 版本段丢失。漏掉 /v1，或把版本信息写进了模型名、请求头等其他位置。
4. 鉴权头风格不匹配。密钥没错，但放错了请求头，或缺少版本声明头。
5. 请求体字段残留。从另一套接口的示例代码里改参数，字段命名和结构没改干净。
6. 流式解析不兼容。端点能通、非流式也正常，一开流式就乱码或卡住，多半是事件结构对不上。
7. 中转/代理服务的路径重写。经过中转服务时，它可能只透传特定路径，其余一律返回 404。

七、最小化排查流程：十分钟定位问题

与其在客户端里反复试错，不如先用一条最小请求直接验证链路：

curl -X POST "https://你的接入域名/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型名",
    "messages": [
      {"role": "user", "content": "ping"}
    ]
  }'

然后按结果二分定位：

1. curl 成功、客户端失败：链路和端点都没问题，问题出在客户端的 Base URL 拼接或它附加的请求头上，对照工具实际发出的请求排查；
2. curl 返回 404：路径错了，检查域名、/v1 段和路径拼写；
3. curl 返回 400：端点可能对了，但请求体格式不匹配，确认字段结构属于这套接口；
4. curl 返回 401/403：核对鉴权头风格与密钥传递方式；
5. 返回 model not found：确认该模型是否确实开放在这个端点下，必要时核对模型名的准确写法。

一个重要习惯：不要只看状态码，要读响应体里的错误详情。服务端返回的错误信息通常比客户端封装的提示具体得多，很多时候答案就写在里面。

八、写在最后

端点是调用链的“门牌号”。当模型、密钥、余额都正常却报“不可用”时，先怀疑门牌号，而不是先怀疑模型。建议养成一个固定动作：接入任何新工具前，先确认三件事——端点路径、鉴权方式、请求体格式，最后才填模型名。无论你使用的是百度智能云这类一站式模型服务平台，还是自建网关或中转服务，这套排查思路都通用。把“三要素核对”变成肌肉记忆，绝大多数“模型不可用”的假警报，都能在十分钟内解除。