# 密钥托管

**Beta 体验：密钥托管目前仅对 Beta 体验用户开放。**

密钥托管（BYOK，Bring Your Own Key）支持将您自有的供应商 API 密钥托管至星图。无需修改现有调用代码，即可通过星图统一接入和管理多个供应商，并享受智能路由、故障切换和星图资源兜底。

调用时优先使用您的供应商密钥；当自有密钥均不可用时，系统将自动切换至星图资源，保障业务连续性。

## 功能优势

- **统一 API 接入**：无需修改现有代码，通过星图统一 API 入口和模型名称调用。
- **智能调度切换**：支持配置多把密钥并设置调用优先级，密钥异常时自动切换，无需自行维护重试逻辑。
- **星图资源兜底**：自有密钥均不可用时，自动切换至星图资源，并按星图模型刊例价计费。
- **统一管理供应商**：集中管理多个供应商及 API 密钥，继续使用原供应商的价格和额度。
- **调用记录可追溯**：支持查看审计日志，统一追踪密钥调用及操作记录。

## 功能入口

进入 **模型服务平台 > 工作台 > 第三方密钥管理**

![密钥托管功能入口](https://cdnv2-cache.udelivrs.com/2026/10/59eb08c91599c17840ff1008241de491_1791456307831.png)

## 使用限制

- 仅支持**文本模型**。
- 仅支持 **OpenAI 兼容协议**的供应商 API。
- 每个账号（Company ID）最多添加 **20 个供应商**，密钥数量不限。

## 快速开始

### 第一步：添加供应商

1. 登录星图控制台，进入侧边栏 **密钥托管** 页面。
2. 点击「新增供应商」，选择平台预定义供应商，或选择「自定义」填写供应商名称和接口地址。
3. 海外供应商可选择代理点：**乌兰察布、洛杉矶、新加坡、法兰克福、上海**；无特殊需求可跳过。
4. 点击「确定」完成创建。

![添加供应商](https://cdnv2-cache.udelivrs.com/2026/10/42b62bcfea93a27fe2b7017d70cc51d8_1791456307843.png)

### 第二步：配置模型映射

模型映射用于指定**星图模型与供应商模型的对应关系**。

1. 在供应商列表中点击该供应商的「托管密钥」，进入详情页。
2. 在「供应商-星图模型映射」板块点击「配置映射」。
3. 填写**供应商模型 ID**，并选择对应的**星图模型 ID**。

> 一个星图模型只能映射到一个供应商。如已被其他供应商映射的模型会标记「已被其他供应商映射」。

![配置模型映射](https://cdnv2-cache.udelivrs.com/2026/10/2288566560c24006776435aaad0d6851_1791456307828.png)

### 第三步：托管密钥

1. 在详情页的「密钥列表」中点击「托管密钥」。
2. 填写**API 密钥**和**显示名称**，设置可调用的模型范围。
3. 点击「开始测试」：系统将检查**接口可达性、密钥有效性和账户余额**。

注意： 测试会使用该供应商下第一个已映射的模型发起一次真实调用，可能产生少量费用。

![托管密钥](https://cdnv2-cache.udelivrs.com/2026/10/fe11b90940a5b20aed050e740faa0734_1791456307841.png)

#### 调整密钥优先级

在密钥列表中**拖拽调整顺序**即可。排在前面的密钥优先调用，调用失败后自动切换至下一把密钥，调整后立即生效。

## 费用怎么算

- **自有密钥调用**：模型调用费用由您的供应商账户承担。Beta 阶段暂不收取星图平台服务费。
- **星图资源兜底**：按星图模型刊例价计费。
- **跨境调用**：根据实际调用链路适用对应单价。

## 常见问题

### 测试失败，密钥保存不了怎么办？

依次检查**接口地址、API 密钥和账户余额**。海外供应商还需确认代理点配置正确。

### 有多把密钥，如何设置？

把额度大、价格优的密钥排在前面，把备用密钥排在后面；模型范围按各密钥实际开通的模型勾选。这样既能优先用好资源，单把密钥出问题也能自动顺延。

### 为什么调用走的是星图兜底而不是我的密钥？

可能原因包括：

- 未配置对应的模型映射；
- 密钥状态为「不可用」；
- 密钥未配置对应模型；
- 所有符合条件的自有密钥均调用失败。