LiteLLM Docker 퀵스타트 — 한 줄로 게이트웨이를 띄우는 법
LiteLLM Docker 퀵스타트 — 한 줄로 게이트웨이를 띄우는 법
설정 파일부터 파고들고 싶지 않을 때, "일단 돌아가는 걸 눈으로 보자" 하고 싶을 때가 있어요. LiteLLM은 그런 상황을 위해 준비된 게이트웨이입니다. 한 줄 명령(또는 클릭 한 번)으로 시작하고, 나머지는 브라우저에서 처리하면 됩니다 — 프로바이더 연결, 모델 추가, 키 생성, 테스트 요청까지 전부 관리 UI에서 해결돼요. 이 가이드에는 설정 파일이 필요 없습니다.
끝나면 LiteLLM이 http://localhost:4000에서 돌고, 모델이 연결되어 있고, 가상 키가 발급되어 있고, 그 키로 요청을 하나 보낼 수 있는 상태가 됩니다.
한 줄로 시작하기
curl로 공식 compose 파일을 파이프해 바로 띄울 수 있어요.
curl -sSL https://docs.litellm.ai/docker-compose.yml | docker compose -f - up -d
이러면 4000번 포트에 게이트웨이가, 그리고 모델·키·지출 로그를 저장하는 Postgres 데이터베이스가 함께 올라옵니다. 딱 두 서비스뿐이니까 구조가 단순해요. 뭔가 바꾸고 싶다면(latest 대신 릴리스 태그 고정이라든지, 자격증명 변경이라든지) compose 파일을 받아서 평소처럼 시작하면 됩니다.
curl -sSLO https://docs.litellm.ai/docker-compose.yml
docker compose up -d
꼭 기억할 것 — salt 키를 진짜 값으로 바꾸세요. LITELLM_SALT_KEY는 UI에서 추가하는 프로바이더 API 키를 암호화합니다. 퀵스타트 compose 파일에는 자리표시자가 들어 있는데, 앞으로 유지할 어떤 것에 모델을 추가하기 전에 긴 랜덤 값으로 바꿔두어야 해요. 그리고 이 값은 나중에 절대 바꾸면 안 됩니다 — 옛 값으로 암호화된 자격증명은 새 값으로 복호화할 수 없거든요.
관리 UI에 로그인하고 요청 보내기
http://localhost:4000/ui를 열면 됩니다. 사용자 이름은 admin, 비밀번호는 LITELLM_MASTER_KEY 값입니다(퀵스타트 compose 파일에서는 sk-1234).
프로바이더 키를 UI에 직접 넣기보다 환경변수로 관리하고 싶다면, compose 파일을 받아 litellm 서비스에 OPENAI_API_KEY: ${OPENAI_API_KEY}처럼 추가하고, API 키 필드에는 원시 키 대신 os.environ/OPENAI_API_KEY를 입력하면 됩니다.
그다음 Playground로 가서 모델을 선택하고 메시지를 보내보세요. 요청이 게이트웨이를 거쳐 프로바이더로 가고, 응답이 지연 시간과 토큰 수와 함께 돌아옵니다.
예산을 쓰고 있다면 데이터베이스가 꼭 필요해요
여기서 짚고 넘어가야 할 함정이 있어요. litellm_settings.max_budget은 이 경로에서는 지출 상한이 아닙니다. 프록시의 전역 지출을 로드하려면 데이터베이스 클라이언트가 필요한데, DB 없이 돌면 누적 지출이 계속 "알 수 없음"이라 전역 예산 체크가 아예 발동하지 않아요. 그러니까 max_budget: 100으로 설정해도 DB 없이는 100달러를 넘겨도 계속 서빙하고, per-request 오류도 예산 알림도 없습니다. 프록시가 기동 시 DB 없이 예산이 설정됐다는 경고를 한 번 남기긴 하는데, 그게 유일한 신호예요.
키·팀 예산도 이 상황의 대안이 안 돼요. 가상 키 자체가 데이터베이스를 필요로 하니까(키를 실은 요청은 No connected db.로 실패) 마스터 키만 남는데, 마스터 키는 자기 예산이 없거든요.
예산으로 지출을 묶는 방식이라면, 위에서 보여준 것처럼 데이터베이스와 함께 LiteLLM을 돌리세요. DB 없이 돌린다면 지출은 업스트림에서 — 프로바이더 자체의 지출 한도로 — 묶어야 해요.
프로덕션으로 가는 길
프로덕션을 염두에 두고 있다면, 프로덕션 배포 가이드가 Helm·Terraform·Kubernetes를 AWS/GCP/Azure에서 다루고 있고, 프로덕션 체크리스트가 강화·튜닝을 다룹니다. 전체 컨테이너·데이터베이스 옵션(Redis, Prometheus 포함)은 저장소의 docker-compose.yml에서 확인할 수 있어요.