模型版本与下线
请求中的 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查询，不要自己拼写或加服务商前缀。斜杠前是模型厂商，不是服务商。 GET /v1/models的条目在模型目录有信息时带display_name，这是显示名称，调用时仍使用id。- 同一模型的不同版本以不同的模型 ID 区分，命名与查询规则见模型命名与查询。
图 1：更换版本前，在模型详情核对模型 ID、各服务商的状态和价格表。 截图为演示数据，点击图片可查看原图。
更换版本的验证步骤
- 确认可调用：在工作空间的 模型广场 确认新版本在「专属可用模型」中，复制它的模型 ID。在「可启用」中时，请当前账号管理员或工作空间管理员开通。团队和企业建议先在测试用的工作空间中开通和验证。
- 核对详情：在模型详情比较各服务商的状态、价格表和计费单位；用
GET /v1/models查看context_length、max_output_tokens、input_modalities、api_types等字段（模型目录有信息时返回）。 - 用真实任务验证：使用应用实际调用的接口（Chat Completions、Anthropic Messages 或 Responses），覆盖长上下文、图片输入、工具调用、JSON 输出和流式输出，检查流式输出是否正常结束（Chat Completions 为
data: [DONE]，Anthropic Messages 为message_stop，Responses 为response.completed）。各接口的差异见模型能力与兼容性。 - 对比结果：在请求日志中查看「模型（实际）」「服务商」、状态、Token、首 Token 和总延迟；在用量分析中按模型比较同一时间段的请求数、成功率和费用。
- 切换并保留回退：更新应用配置或虚拟模型，旧版本在一段时间内作为备用模型保留，确认稳定后再移除。
用虚拟模型降低切换成本
让应用调用 @vmodel/<名称>，而不是直接写模型 ID。之后换版本只需当前账号管理员在 虚拟模型 页面修改「默认模型」，保存后新请求按新配置执行，应用和工具配置都不用改：
- 把旧版本填进「备用模型」，新版本失败时网关按顺序改用旧版本。
- 备用模型应与主模型支持相同的接口、输入类型和工具调用。模型不支持请求的输入或接口时，网关直接返回 400，不再尝试备用模型。
- 虚拟模型可用于
/v1/chat/completions、/v1/messages和/v1/responses；图像、视频和语音接口请直接写模型 ID。 - 日志的「虚拟模型」显示调用的虚拟模型名称，「模型（实际）」显示实际回答的模型，便于确认切换是否生效。
创建和配置方法见虚拟模型。工作空间在通道选择与路由策略中设置的「默认模型」是另一层兜底：请求没写 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 配置的「模型与费用」步骤会看到它标有「目录已下架」。
- 请求由默认模型回答时不会报错，请在日志的「模型（实际）」中确认。
- 各报错的完整处理见模型不可用。平台公告会发到「消息中心」。
常见问题
模型突然调不通，应该先检查什么？
答： 先按报错原文对照上表。返回 403 Model is not available in the model plaza 时，在模型广场确认该模型还在「专属可用模型」中；不在时，可能被工作空间停用或已被平台下线。用 GET /v1/models 可以确认当前 Key 还能调用哪些模型。
调用没有报错，但回答风格突然变了，是什么原因？
答： 在日志中打开这条请求，查看「模型（实际）」。它与请求的模型不同时，说明原模型不可用，请求由虚拟模型的备用模型或工作空间默认模型回答；不需要这种兜底时，请账号管理员清空智能路由中的默认模型。模型相同而「服务商」不同时，说明请求落到了同一模型的另一个通道，见应用接入多个服务商。
下线前能否直接把模型 ID 换成任意新模型？
答： 先按上面的验证步骤确认新模型支持应用使用的接口、输入类型、工具调用和输出格式，再更新配置。只按名称相近替换，可能在工具调用或 JSON 输出上失败。