vrr/OmniRoute
2
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-05-03 08:40:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

docs(i18n): add multilingual documentation translations

Browse source 
Add translated documentation files for multiple languages including
Korean, Polish, and others under docs/i18n/. Translations cover
API reference, quickstart guides, and project documentation to
improve accessibility for non-English speaking contributors.
This commit is contained in:
diegosouzapw 2026-02-26 16:26:59 -03:00
parent 369a0141de
commit 1647005d6e
36 changed files with 16831 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

698
docs/i18n/ko/USER_GUIDE.md Normal file
View file

@ -0,0 +1,698 @@
# 이용안내
🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md)
공급자 구성, 콤보 생성, CLI 도구 통합 및 OmniRoute 배포에 대한 전체 가이드입니다.
---
## 목차
- [Pricing at a Glance](#-pricing-at-a-glance)
- [Use Cases](#-use-cases)
- [Provider Setup](#-provider-setup)
- [CLI Integration](#-cli-integration)
- [Deployment](#-deployment)
- [Available Models](#-available-models)
- [Advanced Features](#-advanced-features)
---
## 💰 가격 한눈에 보기
| 계층 | 공급자 | 비용 | 할당량 재설정 | 최고의 대상 |
| ------------- | ------------------- | ------------------ | --------------- | ----------------- |
| **💳 구독** | 클로드 코드 (Pro) | $20/월 | 5시간 + 매주 | 이미 구독 중 |
| | 코덱스(플러스/프로) | $20-200/월 | 5시간 + 매주 | OpenAI 사용자 |
| | 제미니 CLI | **무료** | 180K/월 + 1K/일 | 모든 사람! |
| | GitHub 부조종사 | $10-19/월 | 월간 | GitHub 사용자 |
| **🔑 API 키** | 딥시크 | 사용량에 따라 지불 | 없음 | 저렴한 추론 |
| | 그로크 | 사용량에 따라 지불 | 없음 | 초고속 추론 |
| | xAI(그록) | 사용량에 따라 지불 | 없음 | Grok 4 추론 |
| | 미스트랄 | 사용량에 따라 지불 | 없음 | EU 주최 모델 |
| | 당혹감 | 사용량에 따라 지불 | 없음 | 검색 증강 |
| | 함께하는 AI | 사용량에 따라 지불 | 없음 | 오픈 소스 모델 |
| | 불꽃놀이 AI | 사용량에 따라 지불 | 없음 | 빠른 FLUX 이미지 |
| | 대뇌 | 사용량에 따라 지불 | 없음 | 웨이퍼 규모 속도 |
| | 코히어 | 사용량에 따라 지불 | 없음 | 커맨드 R+ RAG |
| | 엔비디아 NIM | 사용량에 따라 지불 | 없음 | 엔터프라이즈 모델 |
| **💰 저렴한** | GLM-4.7 | $0.6/1M | 매일 오전 10시 | 예산 백업 |
| | 미니맥스 M2.1 | $0.2/1M | 5시간 롤링 | 가장 저렴한 옵션 |
| | 키미 K2 | $9/월 정액 | 1000만 토큰/월 | 예측 가능한 비용 |
| **🆓 무료** | 아이플로우 | $0 | 무제한 | 8개 모델 무료 |
| | 퀀 | $0 | 무제한 | 3개 모델 무료 |
| | 키로 | $0 | 무제한 | 클로드 프리 |
**💡 전문가 팁:** Gemini CLI(월 180K 무료) + iFlow(무제한 무료) 콤보 = 비용 $0로 시작하세요!
---
## 🎯 사용 사례
### 사례 1: "Claude Pro를 구독하고 있습니다."
**문제:** 할당량은 사용되지 않은 상태로 만료되며, 코딩 작업이 많은 동안 속도 제한이 발생합니다.
```
Combo: "maximize-claude"
1. cc/claude-opus-4-6 (use subscription fully)
2. glm/glm-4.7 (cheap backup when quota out)
3. if/kimi-k2-thinking (free emergency fallback)
Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration
```
### 사례 2: "비용이 0이길 원합니다"
**문제:** 구독료를 감당할 수 없고 안정적인 AI 코딩이 필요함
```
Combo: "free-forever"
1. gc/gemini-3-flash (180K free/month)
2. if/kimi-k2-thinking (unlimited free)
3. qw/qwen3-coder-plus (unlimited free)
Monthly cost: $0
Quality: Production-ready models
```
### 사례 3: "중단 없이 연중무휴 코딩이 필요합니다."
**문제:** 마감일, 가동 중지 시간을 감당할 수 없음
```
Combo: "always-on"
1. cc/claude-opus-4-6 (best quality)
2. cx/gpt-5.2-codex (second subscription)
3. glm/glm-4.7 (cheap, resets daily)
4. minimax/MiniMax-M2.1 (cheapest, 5h reset)
5. if/kimi-k2-thinking (free unlimited)
Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)
```
### 사례 4: "OpenClaw에서 무료 AI를 원합니다"
**문제:** 메시징 앱에 AI 도우미가 필요하며 완전 무료입니다.
```
Combo: "openclaw-free"
1. if/glm-4.7 (unlimited free)
2. if/minimax-m2.1 (unlimited free)
3. if/kimi-k2-thinking (unlimited free)
Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...
```
---
## 📖 공급자 설정
### 🔐 구독 제공업체
#### 클로드 코드(Pro/Max)
```bash
Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking
Models:
cc/claude-opus-4-6
cc/claude-sonnet-4-5-20250929
cc/claude-haiku-4-5-20251001
```
**프로 팁:** 복잡한 작업에는 Opus를 사용하고, 속도를 높이려면 Sonnet을 사용하세요. OmniRoute는 모델당 할당량을 추적합니다!
#### OpenAI 코덱스(Plus/Pro)
```bash
Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset
Models:
cx/gpt-5.2-codex
cx/gpt-5.1-codex-max
```
#### Gemini CLI(월 180K 무료!)
```bash
Dashboard → Providers → Connect Gemini CLI
→ Google OAuth
→ 180K completions/month + 1K/day
Models:
gc/gemini-3-flash-preview
gc/gemini-2.5-pro
```
**최고의 가치:** 엄청난 무료 등급! 유료 등급 이전에 사용하세요.
#### GitHub 코파일럿
```bash
Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)
Models:
gh/gpt-5
gh/claude-4.5-sonnet
gh/gemini-3-pro
```
### 💰 저렴한 공급자
#### GLM-4.7 (일일 재설정, $0.6/1M)
1. 가입: [Zhipu AI](https://open.bigmodel.cn/)
2. Coding Plan에서 API Key 받기
3. 대시보드 → API 키 추가: 공급자: `glm`, API 키: `your-key`
**사용:** `glm/glm-4.7` — **프로 팁:** 코딩 계획은 1/7 비용으로 3배 할당량을 제공합니다! 매일 오전 10시에 초기화됩니다.
#### MiniMax M2.1(5시간 재설정, $0.20/1M)
1. 가입: [MiniMax](https://www.minimax.io/)
2. API 키 받기 → 대시보드 → API 키 추가
**사용:** `minimax/MiniMax-M2.1` — **프로 팁:** 긴 컨텍스트(1M 토큰)에 대한 가장 저렴한 옵션!
#### Kimi K2($9/월 정액)
1. 구독: [Moonshot AI](https://platform.moonshot.ai/)
2. API 키 받기 → 대시보드 → API 키 추가
**사용:** `kimi/kimi-latest` — **프로 팁:** 1,000만 토큰에 대해 월 $9 고정 = 유효 비용 $0.90/1M!
### 🆓 무료 제공업체
#### iFlow(8개 무료 모델)
```bash
Dashboard → Connect iFlow → OAuth login → Unlimited usage
Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1
```
#### Qwen(3개 무료 모델)
```bash
Dashboard → Connect Qwen → Device code auth → Unlimited usage
Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash
```
#### 키로(클로드 프리)
```bash
Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited
Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5
```
---
## 🎨 콤보
### 예시 1: 구독 최대화 → 저렴한 백업
```
Dashboard → Combos → Create New
Name: premium-coding
Models:
1. cc/claude-opus-4-6 (Subscription primary)
2. glm/glm-4.7 (Cheap backup, $0.6/1M)
3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)
Use in CLI: premium-coding
```
### 예시 2: 무료 전용(비용 없음)
```
Name: free-combo
Models:
1. gc/gemini-3-flash-preview (180K free/month)
2. if/kimi-k2-thinking (unlimited)
3. qw/qwen3-coder-plus (unlimited)
Cost: $0 forever!
```
---
## 🔧 CLI 통합
### 커서 IDE
```
Settings → Models → Advanced:
OpenAI API Base URL: http://localhost:20128/v1
OpenAI API Key: [from omniroute dashboard]
Model: cc/claude-opus-4-6
```
### 클로드 코드
`~/.claude/config.json` 편집:
```json
{
"anthropic_api_base": "http://localhost:20128/v1",
"anthropic_api_key": "your-omniroute-api-key"
}
```
### 코덱스 CLI
```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"
codex "your prompt"
```
### 오픈클로
`~/.openclaw/openclaw.json` 편집:
```json
{
"agents": {
"defaults": {
"model": { "primary": "omniroute/if/glm-4.7" }
}
},
"models": {
"providers": {
"omniroute": {
"baseUrl": "http://localhost:20128/v1",
"apiKey": "your-omniroute-api-key",
"api": "openai-completions",
"models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }]
}
}
}
}
```
**또는 대시보드 사용:** CLI 도구 → OpenClaw → 자동 구성
### 클라인 / 계속 / RooCode
```
Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-6
```
---
## 🚀 배포
### VPS 배포
```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build
export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"
npm run start
# Or: pm2 start npm --name omniroute -- start
```
### 도커
```bash
# Build image (default = runner-cli with codex/claude/droid preinstalled)
docker build -t omniroute:cli .
# Portable mode (recommended)
docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli
```
CLI 바이너리를 사용한 호스트 통합 모드의 경우 기본 문서의 Docker 섹션을 참조하세요.
### 환경 변수
| 변수 | 기본값 | 설명 |
| --------------------- | ------------------------------------ | ----------------------------------------------- |
| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT 서명 비밀(**프로덕션 변경**) |
| `INITIAL_PASSWORD` | `123456` | 첫 번째 로그인 비밀번호 |
| `DATA_DIR` | `~/.omniroute` | 데이터 디렉터리(db, 사용량, 로그) |
| `PORT` | 프레임워크 기본값 | 서비스 포트(예시에서는 `20128`) |
| `HOSTNAME` | 프레임워크 기본값 | 호스트 바인딩(Docker의 기본값은 `0.0.0.0`) |
| `NODE_ENV` | 런타임 기본값 | 배포를 위해 `production` 설정 |
| `BASE_URL` | `http://localhost:20128` | 서버측 내부 기본 URL |
| `CLOUD_URL` | `https://omniroute.dev` | 클라우드 동기화 엔드포인트 기본 URL |
| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | 생성된 API 키에 대한 HMAC 비밀 |
| `REQUIRE_API_KEY` | `false` | `/v1/*`에 Bearer API 키 적용 |
| `ENABLE_REQUEST_LOGS` | `false` | 요청/응답 로그 활성화 |
| `AUTH_COOKIE_SECURE` | `false` | `Secure` 인증 쿠키 강제(HTTPS 역방향 프록시 뒤) |
전체 환경 변수 참조는 [README](../README.md)을 참조하세요.
---
## 📊 사용 가능한 모델
<details>
<summary><b>사용 가능한 모든 모델 보기</b></summary>
**Claude 코드(`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001`
**코덱스(`cx/`)** — 플러스/프로: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max`
**Gemini CLI(`gc/`)** — 무료: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro`
**GitHub 부조종사(`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet`
**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7`
**MiniMax(`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1`
**iFlow(`if/`)** — 무료: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1`
**Qwen(`qw/`)** — 무료: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash`
**키로(`kr/`)** — 무료: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5`
**DeepSeek(`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner`
**그로크(`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct`
**xAI(`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini`
**미스트랄(`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501`
**복잡성(`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar`
**함께하는 AI(`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`
**불꽃놀이 AI(`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1`
**대뇌(`cerebras/`)**: `cerebras/llama-3.3-70b`
**Cohere(`cohere/`)**: `cohere/command-r-plus-08-2024`
**NVIDIA NIM(`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct`
</details>
---
## 🧩 고급 기능
### 맞춤 모델
앱 업데이트를 기다리지 않고 공급자에 모델 ID를 추가하세요.
```bash
# Via API
curl -X POST http://localhost:20128/api/provider-models \
-H "Content-Type: application/json" \
-d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}'
# List: curl http://localhost:20128/api/provider-models?provider=openai
# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview"
```
또는 대시보드를 사용하십시오: **공급자 → [공급자] → 사용자 정의 모델**.
### 전용 공급자 경로
모델 검증을 통해 요청을 특정 공급자에게 직접 라우팅합니다.
```bash
POST http://localhost:20128/v1/providers/openai/chat/completions
POST http://localhost:20128/v1/providers/openai/embeddings
POST http://localhost:20128/v1/providers/fireworks/images/generations
```
공급자 접두사가 누락된 경우 자동으로 추가됩니다. 일치하지 않는 모델은 `400`을 반환합니다.
### 네트워크 프록시 구성
```bash
# Set global proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}'
# Per-provider proxy
curl -X PUT http://localhost:20128/api/settings/proxy \
-d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}'
# Test proxy
curl -X POST http://localhost:20128/api/settings/proxy/test \
-d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}'
```
**우선순위:** 키별 → 콤보별 → 공급자별 → 글로벌 → 환경.
### 모델 카탈로그 API
```bash
curl http://localhost:20128/api/models/catalog
```
유형(`chat`, `embedding`, `image`)을 사용하여 공급자별로 그룹화된 모델을 반환합니다.
### 클라우드 동기화
- 여러 장치에서 공급자, 콤보 및 설정을 동기화합니다.
- 시간 초과 + 빠른 실패를 통한 자동 백그라운드 동기화
- 프로덕션에서는 서버측 `BASE_URL`/`CLOUD_URL`을 선호합니다.
### LLM 게이트웨이 인텔리전스(9단계)
- **의미 체계 캐시** — 비스트리밍, 온도=0 응답을 자동 캐시합니다(`X-OmniRoute-No-Cache: true`으로 우회).
- **Idempotency 요청** — `Idempotency-Key` 또는 `X-Request-Id` 헤더를 통해 5초 이내에 요청을 중복 제거합니다.
- **진행 상황 추적** — `X-OmniRoute-Progress: true` 헤더를 통한 SSE `event: progress` 이벤트 선택
---
### 번역가 놀이터
**대시보드 → 번역기**를 통해 액세스합니다. OmniRoute가 공급자 간 API 요청을 변환하는 방법을 디버깅하고 시각화합니다.
| 모드 | 목적 |
| ----------------- | ------------------------------------------------------------------------- |
| **놀이터** | 소스/타겟 형식을 선택하고, 요청을 붙여넣고, 번역된 결과를 즉시 확인하세요 |
| **채팅 테스터** | 프록시를 통해 실시간 채팅 메시지를 보내고 전체 요청/응답 주기 검사 |
| **테스트 벤치** | 여러 형식 조합에 걸쳐 일괄 테스트를 실행하여 번역 정확성 확인 |
| **라이브 모니터** | 프록시를 통한 요청 흐름에 따라 실시간 번역 보기 |
**사용 사례:**
- 특정 클라이언트/공급자 조합이 실패하는 이유 디버그
- 생각 태그, 도구 호출 및 시스템 프롬프트가 올바르게 번역되는지 확인합니다.
- OpenAI, Claude, Gemini 및 Responses API 형식 간의 형식 차이 비교
---
### 라우팅 전략
**대시보드 → 설정 → 라우팅**을 통해 구성합니다.
| 전략 | 설명 |
| -------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **먼저 채우기** | 우선순위에 따라 계정을 사용합니다. 기본 계정은 사용할 수 없을 때까지 모든 요청을 처리합니다. |
| **라운드 로빈** | 구성 가능한 고정 한도를 사용하여 모든 계정을 순환합니다(기본값: 계정당 호출 3회) |
| **P2C(두 가지 선택의 힘)** | 2개의 무작위 계정을 선택하고 더 건강한 계정으로 라우팅 — 건강에 대한 인식과 부하의 균형을 유지 |
| **랜덤** | Fisher-Yates shuffle | 을 사용하여 각 요청에 대해 무작위로 계정을 선택합니다. |
| **최소 사용** | 가장 오래된 `lastUsedAt` 타임스탬프가 있는 계정으로 라우팅하여 트래픽을 균등하게 분산 |
| **비용 최적화** | 가장 낮은 비용의 공급자를 위해 최적화하여 우선순위 값이 가장 낮은 계정으로 라우팅 |
#### 와일드카드 모델 별칭
모델 이름을 다시 매핑하는 와일드카드 패턴을 만듭니다.
```
Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929
Pattern: gpt-* → Target: gh/gpt-5.1-codex
```
와일드카드는 `*`(모든 문자) 및 `?`(단일 문자)을 지원합니다.
#### 대체 체인
모든 요청에 적용되는 전역 대체 체인을 정의합니다.
```
Chain: production-fallback
1. cc/claude-opus-4-6
2. gh/gpt-5.1-codex
3. glm/glm-4.7
```
---
### 탄력성 및 회로 차단기
**대시보드 → 설정 → 복원력**을 통해 구성합니다.
OmniRoute는 다음 네 가지 구성 요소를 사용하여 공급자 수준 복원력을 구현합니다.
1. **공급자 프로필** — 다음에 대한 공급자별 구성:
- 실패 임계값(개방 전 실패 횟수)
- 쿨다운 시간
- 비율 제한 감지 감도
- 지수 백오프 매개변수
2. **편집 가능한 속도 제한** — 대시보드에서 구성 가능한 시스템 수준 기본값:
- **분당 요청(RPM)** — 계정당 분당 최대 요청 수
- **요청 간 최소 시간** — 요청 간 최소 간격(밀리초)
- **최대 동시 요청** — 계정당 최대 동시 요청
- 수정하려면 **수정**을 클릭한 다음 **저장** 또는 **취소**를 클릭하세요. 값은 복원력 API를 통해 유지됩니다.
3. **회로 차단기** — 공급자별 오류를 추적하고 임계값에 도달하면 자동으로 회로를 엽니다.
- **CLOSED**(정상) — 요청 흐름이 정상적으로 진행됩니다.
- **OPEN** — 반복적인 실패 후 공급자가 일시적으로 차단됩니다.
- **HALF_OPEN** — 공급자가 복구되었는지 테스트
4. **정책 및 잠긴 식별자** - 회로 차단기 상태와 강제 잠금 해제 기능이 있는 잠긴 식별자를 표시합니다.
5. **비율 제한 자동 감지** — `429` 및 `Retry-After` 헤더를 모니터링하여 공급자 비율 제한에 도달하는 것을 사전에 방지합니다.
**프로 팁:** 공급자가 중단에서 복구될 때 **모두 재설정** 버튼을 사용하여 모든 회로 차단기와 쿨다운을 해제합니다.
---
### 데이터베이스 내보내기/가져오기
**대시보드 → 설정 → 시스템 및 스토리지**에서 데이터베이스 백업을 관리하세요.
| 액션 | 설명 |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **데이터베이스 내보내기** | 현재 SQLite 데이터베이스를 `.sqlite` 파일로 다운로드 |
| **모두 내보내기(.tar.gz)** | 데이터베이스, 설정, 콤보, 공급자 연결(자격 증명 없음), API 키 메타데이터를 포함한 전체 백업 아카이브를 다운로드합니다. |
| **데이터베이스 가져오기** | 현재 데이터베이스를 대체하려면 `.sqlite` 파일을 업로드하세요. 가져오기 전 백업이 자동으로 생성됩니다. |
```bash
# API: Export database
curl -o backup.sqlite http://localhost:20128/api/db-backups/export
# API: Export all (full archive)
curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll
# API: Import database
curl -X POST http://localhost:20128/api/db-backups/import \
-F "file=@backup.sqlite"
```
**가져오기 유효성 검사:** 가져온 파일은 무결성(SQLite pragma 검사), 필수 테이블(`provider_connections`, `provider_nodes`, `combos`, `api_keys`) 및 크기(최대 100MB)에 대해 유효성이 검사됩니다.
**사용 사례:**
- 머신 간 OmniRoute 마이그레이션
- 재해 복구를 위한 외부 백업 생성
- 팀원 간 구성 공유(모두 내보내기 → 아카이브 공유)
---
### 설정 대시보드
설정 페이지는 쉽게 탐색할 수 있도록 5개의 탭으로 구성되어 있습니다.
| 탭 | 내용 |
| ---------- | ------------------------------------------------------------------------------ |
| **보안** | 로그인/비밀번호 설정, IP 액세스 제어, `/models`에 대한 API 인증 및 공급자 차단 |
| **라우팅** | 글로벌 라우팅 전략(6개 옵션), 와일드카드 모델 별칭, 폴백 체인, 콤보 기본값 |
| **탄력성** | 공급자 프로필, 편집 가능한 속도 제한, 회로 차단기 상태, 정책 및 잠긴 식별자 |
| **AI** | 생각하는 예산 구성, 글로벌 시스템 프롬프트 주입, 프롬프트 캐시 통계 |
| **고급** | 글로벌 프록시 구성(HTTP/SOCKS5) |
---
### 비용 및 예산 관리
**대시보드 → 비용**을 통해 액세스합니다.
| 탭 | 목적 |
| -------- | ----------------------------------------------------------------- |
| **예산** | 일별/주별/월별 예산 및 실시간 추적을 통해 API 키별 지출 한도 설정 |
| **가격** | 모델 가격 항목 보기 및 편집 - 공급자당 1K 입력/출력 토큰당 비용 |
```bash
# API: Set a budget
curl -X POST http://localhost:20128/api/usage/budget \
-H "Content-Type: application/json" \
-d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}'
# API: Get current budget status
curl http://localhost:20128/api/usage/budget
```
**비용 추적:** 모든 요청은 토큰 사용량을 기록하고 가격표를 사용하여 비용을 계산합니다. **대시보드 → 사용량**에서 공급자, 모델, API 키별 분석을 확인하세요.
---
### 오디오 전사
OmniRoute는 OpenAI 호환 엔드포인트를 통해 오디오 전사를 지원합니다.
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
# Example with curl
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@audio.mp3" \
-F "model=deepgram/nova-3"
```
사용 가능한 공급자: **Deepgram**(`deepgram/`), **AssemblyAI**(`assemblyai/`).
지원되는 오디오 형식: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
---
### 콤보 밸런싱 전략
**대시보드 → 콤보 → 생성/편집 → 전략**에서 콤보별 밸런싱을 구성하세요.
| 전략 | 설명 |
| -------------------- | ----------------------------------------------------------- |
| **라운드 로빈** | 모델을 순차적으로 회전 |
| **우선순위** | 항상 첫 번째 모델을 시도합니다. 오류가 발생한 경우에만 폴백 |
| **랜덤** | 각 요청에 대한 콤보에서 무작위 모델 선택 |
| **가중치** | 모델별로 할당된 가중치를 기준으로 비례적으로 라우팅 |
| **가장 적게 사용됨** | 최근 요청이 가장 적은 모델로 라우팅(콤보 메트릭 사용) |
| **비용 최적화** | 가장 저렴한 모델로 연결(가격표 사용) |
글로벌 콤보 기본값은 **대시보드 → 설정 → 라우팅 → 콤보 기본값**에서 설정할 수 있습니다.
---
### 건강 대시보드
**대시보드 → 건강**을 통해 액세스합니다. 6개의 카드를 사용한 실시간 시스템 상태 개요:
| 카드 | 표시되는 내용 |
| ------------------ | ----------------------------------------------- |
| **시스템 상태** | 가동 시간, 버전, 메모리 사용량, 데이터 디렉터리 |
| **제공자 건강** | 공급자별 회로 차단기 상태(폐쇄/개방/반개방) |
| **비율 제한** | 남은 시간에 따른 계정당 활성 속도 제한 쿨다운 |
| **활성 잠금** | 잠금 정책으로 인해 일시적으로 차단된 제공업체 |
| **서명 캐시** | 중복 제거 캐시 통계(활성 키, 적중률) |
| **지연 원격 측정** | 공급자별 p50/p95/p99 대기 시간 집계 |
**프로 팁:** 상태 페이지는 10초마다 자동으로 새로 고쳐집니다. 회로 차단기 카드를 사용하여 어떤 공급자가 문제를 겪고 있는지 식별하십시오.