# 模型命名与查询

来源: https://platform.lyrouter.com/ai_gateway/docs/model-names
更新日期: 2026-10-19

请求中的 `model` 写模型 ID，格式为 `厂商/模型`（例如 `deepseek/deepseek-v4-flash`），区分大小写，必须与模型广场或 `GET /v1/models` 返回的值逐字一致。另有两类特殊名称：`@vmodel/<名称>` 调用虚拟模型，`lyrouter/auto` 调用 Auto 智能路由。客户端始终写模型 ID，服务商那边的真实模型名（包括 BYOK 的接入点编号）由网关替换，不要写进请求。

## 模型 ID 的格式

| 组成 | 示例 | 说明 |
| --- | --- | --- |
| 厂商 | `deepseek`、`qwen`、`anthropic`、`openai`、`google` | 斜杠前是开发模型的厂商，不是提供服务的服务商。同一模型由多个服务商提供时，模型 ID 只有一个 |
| 模型名 | `deepseek-v4-flash`、`qwen3.7-plus`、`claude-sonnet-4.6` | 包含规格和版本号，写法以模型目录为准 |

- **逐字一致**：大小写、标点与目录中的模型 ID 完全相同，前后不带空格。网关不做大小写转换、不补厂商前缀，也不把相近的名称当作同一个模型。
- **版本号照抄**：`anthropic/claude-sonnet-4.6` 的版本号用点号，写成 `anthropic/claude-sonnet-4-6` 找不到这个模型。
- **不同版本是不同的 ID**：同一系列的不同规格、版本使用不同的模型 ID，网关不会把旧 ID 自动指向新版本。更换版本的步骤见[模型版本与下线](https://platform.lyrouter.com/ai_gateway/docs/versions)。
- **显示名称不能调用**：模型广场卡片标题（如「DeepSeek V4 Flash」）只用于展示；`GET /v1/models` 的 `display_name` 同理。

下表列出常见写法的结果（假设工作空间已开通 `deepseek/deepseek-v4-flash` 和 `anthropic/claude-sonnet-4.6`）：

| 请求中的 `model` | 结果 |
| --- | --- |
| `deepseek/deepseek-v4-flash` | 正确 |
| `DeepSeek/deepseek-v4-flash` | 找不到（大小写不同） |
| `deepseek-v4-flash` | 找不到（缺少厂商前缀）；Codex 客户端例外，见下文 |
| `deepseek/deepseek-v4-flash `（末尾有空格） | 找不到 |
| `anthropic/claude-sonnet-4-6` | 找不到（版本号写法不同） |
| `DeepSeek V4 Flash` | 找不到（显示名称） |
| `ep-20260101xxxxxx-xxxxx` | 找不到（服务商的接入点编号） |

「找不到」时的表现取决于工作空间是否在 **智能路由** 中设置了默认模型：

- **设置了默认模型**：对话类请求改由默认模型回答，HTTP 状态是 200。程序拿到了回答，但不是你想调用的模型。
- **没有设置默认模型**：返回 403 `Model is not available in the model plaza`（`error.code` 为 `model_not_available`）。

在 **日志分析** 中对比「模型（请求）」和「模型（实际）」：两者不同、且「模型（实际）」是默认模型时，说明请求中的名称没有匹配上。默认模型的行为见[通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing#默认模型)。

## 特殊名称

| 名称 | 作用 | 规则 |
| --- | --- | --- |
| `@vmodel/<名称>` | 调用工作空间中已启用的[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets) | `<名称>` 只含小写字母、数字和连字符，以字母或数字开头，区分大小写。旧前缀 `@preset/<名称>` 与之等价 |
| `lyrouter/auto` | 按任务难度在已开通的模型中挑选，见[Auto 智能路由](https://platform.lyrouter.com/ai_gateway/docs/auto) | 固定写法 |

- **适用接口**：`lyrouter/auto` 只适合 `/v1/chat/completions`、`/v1/messages` 和 `/v1/responses`；虚拟模型除这三个接口外，也可以用于向量与重排接口（其模型列表须全部是向量或重排模型，见[创建向量](https://platform.lyrouter.com/ai_gateway/docs/embeddings)和[文档重排](https://platform.lyrouter.com/ai_gateway/docs/rerank)）。两者用在图像、视频接口上都返回 403 `Model is not available in the model plaza`。
- **名称失效**：虚拟模型被停用、删除或改名后，旧名称不再匹配。设置了默认模型时由默认模型回答，否则返回 503 `all routed candidates exhausted`。
- **在日志中显示**：通过这两类名称调用时，日志「路由追踪」的「虚拟模型」显示虚拟模型名称（不带 `@vmodel/`）或 `lyrouter/auto`，「模型（实际）」显示实际回答的模型。

## 省略 `model`

请求体没有 `model`，或写成 `""`、`null` 时，网关使用工作空间的默认模型。没有设置默认模型时返回 400 `you must provide a model parameter`（`missing_model`）；`model` 不是字符串时返回 400 `invalid type for 'model': expected a string`（`invalid_model`）。生产代码请始终写明模型 ID，避免默认模型调整后行为随之改变。

## Codex 客户端的名称补全

Codex 的部分界面只能选择不带厂商前缀的模型名（如 `gpt-5.5`）。网关识别到 Codex 客户端发来的请求时，给不含斜杠的模型名自动补上 `openai/`，即 `gpt-5.5` 按 `openai/gpt-5.5` 调用。已经带斜杠的名称不受影响，其他客户端也不做这种补全。在 Codex 中调用非 OpenAI 模型时，请在配置文件中填写完整的模型 ID，见[Codex](https://platform.lyrouter.com/ai_gateway/docs/codex)。

## BYOK 与上游模型名

使用 [BYOK](https://platform.lyrouter.com/ai_gateway/docs/byok) 接入自己的服务商凭证后，客户端仍然写模型 ID，网关在发往服务商时换成映射的上游模型名：

| 名称 | 示例 | 写在哪里 |
| --- | --- | --- |
| 模型 ID | `deepseek/deepseek-v4-pro` | 请求的 `model`、虚拟模型、Auto 候选范围、安全围栏模型策略 |
| 上游模型名 | `deepseek-v4-pro`，或火山方舟的 `ep-*` 接入点编号 | 只出现在网关发给服务商的请求中，由 BYOK 的模型映射决定 |

- **上游名不能当模型 ID**：请求中写 `ep-*` 等上游名，按「找不到」处理，见上文。
- **同一个模型 ID 可能对应不同上游名**：平台通道和各个 BYOK 通道各有自己的映射，网关按实际选中的通道替换。客户端代码不需要关心是哪一个。
- **自定义服务商也映射到模型 ID**：自定义服务商的每个上游模型都要对应一个平台模型目录中的模型，不能新建模型 ID，见[模型映射与来源配置](https://platform.lyrouter.com/ai_gateway/docs/mapping)。
- **核对实际发出的名称**：在日志详情的「原始报文」中查看「上游请求」，其中的 `model` 是上游模型名。正文只在工作空间开启全文日志后保存，失败的请求除外。

响应体中的 `model` 字段是上游返回的值，通常是上游模型名，不一定等于请求时写的模型 ID。程序需要记录「调用了哪个模型」时，请记录自己发送的模型 ID，或以日志的「模型（实际）」为准。

## 查询可用的名称

| 方式 | 得到什么 | 适合 |
| --- | --- | --- |
| 工作空间 **模型广场** | 已开通的模型及其服务商、价格；点击模型 ID 旁的复制按钮 | 人工挑选模型，见[如何选择模型](https://platform.lyrouter.com/ai_gateway/docs/choose) |
| [`GET /v1/models`](https://platform.lyrouter.com/ai_gateway/docs/models) | 这个 API Key 可调用的模型 ID，以及已启用的 `@vmodel/<名称>` 和 `lyrouter/auto` | 程序获取列表、填充模型选择器 |
| **虚拟模型** 页面 | 虚拟模型的调用名称 | 当前账号管理员管理虚拟模型；普通成员用 `GET /v1/models` 查询名称 |

`GET /v1/models` 已经按安全围栏的模型策略过滤，比模型广场更接近「这个 Key 实际能调用什么」。

## 常见问题

### 模型广场能看到这个模型，为什么调用时找不到？

**答：** 先确认它在「专属可用模型」中，而不是「可启用」或「需接入」；再用调用时的 API Key 请求 `GET /v1/models`，确认列表中有这个 ID。不在列表中，说明没有开通，或被安全围栏的模型策略限制了，见[模型授权](https://platform.lyrouter.com/ai_gateway/docs/authorization)。在列表中却仍然失败，按报错原文对照[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable)。

### 客户端只能填不带斜杠的模型名，怎么办？

**答：** Codex 由网关自动补 `openai/` 前缀。其他只接受固定名称的客户端，可以创建一个[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets)，把 `@vmodel/<名称>` 填进客户端；客户端连 `@` 和 `/` 都不接受时，请换用支持自定义模型名的客户端或配置方式，见[工具兼容性与接入总览](https://platform.lyrouter.com/ai_gateway/docs/tools)。

### Claude Code 发出的请求用了 Claude 官方模型名，为什么失败？

**答：** Claude Code 的后台任务和模型别名会使用 Claude 官方模型名（如 `claude-haiku-4-5`），这不是 LYRouter 的模型 ID。按[Claude Code](https://platform.lyrouter.com/ai_gateway/docs/claude-code)补齐各个模型变量，全部填 LYRouter 的模型 ID，再在日志的「模型（请求）」中确认没有遗漏。