LiteLLM 완벽 가이드 — 100+ LLM을 OpenAI API로 통합, 프록시·라우팅·비용 관리

· 22분 읽기 · 수정 중급 실습
LiteLLM 완벽 가이드 — 100+ LLM을 OpenAI API로 통합, 프록시·라우팅·비용 관리

이 글의 핵심

LiteLLM은 OpenAI SDK 호환 인터페이스로 GPT-4/Claude/Gemini/Llama 등 100+ LLM을 통합하는 오픈소스 게이트웨이입니다. 팀 키 발급·사용량 과금·지능형 라우팅·Fallback·캐싱·관측을 코드 변경 없이 얻을 수 있어 AI 제품을 벤더 중립으로 운영하는 표준이 되고 있습니다. 이 글은 SDK/Proxy 설치·라우팅 전략·비용 관리·프로덕션 배포까지 정리합니다.

이 글의 핵심

LiteLLM은 OpenAI SDK와 완전 동일한 인터페이스로 GPT-4o / Claude 3.5 / Gemini 1.5 / Llama 3 / Mistral / Cohere / Bedrock / Azure OpenAI / Groq / Together / Fireworks / Ollama 등 100여 개 LLM을 호출할 수 있게 해주는 오픈소스 게이트웨이입니다.

두 가지 사용 형태가 있습니다.

  1. Python SDK: import litellm으로 직접 호출
  2. Proxy Gateway: 별도 서비스로 띄워 OpenAI API 호환 엔드포인트 제공

엔터프라이즈는 Proxy 모드로 팀별 키·사용량 추적·비용 한도·감사 로그를 얻고, 개인/단일 서비스는 SDK만으로도 벤더 중립·Fallback·A/B 테스트 이점을 즉시 누립니다.

설치

SDK (파이썬)

pip install "litellm[proxy]"

Proxy (Docker)

docker run -d \
  --name litellm \
  -p 4000:4000 \
  -e LITELLM_MASTER_KEY=sk-master-... \
  -e DATABASE_URL=postgresql://... \
  -v $(pwd)/config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm-database:main-stable \
  --config /app/config.yaml

Helm (K8s)

helm repo add litellm https://berriai.github.io/litellm/
helm install litellm litellm/litellm --values values.yaml

첫 호출: OpenAI SDK가 그대로 동작

from litellm import completion
import os

os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..."
os.environ["GEMINI_API_KEY"] = "..."

# GPT-4o
r = completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "2026년 핫한 블루오션 SaaS 아이디어 3가지"}],
)
print(r.choices[0].message.content)

# Claude 3.5 Sonnet (단지 model만 바꿈)
r = completion(
    model="claude-3-5-sonnet-20241022",
    messages=[{"role": "user", "content": "위 아이디어 중 하나를 PRD로 써줘"}],
)

# Gemini
r = completion(
    model="gemini/gemini-1.5-pro-latest",
    messages=[{"role": "user", "content": "한국 시장 맞춤 피처 10개"}],
)

# Ollama (로컬)
r = completion(
    model="ollama/llama3.1",
    messages=[{"role": "user", "content": "위 PRD 영어로 번역"}],
    api_base="http://localhost:11434",
)

응답 포맷은 모두 OpenAI ChatCompletion 객체로 통일됩니다. 코드 변경 없이 모델만 교체할 수 있는 것이 핵심 가치입니다.

Streaming

from litellm import completion

stream = completion(
    model="claude-3-5-sonnet-20241022",
    messages=[{"role": "user", "content": "쉽게 설명해줘: Merkle Tree"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Anthropic/Gemini의 네이티브 스트리밍 이벤트를 OpenAI SSE 포맷으로 정규화해 내보냅니다. 프론트엔드 SSE 소비 코드를 재사용할 수 있습니다.

Fallback: 한 provider 장애에도 서비스 유지

from litellm import completion

response = completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    fallbacks=[
        "claude-3-5-sonnet-20241022",
        "gemini/gemini-1.5-pro-latest",
    ],
    num_retries=3,
)

OpenAI가 timeout/500을 내면 자동으로 Claude → Gemini 순으로 재시도합니다. SLA 달성을 위한 Multi-provider 전략이 몇 줄로 구현됩니다.

타임아웃·재시도

completion(
    model="gpt-4o",
    messages=[...],
    timeout=30,                   # 30초
    num_retries=3,                # 지수 백오프 재시도
    retry_strategy="exponential_backoff_retry",
)

Proxy Gateway: 팀 공유 환경의 필수

config.yaml

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
      rpm: 1000
      tpm: 60000

  - model_name: claude-sonnet
    litellm_params:
      model: claude-3-5-sonnet-20241022
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: llama-local
    litellm_params:
      model: ollama/llama3.1
      api_base: http://ollama.internal:11434

router_settings:
  routing_strategy: latency-based-routing
  fallbacks:
    - gpt-4o: [claude-sonnet, llama-local]

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

litellm_settings:
  set_verbose: false
  cache: true
  cache_params:
    type: redis
    host: redis.internal
    port: 6379
  success_callback: ["langsmith", "prometheus"]
  failure_callback: ["sentry"]
  max_budget: 1000   # USD
  budget_duration: 30d

실행

litellm --config config.yaml --port 4000

클라이언트는 OpenAI SDK 그대로

from openai import OpenAI

client = OpenAI(
    api_key="sk-team-key-...",    # LiteLLM이 발급한 팀 키
    base_url="http://litellm.internal:4000/v1",
)

r = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "..."}],
)

클라이언트 코드 관점에서 완전히 투명하게 LiteLLM을 통하게 됩니다.

팀 키 발급 + 비용 한도

curl -X POST http://litellm:4000/key/generate \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "team-growth",
    "models": ["gpt-4o", "claude-sonnet"],
    "max_budget": 100,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "tpm_limit": 10000,
    "metadata": {"team": "growth", "env": "prod"}
  }'
  • 팀/사용자/프로젝트별로 키 발급
  • 사용량 누적 달러 집계 (공식 단가표 기반)
  • 분당·분당 토큰 한도 설정
  • 메타데이터로 비용 리포트 그룹핑

관리자 UI(/ui)에서 실시간 사용량·모델별 분포·지연 시간·오류율을 확인할 수 있습니다.

지능형 라우팅

1. 지연 시간 기반

router_settings:
  routing_strategy: latency-based-routing

여러 배포(Azure OpenAI 여러 리전, OpenAI+Azure 혼용)의 최근 p95 지연 시간을 측정해 가장 빠른 인스턴스로 라우팅.

2. 가용성 기반

router_settings:
  routing_strategy: usage-based-routing-v2

rate limit이 남은 배포를 우선 선택. 여러 Azure 리소스를 합친 “큰 한 개 풀”처럼 동작.

3. 가중치 기반 (카나리·A/B)

model_list:
  - model_name: chat-model
    litellm_params:
      model: openai/gpt-4o
    model_info:
      weight: 90

  - model_name: chat-model
    litellm_params:
      model: claude-3-5-sonnet-20241022
    model_info:
      weight: 10

“chat-model”을 호출하면 90%는 GPT-4o, 10%는 Claude로 라우팅. 품질 비교 실험에 유용.

4. 가격 기반

router_settings:
  routing_strategy: cost-based-routing

가장 저렴한 모델을 선택 (최소 품질 조건은 별도 fallback 체인으로 관리).

캐싱

litellm_settings:
  cache: true
  cache_params:
    type: redis
    host: redis
    port: 6379
    ttl: 600
    similarity_threshold: 0.95   # semantic caching (임베딩 기반)
  • Exact caching: 동일 프롬프트·파라미터의 응답 재사용
  • Semantic caching: 임베딩 유사도 0.95 이상이면 캐시 히트
  • 지원 백엔드: Redis, S3, Local, Qdrant, DynamoDB

프론트엔드 질문 중 자주 묻는 것들은 캐시로 비용을 80% 절감하는 일이 흔합니다.

관측: 로그·메트릭·트레이스

litellm_settings:
  success_callback:
    - langsmith
    - langfuse
    - prometheus
    - datadog
    - helicone
  failure_callback:
    - sentry
    - slack

Prometheus 메트릭 예시 (/metrics 엔드포인트):

  • litellm_requests_total{model, status}
  • litellm_latency_seconds{model}
  • litellm_tokens_used{model, type=input|output}
  • litellm_spend_total{model, team}

Grafana 대시보드 템플릿이 공식 저장소에 포함되어 있어 바로 import할 수 있습니다.

비용 최적화 전략

1. 모델 계층화

간단 분류/라우팅 → gpt-4o-mini, claude-haiku, gemini-1.5-flash
복잡 reasoning → gpt-4o, claude-sonnet, gemini-1.5-pro
매우 어려운 추론 → o1, claude-opus (fallback 전용)

2. 프롬프트 캐시 활용

Claude와 OpenAI는 system 프롬프트 캐시를 지원합니다. LiteLLM은 provider별 캐시 파라미터를 통합해 전달합니다.

completion(
    model="claude-3-5-sonnet-20241022",
    messages=[...],
    extra_headers={"anthropic-beta": "prompt-caching-2024-07-31"},
    cache_control={"type": "ephemeral"},
)

3. 배치 API

OpenAI/Anthropic의 배치 API로 50% 할인 가격에 비실시간 작업 처리:

from litellm import abatch_completion

results = await abatch_completion(
    model="gpt-4o",
    messages_list=[...],  # 수천 개
    batch=True,           # 24시간 이내 완료, 50% 할인
)

4. tokenizer 기반 예산 체크

from litellm import token_counter

tokens = token_counter(model="gpt-4o", messages=messages)
if tokens > 10000:
    raise ValueError("프롬프트가 너무 깁니다. 청크 분할 필요.")

구조화 출력 (Structured Outputs)

from pydantic import BaseModel
from litellm import completion

class Person(BaseModel):
    name: str
    age: int
    skills: list[str]

r = completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "예시 인물 데이터 생성"}],
    response_format=Person,
)

person = Person.model_validate_json(r.choices[0].message.content)

OpenAI/Anthropic/Gemini 전반에서 JSON Schema 기반 구조화 응답을 얻을 수 있게 정규화합니다.

함수 호출 (Tool Use)

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "날씨 조회",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

r = completion(
    model="claude-3-5-sonnet-20241022",
    messages=[{"role": "user", "content": "서울 날씨 알려줘"}],
    tools=tools,
)

tool_call = r.choices[0].message.tool_calls[0]

Anthropic의 tool_use·Gemini의 function_call·OpenAI tool_calls를 모두 OpenAI tool_calls 포맷으로 통일합니다.

프로덕션 배포 패턴

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: litellm
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: litellm
          image: ghcr.io/berriai/litellm-database:main-stable
          args: ["--config", "/config/config.yaml"]
          envFrom:
            - secretRef: {name: litellm-secrets}
          resources:
            requests: {memory: 512Mi, cpu: 200m}
            limits: {memory: 2Gi, cpu: 2}
          livenessProbe:
            httpGet: {path: /health/liveliness, port: 4000}
          readinessProbe:
            httpGet: {path: /health/readiness, port: 4000}
          volumeMounts:
            - {name: config, mountPath: /config}
      volumes:
        - name: config
          configMap: {name: litellm-config}

3 replicas 이상 + HPA로 자동 확장, Redis 캐시 공유, Postgres로 키·사용량 영속.

Docker Compose

services:
  litellm:
    image: ghcr.io/berriai/litellm-database:main-stable
    ports: ["4000:4000"]
    env_file: .env
    volumes: ["./config.yaml:/app/config.yaml"]
    command: ["--config", "/app/config.yaml"]
    depends_on: [postgres, redis]

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes: ["pg:/var/lib/postgresql/data"]

  redis:
    image: redis:7

volumes:
  pg:

보안 체크리스트

  • LITELLM_MASTER_KEY는 환경변수·Vault에만 저장
  • 팀 키는 최소 권한 (허용 모델·금액 한도·만료)
  • HTTPS 앞단 (nginx/Cloudflare) 필수
  • DB/Redis는 내부망·TLS
  • PII 마스킹 콜백(success_callback 이전 단계) 설정
  • 프롬프트 주입 방지: 시스템 프롬프트 누출 대비 content filter
  • 로깅 시 API 키 redaction (기본 적용)

트러블슈팅

Provider별 예외 처리

try:
    r = completion(model="gpt-4o", messages=[...])
except litellm.exceptions.AuthenticationError as e:
    # 401
except litellm.exceptions.RateLimitError as e:
    # 429
except litellm.exceptions.ContentPolicyViolationError as e:
    # 안전 필터 거부

OpenAI/Anthropic/Gemini의 서로 다른 에러 코드를 통일된 예외 계층으로 매핑합니다.

Token mismatch

OpenAI의 tiktoken vs Anthropic의 자체 tokenizer 차이로 max_tokens 설정이 다를 수 있음. LiteLLM은 모델별 정확한 tokenizer를 사용하므로 token_counter를 신뢰해도 됩니다.

Gemini 응답 필드 누락

Gemini는 content filter로 내용이 비어 있을 수 있음. r.choices[0].finish_reason == "content_filter"를 체크.

함수 호출 포맷 불일치

같은 tools 스펙이라도 Claude·Gemini·OpenAI 각각 미묘한 파라미터 포맷 차이가 있습니다. response_format과 tools는 LiteLLM이 정규화하지만, 각 provider의 test를 CI에 포함해 회귀를 잡으세요.

마무리

AI 제품을 만들 때 초기엔 단일 벤더(OpenAI)로 시작하는 게 간단합니다. 그러나 성장하면서 비용·가용성·벤더 락인·규제·지역이라는 다섯 가지 축에서 반드시 Multi-provider 전략이 필요해집니다. LiteLLM은 이를 코드 변경 없이 해결하는 업계 표준 선택지이며, GitHub 스타 14k+·수많은 AI 스타트업이 이미 Proxy 모드로 배포 중입니다. 오늘 pip install litellm + 10줄 코드로 Multi-LLM 생산성을 즉시 얻을 수 있으니, 다음 AI 기능 PR에 한번 시도해보세요.

관련 글

  • OpenAI API 완벽 가이드
  • Claude API 완벽 가이드
  • Ollama 완벽 가이드
  • LangChain 완벽 가이드