# 模型版本与下线

来源: https://platform.lyrouter.com/ai_gateway/docs/versions
更新日期: 2026-10-16

请求中的 `model` 写的是模型 ID（如 `deepseek/deepseek-v4-pro`），不是模型广场上显示的名称。更换模型版本就是改用另一个模型 ID：先用真实任务验证，再更新应用配置。把模型名集中写在虚拟模型里，切换时只需改一处。模型在工作空间被停用或被平台下线后，调用会返回 403 `Model is not available in the model plaza`；工作空间设置了默认模型时，则可能改由默认模型回答。

## 模型 ID 与显示名称

| 名称 | 示例 | 在哪里看到 | 用途 |
| --- | --- | --- | --- |
| 模型名称 | DeepSeek V4 Pro | 模型广场卡片标题、模型详情页头 | 仅用于展示 |
| 模型 ID | `deepseek/deepseek-v4-pro` | 卡片标题下方、详情页头（带复制按钮）；`GET /v1/models` 返回的 `id` | 填进请求的 `model` |
| 上游模型名 | 服务商自己的模型名或接入点编号 | BYOK 配置的「模型与费用」步骤 | 由网关转换，客户端无需填写 |

- 模型 ID 区分大小写，请从模型广场复制或用 [`GET /v1/models`](https://platform.lyrouter.com/ai_gateway/docs/models) 查询，不要自己拼写或加服务商前缀。斜杠前是模型厂商，不是服务商。
- `GET /v1/models` 的条目在模型目录有信息时带 `display_name`，这是显示名称，调用时仍使用 `id`。
- 同一模型的不同版本以不同的模型 ID 区分，命名与查询规则见[模型命名与查询](https://platform.lyrouter.com/ai_gateway/docs/model-names)。

（截图：更换版本前，在模型详情核对模型 ID、各服务商的状态和价格表。）

## 更换版本的验证步骤

1. **确认可调用**：在工作空间的 **模型广场** 确认新版本在「专属可用模型」中，复制它的模型 ID。在「可启用」中时，请当前账号管理员或工作空间管理员开通。团队和企业建议先在测试用的工作空间中开通和验证。
2. **核对详情**：在模型详情比较各服务商的状态、价格表和计费单位；用 `GET /v1/models` 查看 `context_length`、`max_output_tokens`、`input_modalities`、`api_types` 等字段（模型目录有信息时返回）。
3. **用真实任务验证**：使用应用实际调用的接口（Chat Completions、Anthropic Messages 或 Responses），覆盖长上下文、图片输入、工具调用、JSON 输出和流式输出，检查流式输出是否正常结束（Chat Completions 为 `data: [DONE]`，Anthropic Messages 为 `message_stop`，Responses 为 `response.completed`）。各接口的差异见[模型能力与兼容性](https://platform.lyrouter.com/ai_gateway/docs/capabilities)。
4. **对比结果**：在[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中查看「模型（实际）」「服务商」、状态、Token、首 Token 和总延迟；在[用量分析](https://platform.lyrouter.com/ai_gateway/docs/analytics)中按模型比较同一时间段的请求数、成功率和费用。
5. **切换并保留回退**：更新应用配置或虚拟模型，旧版本在一段时间内作为备用模型保留，确认稳定后再移除。

## 用虚拟模型降低切换成本

让应用调用 `@vmodel/<名称>`，而不是直接写模型 ID。之后换版本只需当前账号管理员在 **虚拟模型** 页面修改「默认模型」，保存后新请求按新配置执行，应用和工具配置都不用改：

- 把旧版本填进「备用模型」，新版本失败时网关按顺序改用旧版本。
- 备用模型应与主模型支持相同的接口、输入类型和工具调用。模型不支持请求的输入或接口时，网关直接返回 400，不再尝试备用模型。
- 虚拟模型可用于 `/v1/chat/completions`、`/v1/messages` 和 `/v1/responses`；图像、视频和语音接口请直接写模型 ID。
- 日志的「虚拟模型」显示调用的虚拟模型名称，「模型（实际）」显示实际回答的模型，便于确认切换是否生效。

创建和配置方法见[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets)。工作空间在[通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing)中设置的「默认模型」是另一层兜底：请求没写 `model`，或请求的模型全部失败、未开通时，由它回答。它适合作为安全网，不适合用来管理版本，因为请求会在你不知情时改由另一个模型回答。

## 模型停用或下线后的表现

| 情况 | 调用结果 | 处理 |
| --- | --- | --- |
| 工作空间停用了该模型的全部来源 | 403 `Model is not available in the model plaza`（`error.code` 为 `model_not_available`）；设置了默认模型时，对话请求改由默认模型回答 | 在模型广场重新开通，或改用其他模型 |
| 平台下线了该模型 | 同上；模型从模型广场和 `GET /v1/models` 中消失 | 改用替代模型的模型 ID |
| 模型仍开通，但没有可用的通道或凭证 | 503 `all routed candidates exhausted` 或 `No configured credential can serve this model`（`error.code` 为 `no_route_candidate`） | 请账号管理员检查服务来源和 BYOK 凭证 |
| 虚拟模型的「默认模型」已不可用 | 改用「备用模型」；都不可用时改用工作空间默认模型，仍没有时返回 503 `all routed candidates exhausted` | 请账号管理员修改虚拟模型配置 |

- 被下线的模型如果配置在 BYOK 中，账号管理员在 BYOK 配置的「模型与费用」步骤会看到它标有「目录已下架」。
- 请求由默认模型回答时不会报错，请在日志的「模型（实际）」中确认。
- 各报错的完整处理见[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable)。平台公告会发到「消息中心」。

## 常见问题

### 模型突然调不通，应该先检查什么？

**答：** 先按报错原文对照上表。返回 403 `Model is not available in the model plaza` 时，在模型广场确认该模型还在「专属可用模型」中；不在时，可能被工作空间停用或已被平台下线。用 `GET /v1/models` 可以确认当前 Key 还能调用哪些模型。

### 调用没有报错，但回答风格突然变了，是什么原因？

**答：** 在日志中打开这条请求，查看「模型（实际）」。它与请求的模型不同时，说明原模型不可用，请求由虚拟模型的备用模型或工作空间默认模型回答；不需要这种兜底时，请账号管理员清空智能路由中的默认模型。模型相同而「服务商」不同时，说明请求落到了同一模型的另一个通道，见[应用接入多个服务商](https://platform.lyrouter.com/ai_gateway/docs/multi-provider)。

### 下线前能否直接把模型 ID 换成任意新模型？

**答：** 先按上面的验证步骤确认新模型支持应用使用的接口、输入类型、工具调用和输出格式，再更新配置。只按名称相近替换，可能在工具调用或 JSON 输出上失败。