模型明明存在，为何一调用就报“不可用”？多数是 API 端点填错了

在接入大模型服务时，有一种问题看起来非常像“模型挂了”，但实际原因往往更简单：请求被发送到了一个并不匹配的 API 端点。

典型表现包括：

• 模型清单里能看到某个模型，应用侧却提示模型不可用；
• 同一个模型在 A 客户端可以正常调用，换到 B 客户端就报错；
• 接口密钥正确、额度充足、网络也通，但服务端始终返回 model unavailable；
• 有的资料要求填写 /v1/messages，有的又要求 /v1/chat/completions，配置界面却只有一个 Base URL 输入框。

出现这些现象时，很多人的第一反应是“模型下线了”“账号没权限”“网关拦截了”。但根据实际排查经验，更常见的原因是 API 端点与请求格式不匹配。

本文将围绕最常见的三个端点进行说明：

/v1/chat/completions
/v1/responses
/v1/messages

它们虽然都与“生成回复”有关，但面向的协议、请求结构、响应结构和兼容生态并不相同，不应混用。

---

一、先给出结论：不知道选哪个时，优先看这里

如果你正在配置某个工具、网关、客户端或自建代理，只想知道“应该填哪个端点”，可以先根据工具类型判断：

使用场景	推荐优先尝试的端点
兼容常见聊天补全协议的第三方工具、中转网关、自定义 Base URL	/v1/chat/completions
明确面向新版 Responses 协议设计的新客户端或官方新接口	/v1/responses
面向 Anthropic 风格协议、使用原生 SDK 或专用客户端	/v1/messages

更简化的判断方式如下：

普通兼容工具        → /v1/chat/completions
新协议 Responses    → /v1/responses
专用原生协议        → /v1/messages

如果你完全没有头绪，建议先尝试 /v1/chat/completions。原因在于，目前大量第三方客户端、插件、网关、本地调试工具在提到“兼容 API”时，实际实现的是聊天补全协议。它已经成为一种事实上的通用接入格式。

---

二、为什么端点填错，会表现为“模型不可用”

一次大模型调用要成功，至少需要同时满足以下条件：

请求地址正确
请求体格式正确
模型名称在当前地址支持下可用
认证信息与权限正确

任何一环不匹配，服务端都可能返回不同的错误。问题在于，很多客户端和网关并不会精确区分错误类型，而是把各种失败统一显示为“模型不可用”或“请求失败”。

常见错误包括：

model unavailable
unsupported endpoint
invalid request body
schema mismatch
404 not found
405 method not allowed

因此，当模型名称本身确实存在时，“模型不可用”并不能证明模型服务异常。更可能的原因是：

• 使用了 A 协议，却把请求发到 B 端点；
• 请求体字段名、结构或角色定义不符合当前端点预期；
• 工具要求填写 Base URL，用户却填入了完整路径；
• 某些代理只暴露部分端点，例如只支持 /v1/chat/completions，但不支持 /v1/messages。

---

三、/v1/chat/completions：最常见，也最容易接入成功

/v1/chat/completions 是目前最普遍的聊天补全端点。它接收一种结构清晰的对话请求，核心要素通常包括：

{
  "model": "model-name",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}

它的主要特征如下：

1. 以 messages 组织上下文

请求中以消息数组描述多轮对话，通常包含 system、user、assistant 三种角色。这种结构直观、易于拼接，已经成为大量上层应用的通用表达。

2. 响应结构以 choices 为中心

典型成功响应中，生成结果通常放在 choices 下，每个选项包含 message 与 finish_reason 等信息。上层工具大多按照这一结构解析回复。

3. 第三方兼容生态广泛

虽然不同服务商在参数扩展、流式返回、工具调用方面可能有所差异，但基础请求与响应结构保持了较高一致性。因此，许多客户端默认使用该端点。

如果你的目标是“快速跑通”，并且不确定目标服务完整支持哪些协议，从 /v1/chat/completions 开始通常是最稳妥的选择。

---

四、/v1/responses：面向新协议，不等于简单改名

/v1/responses 是较新的协议形态。它并不是把 chat/completions 换个名字，而是在输入表达、输出结构、状态管理和事件流上有明显区别。

1. 输入结构更灵活

它通常支持以 input 或类似字段组织内容，而不是简单使用 messages 数组。某些实现允许在输入中混合多种内容块，如文本、图像、引用等。

2. 响应更面向“任务结果”

部分新协议倾向返回完整响应对象，而不是将文本放在 choices 中。这样做便于支持更复杂的结果类型、状态字段和工具调用过程。

3. 兼容边界更明显

如果把一个按 chat/completions 结构编写的请求直接发给 /v1/responses，即使模型存在，也可能因协议不匹配而失败。反之亦然。

因此，只有在工具或 SDK 明确说明其使用新 Responses 协议时，才建议填写 /v1/responses。

---

五、/v1/messages：面向专用原生协议

/v1/messages 常见于某些专用模型服务的原生协议中。它同样用于生成回复，但在很多细节上与聊天补全协议并不一致。

1. 请求字段含义不同

虽然也存在类似“消息”的概念，但字段命名、角色类型、系统提示位置、参数名称可能均不相同。例如，某些协议可能不使用 system 角色，而是要求通过独立字段传递系统提示。

2. 错误处理与流式机制不同

不同协议的流式事件、错误码、限流字段和完成原因定义可能存在较大差异。上层工具若按聊天补全协议解析，容易出现“连接成功但读不到内容”或“返回异常但无法识别错误”的情况。

3. 只适合协议兼容的客户端

如果你使用的是专为该协议设计的上层应用或 SDK，填写 /v1/messages 是合理的。但如果你在一个只支持聊天补全协议的通用客户端中强行填写该端点，则很容易得到“模型不可用”的错误提示。

---

六、Base URL 与 Endpoint 的常见填写误区

很多配置界面只提供一个“Base URL”输入框，而不同工具对 Base URL 的定义可能不同。

有的工具期望：

https://example.com

也有的工具期望：

https://example.com/v1

用户如果额外拼上完整端点，就可能出现重复路径：

https://example.com/v1/chat/completions/v1/chat/completions

这种错误不会提示“路径写错”，而常常表现为 404、认证失败或模型不可用。

一个更稳妥的检查方式是：

1. 先确认工具希望填写的是“服务根路径”还是“完整接口路径”；
2. 查看实际发出的完整请求 URL；
3. 如果工具提供调试日志，直接检查最终请求地址是否出现重复段。

---

七、如何快速判断是“模型问题”还是“端点问题”

当出现“模型不可用”时，可以按以下顺序排查：

第一步：确认模型名称

检查配置中的模型名是否与目标服务提供的名称完全一致，包括大小写、中划线、版本后缀等。

第二步：确认端点类型

查看客户端或 SDK 明确要求使用哪种协议。若客户端只支持聊天补全协议，则应使用 /v1/chat/completions，而不是 /v1/responses 或 /v1/messages。

第三步：使用最小请求验证

可以先用最小请求体测试连通性：

{
  "model": "your-model-name",
  "messages": [
    {
      "role": "user",
      "content": "ping"
    }
  ]
}

如果最小请求成功，但复杂请求失败，则问题可能出在参数、工具调用、多模态输入或上下文长度上。

第四步：检查最终请求 URL

通过调试日志或本地代理查看完整请求地址，确认是否存在路径重复、缺失版本号或错误拼接。

---

八、不同调用链路的正确配置思路

1. 使用通用聊天客户端

建议选择：

Base URL: https://your-service.example.com/v1
Endpoint: /chat/completions

具体填写方式取决于客户端是否会自动补齐端点路径。

2. 使用新协议 SDK

如果 SDK 默认请求 /v1/responses，则不宜手动将 Base URL 指定到 /v1/chat/completions。此时应保持 SDK 默认行为，只修改服务地址与模型名。

3. 使用专用协议客户端

对于使用 /v1/messages 的客户端，应确保服务端确实暴露了该端点，并且客户端版本与服务端协议版本匹配。

---

九、为什么不同协议不能随意混用

从表面看，不同端点都在完成“输入文本、生成回复”的工作。但在工程实现上，它们涉及不同的序列化方式、字段映射、错误语义和流式事件设计。

混用协议可能导致：

• 请求被服务端拒绝；
• 请求被网关错误转发；
• 请求被接收但返回异常结构；
• 客户端误判模型状态；
• 日志中出现“认证失败”或“模型不存在”等误导性信息。

因此，遇到“模型明明有，却不可用”，首先应该确认：你当前使用的端点，是否真的与客户端所采用的协议一致。

---

十、总结

“模型不可用”并不总是模型的问题。更多时候，它反映的是接入配置中的协议错配。

三个端点可以这样理解：

/v1/chat/completions     → 最常见的聊天补全协议，兼容面广
/v1/responses            → 新协议，结构更面向复杂任务结果
/v1/messages             → 专用原生协议，需与专用客户端匹配

对于大多数普通工具和快速接入场景，优先选择 /v1/chat/completions，通常能显著减少无谓的试错。若你确定使用的是新协议 SDK 或专用客户端，再对应选择 /v1/responses 或 /v1/messages。

最终排查的核心不是反复更换模型名，而是确认：

模型名正确
端点匹配
请求格式匹配
Base URL 拼接正确

只要这四项对齐，大部分“模型不可用”都会消失。