LiteLLM 설치 및 설정 방법 – Docker로 LLM 게이트웨이 구축하기

LiteLLM이란?

LiteLLM은 OpenAI, Anthropic, Gemini, Azure, Bedrock 같은 100개 이상의 LLM API를 OpenAI 호환 형식 하나로 호출하게 해 주는 오픈소스 도구입니다. 앱 코드는 base_url만 바꾸면 되고, 모델 교체·키 관리·비용 추적은 게이트웨이에서 처리합니다.

클라이언트는 LiteLLM 엔드포인트 하나만 알면 되고, 어떤 모델·서버로 보낼지는 LiteLLM이 결정합니다.

1. 설치 (Docker Compose)

환경 변수 파일을 만듭니다. 마스터 키는 sk-로 시작해야 합니다.

# mkdir -p /opt/litellm && cd /opt/litellm

# cat > /opt/litellm/.env << ‘EOF’
LITELLM_MASTER_KEY=sk-CHANGE-ME-master
LITELLM_SALT_KEY=sk-CHANGE-ME-salt
DATABASE_URL=postgresql://litellm:CHANGE-ME@db:5432/litellm
OPENAI_API_KEY=sk-…
EOF

LiteLLM과 PostgreSQL을 함께 띄우는 compose 파일입니다.

# cat > /opt/litellm/docker-compose.yml << ‘EOF’
services:
litellm:
image: ghcr.io/berriai/litellm-database:main-stable
restart: unless-stopped
env_file: .env
volumes:
– ./config.yaml:/app/config.yaml:ro
command: [“–config”, “/app/config.yaml”, “–port”, “4000”]
ports:
– “127.0.0.1:4000:4000”
depends_on: [db]

db:
image: postgres:16
restart: unless-stopped
environment:
POSTGRES_USER: litellm
POSTGRES_PASSWORD: CHANGE-ME
POSTGRES_DB: litellm
volumes:
– pgdata:/var/lib/postgresql/data

volumes:
pgdata:
EOF

2. config.yaml 작성

model_name은 클라이언트가 부를 이름이고, model은 공급자/실제모델명입니다. 키는 os.environ/변수명으로 참조합니다.

#cat > /opt/litellm/config.yaml << ‘EOF’
model_list:
– model_name: gpt-4o-mini
litellm_params:
model: openai/gpt-4o-mini
api_key: os.environ/OPENAI_API_KEY

# 자체 vLLM 서버 (OpenAI 호환)
– model_name: qwen-local
litellm_params:
model: openai/Qwen/Qwen2.5-7B-Instruct
api_base: http://10.0.0.10:8000/v1
api_key: “none”

general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
database_url: os.environ/DATABASE_URL
EOF

3. 실행과 테스트

# docker compose up -d
# docker compose logs -f litellm

# curl -s http://127.0.0.1:4000/v1/chat/completions \
-H “Authorization: Bearer sk-CHANGE-ME-master” \
-H “Content-Type: application/json” \
-d ‘{“model”: “gpt-4o-mini”, “messages”: [{“role”: “user”, “content”: “안녕”}]}’

관리 화면은 http://<서버>:4000/ui이며, 아이디 admin, 비밀번호는 마스터 키입니다.

4. 가상 키 발급

앱에는 마스터 키 대신 모델·예산이 제한된 가상 키를 나눠 줍니다.

# curl -s -X POST http://127.0.0.1:4000/key/generate \
-H “Authorization: Bearer sk-CHANGE-ME-master” \
-H “Content-Type: application/json” \
-d ‘{“models”: [“gpt-4o-mini”], “max_budget”: 10, “budget_duration”: “30d”}’

응답의 key 값을 OpenAI SDK의 api_key로, http://<서버>:4000/v1을 base_url로 쓰면 됩니다.

. 운영 시 주의할 점

버전 고정: 2026년 3월 PyPI에 악성 litellm 1.82.7·1.82.8이 올라온 공급망 공격이 있었습니다. 이미지 태그와 pip 버전을 고정하세요.
솔트 키: LITELLM_SALT_KEY는 모델 등록 후 바꾸면 저장된 키를 복호화할 수 없습니다.
외부 공개: 4000 포트는 127.0.0.1에만 열고 Nginx로 HTTPS를 붙입니다. 스트리밍을 위해 proxy_buffering off;를 꼭 넣으세요.
백업: docker compose down -v는 DB 볼륨까지 지우니 주의합니다.

참고 자료

*이 글은 본인의 실제 경험과 학습을 기반으로 직접 작성하였으며, AI는 참고용으로만 활용하였습니다.

LiteLLM 설치부터 설정까지