LiteLLM 게이트웨이 퀵스타트

LiteLLM 게이트웨이 퀵스타트 (Gateway Quickstart)

여러 사람·플랫폼이 함께 쓰는 하나의 OpenAI 호환 엔드포인트가 필요할 때, LiteLLM 게이트웨이를 가장 빠르게 띄워 보는 길을 알려드릴게요. 코드 몇 줄이면 단일 진입점을 만들 수 있고, 뒤에서 여러 LLM 프로바이더로 트래픽을 분산시킬 수 있어요. 빨리 동작하는 요청 하나부터 완성해 볼게요.

출처: 공식문서 Gateway Quickstart

게이트웨이 설치하기

litellm[proxy]를 uv로 설치하면 게이트웨이 실행 환경이 준비돼요.

uv tool install 'litellm[proxy]'

프로바이더 키 하나 설정하기

설치 다음에 할 일은 LLM 프로바이더 키를 환경변수로 등록하는 거예요. 여기서는 OpenAI 키를 예로 들게요.

export OPENAI_API_KEY="your-api-key"

config.yaml 만들기

게이트웨이의 모델 목록과 일반 설정을 config.yaml에 적어요. model_name은 클라이언트가 호출할 이름이고, litellm_params.model은 실제 프로바이더 모델을 가리켜요. API 키는 os.environ/OPENAI_API_KEY처럼 환경변수를 참조할 수 있어요.

model_list:
  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

general_settings:
  master_key: sk-1234
  database_url: postgresql://llmproxy:dbpassword9090@db:5432/litellm

여기서 master_key는 게이트웨이 관리용 키, database_url은 가상 키·지출 추적·어드민 UI를 쓰려면 나중에 추가하는 값이에요. 지금은 요청이 동작하는 걸 먼저 확인해 볼게요.

게이트웨이 시작하기

작성한 설정으로 게이트웨이를 실행해요.

litellm --config config.yaml

정상적으로 뜨면 프록시가 http://0.0.0.0:4000에서 시작돼요.

첫 요청 보내기

OpenAI 스타일의 chat/completions 요청을 보내요. 인증 헤더에 master_key(여기선 sk-1234)를 넣는 걸 잊지 마세요.

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-1234' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Hello from LiteLLM Gateway"}
    ]
  }'

응답 확인하기

요청이 성공하면 프록시가 200 OK와 OpenAI 스타일 응답을 돌려줘요. 어시스턴트 텍스트는 choices[0].message.content에서 읽을 수 있어요. OpenAI로 라우팅됐다면 대략 이런 응답이 나와요.

{
  "content": "Hello! How can I assist you today?",
  "tool_calls": null,
  "function_call": null,
  "annotations": []
}

id, created, 실제로 해석된 모델 버전, 토큰 수, 메시지 텍스트는 요청마다 달라질 수 있어요. choices[0].message.content가 핵심 필드니까 여기부터 읽으면 돼요. 다른 프로바이더로 라우팅되면 필드가 조금씩 줄거나 달라질 수 있어요.

키와 UI 추가하기

가상 키, 지출 추적, 어드민 UI가 필요해지면 데이터베이스를 추가하는 단계로 넘어가요.

general_settings 아래에 database_url 추가하기
가상 키로 키 생성·예산 관리하기
어드민 UI에서 모델·키 관리하기
더 완전한 구성이 필요하면 Quickstart 문서 참고하기

다음 단계 고르기

LLM 요청 만들기: OpenAI 호환 클라이언트를 게이트웨이로 연결하기
모델 설정: 더 많은 모델과 게이트웨이 설정 추가하기
가상 키: 키·예산·접근 제어 만들기
로깅 추가: 로그·지출·트레이스 수집하기
로드 밸런싱: 배포·리전·프로바이더 간 라우팅하기
가드레일 추가: 안전 검사와 정책 강제하기
신뢰성: 재시도·폴백·타임아웃 구성하기

SDK 경로는 언제 쓰나요

중앙 인증이나 공유 인프라가 필요 없고 한 애플리케이션에서만 모델을 호출한다면 SDK Quickstart를 시작점으로 두는 게 좋아요.

LiteLLM 게이트웨이 퀵스타트