벤더 락인 방지와 비용 최적화를 위한 LLM 게이트웨이, LiteLLM

AI Infra · LLM Gateway · Multi-Provider · OpenAI-Compatible · Routing · Fallback · Spend Guardrail

"GPT-4o로 짜둔 코드를 Claude Sonnet으로 옮기는 데 왜 일주일이 걸리지?", "Bedrock·Vertex·Azure가 다 다른 인증 방식과 응답 스키마를 쓴다", "어제 갑자기 OpenAI가 5xx를 토해내는데 Anthropic으로 자동 전환할 방법이 없다", "팀 막내가 실수로 GPT-4 32k에 100만 토큰 프롬프트를 박았는데 Slack 알림조차 없다." 이 네 줄이 2024–2026 모든 LLM 프로덕션 팀의 공통 비명이다. LiteLLM은 정확히 이 자리에 들어온다 — "100+ LLM API의 사실상 표준 어댑터 + 게이트웨이". 모든 호출을 OpenAI chat/completions 스키마로 정규화하고, 그 위에 라우팅·폴백·재시도·캐시·레이트리밋·예산·가상 키·로깅을 한 레이어로 얹었다. BerriAI(YC W23)가 Python으로 짠 단일 SDK + Proxy Server 구조이며, MIT 라이선스로 공개된 OSS 코어 위에 Enterprise 기능이 붙는다. 결과는 한 줄 — "openai.chat.completions.create(model='claude-3-5-sonnet')"이 그대로 동작한다. 그 뒤로 어떤 모델·어떤 클라우드·어떤 키로 갔는지는 LiteLLM이 책임진다.

목차

1. LiteLLM이란? — 100+ LLM SDK 파편화의 끝
2. LiteLLM의 핵심 특징
3. 동작 방식 — SDK 모드와 Proxy 모드
4. 구성 요소 및 요청 흐름도
5. 설치 방법 — 로컬·Docker·K8s·Helm
6. 사용 방법 — 코드·config·운영 가드레일
7. 자주 쓰는 명령어와 사례
8. 활용 방안·대안 비교·안 써야 할 때

---

1. LiteLLM이란? — 100+ LLM SDK 파편화의 끝

1-1. 왜 필요한가 — 2024–2026 LLM 프로덕션의 4대 고통

GPT가 던져 놓은 chat/completions 한 가지 호출 패턴은 사실상 표준이 됐지만, 그 표준을 각 벤더가 다른 SDK·다른 응답 스키마·다른 인증·다른 토큰 카운팅으로 구현하면서 프로덕션 팀이 떠안는 부담이 폭발했다. 2025년 기준 한 회사가 "동시에 다루는 LLM"의 평균 개수는 이미 6~9개다(Anthropic + OpenAI + Bedrock + Vertex + Azure + 자사 파인튜닝 + 오픈소스). 코드 한 줄에 모델 이름만 바꿔서 옮기는 것이 안 된다.

고통의 축	현실	LiteLLM 이전 해결법
SDK 파편화	openai, anthropic, boto3.bedrock-runtime, google-cloud-aiplatform, azure-openai — 5개 SDK·5개 응답 스키마·5개 에러 클래스	회사마다 자체 어댑터 클래스를 짜고 매번 깨짐. if model.startswith("claude") 분기가 100개 코드에 박힘
벤더 장애	OpenAI 5xx, Anthropic 529 overloaded, Bedrock throttling — 평균 0.3~1.2% 발생	애플리케이션 코드에서 try/except + 수동 재시도. 다른 벤더로 폴백은 거의 못 함
키·할당량 운영	팀별·프로젝트별 분리, RPM·TPM 제한, 키 회전, 사용자별 마스킹	API Gateway에 라우팅 룰 + 회사 SSO + 자체 미터링 대시보드를 따로 구축
비용 가시성	벤더별 토큰 단가·캐시 할인·프롬프트/완성/도구 호출 분리·이미지·오디오 단가	월말 인보이스 보고 놀람. 사람이 일일이 단가표 적어둔 스프레드시트로 계산

1-2. 기술 정의

LiteLLM은 100+ LLM 제공자(텍스트·이미지·임베딩·오디오·재랭킹)를 OpenAI chat/completions 호환 인터페이스로 정규화하는 Python 라이브러리이자, 그 위에 라우팅·폴백·캐시·키 관리·예산·관측을 얹은 게이트웨이(Proxy Server)다. 입력은 OpenAI 형태, 출력도 OpenAI 형태, 그 사이에서 어떤 벤더·어떤 키·어떤 인스턴스로 갈지는 LiteLLM이 결정한다.

1-3. 한 줄 정체성

• 개발자 SDK litellm.completion(...) 한 함수로 모든 모델 호출
• Proxy Server Python FastAPI로 OpenAI 호환 엔드포인트(/v1/chat/completions) 노출
• 엔터프라이즈 게이트웨이 가상 키·예산·SSO·감사 로그·Guardrail·OpenTelemetry — Enterprise 라이선스
• 아닌 것 추론 엔진(vLLM·SGLang)도 아니고, 모델 자체도 아니다 — 모델 앞 단의 어댑터·라우터일 뿐

1-4. 비교 좌표 — 어디에 위치하는가

┌─────────────────────────────────────────────────────────────────┐ │ Application / Agent / RAG │ └────────────────────────────────┬────────────────────────────────┘ │ (OpenAI 호환 호출) ┌─────────▼──────────┐ │ LiteLLM │ ◀── 이 글의 주제 │ (SDK or Proxy) │ │ router · fallback │ │ cache · budget │ │ guardrail · logs │ └────┬─────┬─────┬───┘ ┌──────────────────┘ │ └──────────────────┐ ▼ ▼ ▼ OpenAI / Azure Anthropic / Bedrock Vertex / Gemini vLLM·SGLang·Ollama Cohere · Mistral · DeepSeek · 기타 100+

LiteLLM은 "모델"이 아니라 "모델 앞 단"이다. 그 자리에는 Portkey, OpenRouter, Kong AI Gateway, AWS Bedrock(자체), Cloudflare AI Gateway, OneAPI 등이 함께 경쟁한다. LiteLLM이 한국·일본·미국 OSS 진영에서 독보적인 이유는 ① OSS 코어가 MIT, ② Python 라이브러리로도 쓰고 Proxy로도 쓰는 이중 노출, ③ 100+ 프로바이더 매트릭스의 빠른 갱신 속도다.

1-5. 한 마디로

"OpenAI SDK 코드를 그대로 두고 모델만 바꾸고 싶다"는 한 줄 요구를, 코드·운영·비용·보안 4축에서 동시에 풀어낸 도구다.

---

2. LiteLLM의 핵심 특징

① 입력·출력 정규화

모든 응답을 OpenAI ChatCompletion 스키마로 변환. response.choices[0].message.content가 어떤 벤더든 그대로 통한다. 비용도 response._hidden_params["response_cost"]로 정규화.

② Drop-in 100+ Provider

모델 이름 prefix만 보고 라우팅 — claude-3-5-sonnet, bedrock/anthropic.claude-3-haiku, vertex_ai/gemini-1.5-pro, azure/gpt-4o, ollama/llama3.

③ Router — 라우팅·폴백·재시도

같은 논리 모델 이름 뒤에 N개 deployment 등록 → 가중치·RPM·TPM·지연 기반 라우팅. 1차 실패 시 다른 deployment, 그래도 실패 시 다른 모델로 폴백.

④ Spend Tracking

요청마다 토큰 카운팅 + 단가 매칭으로 비용을 즉시 산정. user / team / key 단위 누적, Postgres에 영속, Prometheus 익스포트.

⑤ Virtual Key 시스템

Master Key 하나로 N개의 가상 키를 발급 — 모델 화이트리스트·RPM·TPM·일/월 예산·만료. 사용자가 LiteLLM 키를 쓰지만 뒤에서는 회사 OpenAI 키 하나로 통합.

⑥ Caching

Redis·in-memory·S3·Qdrant 백엔드. exact cache(프롬프트 해시) + semantic cache(임베딩 유사도). Anthropic prompt caching 같은 벤더 캐시도 한 깃발로 활성화.

⑦ Streaming & Tools

SSE 스트리밍·function calling·vision·audio·embedding·rerank·image generation·moderation까지 한 함수에서 모두 처리. 모델별 차이는 LiteLLM이 흡수.

⑧ Guardrail Hooks

요청 전/후 hook으로 PII 마스킹·정책 검사·금칙어. Aporia·Bedrock Guardrail·Lakera·Presidio·자작 hook 모두 플러그인 가능.

⑨ Observability

Langfuse·LangSmith·Helicone·Phoenix·Datadog·OpenTelemetry·Slack·S3 — 30+ 백엔드를 동시에 fan-out. callback 한 줄로 끝.

---

3. 동작 방식 — SDK 모드와 Proxy 모드

3-1. 두 가지 사용 모드

LiteLLM은 같은 코드를 두 가지 모양으로 노출한다 — Python 라이브러리(SDK) 모드와 단독 서버(Proxy) 모드. 핵심 코어는 동일하다.

모드	SDK 모드 (import litellm)	Proxy 모드 (litellm --config)
호출 위치	애플리케이션 프로세스 안	별도 프로세스 (FastAPI, Uvicorn)
설정 위치	코드 안 환경변수·딕셔너리	YAML config + Postgres + Master Key
사용 언어	Python만	OpenAI 호환 HTTP — 모든 언어 가능 (Node, Go, Rust, Java)
가상 키	없음	있음 (사용자별 발급·예산·만료)
적합한 자리	실험·노트북·단일 서비스	여러 팀·여러 서비스가 공유하는 사내 게이트웨이
운영 비용	0 (라이브러리)	1~3 pod + Postgres + Redis

3-2. 핵심 구성 요소(Proxy 기준)

• Auth Layer — 들어온 요청 헤더의 Bearer 토큰을 가상 키 DB에서 조회 → user/team/budget 매핑
• Pre-call Hooks — Guardrail·PII·prompt injection 검사. 차단 시 즉시 4xx
• Router — config에 등록된 deployment 풀에서 가중치·헬스·RPM/TPM 기반으로 1개 선정
• Provider Adapter — 선정된 deployment에 맞춰 OpenAI 스키마 → 벤더별 페이로드로 변환, 응답을 다시 OpenAI로 변환
• Cache — 요청 해시·임베딩으로 Redis/Qdrant 캐시 hit 확인. hit 시 어댑터 단계 생략
• Cost Tracker — 응답 토큰 × 단가 표 → user/team/key spend 갱신, Postgres·Prometheus 기록
• Post-call Hooks — 출력 PII 마스킹·로깅·관측 백엔드 fan-out
• Failure Handler — 정의된 fallback 체인을 순회. 모든 단계 실패 시 502 + 구조화 에러

3-3. 데이터 흐름 — 한 요청의 라이프사이클

[Client] │ POST /v1/chat/completions (Authorization: Bearer sk-xxx) ▼ [Auth] ── 가상 키 검증 ── [Budget Check] ── 한도 초과? ──► 429 │ pass ▼ [Pre-call Guardrail] ── PII/금칙어 차단? ──► 400 │ pass ▼ [Cache Lookup] ── exact/semantic hit? ──► 200 (캐시 응답) │ miss ▼ [Router] ── 정책: weighted·least-busy·latency 등 │ 선정된 deployment = e.g. azure/gpt-4o-eastus ▼ [Provider Adapter] ── OpenAI 스키마 → Azure 페이로드 변환 │ HTTPS 호출 ▼ [Vendor API] (OpenAI / Anthropic / Bedrock / …) │ 5xx? ──► [Fallback] (다른 deployment / 다른 모델) │ 200 ▼ [Adapter] ── 응답 → OpenAI 스키마 정규화 ▼ [Cache Write] ▼ [Cost Tracker] ── Postgres user_spend, key_spend 누적 ▼ [Post-call Hook] ── Langfuse / OTel / S3 fan-out ▼ [Client] 200 OK + 표준 OpenAI 응답

---

4. 구성 및 흐름도

4-1. 단계별 설명

1. 1단계 — 모델 선언: config.yaml의 model_list에 (논리 이름, 실제 deployment, 키, 옵션)을 N개 등록한다. 같은 논리 이름에 여러 deployment를 묶으면 Router가 자동으로 풀로 본다.
2. 2단계 — 라우팅 정책 선택: router_settings.routing_strategy로 simple-shuffle·least-busy·usage-based-routing-v2·latency-based-routing 중 선택.
3. 3단계 — 가상 키 발급: Master Key로 POST /key/generate를 호출 → 사용자/팀에게 줄 sk-xxx를 발급. 모델 화이트리스트·예산·RPM 함께 박는다.
4. 4단계 — 호출: 사용자는 OpenAI Python SDK든 curl이든 그대로 쓰되 base_url을 LiteLLM으로 돌린다. 모델 이름은 논리 이름.
5. 5단계 — 폴백 활성화: litellm_settings.fallbacks로 1차 실패 시 어디로 갈지 정의. 예: gpt-4o 5xx → claude-3-5-sonnet.
6. 6단계 — 캐시·관측 연결: litellm_settings.cache: true + Redis URL, callbacks: ["langfuse", "otel"].
7. 7단계 — Guardrail 부착: guardrails: 섹션에 Bedrock Guardrail·Aporia·Presidio·자작 Python 클래스 등록.
8. 8단계 — 운영: Grafana로 spend·error rate·latency 모니터링, 예산 임계 도달 시 Slack 알림, 키 만료/회전.

4-2. 실제 처리 흐름 — 다중 벤더·다중 리전 라우팅 예

config.yaml model_list: - model_name: prod-chat ◀── 논리 이름 litellm_params: model: azure/gpt-4o api_base: https://eu.openai.azure.com api_key: os.environ/AZURE_KEY_EU rpm: 600 - model_name: prod-chat litellm_params: model: azure/gpt-4o api_base: https://us.openai.azure.com rpm: 1200 - model_name: prod-chat litellm_params: model: bedrock/anthropic.claude-3-5-sonnet aws_region_name: us-east-1 litellm_settings: fallbacks: - prod-chat: ["prod-chat-fallback"] cache: true callbacks: ["langfuse", "otel", "prometheus"] 요청 흐름: Client ──► Router ──┬──► Azure-EU (실패) ├──► Azure-US (성공) ──► Cache 저장 ──► Client └──► Bedrock-Claude (사용 안 됨) Azure 둘 다 5xx인 경우: Router ──► fallback "prod-chat-fallback" ──► Anthropic API

4-3. 흐름의 트레이드오프

설계 결정	얻는 것	잃는 것
OpenAI 스키마로 정규화	코드 한 가지·모든 모델	벤더 고유 기능(Anthropic system 캐시 등) 일부는 별도 파라미터로만 노출
Proxy를 별도 프로세스화	다언어·다팀·중앙 가버넌스	1 hop 추가(보통 1~5ms) + 운영 부담
가상 키 + Postgres 영속	SSO·예산·감사 로그	Postgres 의존, 키 검증 hot path 캐시 필요
Python 단일 언어 게이트웨이	빠른 provider 추가	Go/Rust 게이트웨이 대비 지연·메모리 풋프린트 큼
요청별 비용 산정	비용 가시성·청구	벤더 단가 변동 시 단가표 즉시 갱신 필요

---

5. 설치 방법 — 로컬·Docker·K8s·Helm

5-1. SDK 모드 — 가장 빠른 시작

# Python 3.9+
pip install "litellm[proxy]"

# 환경변수에 키만 넣으면 끝
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

python - <<'PY'
from litellm import completion
r = completion(model="claude-3-5-sonnet-20241022",
               messages=[{"role":"user","content":"안녕"}])
print(r.choices[0].message.content)
PY

5-2. Proxy 모드 — 단독 서버

# 1) config.yaml 작성
cat > config.yaml <<'YAML'
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: os.environ/ANTHROPIC_API_KEY
litellm_settings:
  drop_params: true
YAML

# 2) 실행
litellm --config config.yaml --port 4000

# 3) 호출 (OpenAI SDK 그대로)
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-1234" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude","messages":[{"role":"user","content":"hi"}]}'

5-3. Docker

docker run -d --name litellm \
  -p 4000:4000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $PWD/config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml --port 4000

5-4. Postgres + Master Key — 가상 키를 쓰려면 필수

docker run -d --name litellm-db \
  -e POSTGRES_PASSWORD=litellm \
  -p 5432:5432 postgres:16

docker run -d --name litellm \
  -p 4000:4000 \
  -e DATABASE_URL=postgresql://postgres:litellm@host.docker.internal:5432/postgres \
  -e LITELLM_MASTER_KEY=sk-master-1234 \
  -e LITELLM_SALT_KEY=salt-anything \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $PWD/config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml

5-5. Helm — 쿠버네티스 운영

helm repo add litellm https://berriai.github.io/litellm
helm install litellm litellm/litellm-helm \
  --set masterkey=sk-master-1234 \
  --set proxy_config.model_list[0].model_name=gpt-4o \
  --set db.deployStandalone=true

실서비스에서는 db.deployStandalone=false로 두고 외부 RDS/Cloud SQL을 붙이며, Redis(캐시)·Prometheus(메트릭)·Vault/SOPS(시크릿)를 함께 구성한다.

---

6. 사용 방법 — 코드·config·운영 가드레일

6-1. SDK 모드 — 한 함수, 모든 모델

from litellm import completion, embedding, image_generation

# 1) 텍스트 — 모델 이름만 갈아끼우면 끝
r = completion(model="gpt-4o",                     messages=[{"role":"user","content":"hi"}])
r = completion(model="claude-3-5-sonnet-20241022", messages=[{"role":"user","content":"hi"}])
r = completion(model="bedrock/anthropic.claude-3-haiku-20240307-v1:0",
               messages=[{"role":"user","content":"hi"}],
               aws_region_name="us-east-1")
r = completion(model="vertex_ai/gemini-1.5-pro",   messages=[{"role":"user","content":"hi"}],
               vertex_project="my-gcp-proj", vertex_location="us-central1")
r = completion(model="ollama/llama3",              messages=[{"role":"user","content":"hi"}],
               api_base="http://localhost:11434")

# 2) 스트리밍
for chunk in completion(model="gpt-4o", messages=[...], stream=True):
    print(chunk.choices[0].delta.content or "", end="", flush=True)

# 3) 임베딩
e = embedding(model="text-embedding-3-small", input=["문장1", "문장2"])

# 4) 이미지 생성
img = image_generation(model="dall-e-3", prompt="seoul night skyline")

6-2. Proxy config.yaml — 라우팅·폴백·캐시·관측·Guardrail 종합본

model_list:
  # 같은 논리 이름에 여러 deployment ── Router가 풀로 본다
  - model_name: prod-chat
    litellm_params:
      model: azure/gpt-4o
      api_base: https://eu.openai.azure.com/
      api_key: os.environ/AZURE_KEY_EU
      rpm: 600
      tpm: 600000
  - model_name: prod-chat
    litellm_params:
      model: azure/gpt-4o
      api_base: https://us.openai.azure.com/
      api_key: os.environ/AZURE_KEY_US
      rpm: 1200
  - model_name: prod-chat-fallback
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: os.environ/ANTHROPIC_API_KEY

  # 임베딩
  - model_name: emb
    litellm_params:
      model: openai/text-embedding-3-small
      api_key: os.environ/OPENAI_API_KEY

router_settings:
  routing_strategy: usage-based-routing-v2     # RPM·TPM·latency 기반
  redis_host: redis.internal
  redis_port: 6379
  num_retries: 2
  timeout: 30
  cooldown_time: 30                            # 5xx 후 30초 격리

litellm_settings:
  drop_params: true                            # 모델별 미지원 파라미터 자동 제거
  cache: true
  cache_params:
    type: redis
    host: redis.internal
    ttl: 600
    similarity_threshold: 0.92                 # 의미론적 캐시
  fallbacks:
    - prod-chat: ["prod-chat-fallback"]
  callbacks: ["langfuse", "otel", "prometheus"]
  success_callback: ["langfuse"]
  failure_callback: ["slack"]

guardrails:
  - guardrail_name: pii-mask
    litellm_params:
      guardrail: presidio
      mode: pre_call
      pii_entities_config:
        EMAIL_ADDRESS: MASK
        PHONE_NUMBER: MASK

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL
  alerting: ["slack"]
  alerting_threshold: 300                       # 5분 이상 지연 시 알림

6-3. 가상 키 발급 — 사용자별·팀별 격리

# 1) 새 키 발급
curl -X POST http://litellm:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["prod-chat", "emb"],
    "max_budget": 100.0,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "metadata": {"team": "growth", "owner": "feccle@kakao.com"}
  }'
# → {"key":"sk-abc123...", "expires":null}

# 2) 사용자가 그대로 사용 (OpenAI SDK 코드 변경 0줄)
curl http://litellm:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-abc123..." \
  -d '{"model":"prod-chat","messages":[{"role":"user","content":"hi"}]}'

6-4. 운영 시 고려사항 — 5번 더 점검할 항목

축	점검 포인트
가용성	Proxy를 SPOF로 두지 마라 — 최소 2 pod, ALB·Service 헬스체크는 /health/liveliness가 아니라 /health/readiness로. 또한 SDK 모드 fallback을 코드에도 둬서 Proxy 자체가 죽었을 때를 대비.
비용 정확도	벤더 단가는 자주 바뀐다. model_cost_map.json은 LiteLLM 업데이트로 들어오지만, Bedrock·Vertex의 리전별 단가 차이는 직접 override 필요. 실제 인보이스와 월 1회 대조.
키 관리	Master Key는 KMS·Vault에 보관, 가상 키는 90일 회전, 만료 임박 시 자동 알림. permissions로 user/team/admin 분리.
레이트리밋	Router의 rpm/tpm은 deployment 단위, Virtual Key의 rpm_limit은 사용자 단위. 두 축이 동시에 걸린다 — 내부 한도는 항상 벤더 한도보다 낮게.
장애 격리	cooldown_time으로 5xx 후 풀에서 잠시 빼고, num_retries는 2 이하. 무한 폴백은 비용·지연을 폭발시킨다.
관측·감사	OpenTelemetry로 traceparent 보존, Langfuse로 프롬프트·응답 저장, Loki/Splunk로 1년 보관. PII는 저장 전에 반드시 마스킹.
스트리밍 일관성	벤더별 SSE 청크 모양이 다르다 — LiteLLM이 흡수하지만, tool_calls delta는 모델별 상이. 클라이언트 파서 테스트 필수.
캐시 안전	의미론적 캐시는 동일 의미·다른 컨텍스트 답변을 잘못 재사용할 수 있다 — 사용자 ID·세션 ID를 캐시 키에 섞어라(cache_params.user_id_cache_key).

---

7. 자주 쓰는 명령어와 사례

7-1. CLI

명령	설명
litellm --config config.yaml --port 4000	Proxy 실행
litellm --model gpt-4o	config 없이 단일 모델로 빠른 노출
litellm --health	config의 모든 deployment 헬스체크
litellm --test	모든 모델에 sample 호출을 던져 검증
litellm --num_workers 4	Uvicorn worker 수 지정
litellm --debug	모든 어댑터 변환을 콘솔에 출력

7-2. HTTP API (관리)

# 키 발급
POST /key/generate                 { "models":[...], "max_budget":..., "rpm_limit":... }

# 키 정보 / 잔액 조회
GET  /key/info?key=sk-abc...

# 키 폐기
POST /key/delete                   { "keys": ["sk-abc..."] }

# 사용량 조회
GET  /spend/logs?api_key=sk-...&start_date=...&end_date=...

# 모델 풀 목록
GET  /v1/models

# 헬스
GET  /health/readiness
GET  /health/liveliness

# 메트릭 (Prometheus)
GET  /metrics

7-3. 사례 ① OpenAI SDK 코드 변경 0줄로 멀티 LLM

from openai import OpenAI

client = OpenAI(
    base_url="http://litellm:4000",          # ← 단 한 줄
    api_key="sk-abc123"                      # ← LiteLLM 가상 키
)

# 모델 이름만 바꾸면 Anthropic·Bedrock·Gemini 어디든 간다
client.chat.completions.create(model="prod-chat",
    messages=[{"role":"user","content":"안녕"}])

7-4. 사례 ② LangChain·LlamaIndex와의 결합

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(base_url="http://litellm:4000", api_key="sk-abc",
                 model="prod-chat")
# LangChain·LlamaIndex의 OpenAI 인터페이스가 그대로 LiteLLM Proxy로 흐른다 →
# 프레임워크 안에서 모델만 갈아끼우면 된다.

7-5. 사례 ③ 비동기·고동시성 — Python 백엔드

import asyncio
from litellm import acompletion

async def ask(q):
    r = await acompletion(model="prod-chat",
                          messages=[{"role":"user","content":q}])
    return r.choices[0].message.content

asyncio.run(asyncio.gather(*[ask(q) for q in questions]))

7-6. 사례 ④ Guardrail 한 줄 부착

# Bedrock Guardrail을 LiteLLM에 붙이고, 특정 키만 활성화
guardrails:
  - guardrail_name: bedrock-pii
    litellm_params:
      guardrail: bedrock
      mode: pre_call
      guardrailIdentifier: bg-2k4j5h6
      guardrailVersion: "DRAFT"

7-7. 사례 ⑤ 폴백 체인 — 비용·품질·가용성을 동시에

litellm_settings:
  fallbacks:
    # 1차: GPT-4o → 5xx 시 Claude → 그래도 실패 시 Llama-on-Bedrock
    - prod-chat: ["claude-fast", "bedrock-llama"]
    # 컨텍스트 길이 초과 시 longer-context 모델로
    - context_window_fallbacks:
        - prod-chat: ["claude-3-5-sonnet-200k"]
    # 콘텐츠 정책 차단 시 (벤더에 따라 4xx) 다른 모델로
    - content_policy_fallbacks:
        - gpt-4o: ["claude-3-5-sonnet-20241022"]

---

8. 활용 방안·대안 비교·안 써야 할 때

8-1. 잘 맞는 자리

중앙 사내 LLM 게이트웨이

여러 팀이 OpenAI·Anthropic·Bedrock을 동시에 쓰는 환경에서 키·예산·감사 로그를 한 군데로. 보안팀이 LiteLLM 앞에 SSO 프록시를 두면 사용자별 통제까지 끝.

멀티-리전·멀티-클라우드 가용성

Azure-EU + Azure-US + Bedrock + Vertex를 한 풀로 묶고 폴백. 단일 벤더 5xx에 서비스가 멈추지 않는다.

비용 + 품질 라우팅

저비용 모델(Haiku, Mini, Nano)로 1차 응답 → 품질 미달이면 상위 모델로 escalation. semantic cache + cheap model + fallback 조합이 OPEX를 30~70% 줄인다.

Self-host 모델 + SaaS 모델 혼합

vLLM·SGLang·Ollama로 띄운 자가 모델을 LiteLLM 풀에 같이 넣고, OpenAI 호환 인터페이스로 노출. 클라이언트는 차이를 모른다.

실험·A/B

가중치 라우팅으로 신규 모델에 5%만 트래픽을 흘리고, 응답 품질 메트릭을 Langfuse에서 비교.

레거시 OpenAI 코드 마이그레이션

이미 OpenAI SDK로 짜둔 1만 줄 코드를 안 건드리고 모델만 갈아끼우고 싶을 때.

8-2. 대안 기술 비교

도구	구현 언어	라이선스	위치	특징·차이
LiteLLM	Python	MIT (코어) + Enterprise	SDK + Proxy	100+ provider, OpenAI 호환, 가상 키·예산·캐시·Guardrail까지 한 레이어. OSS 비중이 가장 크다.
Portkey	Node.js (Hono)	MIT (게이트웨이) + SaaS	Proxy	SaaS 강점·UI 풍부. OSS 게이트웨이는 가벼움. Python SDK 통합은 LiteLLM이 더 깊다.
OpenRouter	SaaS (closed)	SaaS	API 서비스	모델 마켓 + 결제 통합. self-host 불가 — 데이터 통제·사내 키 운영 안 맞음.
Kong AI Gateway	Lua/OpenResty	Apache-2.0 (OSS) + Enterprise	Plugin on Kong	API Gateway 기반 — 기존 Kong 운영 팀에 잘 맞음. provider 매트릭스는 LiteLLM이 압도적.
Cloudflare AI Gateway	Workers (V8)	SaaS	엣지 SaaS	엣지 캐시·로깅 강점. 자체 호스팅 불가, 가상 키 시스템은 약함.
OneAPI	Go	MIT	Proxy	중국 OSS 진영의 다중 LLM 게이트웨이. provider 커버리지·Guardrail은 LiteLLM이 더 넓음.
vLLM·SGLang·TGI	Python·C++	Apache-2.0	추론 엔진	같은 레이어가 아님 — LiteLLM 뒤에 배치하는 자가 호스트 모델 실행기. 보완 관계.
LangChain	Python·JS	MIT	프레임워크	같은 레이어가 아님 — LangChain의 LLM 어댑터 역시 LiteLLM을 백엔드로 쓸 수 있다.

8-3. 언제 쓰면 안 되는가

• 단일 모델·단일 팀·실험 단계 — Proxy 운영 부담이 가치를 넘는다. SDK 모드만으로 충분하거나 OpenAI SDK 직타가 더 단순할 수 있다.
• 레이턴시가 5ms 이내까지 깎이는 초저지연 응답 — Python proxy 1 hop이 부담이면 클라이언트 SDK 모드 또는 Go 기반 게이트웨이를 우선 검토.
• 벤더 고유 기능에 깊이 기대는 워크로드 — Anthropic의 long-running batch, OpenAI의 Assistants v2 thread 같이 사실상 OpenAI 호환이 안 되는 영역은 LiteLLM에 얹어도 추상화 누수가 크다. 그 부분만 직접 SDK 사용.
• 완전 오프라인·에어갭 환경에서 LiteLLM의 callback 백엔드 의존이 부담일 때 — Langfuse·OTel 백엔드 자가 호스팅 가능 여부를 미리 확인.
• 단가 정확도가 분당 단위로 중요한 청구 시스템 본체 — LiteLLM의 비용은 best-effort 추정이다. 벤더 인보이스와 월 1회 보정하는 운영이 전제.

8-4. 한 페이지 회고 — 문제·아키텍처·트레이드오프

문제 제기 — LLM 시대에 100+ 모델·다중 클라우드를 다루는데 SDK·인증·스키마·비용·키 운영이 따로 놀고, 벤더 장애가 곧 서비스 장애가 된다.

개념 — LiteLLM은 ① OpenAI 스키마로 정규화한 어댑터, ② 그 위에 라우팅·폴백·캐시·Guardrail·가상 키를 얹은 게이트웨이.

구조·동작 원리 — SDK 함수 한 개와 FastAPI Proxy 한 개가 같은 코어를 공유. 요청은 Auth → Pre-hook → Cache → Router → Adapter → Vendor → Cost → Post-hook 순.

실제 사례 — OpenAI SDK 코드를 1줄 base_url 변경만으로 LiteLLM에 흘려보내고, 모델 이름은 논리 풀로 두며, 5xx 시 자동 폴백, 비용은 가상 키별 누적.

트레이드오프 — Python proxy 1 hop·운영 부담·벤더 고유 기능 추상화 누수를 받는 대신, 코드·키·예산·관측·가용성 5축의 일관성을 얻는다. 여러 모델·여러 팀·여러 클라우드를 동시에 다루는 순간부터, LiteLLM은 "있으면 좋은 도구"가 아니라 "없으면 안 되는 인프라"가 된다.

---

※ 본 글은 2026-05 시점 LiteLLM v1.x 라인업 기준이며, provider 매트릭스·단가표·Enterprise 기능은 빠르게 변동된다. 실제 도입 시에는 공식 문서(docs.litellm.ai)와 model_prices_and_context_window.json의 최신 버전을 기준으로 한다.