> ## 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，直接掌控速率限制、費用與供應商存取權限。

## 概述

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 Key                  |
| **Azure**     | Azure OpenAI                            | API Key、端點 URL、部署名稱      |
| **Bedrock**   | AWS Bedrock                             | Access Key、Secret Key、區域 |
| **Vertex AI** | Google Vertex AI                        | 服務帳戶 JSON、區域             |

## 新增 BYOK 金鑰

### 控制台操作

1. 前往 **設定 → 整合**。
2. 點選 **新增供應商金鑰**。
3. 選擇供應商與憑證類型。
4. 輸入您的金鑰或憑證。
   5.（選填）點選 **測試金鑰** 確認金鑰有效。
5. 點選 **儲存**。

### 進階選項

新增金鑰時，您可以設定：

| 選項           | 說明               | 預設值      |
| ------------ | ---------------- | -------- |
| **標籤**       | 為此金鑰命名（例如「正式環境」） | —        |
| **一律使用此金鑰**  | 不退回平台金鑰          | 關閉（允許退回） |
| **權重**       | 同一供應商有多組金鑰時的路由權重 | 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": "{...your service account JSON...}",
  "region": "us-central1"
}
```

## 排除 BYOK 問題

如果 BYOK 請求失敗：

1. 前往 **設定 → 整合**，檢查金鑰健康狀態。
2. 點選金鑰以查看最近的錯誤訊息。
3. 使用 **測試金鑰** 按鈕確認金鑰仍然有效。
4. 在 **用量** 頁面查看 BYOK 專屬的錯誤率。

常見問題：

| 症狀                  | 原因            | 解決方式             |
| ------------------- | ------------- | ---------------- |
| `invalid x-api-key` | 金鑰已過期或被撤銷     | 從供應商重新產生金鑰       |
| 金鑰顯示為不健康            | 過多錯誤觸發了冷卻期    | 等待冷卻期結束，或編輯後重新啟用 |
| 請求未使用 BYOK          | 供應商/模型不符      | 檢查金鑰的支援模型與區域設定   |
| 退回至平台               | BYOK 金鑰達到速率限制 | 提高 RPM 限制或新增更多金鑰 |