ypollak2/llm-router

pip install llm-routing   # PyPI name is llm-routing; the CLI command is llm-router

• 설치하는 이유

• RouterArena 8위

• 빠른 시작

• 라우팅 예시

• 호환 대상

• 작동 방식

• 기능

• CLI

• 제공자

• 라우팅 정책

• MCP 도구

• 절감 효과: 작동 방식

• 신뢰, 개인정보 보호, 로컬 우선 설계

• 구성

• 문서

• 엔터프라이즈

• 기여

설치하는 이유

AI 코딩 도구는 기본적으로 너무 많은 프롬프트를 프리미엄 모델로 보냅니다.

즉, 다음과 같은 문제가 발생합니다:

• 간단한 질문에 유료 토큰을 낭비합니다

• Claude, Gemini, OpenAI 할당량을 필요 이상으로 빠르게 소진합니다

• 한 제공자가 속도 제한에 걸리거나 다운되면 작업을 중단해야 합니다

llm-router는 코딩 도구와 모델 제공자 사이에 위치합니다. 각 프롬프트를 분류하고, 가장 저렴하면서도 작업을 처리할 수 있는 모델을 먼저 시도하며, 필요할 때 자동으로 대체합니다.

기존 워크플로우는 그대로 유지됩니다. 라우터가 그 아래에서 모델 선택만 변경합니다.

Related MCP server: MCP AI Router

RouterArena 8위

llm-router는 독립적으로 벤치마킹되어 RouterArena에서 8위를 차지했습니다. RouterArena는 라우팅 정확도, 지연 시간, 비용 효율성, 대체 신뢰성을 기준으로 모델 라우터를 평가하는 커뮤니티 리더보드입니다.

빠른 시작

1. 설치

pip install llm-routing
llm-router install

PyPI 패키지 이름: llm-routing. CLI 명령어: llm-router.

2. 제공자 추가 (선택 사항)

export OPENAI_API_KEY="sk-..."          # GPT-4o, o3
export GEMINI_API_KEY="AIza..."         # Gemini Flash/Pro (free tier available)
export OLLAMA_BASE_URL="http://localhost:11434"  # Local models (free)
export OPENROUTER_API_KEY="sk-or-v1-…"  # 343 OpenRouter models (qwen, deepseek, grok, …)

Claude Code Pro/Max 구독에서는 API 키 없이 작동합니다. 라우팅은 유익한 경우에만 외부 모델을 호출하는 MCP 도구를 사용합니다. OPENROUTER_API_KEY를 추가하면 cost_aggressive 정책에서 사용하는 오픈 가중치 워크호스 풀을 사용할 수 있습니다.

3. 확인

llm-router health            # Check provider connectivity

이미 Claude Code, Codex, Gemini CLI를 사용 중이라면 기존 워크플로우를 유지하고 llm-router가 그 아래에서 모델을 선택하도록 하세요.

라우팅 예시

정확한 체인은 구성된 제공자, 예산 프로필, 라우팅 정책에 따라 달라집니다.

호환 대상

• 전체 자동 라우팅은 후크가 프롬프트를 가로채 워크플로우 변경 없이 자동으로 라우팅함을 의미합니다.

• 수동 MCP 도구는 llm_query와 같은 도구를 통해 필요할 때 라우팅을 사용할 수 있음을 의미합니다.

llm-router install                    # Claude Code (default)
llm-router install --host codex       # Codex CLI
llm-router install --host gemini-cli  # Gemini CLI
llm-router install --host vscode      # VS Code
llm-router install --host cursor      # Cursor

각 호스트에 대한 자세한 내용은 guide/HOST_SUPPORT_MATRIX.md를 참조하세요.

Claude Code 5시간 할당량 보호

enforce: smart + mode: zero_claude를 사용하면 프롬프트가 외부에서 완료되거나 네이티브 Claude가 실행되기 전에 중지됩니다. 자세한 내용은 **guide/GETTING_STARTED.md**를 참조하세요.

작동 방식

User prompt
    │
    ▼
┌──────────────────────┐
│ Complexity Classifier │  ← Heuristic (free, instant) or Ollama/Flash ($0.0001)
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Free-First Router   │  ← Tries cheapest model first, walks up the chain
│                      │
│  Ollama (free)       │
│  → Codex (prepaid)   │
│  → Gemini Flash      │
│  → GPT-4o / Claude   │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Guards (parallel)   │  ← Circuit breaker, budget pressure, quality check
└──────────┬───────────┘
           │
           ▼
      Response + cost logged to local SQLite

분류는 많은 작업에서 무료입니다(정규식 휴리스틱이 약 70%를 처리) 또는 로컬 Ollama나 Gemini Flash를 사용할 때 모호한 프롬프트의 경우 거의 무료입니다.

기능

"저렴한 프롬프트를 저렴한 모델로 보내기" 그 이상:

• 비밀 정보가 기기를 벗어나지 않습니다. API 키, 토큰 또는 개인 키가 포함된 프롬프트는 로컬 모델로만 라우팅됩니다. 외부 제공자에 도달할 수 없도록 fail-closed 방식입니다.

• 비용 역전 구독 라우팅. 간단하고 보통 수준의 프롬프트에는 무료/로컬을 우선 사용하고, 복잡한 프롬프트에는 유료 좌석을 우선 사용하며, 할당량이 부족할 때는 해당 좌석을 하위로 강등합니다. LLM_ROUTER_SUBSCRIPTION_PROVIDER로 선택할 수 있습니다.

• 회로 차단기가 포함된 자동 대체. 실패하거나 속도 제한에 걸린 제공자는 반복 재시도하지 않고 건너뜁니다.

• 작동 과정을 직접 볼 수 있습니다. 상태 표시줄, 터미널 제목, OS 알림에 마지막으로 라우팅된 모델, 절감액, 상태가 표시됩니다. 네이티브 상태 표시줄이 없는 호스트를 위한 기능입니다.

• 세션 종료 요약. 기준 대비 절감액, 계층 분포, 제공자별 비용, 지연 시간 p50/p95/p99, 주요 라우팅 경로가 표시됩니다.

• 미디어와 파이프라인도 지원합니다. llm_image / llm_video / llm_audio, 다단계 리서치를 위한 llm_orchestrate.

CLI

llm-router install      # wire up your host (Claude Code by default)
llm-router health       # provider connectivity
llm-router status       # savings + quota at a glance
llm-router doctor       # diagnose a broken setup

전체 명령어 참조: guide/GETTING_STARTED.md

제공자

20개 이상의 제공자, 무료 우선. Ollama(로컬, 무료)가 체인의 선두이며, OpenRouter(하나의 키로 343개 모델)가 가장 큰 단일 해금이며, Gemini와 Groq는 사용 가능한 무료 티어가 있습니다. Anthropic은 기존 Claude 구독을 통해 작동합니다. API 키가 필요 없습니다.

모든 제공자, 모델, 비용 티어, 환경 변수: guide/PROVIDERS.md

라우팅 정책

정책은 라우터가 프리미엄 모델에서 얼마나 적극적으로 라우팅하는지를 결정합니다. conservative(10–15% 절감)부터 balanced(기본값, 35–45%), cost_aggressive(70–85%, OPENROUTER_API_KEY 필요)까지 있습니다.

llm-router policy set cost_aggressive

6가지 정책 전체, 임계값, YAML 스키마: guide/POLICIES.md

MCP 도구

라우팅, 분석, 코드, 미디어, 예산, 진단에 걸친 60개 도구가 모든 MCP 호스트에 노출됩니다. 기본 consolidated 표면에는 11개의 프런트 도어 도구가 표시되며, LLM_ROUTER_SLIM=full로 설정하면 60개 모두 표시됩니다.

각 도구와 시그니처: guide/TOOLS.md

절감 효과: 작동 방식

절감액은 모든 작업을 Claude Sonnet/Opus로 라우팅하는 기준선과 실제 지출을 비교하여 계산됩니다.

방법론:

1. 라우팅된 각 작업이 기록: 사용된 모델, 소비된 토큰, 예상 비용

2. 동일한 토큰을 체인에서 가장 비싼 모델이 처리했을 때의 기준 비용을 계산

3. 절감액 = (기준 - 실제) / 기준

가정 및 제한 사항:

• 기준선은 모든 작업에 Opus/Sonnet을 사용했을 경우를 가정합니다(최악의 경우)

• 토큰 추정치는 정확한 토크나이저 수가 아닌 len(text) / 4 근사치를 사용합니다

• 비용 데이터는 LiteLLM의 가격 테이블에서 가져옵니다(제공자 가격 변경에 뒤처질 수 있음)

• 절감액은 워크로드에 따라 크게 달라집니다. 코드 중심 세션은 저렴한 모델로 더 많이 라우팅됩니다

• 라우터 자체는 약간의 오버헤드를 추가합니다(모호한 작업당 분류 비용 약 $0.0001)

관찰 범위: 정책과 작업 구성에 따라 35–80% 절감. 일부 문서의 "87%" 수치는 특정 개발 기간 동안의 단일 사용자 최고치이며 보장된 결과가 아닙니다.

신뢰, 개인정보 보호, 로컬 우선 설계

llm-router는 전적으로 사용자 기기에서 실행됩니다. 호스팅 프록시, 텔레메트리, 계정이 필요 없습니다.

우리가 하는 일:

• 구조화된 로그에서 API 키 제거

• 설치 전 후크 교착 상태 감지

• 모든 데이터를 ~/.llm-router/에 로컬 저장

• 공급업체 속도 제한 및 서비스 약관(TOS) 준수

알아야 할 사항:

• 프롬프트는 라우터가 선택한 공급업체로 전송됩니다 — 공급업체의 개인정보 처리방침을 검토하세요.

• 사용 로그(SQLite)는 저장 시 암호화되지 않습니다 — 필요한 경우 전체 디스크 암호화를 사용하세요.

• 라우터는 공급업체 수준에서 모델 탈옥이나 프롬프트 인젝션을 방지할 수 없습니다.

책임 있는 공개 정책은 SECURITY.md를 참조하세요.

구성

모든 것이 환경 변수입니다 — 시작하는 데 구성 파일이 필요 없습니다:

export OPENROUTER_API_KEY="sk-or-v1-..."          # biggest single unlock
export OLLAMA_BASE_URL="http://localhost:11434"   # local, free
export LLM_ROUTER_POLICY="cost_aggressive"        # routing policy
export LLM_ROUTER_ENFORCE="smart"                 # off | advise | smart | hard

전체 참조, 구성 파일 스키마 및 호스트별 재정의: guide/GETTING_STARTED.md

문서

전체 색인: guide/README.md

엔터프라이즈

llm-router는 개인 개발자와 소규모 팀을 위해 만들어졌습니다: 로컬 비용 절감, 운영 오버헤드 제로, 호스팅 서비스 없음. 팀 전체 정책 적용, 감사 내보내기, SSO 또는 조직별 예산이 필요하다면, 그것이 바로 **Chuzom**의 용도입니다.

기여

기여를 환영합니다. 전체 지침은 CONTRIBUTING.md를 참조하세요.

git clone https://github.com/ypollak2/llm-router.git
cd llm-router
uv sync --extra dev
uv run pytest tests/ -q         # Run tests (1900+)
uv run ruff check src/ tests/   # Lint

-|-----------| | llm-routing | 현재 PyPI 패키지(pip install llm-routing) | | llm-router | CLI 명령 및 GitHub 저장소 이름 | | claude-code-llm-router | 더 이상 사용되지 않는 레거시 패키지(llm-routing으로 리디렉션됨) |