다중 LLM 키·라우팅 지옥 끝낸 LiteLLM 2.x AI Gateway

Ⅰ. LiteLLM 기술이란?

 ⅰ. 기존 방식(제공자별 SDK 직접 호출)의 한계

2023년만 해도 OpenAI 하나만 잘 다루면 됐습니다. 2024~2025년을 거치며 Anthropic Claude, Together, Fireworks, DeepSeek, AWS Bedrock(Claude·Llama·Mistral·Nova), Vertex(Gemini), Azure OpenAI, Groq,  Qwen이 동시에 운영 자산이 됐습니다. 여기서 6가지 운영 통증이 반복됩니다.

 1) SDK 분열 : openai-python, anthropic, boto3, google-genai, mistralai… 각자 응답 스키마·예외 클래스·스트리밍 포맷이 다르다. 같은 “429 too many requests”도 SDK마다 예외 타입이 다릅니다.

 2) 키·시크릿 관리 : 제공자 5개 × 환경 3개 × 팀 10개 = 150쌍의 키. 회수·로테이션이 사람 손으로 가면 사고 시간 문제입니다.

 3) 요금/사용량 추적 — 누가, 어떤 모델로, 몇 토큰 썼는지 팀별·기능별로 알려면 SDK 호출마다 사이드카로 로그를 박아야 합니다.

 4) 레이트리밋 폭주 — 한 팀의 배치 잡이 OpenAI TPM 한도를 다 먹으면 사내 다른 서비스가 모두 429. 우선순위 큐가 없습니다.

 5) 폴백 없음 — Anthropic 장애 시 Bedrock Anthropic으로 갈아타는 로직을 매 서비스가 자기 코드에 박습니다.

 6) 거버넌스/감사 — PII 마스킹, 프롬프트 인젝션 차단, 출력 검열 같은 정책이 서비스마다 따로 박혀 있어 일관성이 없습니다.

 

 ⅱ. 기술 정의

 BerriAI가 개발하는 OpenAI 호환 LLM 게이트웨이/프록시다. SDK 모드(라이브러리)와 Proxy 모드(독립 서버) 두 가지로 쓰며, 2026년 현장은 거의 Proxy 모드가 표준입니다. 모든 제공자 호출이 /v1/chat/completions · /v1/embeddings · /v1/responses 같은 OpenAI 호환 엔드포인트로 통일되고, 내부에서 모델명에 따라 적절한 제공자 SDK로 변환·호출·정규화합니다. 2.x에서는 가상키(Virtual Key)·예산(Budget)·태그 라우팅·Prometheus 메트릭·Guardrail 훅·MCP 도구 프록시·Responses API 호환이 1급 시민으로 들어왔습니다.

Ⅱ. LiteLLM 기술 특징

속성	설명
인터페이스	제공자 100+개를 OpenAI 호환 단일 스키마로 통합. 기존 OpenAI SDK 그대로 base_url만 바꿔 모든 모델 호출 가능.
지원 제공자	OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, GCP Vertex, Mistral, Cohere, Groq, Together, Fireworks, DeepSeek, Qwen/DashScope, Ollama, vLLM/SGLang 자체 호스팅, HuggingFace TGI 등.
가상키(Virtual Key)	실 제공자 키 대신 팀/사용자/서비스별 가상키를 발급. 모델 화이트리스트·예산·RPM/TPM·만료일을 키 자체에 묶어 발급.
라우팅 전략	가중치, 최소 latency, 최저 비용, Usage-based(TPM/RPM 남는 노드 우선), Tag 기반(prod-only, region-eu) 라우팅 지원.
자동 폴백	제공자 장애·429·5xx 발생 시 사전 정의된 fallback model 리스트로 자동 재시도. 헤더에 시도 이력 기록.
요금/예산	모든 요청에 토큰·비용 산정. 키·팀·태그 단위 누적 비용을 Postgres에 기록하고 한도 초과 시 자동 차단.
관측성	Prometheus 메트릭(latency p95/p99, error rate by model), 로그 콜백(Langfuse, Helicone, Datadog, S3, OTLP, Slack).
가드레일	Presidio PII 마스킹, Lakera/Aporia/Bedrock Guardrails, 프롬프트 인젝션 탐지, 출력 검열 훅을 pre/post 단계에 끼움.
캐싱	Redis/Qdrant/S3 기반 응답 캐시. 의미론적(semantic) 캐시 옵션. Anthropic prompt caching·OpenAI cached input은 패스스루 헤더로 보존.
MCP 프록시	2.x 신규. Model Context Protocol 도구 서버를 게이트웨이가 등록·중계해 어떤 모델이든 동일 도구를 쓰게 만든다.
배포	도커 단일 컨테이너, Helm 차트, Postgres + Redis만 있으면 동작. 무상태 워커 N대로 수평 확장.
라이선스	코어 MIT(완전 OSS), Enterprise 기능(SSO/SCIM, JWT auth, Audit Log, 고급 가드레일)은 별도 라이선스. 자체 호스팅 가능.

Ⅲ. LiteLLM 기술 동작방식

 ⅰ. 구성 요소

• Proxy Server(Uvicorn/FastAPI) — OpenAI 호환 HTTP 엔드포인트. 다중 워커, 무상태. RPS 수천 처리.
• Router — 모델 그룹(예: gpt-4o-mini)에 매핑된 여러 deployment(Azure 리전 A, Azure 리전 B, OpenAI 본가) 중 하나를 선택. 헬스체크·쿨다운·폴백 책임.
• Virtual Key Store(Postgres) — 가상키, 팀, 사용자, 예산, 사용량 누적치 저장. 모든 요청 인증의 1차 진입점.
• Cost Tracker — 응답 토큰 × 제공자 가격표(model_cost.json)로 비용 산정. 캐시 hit는 별도 단가.
• Cache Layer(Redis) — exact-match 또는 semantic 응답 캐시. TTL·키 스코프 설정 가능.
• Callback Hooks — 요청 시작/완료/실패 시점에 사용자 정의 함수·외부 SaaS로 비동기 전송. 로깅·과금·감사 라인을 분리.
• Guardrail Adapters — 호출 전/후에 PII 마스킹·인젝션 탐지·출력 검열을 끼우는 플러그인.
• Admin UI(Next.js) — 키 발급, 사용량 대시보드, 모델/팀 관리 GUI. 2.x에서 큰 폭으로 개선.

 ⅱ. 데이터 흐름 (chat completion 한 번을 추적)

• 클라이언트가 OpenAI SDK로 POST /v1/chat/completions 호출. Authorization: Bearer sk-...(가상키).
• Proxy가 가상키 검증 → 팀·예산·모델 화이트리스트·RPM/TPM 통과 여부 확인.
• Pre-call hook 동작 — PII 마스킹, 인젝션 검사, 캐시 조회. 캐시 hit면 즉시 응답.
• Router가 모델 그룹에서 deployment 선택 — 라운드로빈/가중치/usage-based.
• 제공자 SDK 호출. 스트리밍이면 text/event-stream 청크를 그대로 패스스루(중간에 토큰 카운팅).
• 429/5xx면 라우터가 다음 deployment 또는 fallback model로 재시도. x-litellm-attempted-fallbacks 헤더에 이력.
• Post-call hook — 출력 검열, 비용 산정, 사용량 카운터 증분(Postgres + Redis), Langfuse/Datadog 비동기 전송.
• 응답 정규화(OpenAI 스키마)해서 클라이언트에 반환. 모든 단계의 latency가 Prometheus에 기록.

Ⅳ. LiteLLM 기술 구성 및 흐름도

 ⅰ. 단계별 설명

1. 인증 — 가상키 → 팀/사용자 매핑, 만료/예산/모델 권한 검사.
2. 전처리 — PII 마스킹, 인젝션 가드, 캐시 조회.
3. 라우팅 — 모델 그룹에서 deployment 선택(가중치/usage-based/태그).
4. 호출 — 제공자 SDK로 변환, 스트리밍 청크 패스스루.
5. 실패 처리 — 동일 그룹 내 다음 deployment, 그래도 실패면 fallback model.
6. 후처리 — 출력 검열, 토큰·비용 계산, 사용량 누적, 콜백 전송.
7. 응답 — OpenAI 호환 스키마로 정규화, 메트릭 기록.

 ⅱ. 실제 처리 흐름

Ⅴ. LiteLLM 기술 설치 방법

 ⅰ. Docker 단독 (개발/PoC)

# 최신 안정 태그 사용 (2026-05 기준 v1.x 라인은 v1, 2.x preview는 main-stable)
docker run --rm -d \
  --name litellm \
  -p 4000:4000 \
  -e LITELLM_MASTER_KEY="sk-master-rotate-me" \
  -e OPENAI_API_KEY="sk-..." \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e DATABASE_URL="postgresql://litellm:pw@db:5432/litellm" \
  -v $(pwd)/config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml --port 4000

 ⅱ. Helm (운영 권장)

helm repo add litellm https://berriai.github.io/litellm-helm
helm repo update

helm upgrade --install litellm litellm/litellm \
  -n litellm --create-namespace \
  -f values.yaml \
  --set masterkeySecretName=litellm-master \
  --set db.deployStandalone=false \
  --set db.useExisting=true \
  --set db.endpoint=postgres-ha.svc:5432 \
  --set redis.useExisting=true \
  --set replicaCount=4

아키텍처 시사점 — Proxy는 완전 무상태입니다. Postgres와 Redis만 HA로 잡고 워커는 HPA로 트래픽 따라 늘리면 끝입니다.
다만 가상키 정보가 Redis 캐시되므로 키 회수 시 TTL 안에 모든 워커가 인지하도록 -polling-interval을 짧게 잡습니다.

Ⅵ. LiteLLM 기술 사용방법

 ⅰ. 코드 / 설정 — config.yaml

model_list:
  - model_name: gpt-4o            # 클라이언트가 부르는 가상 모델명
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
      rpm: 5000
      tpm: 2000000
    model_info:
      mode: chat

  - model_name: gpt-4o            # 같은 그룹에 Azure 추가 = 자동 로드밸런싱
    litellm_params:
      model: azure/gpt-4o
      api_base: https://my-eu.openai.azure.com/
      api_key: os.environ/AZURE_OPENAI_API_KEY
      api_version: "2025-04-01-preview"
      weight: 2

  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-3-7-sonnet-latest
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: claude-sonnet     # Bedrock fallback (IAM 역할 사용)
    litellm_params:
      model: bedrock/anthropic.claude-3-7-sonnet-20250219-v1:0
      aws_region_name: us-west-2

router_settings:
  routing_strategy: usage-based-routing-v2   # TPM/RPM 남는 deployment 우선
  num_retries: 2
  timeout: 30
  fallbacks:
    - { "gpt-4o": ["claude-sonnet"] }        # OpenAI 죽으면 Anthropic으로
    - { "claude-sonnet": ["gpt-4o"] }
  context_window_fallbacks:
    - { "gpt-4o": ["claude-sonnet"] }        # context 초과 시 큰 모델로
  cooldown_time: 60

litellm_settings:
  drop_params: true                          # 제공자가 모르는 파라미터 자동 drop
  set_verbose: false
  cache: true
  cache_params:
    type: redis
    host: redis.svc
    ttl: 600
  callbacks: ["langfuse", "prometheus"]
  guardrails:
    - guardrail_name: "pii-mask"
      litellm_params:
        guardrail: presidio
        mode: pre_call

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL
  alerting: ["slack"]
  alert_types: ["budget_alerts", "outage_alerts", "llm_too_slow"]

 ⅱ. 클라이언트는 그냥 OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://llm-gw.internal/v1",
    api_key="sk-virt-team-payments-...",   # 가상키 (실제 OpenAI 키 아님)
)

resp = client.chat.completions.create(
    model="gpt-4o",                         # 모델 그룹 이름
    messages=[{"role":"user","content":"한 문장으로 인사"}],
    extra_headers={"x-tags": "service=checkout,env=prod"},   # 태그 라우팅용
)
print(resp.choices[0].message.content)

 ※ 운영 시 고려사항

• 가상키는 만료·예산을 반드시 같이 — 개발 환경 키가 1년짜리 영구로 발급되면 사고 시 회수 불가. duration: 30d 기본 정책 권장.
• 모델 그룹은 의미 단위로 — “gpt-4o”라는 그룹 안에 OpenAI/Azure를 같이 두면 클라이언트는 한 모델로 부르고 운영은 무중단 전환 가능.
• 스트리밍은 stream_options.include_usage=true — 그래야 마지막 청크에 usage가 들어와 비용 산정이 정확.
• Postgres·Redis 분리 — 같은 인스턴스에 박으면 캐시 폭주가 사용량 기록까지 막는다.
• master key는 KMS 보관 — master로 무한 권한 가상키를 발급할 수 있다. 회수는 /key/regenerate로 즉시.
• Anthropic prompt caching은 extra_headers·메시지 cache_control 블록을 그대로 패스스루해야 한다. 클라이언트가 보낸 캐시 컨트롤을 게이트웨이가 제거하면 캐시 적중이 사라진다.

Ⅶ. LiteLLM 기술 자주 쓰는 명령어

명령 / API	설명 · 사례
litellm --config config.yaml --port 4000	로컬 실행. --detailed_debug는 인증/라우팅 결정 로그까지 표시.
curl -X POST $GW/key/generate -H "Authorization: Bearer $MASTER" -d '{...}'	가상키 발급. models, max_budget, budget_duration, rpm_limit, duration, team_id, tags 지정.
curl -X POST $GW/key/regenerate -d '{"key":"sk-virt-..."}'	키 즉시 회전. 새 secret 반환, 옛 secret은 즉시 폐기.
curl -X POST $GW/team/new -d '{"team_alias":"payments","max_budget":500}'	팀 생성. 팀 단위 누적 예산·모델 권한.
curl $GW/global/spend/report?start_date=2026-05-01	기간별 비용 보고. group_by=team|model|tag.
curl $GW/model/info	로드된 모델 그룹·deployment·헬스 상태 확인.
curl $GW/health/readiness	K8s readinessProbe 용. /health/liveliness와 분리.
curl $GW/cache/flushall	Redis 캐시 전수 무효화. 가격표·시스템 프롬프트 바뀐 직후 1회.
curl -X POST $GW/v1/chat/completions -H "x-litellm-fallbacks: claude-sonnet,gpt-4o"	요청별 폴백 오버라이드. 글로벌 설정 대신 호출 시점 지정.
litellm-proxy migrate	버전 업그레이드 시 Postgres 스키마 마이그레이션. 업그레이드 직전 필수.

Ⅷ. LiteLLM 기술 활용 방안

ⅰ. 활용 사례

• 사내 단일 LLM 엔드포인트 — 모든 서비스가 https://llm-gw.internal/v1 하나만 알면 되는 구조. 키 회수·모델 교체가 단일 지점.
• 리전 페일오버 — Azure East US 죽으면 Azure West Europe로 자동 전환, 그래도 안 되면 OpenAI 본가로 폴백.
• 비용 거버넌스 — 팀별 월 예산, 초과 시 자동 차단·Slack 알림. CFO가 보는 비용 리포트가 게이트웨이 하나에서 나옴.
• 실험 트래픽 분기 — weight로 신규 모델에 5%만 흘리고 latency/품질 비교. 가중치만 바꾸면 끝.
• RAG 파이프라인 표준화 — 임베딩도 동일 게이트웨이로 통일. /v1/embeddings 호출 한 가지로 OpenAI text-embedding-3, Voyage, Cohere 모두 호환.
• MCP 도구 중계 — 2.x에서 게이트웨이가 MCP 서버를 등록해 두면 어떤 모델이든 동일 도구 세트를 호출. 도구 정의 분열 해소.
• 온프레 모델 통합 — 자체 vLLM/SGLang/Ollama 인스턴스도 OpenAI 호환 deployment로 등록. 클라이언트 코드는 SaaS 모델과 동일.

 ⅱ. 대안 기술 비교

도구	특징	강점	약점/고려
LiteLLM 2.x	OSS 게이트웨이, 자체 호스팅	제공자 100+개, 가상키·예산·폴백 1급	오버헤드 5~15ms, 운영 책임 자기 몫
OpenRouter	SaaS, 통합 빌링	가입 즉시 사용, 모델 카탈로그 풍부	외부 의존, PII 전송, 사용량 모두 OpenRouter 경유
Portkey	SaaS + OSS 코어	가드레일·관측성 잘 다듬어짐	고급 기능 SaaS 종속, 가격
Helicone	관측성 중심 게이트웨이	로그/분석 강력	라우팅·폴백은 LiteLLM 대비 약함
Cloudflare AI Gateway	CDN 엣지 프록시	지연 시간 좋음, 캐싱·레이트리밋 견고	가상키·팀 거버넌스 약함, 정책 표현력 제한
Kong AI Gateway	API GW 위 플러그인	기존 Kong 운영팀에게 자연스러움	LLM 전용 기능(prompt caching·token cost)은 후발
직접 구현	FastAPI + httpx	완전한 통제	요금표·모델 카탈로그·폴백을 매주 업데이트해야 함

※ 언제 쓰면 안 되는지

• 단일 제공자만 영구히 쓰는 경우 : OpenAI만 평생 쓰는 작은 팀이면 게이트웨이 운영 비용이 이득보다 큼. 그냥 SDK 직접.
• μs 단위 레이턴시가 SLA : 음성 실시간 합성처럼 5~15ms 오버헤드도 부담이면 사이드카(같은 노드 Unix socket) 구성이거나 SDK 모드를 검토.
• 제공자 고유 SDK 기능을 깊게 쓰는 코드 : Anthropic Computer Use, OpenAI Realtime WebSocket, Vertex Live API 같은 비-OpenAI-호환 기능은 게이트웨이가 못 따라가는 경우가 있다. 해당 경로만 SDK 직접, 나머지만 게이트웨이.
• 완전 오프라인 환경 : 게이트웨이만 두고 모델이 외부면 의미 없다. 자체 호스팅 모델만 쓰는 환경에선 vLLM·SGLang 라우터 자체가 충분할 수도.
• 한 개 키만 있고 팀 분리 필요 없을 때 : 가상키·예산이 핵심 가치인데 그걸 안 쓰면 가져올 게 캐싱 정도뿐. 가성비가 떨어진다.

Ⅸ. LiteLLM 기술 트러블 슈팅

증상	원인	해결
스트리밍 마지막에 usage가 안 들어와 비용이 0으로 기록됨	클라이언트가 stream=true만 보내고 stream_options.include_usage를 안 보냄. OpenAI 호환 SDK 일부 구버전은 기본값이 false.	게이트웨이 측 litellm_settings.force_include_usage: true 옵션을 켜면 누락된 요청에도 강제로 추가한다. 또는 SDK 업그레이드. 누락된 과거 데이터는 /cost/recalculate로 응답 토큰 기반 추정 재계산 가능.
콜백(Langfuse/Slack) 외부 SaaS가 느려져 응답 latency가 200ms→3s로 튐	콜백을 동기로 처리하던 구간이 있거나 콜백 큐가 backpressure 없이 메인 루프를 막음.	litellm_settings.async_logging: true + callback_settings.max_queue: 10000. 큐가 가득 차면 콜백을 drop하고 메인 응답은 보호. Prometheus의 litellm_callback_queue_size를 알람 걸어라.
Bedrock 호출만 403 — 키 넣었는데 안 됨	Bedrock는 API 키가 아니라 IAM이다. api_key 박지 말고 IRSA(EKS)·인스턴스 프로파일·aws_access_key_id/secret_access_key로 자격 증명, aws_region_name 명시.	litellm_params: {aws_region_name: us-west-2}만 두고 자격 증명은 IRSA. 또한 모델 ARN(arn:aws:bedrock:...:inference-profile/...)을 쓰면 cross-region inference로 throttle 회피.
모델 deprecation으로 운영 중단 “gpt-4o-2024-05-13 not found”	코드에 모델 버전을 박았는데 제공자가 sunset.	config.yaml의 model_name(가상명)과 litellm_params.model(실 모델)을 분리해 클라이언트는 “gpt-4o”만 알게 만든다. 실 모델 교체는 운영자가 config 한 줄 바꾸고 reload. model_alias_map으로 한시적 호환도 가능.
Anthropic 캐시 적중률이 게이트웨이 거치면 30%→0%	게이트웨이가 메시지를 정규화하면서 cache_control 블록을 strip하거나 시스템 프롬프트 순서를 바꿈.	litellm_settings.drop_params: true지만 safe_drop_params: ["cache_control"]로 예외. 또한 litellm_settings.add_function_to_prompt: false로 추가 변형 차단. 검증은 x-anthropic-cache-control-hit 응답 헤더.
가상키 회수했는데 30~60초 동안 계속 통과	워커별 in-process key cache TTL이 길게 잡혀 있음.	general_settings.user_api_key_cache_ttl: 5(초)로 단축. 즉시 회수가 필요하면 /key/regenerate가 아니라 /key/block으로 차단 후 /cache/flushall 호출. 멀티 워커 환경에서는 Redis pub/sub 무효화 채널(litellm_settings.cache_invalidation_pubsub: true)을 켜라.

Ⅹ. LiteLLM 기술 아키텍처 시사점

 ⅰ. 게이트웨이는 지능이 아닌 스위치 : 모델 선택 로직은 단순할수록 좋음. usage-based + weight 두 개면 대부분 해결

 ⅱ. 가상키 = OAuth refresh token처럼 다루세요 : 짧은 만료 + 회수 가능 + 감사 로그 필수.

 ⅲ. 폴백은 품질이 비슷한 모델 사이에서만 :  가격·품질 갭이 크면 사용자가 모르게 열화된 답

 ⅳ. 캐시 정책은 응답이 결정적인 시스템 프롬프트에만 temperature>0 챗봇 응답을 캐시하면 디버깅 지옥

 ⅴ. 게이트웨이 자체는 SLO 별도 관리. 99.95% 미만이면 게이트웨이가 곧 SPOF. multi-AZ + 헬스체크 + 클라이언트 측 1단계 폴백을 고려