> ## 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: 나만의 키 사용하기

> ARouter에서 직접 보유한 LLM 공급자 API 키를 사용하여 요청 제한, 비용, 공급자 접근 권한을 직접 관리하세요.

## 개요

ARouter는 플랫폼 크레딧과 직접 보유한 공급자 키 사용(BYOK) 두 가지 모드를 모두 지원합니다. 자체 키를 사용하면 요청이 해당 공급자 계정을 통해 라우팅되며, 통합 API, 장애 전환, 분석, 지출 관리 등 ARouter의 모든 기능을 그대로 이용할 수 있습니다.

공급자 키는 안전하게 암호화되어 저장되며 라우팅 시 자동으로 우선 사용됩니다. 코드 변경은 필요 없습니다. 대시보드에서 키를 추가하기만 하면 기존 ARouter API Key가 그대로 동작합니다.

## 작동 방식

```
사용자 앱 → ARouter API (ARouter 키) → 공급자 (BYOK 키)
```

1. **설정 → 연동**에서 공급자 API 키를 추가합니다.
2. ARouter가 해당 공급자에 대해 자동으로 사용자의 키를 사용합니다.
3. 키를 사용할 수 없는 경우 플랫폼 키로 대체할 수 있습니다(설정 가능).
4. 사용량은 BYOK과 플랫폼으로 별도 추적됩니다.

## 지원 공급자

ARouter는 다음 인증 유형의 BYOK를 지원합니다:

| 인증 유형         | 공급자                                         | 필수 항목                     |
| ------------- | ------------------------------------------- | ------------------------- |
| **API Key**   | OpenAI, Anthropic, DeepSeek, xAI, Mistral 등 | API Key                   |
| **Azure**     | Azure OpenAI                                | API Key, 엔드포인트 URL, 배포 이름 |
| **Bedrock**   | AWS Bedrock                                 | 액세스 키, 시크릿 키, 리전          |
| **Vertex AI** | Google Vertex AI                            | 서비스 계정 JSON, 리전           |

## BYOK 키 추가

### 대시보드

1. **설정 → 연동**으로 이동합니다.
2. **공급자 키 추가**를 클릭합니다.
3. 공급자와 인증 유형을 선택합니다.
4. 키 또는 인증 정보를 입력합니다.
5. (선택) **키 테스트**를 클릭하여 정상 동작을 확인합니다.
6. **저장**을 클릭합니다.

### 고급 옵션

키 추가 시 다음을 설정할 수 있습니다:

| 옵션            | 설명                         | 기본값        |
| ------------- | -------------------------- | ---------- |
| **라벨**        | 키 이름 (예: "프로덕션")           | —          |
| **항상 이 키 사용** | 플랫폼 키로 대체하지 않음             | 꺼짐 (대체 허용) |
| **가중치**       | 동일 공급자에 여러 키가 있을 때 라우팅 가중치 | 1          |
| **RPM 제한**    | 이 키의 분당 최대 요청 수            | 무제한        |
| **Base URL**  | 사용자 정의 엔드포인트 URL           | 공급자 기본값    |
| **리전**        | 선호하는 라우팅 리전                | 모든 리전      |
| **지원 모델**     | 이 키를 특정 모델로 제한             | 모든 모델      |
| **일일/월간 예산**  | USD 기준 지출 한도               | 무제한        |

## 대체(Fallback) 동작

기본적으로 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 제한을 높이거나 키를 추가      |