---
outline: [2, 3]
head:
  - - meta
    - name: description
      content: 介绍 OneGateway 供应商接入、模型市场、模型路由、模型定义与分组定价的管理流程，包括连接测试、模型启停、主备分流、定价倍率及价格配置。
---

# 供应商与模型

管理员通过 **模型 → 供应商、模型市场、模型定义、分组定价**，接入上游模型服务，管理可调用的模型，并配置请求分流和计费价格。

首次接入建议按“确认模型定义 → 创建供应商并选择模型 → 检查模型市场与路由 → 验证调用”的顺序操作。已有供应商时，可直接查找模型，调整承载关系、路由或定价。

| 页面 | 管理对象 | 常见操作 |
| --- | --- | --- |
| 供应商 | 上游模型服务的接入配置 | 配置接入类型、API 地址、密钥、分组定价及支持的模型，维护启停状态 |
| 模型市场 | 按模型汇总的可用情况 | 查找和复制模型 ID、查看承载供应商与近 24 小时状态、启停模型、调整路由 |
| 模型定义 | 模型的基础信息和计费配置 | 维护名称、显示名、描述、上下文和各类价格 |
| 分组定价 | 调用适用的计费倍率配置 | 新建和维护分组定价，设置定价倍率与用户可选范围 |

## 供应商

一个供应商可以提供多个模型；同一个模型也可以由多个供应商承载。例如，“生产主用”和“生产备用”可以接入同一种服务，但分别使用不同的上游地址或账号密钥。

### 准备连接信息

接入前，准备好上游服务的 API 地址、API 密钥和实际支持的模型名称，并确定该服务适用哪些[分组定价](#分组定价)。

这里填写的是**上游供应商的 API 密钥**。应用调用 OneGateway 时使用的 [API Keys](/user/tokens)需要单独创建。

### 创建供应商

1. 进入 **模型 → 供应商**，点击 **新建**。
2. 选择与上游接口匹配的接入类型。未在常用选项中找到时，展开 **更多接入类型** 后搜索。
3. 填写连接信息，并核对自动带出的 API 地址。

| 字段 | 填写说明 |
| --- | --- |
| 供应商名称 | 使用便于区分用途的名称，例如“生产主用”“生产备用”；避免使用重复名称 |
| API 密钥 | 填写上游服务提供的有效密钥 |
| 分组定价 | 选择该供应商适用的分组定价，可选择多个 |
| API 地址 | 填写该接入类型要求的服务基础地址，按字段提示确认路径，不要直接填写聊天请求的完整 URL |

接入类型应以上游提供的接口协议为准。通过兼容接口或代理服务接入时，也应核对其要求的接入类型、地址和密钥。

### 测试连接并选择模型

填写连接信息后，点击 **测试连接**。系统尝试访问上游的模型列表接口，检查连接并发现可用模型。

- **测试成功且有可选模型**：检查待同步的模型，保留本次需要接入的模型后创建供应商。
- **测试成功但没有可选模型**：核对当前网关实例的模型定义。可选模型需要在该实例中存在同名定义；必要时先补充模型定义，再重新进入创建流程。
- **测试失败或超时**：先核对接入类型、地址、密钥和网络。页面允许从已有模型定义中手动选择模型后继续创建，但创建成功仍需通过实际调用验证服务可用性。

至少选择一个模型和一个分组定价后，点击 **创建供应商**。返回列表，检查记录状态及支持的模型。

测试连接主要验证模型列表接口，不能证明每个模型都能正常生成回答，也不能证明用户的分组定价和 API Key 限制已经配置正确。

### 日常维护

在供应商列表中，按名称搜索或使用筛选条件定位记录，点击名称查看和编辑配置。

| 列表信息 | 使用方式 |
| --- | --- |
| 类型与分组定价 | 检查接口接入方式，以及供应商适用的分组定价 |
| 状态 | 确认供应商是否启用；停用会影响通过该供应商承载的模型调用 |
| 优先级与权重 | 检查主备顺序和同层分流比例，也可从模型市场的路由视图调整 |
| 已用 / 剩余 | 查看回流的运行数据，结合上游账户情况判断是否需要补充额度；数据可能存在刷新延迟 |

更新地址或密钥后，重新测试并验证实际调用。需要临时停止使用某条供应商时，先确认相关模型是否还有其他可用供应商，再执行停用。

## 模型市场

模型市场按模型汇总供应商、价格和运行状态，也提供模型启停与路由配置入口。

### 查看模型可用情况

进入 **模型 → 模型市场**，按模型名称、模型 ID 或供应商搜索，结合模型类型、供应商和启用状态（全部、已启用、已禁用）筛选定位目标模型。

| 卡片内容 | 含义 |
| --- | --- |
| 显示名与模型 ID | 显示名便于阅读；模型 ID 用于应用请求的 `model` 字段，可通过复制入口获取 |
| 供应商 | 展示承载该模型的供应商数量，点击可进一步查看承载情况 |
| 上下文 | 展示模型定义中配置的上下文信息 |
| 价格 | 展示当前模型配置的价格，阅读时注意按量或按次的计费单位 |
| 近 24 小时状态与可用性 | 帮助观察近期运行情况；灰色状态块或 `--` 表示缺少可展示数据时，不能直接据此判断模型故障 |

目录中的“已启用”表示模型存在供应商承载关系。是否能成功调用，还需要检查供应商状态、上游服务、分组定价配置及 API Key 限制。

### 启用与停用模型

使用模型卡片上的开关管理模型启停。停用前阅读确认提示，并确认依赖该模型的应用已经做好调整。

停用模型会从当前网关实例内相关供应商的支持模型范围中移除该模型，并保留原有承载关系供恢复。重新启用时，系统尝试恢复这些关系；恢复后仍需检查供应商是否启用、配置是否同步成功。

### 模型路由

在模型市场中打开目标模型的 **模型路由可视化**，查看该模型对应的供应商、响应时间、优先级和权重。

::: info 这里管的是同一模型的供应商选择

本节的优先级与权重决定**同一个模型**由哪家供应商承载。需要按请求复杂度选择不同模型、把一个模型灰度替换成另一个模型，或在模型不可用时换用其他模型，请使用 [智能路由插件](/guide/intelligent-routing)。插件改写模型后，每次请求仍会经过本节的供应商选择；插件规则里用到的目标模型和候选模型，都需要在这里接入并定价。

:::

#### 理解主备与分流

| 配置或标记 | 含义 |
| --- | --- |
| 优先级 | 数值越大，越优先被选择；较低优先级用于备用 |
| 权重 | 同一优先级内的相对分流权重；它不是固定百分比 |
| 实线 | 主优先级层的供应商，在同层内按权重分流 |
| 虚线 | 备用优先级层，主层失败时结合重试策略尝试使用 |
| 灰虚线 | 已摘除、不参与调度的供应商 |

例如，同一个模型由三条供应商承载：

| 供应商示例 | 优先级 | 权重 | 预期用途 |
| --- | --- | --- | --- |
| 生产主用 A | 10 | 3 | 主层中约承担 3/4 的选择概率 |
| 生产主用 B | 10 | 1 | 主层中约承担 1/4 的选择概率 |
| 生产备用 | 0 | 1 | 主层失败时作为备用候选 |

上述比例用于理解加权分流，不保证少量请求恰好按 3:1 分配。实际调度还受到分组定价配置、供应商可用状态及重试策略影响。设置备用供应商后，需结合实际重试配置验证切换效果。

#### 保存路由调整

1. 确认目标模型的承载供应商与当前主备关系。
2. 调整可编辑供应商的优先级和权重。
3. 点击 **保存**，重新打开路由视图检查结果。
4. 发起测试调用，在日志中核对实际使用的供应商和请求结果。

::: warning 调整会影响供应商承载的所有模型
优先级和权重属于供应商配置。在某个模型的路由视图中修改它们，保存后，该供应商承载的其他模型也会使用新值。修改前先确认完整的影响范围。
:::

## 模型定义

进入 **模型 → 模型定义**，通过显示名等条件查找模型。点击记录维护已有定义；接入新的模型名称时，点击 **新建**补充定义。

常见模型不需要自己维护：平台已内置主流模型的定义（基础信息和价格），其显示名、上下文和描述会自动更新。只有公共模型库中没有的模型，才需要通过 **新建** 手工补充。

### 基础信息

| 字段 | 说明 |
| --- | --- |
| 名称 | 模型的标识，需与接入配置使用的模型名称匹配；应用请求使用对应的模型 ID |
| 显示名 | 在目录等页面展示的易读名称，修改它不会自动改变应用请求中的模型 ID |
| 图标 | 用于模型展示，不会改变供应商接入协议或请求路由 |
| 上下文 | 模型的上下文信息，按实际能力填写；修改此处不会扩展上游模型的能力 |
| 描述 | 说明用途、能力和使用限制，便于用户选择模型 |

模型定义负责展示和计费信息；模型的实际接入由供应商配置完成。创建定义后，还需把模型加入对应供应商的支持范围。

### 计费方式与价格项

选择 **按量计费** 或 **按次计费**。按量计费按 Token 用量结算；按次计费使用每次调用的固定价格，应根据服务的实际计费方式选择。

按量计费时，先启用需要配置的价格项，再填写价格。页面中的 `$/1M tokens` 表示每百万 Token 的美元价格。

| 价格项 | 对应用量 |
| --- | --- |
| 输入价格 | 输入 Token |
| 输出价格 | 模型生成的输出 Token |
| 缓存读取价格 | 上游报告的缓存读取 Token |
| 缓存创建价格 | 上游报告的缓存创建 Token |
| 图片输入价格 | 对应的图片输入用量 |
| 音频输入价格 | 对应的音频输入用量 |
| 音频补全价格 | 对应的音频输出用量；配置前需先启用音频输入价格项 |

按业务要求填写实际价格后，提交或更新记录，再检查模型市场中的价格展示。

价格项的开关用于管理计费配置，不是模型能力开关。不要把停用某个价格项理解为该类调用免费；实际费用还与网关计费规则、定价倍率和上游报告的用量有关。

## 分组定价

**分组定价** 用于为调用设置定价倍率。例如，可建立 `standard`、`discount` 等分组定价，为不同成员或 API Key 应用不同的倍率，并在供应商上选择适用的分组定价。

### 创建与维护分组定价

进入 OneGateway **分组定价**，新建记录并填写配置。

| 配置项 | 说明 |
| --- | --- |
| 名称 | 实例内唯一，最长 50 字符；建议使用便于识别的小写字母、数字、下划线或短横线，创建后不可修改 |
| 描述 | 用于向成员说明该分组定价的适用场景 |
| 定价倍率 | 非负数，默认 1；例如 0.8 表示在适用计费规则下乘以 0.8 |
| 用户可选 | 控制该分组定价是否向用户提供选择；关闭后应同时核对已有 API Key 的分组定价配置 |
| 排序 | 调整分组定价的展示顺序 |

创建后，在[供应商](#供应商)中为适用的供应商选择该分组定价，并检查供应商支持的模型和启用状态。仅创建分组定价不会自动为它接入模型服务。

分组定价被 API Key、供应商等记录引用时无法删除，需先解除引用。

### 设置用户的分组定价

新用户初始化 OneGateway 账号时，系统从当前租户符合条件的分组定价中，选择创建时间最早的一个作为默认分组定价。

调整用户的分组定价：

1. 在 **用户** 列表中打开目标用户。
2. 使用 **编辑分组定价** 入口，选择用户的分组定价。
3. 如果页面显示 **可选分组定价**，按需配置用户创建 API Key 时还可以选择的其他分组定价。
4. 点击 **保存**，核对更新后的分组定价和可选分组定价。

用户自己的分组定价默认可选。若提示账号尚未初始化，先确认用户已激活、具备 OneGateway 角色且相关账号配置已完成。

### 为 API Key 指定分组定价

创建或编辑 [API Keys](/user/tokens)时，通过 **分组定价** 选择该密钥适用的定价。未设置时使用用户的分组定价。

API Key 可调用的模型由密钥的 **可用模型** 限制。若调用提示模型不可用，还需确认承载该模型的供应商已启用，并已选择该密钥使用的分组定价。

调整用户的分组定价或可选分组定价后，应逐一核对仍在使用的 API Key，特别是已经明确指定分组定价的密钥。完成调整后，用对应 API Key 发起一次调用，在[日志](/user/usage)中确认模型、供应商及费用符合预期。

## 验证与排障

### 快速验证

完成接入或修改后，用一次实际调用串联检查配置：

1. 在供应商中确认接入信息、支持模型和分组定价，检查供应商已启用。
2. 在模型市场中找到目标模型，确认存在可用承载供应商，并复制模型 ID。
3. 使用分组定价与供应商匹配、且可用模型包含该模型的 API Key，按[快速开始](/guide/getting-started)发起简单提问，例如“请用一句话介绍你自己”，将请求的 `model` 替换为刚复制的 ID。
4. 在[日志](/user/usage)中检查请求结果、模型、供应商、Token 用量和费用。
5. 涉及路由或价格调整时，再结合[看板与统计](/user/dashboard)观察后续调用的分布和费用变化。

### 配置未生效时的检查

如果出现已保存但调用结果未变化的情况，可按以下顺序检查：

1. **确认同步结果**：查看同步状态和错误提示，处理失败原因，确认配置已同步后再复测。
2. **核对模型与供应商**：确认当前网关实例、模型 ID 和供应商的支持模型范围一致，且供应商已启用。
3. **检查调用权限**：核对 API Key 的分组定价、模型限制和可用额度。
4. **对照日志**：发起一次新请求，检查实际使用的模型、供应商和错误信息。路由或价格变更后，用新请求的结果验证调整。