> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# BYOK: 自带密钥

> 使用您自己的 LLM 供应商 API 密钥，直接控制速率限制、费用和供应商访问。

## 概述

ARouter 支持平台额度和自带供应商密钥（BYOK）两种模式。使用自己的密钥时，请求通过您的供应商账户路由，同时保留 ARouter 的所有功能 —— 统一 API、故障转移、分析和费用控制。

您的供应商密钥经过安全加密存储，并在路由时自动优先使用。无需修改代码 —— 只需在控制台添加密钥，现有的 ARouter API Key 照常使用。

## 工作原理

```
您的应用 → ARouter API（您的 ARouter Key）→ 供应商（您的 BYOK 密钥）
```

1. 在 **设置 → 集成** 中添加您的供应商 API 密钥。
2. ARouter 自动为该供应商使用您的密钥。
3. 如果您的密钥不可用，ARouter 可以回退到平台密钥（可配置）。
4. 用量按 BYOK 和平台分别统计。

## 支持的供应商

ARouter 支持以下凭证类型的 BYOK：

| 凭证类型          | 适用供应商                                   | 所需字段                |
| ------------- | --------------------------------------- | ------------------- |
| **API Key**   | OpenAI、Anthropic、DeepSeek、xAI、Mistral 等 | API 密钥              |
| **Azure**     | Azure OpenAI                            | API 密钥、终结点 URL、部署名称 |
| **Bedrock**   | AWS Bedrock                             | 访问密钥、私有密钥、区域        |
| **Vertex AI** | Google Vertex AI                        | 服务账户 JSON、区域        |

## 添加 BYOK 密钥

### 控制台操作

1. 进入 **设置 → 集成**。
2. 点击 **添加供应商密钥**。
3. 选择供应商和凭证类型。
4. 输入您的密钥/凭证。
5. （可选）点击 **测试密钥** 验证有效性。
6. 点击 **保存**。

### 高级选项

添加密钥时可配置：

| 选项           | 说明             | 默认值      |
| ------------ | -------------- | -------- |
| **标签**       | 密钥名称（如"生产环境"）  | —        |
| **始终使用此密钥**  | 不回退到平台密钥       | 关闭（允许回退） |
| **权重**       | 同供应商多个密钥时的路由权重 | 1        |
| **RPM 限制**   | 该密钥的每分钟最大请求数   | 无限制      |
| **Base URL** | 自定义终结点 URL     | 供应商默认值   |
| **地区**       | 路由偏好区域         | 任意       |
| **支持的模型**    | 限制该密钥只用于特定模型   | 全部模型     |
| **每日/每月预算**  | 费用上限（美元）       | 无限制      |

## 回退策略

默认情况下，如果您的 BYOK 密钥遇到速率限制或错误，ARouter 会无缝回退到平台密钥。您可以按密钥修改此行为：

| 回退策略       | 行为               |
| ---------- | ---------------- |
| **允许**（默认） | BYOK 不可用时回退到平台密钥 |
| **禁止**     | BYOK 密钥不可用时拒绝请求  |

在控制台启用 **"始终使用此密钥"** 即设置为禁止回退。

## 多密钥支持

您可以为同一供应商添加多个 BYOK 密钥。ARouter 在所有可用密钥间按加权随机选择。通过 **权重** 字段控制流量分配。

## BYOK 用量统计

BYOK 请求在用量面板中单独统计：

* **BYOK 请求数** — 使用您密钥的请求数量
* **预估 BYOK 花费** — 基于供应商定价的估算成本
* **平台花费** — 使用平台密钥的请求成本

按模型用量表格中有 **来源** 列，显示每个模型的请求来自 BYOK、平台还是混合。

## Azure 配置

Azure OpenAI 需提供 JSON 格式的密钥配置：

```json theme={null}
{
  "api_key": "your-azure-api-key",
  "endpoint_url": "https://your-resource.openai.azure.com/openai/deployments/your-deployment/chat/completions?api-version=2024-08-01-preview",
  "deployment_name": "your-deployment-name"
}
```

## AWS Bedrock 配置

AWS Bedrock 需提供 AWS 凭证：

```json theme={null}
{
  "access_key": "AKIAIOSFODNN7EXAMPLE",
  "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "region": "us-east-1"
}
```

## Google Vertex AI 配置

Vertex AI 需提供服务账户凭证：

```json theme={null}
{
  "service_account_json": "{...您的服务账户 JSON...}",
  "region": "us-central1"
}
```

## 排查 BYOK 问题

如果 BYOK 请求失败：

1. 进入 **设置 → 集成** 检查密钥健康状态。
2. 点击密钥查看最近的错误信息。
3. 使用 **测试密钥** 按钮验证密钥是否仍然有效。
4. 在 **用量** 页面查看 BYOK 错误率。

常见问题：

| 现象                  | 原因         | 解决方法             |
| ------------------- | ---------- | ---------------- |
| `invalid x-api-key` | 密钥已过期或被吊销  | 从供应商处生成新密钥       |
| 密钥显示不健康             | 过多错误触发冷却   | 等待冷却期结束，或编辑后重新启用 |
| 请求未使用 BYOK          | 供应商/模型不匹配  | 检查密钥的支持模型和区域配置   |
| 回退到平台               | BYOK 密钥被限速 | 提高 RPM 限制或添加更多密钥 |