模型调用报“不可用”？多半是API端点填错了

一、现象：模型“存在”却“调不通”

在接入大模型API的过程中，下面这类困惑几乎每周都会出现：

• 模型列表接口明明返回了某个模型名称，可一旦发起推理请求就提示模型不可用；
• 同一个模型，在某个客户端里工作正常，换一个客户端就报错；
• API Key 有效、账户余额充足，返回的却是 model unavailable；
• 有的文档写 /v1/messages，有的工具却要求填 /v1/chat/completions，到底该听谁的。

从表面看，这些现象都指向“模型侧故障”。但排查经验表明，很大一部分根因并不在模型服务本身，而在于请求走错了端点，或者端点与请求体格式不匹配。

一次成功的大模型调用，至少要同时满足三个条件：

1. 模型标识正确（model 字段与平台暴露的名称一致）
2. 端点正确（endpoint 与该模型支持的协议一致）
3. 请求体格式正确（字段结构符合该端点的 schema）

三者中任意一个不满足，服务端就可能在路由阶段、协议解析阶段或模型分发阶段返回错误。而由于错误信息通常被客户端统一包装，最终呈现在界面上的往往只有一句笼统的“模型不可用”，于是误导了排查方向。

二、三类常见端点：看起来都像“聊天”，其实不是一套协议

当前业界常见的大模型 HTTP 接口，围绕“对话/生成”这一场景，大致形成了三类端点形态：

/v1/chat/completions     —— 会话补全风格
/v1/responses            —— 响应式生成风格
/v1/messages             —— 消息式（原生对话协议）风格

它们的共同点是都接收“输入”并返回“生成结果”，但请求体结构、返回结构、多轮对话的表达方式、工具调用（function/tool calling）的字段命名都不相同。把它们当作同一种东西互换使用，是端点填错问题的主要来源。

2.1 /v1/chat/completions：兼容性最广的默认选择

这是目前第三方工具生态支持最普遍的形态。大量客户端、SDK、编排框架在宣称“兼容 OpenAI 风格接口”时，实际指的就是这一套会话补全协议。其典型请求体形如：

{
  "model": "your-model-name",
  "messages": [
    {"role": "system", "content": "你是一个严谨的技术助手"},
    {"role": "user", "content": "解释一下端点与Base URL的区别"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}

关键特征：

• 对话历史以 messages 数组表达，每条消息含 role 与 content；
• 生成参数（温度、最大长度、停止词等）与消息体平级；
• 返回结构通常包含 choices 数组，结果在 choices[0].message.content 中。

适用判断：如果你使用的工具只让你填一个“Base URL”，或者其配置界面出现了“OpenAI 兼容”“自定义模型服务”之类的选项，且没有明确声明支持响应式接口，那么优先选择这一端点。它是失败率最低的起点。

2.2 /v1/responses：面向“响应式生成”的新形态

这一类端点把“输入”抽象得更为通用，不再强制要求把上下文组织成严格的角色消息数组，而是允许以更灵活的方式传入输入项，并把工具调用、结构化输出等能力统一到同一套请求语义中。其请求体大致呈现为：

{
  "model": "your-model-name",
  "input": "请总结下面这段日志的关键异常",
  "instructions": "输出保持简洁，按严重程度排序"
}

关键特征：

• 输入字段通常为 input（可为字符串或结构化输入项），系统级指令通过 instructions 等独立字段表达；
• 返回结构不以 choices 为中心，而是以“输出项”组织；
• 多轮上下文需要按该协议的约定方式回传，不能直接照搬会话补全的 messages 数组。

适用判断：只有当工具或文档明确写明支持响应式接口时，才应选择它。把会话补全的请求体原样发往该端点，通常会被判定为 schema 不匹配，而不是“模型不存在”。

2.3 /v1/messages：原生对话协议

这一类端点来自“消息式”对话协议的设计，请求体以 messages 为核心，但字段细节与 2.1 不同，例如系统提示往往独立为顶层字段，而不是放进消息数组：

{
  "model": "your-model-name",
  "system": "你是一个严谨的技术助手",
  "messages": [
    {"role": "user", "content": "解释一下端点与Base URL的区别"}
  ],
  "max_tokens": 1024
}

关键特征：

• 系统提示常为顶层 system 字段；
• max_tokens 通常为必填，缺失会直接报参数错误；
• 返回结构以内容块数组表达，文本结果需要从内容块中提取。

适用判断：使用原生 SDK 或明确面向该协议的工具时选择它。若把一个只支持会话补全的客户端指向该端点，最常见的表现就是参数校验失败或 404。

三、对照表：先按工具类型选端点

你使用的工具类型	大概率应使用
通用兼容型客户端 / 中转配置 / 自定义 Base URL	/v1/chat/completions
明确声明支持响应式生成接口的工具	/v1/responses
使用原生对话协议 SDK 或对应工具	/v1/messages

一句话记忆：

普通兼容型工具        → chat/completions
声明响应式接口的工具  → responses
原生对话协议工具      → messages

若完全无法判断，先用会话补全方向验证连通性，再根据工具文档切换。这样做的好处是：绝大多数第三方工具对会话补全的支持最完整，能最快区分“是端点问题”还是“是模型或鉴权问题”。

四、Base URL 与完整端点：另一个高频填错点

端点填错还有一类变体：把 Base URL 和完整端点混为一谈。

很多工具要求填写的是“基础地址”（Base URL），SDK 会在其后自动拼接 /v1/chat/completions 之类的路径；而另一些工具要求填写的是“完整请求地址”。两类配置的写法完全不同：

Base URL 形式：  https://<服务地址>/v1
完整端点形式：    https://<服务地址>/v1/chat/completions

如果工具要 Base URL，你却填了完整端点，SDK 拼接后可能变成：

https://<服务地址>/v1/chat/completions/v1/chat/completions

结果自然是 404。反过来，如果工具要完整端点，你只填了基础地址，请求会打到根路径或错误的默认路径上，同样失败。这类错误在日志里常常表现为路径不存在，但被客户端包装后仍显示为“模型不可用”。

五、按错误码反推：一套可复用的排查清单

遇到“模型不可用”时，建议按以下顺序逐项核对，而不是反复更换模型名称：

第一步：确认模型标识。 通过模型列表接口拉取当前可用的模型名称，逐字符比对，注意大小写、版本后缀、日期后缀等细节。

第二步：确认端点与工具协议是否匹配。 对照第三节的表格，检查客户端文档声明的协议类型，再检查实际填写的路径。

第三步：确认 Base URL 与完整端点的填写方式。 查看工具文档或 SDK 源码，确认它是否会自动拼接路径；可以用一次最小请求观察实际请求路径。

第四步：检查请求体 schema。 常见差异包括：系统提示是放在 messages 里还是顶层 system 字段；max_tokens 是否必填；input 与 messages 是否混用。

第五步：用最小请求隔离变量。 构造只含一条用户消息、最小参数集的最简请求，先打通链路，再逐步加回参数。

常见的错误信息与可能原因的对应关系：

model unavailable      → 模型名不匹配，或端点不支持该模型的分发路径
unsupported endpoint   → 路径与协议不匹配，或 Base URL 拼接错误
invalid request body   → 请求体 schema 与端点不符（字段名/必填项）
schema mismatch        → 混用了另一套协议的结构
404 not found          → 路径拼写错误，或 Base URL 与完整端点混填

六、实践建议：把“配对”固化成配置规范

要长期规避这类问题，可以把端点选择固化为团队内的配置规范：

1. 在配置模板中显式区分两种字段：base_url 与 endpoint_path 分开维护，避免混填；
2. 为每个客户端标注协议类型：在接入文档中写明“本客户端使用会话补全协议”，减少后来者猜测；
3. 保留一次最小连通性测试：接入新工具时，先用最简请求验证路径与协议，再接入业务逻辑；
4. 错误信息分级：在客户端封装层把 404、参数校验失败与真正的模型不可用区分开，避免统一显示为“模型不可用”。

结语

“模型明明有，一调用就不可用”，本质上是一个协议配对问题，而不是模型可用性问题。会话补全、响应式生成、消息式对话这三类端点各有其请求结构与适用工具，端点、Base URL 写法、请求体 schema 三者只要有一处错位，就会在客户端被压缩成一句误导性的错误提示。把端点选择对照表、Base URL 与完整端点的区分、以及按错误码反推的排查清单固化下来，绝大多数“不可用”都能在几分钟内定位到真正的原因。