LiteLLM Proxy 완전 가이드 2026 — Claude·GPT·Gemini를 하나의 엔드포인트로 묶는 법

 

Claude·GPT·Gemini API 키를 앱마다 따로 박아넣고 있다면, LiteLLM Proxy를 모르는 겁니다.

---

핵심 요약

→ LiteLLM Proxy = OpenAI·Anthropic·Google·AWS Bedrock 등 100개+ 모델을 단일 OpenAI 호환 엔드포인트로 묶는 오픈소스 LLM 게이트웨이
→ 핵심 기능 5가지: 멀티모델 라우팅·가상 키(Virtual Keys)·팀별 예산 제한·자동 폴백·비용 추적
→ 기존 코드 변경 최소: openai.base_url만 프록시 주소로 바꾸면 모든 모델 즉시 사용 가능
→ 비용 추적 단독으로도 월 $100 이상 쓰는 팀에게 충분한 도입 이유가 됨
→ Claude Code·Cursor·Copilot 같은 AI 코딩 툴도 프록시 경유로 비용 추적 가능
→ 2026년 3월 24일 공급망 보안 사고: v1.82.7·v1.82.8에 자격증명 탈취 악성코드 포함 — 해당 버전 즉시 교체 필수
→ 현재 안전한 버전: v1.83.0 이후, Docker 이미지는 cosign 서명 시작
→ 프로덕션 배포: Docker Compose + PostgreSQL, 버전 반드시 고정 (latest 태그 금지)
→ GitHub Stars 40K+, 월 9,500만+ PyPI 다운로드 — 사실상 오픈소스 LLM 게이트웨이 표준

---

실전 1 — LiteLLM Proxy가 뭔지, 왜 필요한가

없을 때의 문제:

# API 키가 앱마다 분산
# OpenAI 쓰는 서비스
import openai
client = openai.OpenAI(api_key="sk-openai-...")

# Anthropic 쓰는 서비스
import anthropic
client = anthropic.Anthropic(api_key="sk-ant-...")

# 팀원 5명이 각자 API 키 가지고 있음
# 이번 달 얼마 썼는지 아무도 모름
# Claude가 429 에러 나도 GPT로 자동 전환 안 됨

LiteLLM Proxy 도입 후:

# 코드 한 줄만 바꿈
import openai
client = openai.OpenAI(
    base_url="http://your-proxy:4000",
    api_key="sk-virtual-key"  # 팀원별 가상 키
)

# 이제 어떤 모델이든 같은 코드로
response = client.chat.completions.create(
    model="claude-sonnet-4-6",  # 또는 gpt-5.4, gemini-2.5-pro
    messages=[{"role": "user", "content": "안녕"}]
)
# → 프록시가 Anthropic API 형식으로 자동 변환
# → 비용 자동 기록
# → Claude 실패 시 GPT로 자동 폴백

---

실전 2 — 프로덕션 배포: Docker Compose + PostgreSQL

⚠️ 먼저 보안 경고:

2026년 3월 24일, LiteLLM v1.82.7과 v1.82.8이 공급망 공격으로 악성코드가 포함된 채 PyPI에 배포됐습니다. 해당 버전들은 약 40분간 노출됐으며 자격증명 탈취 페이로드를 포함했습니다.

→ v1.82.7 또는 v1.82.8을 설치한 적 있다면 모든 API 키 즉시 교체
→ v1.83.0부터 Docker 이미지에 cosign 서명 적용
→ 절대 latest 태그 사용 금지 — 버전 반드시 고정

Step 1. 디렉토리 구성

mkdir litellm-proxy && cd litellm-proxy
touch config.yaml docker-compose.yml .env

Step 2. config.yaml 작성

# config.yaml
model_list:
  # Anthropic
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: anthropic/claude-sonnet-4-6
      api_key: os.environ/ANTHROPIC_API_KEY

  # OpenAI
  - model_name: gpt-5.4
    litellm_params:
      model: openai/gpt-5.4
      api_key: os.environ/OPENAI_API_KEY

  # Google
  - model_name: gemini-2.5-pro
    litellm_params:
      model: gemini/gemini-2.5-pro
      api_key: os.environ/GEMINI_API_KEY

# 폴백 라우팅
router_settings:
  routing_strategy: simple-shuffle
  allowed_fails: 3
  cooldown_time: 60
  fallbacks:
    - gpt-5.4: ["claude-sonnet-4-6", "gemini-2.5-pro"]
  context_window_fallbacks:
    - gpt-5.4-mini: ["gpt-5.4"]

# 일반 설정
litellm_settings:
  drop_params: true
  success_callback: ["langfuse"]  # 옵션: 모니터링 연동

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL
  store_model_in_db: true

Step 3. docker-compose.yml

# docker-compose.yml
services:
  litellm:
    # ⚠️ 버전 반드시 고정 — latest 금지
    image: ghcr.io/berriai/litellm:v1.85.0-stable
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml
    env_file:
      - .env
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: litellm
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

Step 4. .env 파일

# .env — 절대 git에 커밋 금지
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AIza...
LITELLM_MASTER_KEY=sk-master-...  # 관리자 키
POSTGRES_PASSWORD=your-strong-password
DATABASE_URL=postgresql://litellm:your-strong-password@postgres:5432/litellm

Step 5. 실행

docker compose up -d

# 확인
curl http://localhost:4000/health
# → {"status":"healthy","litellm_version":"1.85.0",...}

---

실전 3 — 가상 키(Virtual Keys)로 팀 접근 제어

프록시의 핵심 기능입니다. 실제 API 키는 프록시 서버만 알고, 팀원에게는 가상 키를 발급합니다.

가상 키 생성 (Admin UI 또는 API):

# 팀원용 가상 키 생성
curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-master-..." \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "backend-team",
    "models": ["claude-sonnet-4-6", "gpt-5.4"],
    "max_budget": 50.0,          # 월 $50 한도
    "budget_duration": "1mo",
    "tpm_limit": 100000,         # 분당 토큰 한도
    "rpm_limit": 100             # 분당 요청 한도
  }'

# 응답: {"key": "sk-vk-abc123...", "key_alias": "backend-team", ...}

팀별 예산 시나리오:

팀 월 예산 허용 모델 비고

백엔드	$50	Claude·GPT	프로덕션 서비스용
AI 연구팀	$200	전체 모델	실험·개발용
프론트엔드	$20	GPT-5.4-mini	가벼운 태스크
인턴	$5	Gemini Flash	학습용

---

실전 4 — 폴백 라우팅: 자동 장애 대응

router_settings:
  fallbacks:
    # gpt-5.4 실패 → claude → gemini 순으로 자동 시도
    - gpt-5.4: ["claude-sonnet-4-6", "gemini-2.5-pro"]

  context_window_fallbacks:
    # 컨텍스트 초과 시 더 큰 모델로 자동 업그레이드
    - gpt-5.4-mini: ["gpt-5.4"]

  content_policy_fallbacks:
    # Claude가 정책 거부 시 GPT로 자동 전환
    - claude-sonnet-4-6: ["gpt-5.4"]

실제 동작 예시:

요청: "claude-sonnet-4-6으로 이 작업 해줘"

1. claude-sonnet-4-6 → 429 에러 (레이트 리밋)
   → 자동 폴백 시작
2. gpt-5.4 시도
   → 성공
   
클라이언트: 에러 없이 응답 수신
로그: "fallback used: gpt-5.4 (reason: rate_limit)"

---

실전 5 — 비용 추적과 Admin UI

Admin UI 접속:

http://localhost:4000/ui
→ 기본 로그인: admin / master_key 값

대시보드에서 볼 수 있는 것들:

→ 팀·사용자별 일간/주간/월간 비용
→ 모델별 토큰 사용량과 비용
→ 요청 성공률·레이턴시
→ 예산 소진율 (알림 설정 가능)

API로 비용 조회:

# 전체 비용 현황
curl http://localhost:4000/spend/report \
  -H "Authorization: Bearer sk-master-..."

# 특정 키 사용량
curl http://localhost:4000/key/sk-vk-abc123/spend \
  -H "Authorization: Bearer sk-master-..."

Slack 알림 설정 (예산 80% 소진 시):

# config.yaml에 추가
litellm_settings:
  alerting: ["slack"]
  alerting_threshold: 0.8  # 예산 80% 소진 시 알림
  slack_webhook_url: os.environ/SLACK_WEBHOOK_URL

---

실전 6 — AI 코딩 툴(Claude Code·Cursor)도 프록시 경유

하나의 프록시로 모든 IDE 툴을 연결할 수 있습니다. 이를 통해 개발자별 AI 코딩 어시스턴트 사용 비용 추적, 특정 개발자가 실수로 $500어치를 소진하지 않도록 레이트 리밋 설정, 그리고 모델 전환을 한 곳에서 관리할 수 있습니다.

Claude Code 연동:

# ~/.claude/settings.json
{
  "api_key": "sk-vk-your-virtual-key",
  "base_url": "http://your-proxy:4000"
}

Cursor 연동:

Cursor → Settings → AI → OpenAI API Base URL
→ http://your-proxy:4000 입력
→ API Key: 가상 키 입력
→ Model: claude-sonnet-4-6 또는 gpt-5.4

→ 이제 팀 전체 IDE 사용량이 Admin UI에 한 번에 집계됨

---

실전 7 — 보안 운영 체크리스트

2026년 공급망 사고 이후 필수 항목입니다.

✅ Docker 이미지 버전 고정 (latest 절대 금지)
✅ .env 파일 .gitignore에 추가
✅ config.yaml에 API 키 직접 입력 금지 (os.environ/ 참조 사용)
✅ 마스터 키와 가상 키 분리 운영
✅ PostgreSQL 비밀번호 강도 확인
✅ 프록시 포트(4000) 외부 노출 금지 — 내부 네트워크만
✅ 정기 버전 업그레이드 + 보안 공지 구독 (https://docs.litellm.ai/blog)
✅ v1.83.0+ 버전에서 cosign 서명 검증 활성화

버전 업그레이드 전 확인:

# 현재 버전 확인
curl http://localhost:4000/ | grep version

# 보안 공지 확인 후 업그레이드
docker compose pull
docker compose up -d

---

✅ 도입해야 하는 경우 / ❌ 오버엔지니어링인 경우

✅ 도입 권장 ❌ 일단 패스

팀원 2명 이상이 LLM API 직접 사용	혼자 개발하고 월 비용 $30 이하
월 LLM 비용 $100 이상	단일 모델(Claude만 또는 GPT만)만 사용
여러 모델을 서비스에서 동시에 사용	앱이 아직 프로토타입 단계
프로바이더 장애 시 자동 폴백 필요	팀에 Docker 운영 경험 없는 경우 (학습 비용 있음)
팀별 API 접근 권한 분리 필요

---