LiteLLM Proxy: 100개 이상의 LLM을 위한 1개의 API (15분 Docker 설정)

당신의 팀이 Slack DM으로 OpenAI API 키를 공유하고 있다면? 지난 화요일에 누가 400달러를 썼는지 아무도 모른다면? 제공자 장애 시 폴백이 없고, GPT-4o에서 Claude로 전환하려면 12개 장소의 코드를 바꿔야 한다면? 낡은 문제들이죠? 자체 호스팅 LLM 게이트웨이가 이 모든 것을 해결합니다. LiteLLM 프록시는 가장 인기 있는 오픈소스 옵션입니다 -- 100개 이상의 LLM 제공자로 요청을 라우팅하는 하나의 OpenAI 호환 엔드포인트입니다.

이 가이드는 완전한 litellm 프록시 설정을 다룹니다: PostgreSQL이 포함된 Docker Compose, 예산이 있는 가상 팀 키, 비용 추적, 레이트 제한, 그리고 Claude Code와 Cursor 같은 AI IDE 연결. LLM 게이트웨이 도구를 평가 중이라면, 이것이 완전 초보부터 프로덕션까지 가는 실습 튜토리얼입니다.

시작하기 전에 한 가지 중요한 참고: LiteLLM의 SDK(Python 라이브러리)와 프록시 서버는 다릅니다. SDK는 단일 개발자가 Python에서 여러 LLM API를 호출할 때 사용합니다. 프록시는 팀용입니다 -- 앱과 LLM 제공자 사이에 서버로 위치합니다. 혼자서 스크립트를 작성하는 개발자라면 SDK로 충분합니다. 팀을 위해 키, 예산, 액세스를 관리한다면 프록시가 필요합니다. 여기서 설정하는 것이 바로 그것입니다.

LiteLLM 프록시 한눈에 보기

배포 방법 비교는 다음과 같습니다:

대부분의 팀에게 PostgreSQL이 포함된 Docker Compose가 최적입니다. 여기로 나아가겠지만, 먼저 60초 안에 프록시를 실행해봅시다.

사전 조건 및 환경 설정

시작하기 전에 다음을 확인하세요:

• Docker와 Docker Compose 설치됨 (Docker Desktop에 둘 다 포함)
• 최소한 하나의 LLM API 키 (OpenAI, Anthropic 또는 로컬 Ollama 인스턴스)
• 기본적인 터미널/CLI 친숙도

Docker가 준비되었는지 확인하고 API 키를 내보내세요:

docker --version
export OPENAI_API_KEY="sk-..."

이것으로 끝입니다. 특별한 Python 버전도 필요 없고, OS별 도구도 필요 없습니다. Docker가 당신의 머신에서 실행되면 준비된 것입니다.

빠른 시작 -- 60초 안에 첫 LiteLLM 프록시 실행

한 명령으로 GPT-4o를 사용하여 프록시 시작:

docker run \
  -p 4000:4000 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  ghcr.io/berriai/litellm:latest

curl로 테스트하세요:

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

또는 Python에서 테스트하세요:

from openai import OpenAI
client = OpenAI(api_key="anything", base_url="http://localhost:4000")
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

무슨 일이 일어났을까요? 당신의 코드가 localhost:4000으로 표준 OpenAI SDK 형식을 사용하여 통신합니다. 프록시가 요청을 받아 실제 키로 OpenAI API에 전달하고 응답을 반환합니다. 당신의 애플리케이션 코드는 절대 실제 API 키에 접근하지 않습니다.

이것이 핵심 아이디어입니다. 이제 프로덕션 설정을 만들어봅시다.

PostgreSQL이 포함된 프로덕션 Docker Compose 설정

단일 docker run 명령은 테스트에는 작동하지만, 프로덕션 팀은 지속적인 비용 추적, 가상 키, 적절한 데이터베이스 저장소가 필요합니다. 즉, PostgreSQL이 포함된 Docker Compose를 의미합니다.

Docker Compose 파일

version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm_password
      POSTGRES_DB: litellm_db
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 10s
      timeout: 5s
      retries: 5

  litellm:
    image: ghcr.io/berriai/litellm:latest
    ports:
      - "4000:4000"
    environment:
      DATABASE_URL: "postgresql://litellm:litellm_password@postgres:5432/litellm_db"
      LITELLM_SALT_KEY: "sk-1234567890abcdefghijklmnopqrstuv"
      OPENAI_API_KEY: "${OPENAI_API_KEY}"
      ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
    volumes:
      - ./config.yaml:/app/config.yaml
    depends_on:
      postgres:
        condition: service_healthy
    command: litellm --config /app/config.yaml --port 4000

volumes:
  postgres_data:

LITELLM_SALT_KEY는 데이터베이스의 가상 키 데이터를 암호화합니다. LiteLLM 프로덕션 모범 사례 문서는 팀 배포 시 이를 설정할 것을 권장합니다.

스택 시작

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
docker compose up -d

모든 것이 작동하는지 확인

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Test"}]}'

성공적인 응답이 보이면, 당신의 프로덕션 스택이 실행 중입니다. PostgreSQL은 모든 비용 데이터, 가상 키, 사용 메트릭을 컨테이너 재시작 시에도 지속적으로 저장합니다.

평결: Docker Compose + PostgreSQL은 권장 프로덕션 설정입니다. 약 10분의 작업으로 지속적인 저장소, 비용 추적, 가상 키를 제공합니다. Docker 배포 문서는 나중에 자동 확장이 필요하면 Kubernetes와 Helm을 다룹니다.

Config.yaml 상세 설명 -- 실제 다중 제공자 설정

대부분의 튜토리얼은 하나의 모델로 config.yaml을 보여줍니다. 여기 세 개의 제공자, 폴백, 로드 밸런싱이 있는 실제 팀 설정입니다.

설정 파일

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: gpt-4o
      api_key: ${OPENAI_API_KEY}

  - model_name: gpt-4o
    litellm_params:
      model: claude-3-5-sonnet-20241022
      api_key: ${ANTHROPIC_API_KEY}

  - model_name: claude-opus
    litellm_params:
      model: claude-3-opus-20250219
      api_key: ${ANTHROPIC_API_KEY}

  - model_name: local-llama
    litellm_params:
      model: ollama/llama2
      api_base: http://localhost:11434

router_settings:
  routing_strategy: "least-busy"

  fallbacks:
    - {"gpt-4o": ["claude-3-5-sonnet-20241022"]}

모델 별명 및 라우팅

config에서 gpt-4o가 두 번 나타나는 것을 주목하세요 -- 한 번은 OpenAI를 가리키고, 한 번은 Anthropic을 가리킵니다. 당신의 코드가 gpt-4o를 요청하면, LiteLLM은 먼저 OpenAI를 시도합니다. 실패하면, fallbacks 설정이 Claude로 자동으로 라우팅합니다. 당신의 애플리케이션 코드는 전혀 변하지 않습니다.

vLLM이나 SGLang 같은 프로덕션 추론 백엔드를 사용 중이라면, 같은 방식으로 추가할 수 있습니다 -- 단지 api_base를 추론 서버로 설정하면 됩니다.

제공자 빠른 참조

routing_strategy: least-busy 설정은 같은 model_name 을 가진 모델 전체에 요청을 분산합니다. 두 개의 OpenAI 키가 있다면 (아마도 다른 제한률을 가진 다른 조직), 둘 다 gpt-4o 아래에 나열하고 LiteLLM은 로드를 균형 맞춥니다.

가상 키 -- 예산 및 레이트 제한이 있는 팀별 API 키

이것이 LiteLLM이 "단지 프록시"에서 팀 관리 도구로 변하는 곳입니다. 가상 키를 사용하면 각 팀 구성원 또는 서비스에 지출 제한과 레이트 캡이 있는 자신의 API 키를 제공할 수 있습니다 -- 모두 하나의 제공자 API 키 세트를 통해 라우팅됩니다.

예산이 있는 팀 키 생성

curl -X POST http://localhost:4000/team/new \
  -H "Authorization: Bearer sk-1234567890abcdefghijklmnopqrstuv" \
  -H "Content-Type: application/json" \
  -d '{
    "team_alias": "frontend-team",
    "models": ["gpt-4o", "claude-opus"],
    "budget_per_month": 50,
    "budget_duration": "monthly"
  }'

응답은 sk-team-abc123... 같은 새로운 키를 제공합니다. 이를 프론트엔드 팀에 전달하세요. 정확히 OpenAI 키처럼 사용할 수 있지만, 월 50달러로 제한되고 지정한 모델에만 액세스할 수 있습니다.

레이트 제한 설정

curl -X POST http://localhost:4000/team/update \
  -H "Authorization: Bearer sk-1234567890abcdefghijklmnopqrstuv" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team-123",
    "tpm_limit": 90000,
    "rpm_limit": 1000
  }'

가상 키 문서는 모든 파라미터를 다룹니다. 사용자별 예산과 레이트 제한도 설정할 수 있어 훨씬 더 세밀한 제어가 가능합니다.

키 사용 모니터링

curl http://localhost:4000/team/info \
  -H "Authorization: Bearer sk-1234567890abcdefghijklmnopqrstuv" \
  -d '{"team_id": "team-123"}'

손상된 키를 취소해야 할까요? 한 번의 API 호출:

curl -X POST http://localhost:4000/key/delete \
  -H "Authorization: Bearer sk-1234567890abcdefghijklmnopqrstuv" \
  -d '{"keys": ["sk-team-abc123"]}'

평결: 가상 키는 LiteLLM을 팀 도구로 만드는 것입니다. 단순한 개인 프록시가 아니라요. 이것 없이는 코드와 LLM 사이에 홉을 추가할 뿐입니다. 이것으로, 당신은 액세스 제어, 예산 집행, 사용 귀속을 갖습니다 -- CFO가 당황하지 않도록 하는 종류의 것들입니다.

비용 추적 및 LiteLLM 대시보드

PostgreSQL이 연결되면, LiteLLM은 모든 요청의 비용을 자동으로 추적합니다. 아무것도 설정할 필요가 없습니다 -- 지원하는 모든 모델의 토큰당 가격을 알고 있습니다.

대시보드

http://localhost:4000/ui 에서 내장 UI에 액세스하세요 (마스터 키로 로그인). 다음을 볼 수 있습니다:

• 모든 팀과 키 전체의 총 지출
• 모델별 분석 -- 어떤 모델이 당신의 예산을 먹고 있는가
• 팀별 지출 -- 누가 뭘 사용 중인가
• 시간 경과에 따른 요청 량

LLM API 비용 감소에 진지한 팀들에게, 대시보드 하나만 해도 프록시 실행을 정당화합니다. 더 깊은 분석을 위해 LiteLLM을 Langfuse 또는 Helicone 같은 외부 AI 관찰성 플랫폼에 연결할 수도 있습니다.

제공자별 비용 비교

주요 모델이 백만 토큰당 드는 비용입니다 (2026년 4월 기준):

모델	입력	출력
GPT-4o	$5	$15
Claude 3.5 Sonnet	$3	$15
Claude 3 Opus	$15	$75
Gemini 2.0 Flash	$0.075	$0.3

대시보드에서 팀별로 나뉜 이 숫자들을 보면, "이 사용 사례에 더 싼 모델을 사용해야 할까?"에 대한 대화가 매우 구체적이 됩니다.

평결: 월 100달러 이상을 LLM API에 쓰는 팀이라면 비용 추적만 해도 프록시를 정당화합니다. 측정할 수 없는 것은 최적화할 수 없습니다.

AI IDE 연결 -- Claude Code, Cursor, 그리고 Continue

대부분의 LiteLLM 가이드가 완전히 건너뛰는 뭔가가 있습니다: 당신은 AI 코딩 도구도 프록시로 지정할 수 있습니다. 하나의 프록시, 모든 IDE 도구, 통합 청구.

Claude Code

Claude Code 설정에서:

API Provider: Anthropic
API Key: sk-team-abc123...
Base URL: http://localhost:4000/v1

이것으로 끝입니다. Claude Code가 프록시로 요청을 보내고, 프록시가 Anthropic으로 라우팅합니다 (또는 당신의 설정이 어디로 말하든). 비용이 가상 키 아래에서 추적됩니다.

Cursor

Cursor 설정에서 사용자 지정 OpenAI 호환 엔드포인트를 추가하세요:

Base URL: http://localhost:4000/v1
API Key: sk-team-abc123...
Model: gpt-4o

Continue (VS Code)

Continue의 config.json:

{
  "models": [
    {
      "title": "gpt-4o",
      "provider": "openai",
      "model": "gpt-4o",
      "apiBase": "http://localhost:4000/v1",
      "apiKey": "sk-team-abc123..."
    }
  ]
}

왜 신경 써야 할까요? 이제 모든 개발자의 IDE 사용이 프록시를 통합니다. 인물당 비용 추적을 AI 코딩 보조자에 대해 얻고, 누군가 실수로 한 코딩 세션에 500달러를 태우지 않도록 하는 레이트 제한, 더 나은 옵션을 찾으면 모델을 전환할 수 있는 단일 장소.

일반적인 문제 해결

"Config file not found"

이것은 보통 Docker의 볼륨 마운트 경로가 잘못되었다는 의미입니다. config.yaml이 마운트하는 디렉토리에 있는지 확인하세요:

ls -la ./config.yaml
docker compose up

"Connection refused" to PostgreSQL

Docker 네트워킹은 적어도 한 번은 누구나 걸립니다. LiteLLM이 Postgres에 도달할 수 없으면, 다음을 확인하세요:

• DATABASE_URL의 서비스 이름이 Docker Compose 서비스 이름과 일치하는가 (localhost가 아닌 postgres)
• depends_on이 condition: service_healthy로 설정되어 있는가 (LiteLLM이 Postgres가 준비될 때까지 대기하도록)
• 두 서비스가 같은 Docker 네트워크에 있는가 (Compose에서는 기본적으로 있음)

"Invalid API key format"

LiteLLM이 마스터 키를 인식하지 못합니다. Authorization 헤더가 "Bearer" 다음에 LITELLM_SALT_KEY 값을 포함하는지 확인하세요:

curl -H "Authorization: Bearer sk-1234567890abcdefghijklmnopqrstuv" \
  http://localhost:4000/team/new

...

출처 바로가기