# 模型映射与来源配置

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

客户端始终用系统模型 ID（例如 `deepseek/deepseek-v4-pro`）调用，模型映射决定网关把它换成哪个上游模型名发给服务商。内置服务商的映射由平台维护，在 BYOK 的「模型与费用」步骤中勾选模型即可；自定义服务商需要先读取上游模型列表，再把每个上游模型对应到一个系统模型。保存后，这些模型在模型广场获得 BYOK 来源。

## 系统模型 ID 与上游模型名

| 名称 | 示例 | 用在哪里 |
| --- | --- | --- |
| 系统模型 ID | `deepseek/deepseek-v4-pro` | 请求中的 `model`、模型广场、请求日志、虚拟模型、安全围栏 |
| 上游模型名 | `deepseek-v4-pro`、火山方舟的 `ep-*` 接入点 ID | 只出现在网关发给服务商的请求中 |

请求中的 `model` 必须写系统模型 ID。直接写上游模型名（例如 `ep-*`）会被当作未开通的模型，返回 403 `Model is not available in the model plaza`；工作空间设置了默认模型时，会改由默认模型回答。可用的系统模型 ID 用 [`GET /v1/models`](https://platform.lyrouter.com/ai_gateway/docs/models) 查询。

## 内置服务商：勾选模型

「模型与费用」表格列出平台为该服务商通道发布的模型：

- 「系统内置模型」列显示系统模型 ID 和模型名称，并注明「系统内置，不需要映射」。
- 勾选要使用的模型；「API 按量计费」时可为每个模型设置「Channel 价格折扣（%）」。
- 标记「目录已下架」的是之前选过、平台已不再发布的模型，可以取消勾选。
- 表格显示「该服务商没有符合本期发布范围的目录模型」时，这个通道暂时没有可接入的模型。

（截图：内置模型显示系统模型 ID、刊例价和 Channel 折扣，不需要手动映射。）

## 自定义服务商：映射上游模型

1. 在「接入凭证」中至少填写一个 API Key。
2. 在「模型与费用」点击 **获取服务商模型列表**。控制台用第一个填写了 Key 的凭证（没有时用已保存的凭证）读取上游模型列表，成功后提示「已获取 N 个上游模型」。新建自定义服务商时，如果 Base URL 缺少 `/v1`、补上后才读取成功，控制台会自动把 Base URL 改为补全后的地址。
3. 在「上游服务商模型」中选择要接入的模型，只能从读取到的列表中选择。
4. 为每个上游模型选择「系统内建统一模型名称」。名称一致时会自动预选，版本号中的 `.` 和 `-` 视为相同，例如 `claude-opus-4-6` 会匹配 `anthropic/claude-opus-4.6`。下拉只列出平台模型目录中的模型，不能输入新名称。
5. 「API 按量计费」时，每行显示该系统模型的「运营平台刊例价」，可以设置「Channel 价格折扣（%）」。

## 映射规则

- **只限文本对话模型**：系统模型必须是输出为文本的对话模型，可以接受图片输入。图像、视频、语音和向量模型不能通过 BYOK 接入，保存时提示 `model is unavailable for text chat completions`。
- **一一对应**：一个 BYOK 内，每个系统模型只能映射一次，每个上游模型名也只能使用一次，重复时提示 `invalid BYOK billing configuration: duplicate model` 或 `invalid BYOK billing configuration: duplicate upstream model name`。
- **按量计费需要价格**：「API 按量计费」时，映射的系统模型必须有平台发布的价格，否则提示 `the selected model has no active operations pricing strategy: <模型>`。折扣以这个价格为基准。
- **多个来源并存**：同一个系统模型可以同时由平台来源和多个 BYOK 提供，网关按[通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing)在它们之间选择。

## 在模型广场核对来源

- 保存后，映射的模型自动获得 BYOK 来源并默认开通，出现在模型广场的「专属可用模型」中。在左侧「接入来源」中选择「BYOK」，只看 BYOK 来源。
- 模型详情页的「服务商与价格」逐个列出来源及状态。关闭某个 BYOK 来源后，网关不再通过它调用该模型。
- 「需接入」页签中的模型在本工作空间还没有可用来源。在模型详情页点击 **接入 BYOK**，会打开新建 BYOK 的编辑器。
- 在 BYOK 中取消勾选或删除映射后，对应的 BYOK 来源随之移除。

## 验证映射

用该工作空间的 API Key 调用系统模型 ID，在[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中打开这条记录：「模型（实际）」显示系统模型 ID，「服务商」旁带「BYOK」标记。需要核对实际发给服务商的模型名时，查看日志详情「原始报文」中的上游请求，其中的 `model` 是上游模型名。

## 常见问题

### 点击「获取服务商模型列表」后提示「获取服务商模型失败」，怎么办？

**答：** 依次核对 Base URL、「接口类型」和 API Key。OpenAI 兼容、Responses API 和 Anthropic 原生的地址通常都以 `/v1` 结尾；网关会在 Anthropic 原生地址后面拼接 `/messages`，少了 `/v1` 时测试连接可能通过，真实调用却返回 404。服务商需要提供模型列表接口，控制台只能从读到的列表中选择上游模型。

### 下拉中找不到想要的系统模型，怎么办？

**答：** 下拉只列出平台模型目录中的模型。目录中没有的模型暂时不能通过 BYOK 接入，请联系支持说明服务商和模型名称；不要把上游模型名当作系统模型 ID 使用。

### 调用后「模型（实际）」不是我映射的模型，为什么？

**答：** 这个模型的 BYOK 凭证都失败后，网关按回退规则改用了其他通道或默认模型，见[失败重试与备用模型](https://platform.lyrouter.com/ai_gateway/docs/fallback)。在日志详情的「路由追踪」中查看每次尝试的结果；需要只用这个 BYOK 时，在其「使用配置」中开启「仅用此 BYOK」。