본문으로 건너뛰기

LiteLLM으로 vLLM 앞단 프록시 구축하기

LiteLLM Proxy로 vLLM 백엔드 장애 조치와 SSE 스트리밍을 안정화하는 운영 구성입니다.

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

vLLM 엔진 앞에 LiteLLM Proxy를 배치하면 하나의 OpenAI 호환 엔드포인트에서 소비자별 가상 키, 지출 추적, 중복 백엔드 간 상태 확인과 장애 조치를 통합할 수 있습니다. PostgreSQL과 Prisma를 연결할 때는 LiteLLM 설치 경로의 스키마를 지정해 Prisma generate를 별도로 실행해야 하며, systemd 서비스의 PATH와 초기 마이그레이션 시간을 함께 설정해야 합니다. 동일한 model_name에 여러 백엔드를 등록하면 LiteLLM이 셔플 라우팅과 헬스 체크를 수행하고, 인증 오류·타임아웃·속도 제한별로 서로 다른 실패 허용 횟수를 적용합니다. nginx는 HTTP/1.1, 버퍼링 해제, gzip 비활성화, 충분한 타임아웃으로 SSE 스트리밍을 보존하고 LiteLLM만 재시도 주체로 남겨야 합니다. 또한 LiteLLM 헤더와 문서 경로를 숨기고 readiness 엔드포인트를 외부에 노출하지 않으며, Certbot 갱신 뒤 LiteLLM을 재시작해야 합니다.

섹션별 상세

01
vLLM 서버 여러 대를 직접 노출하면 소비자별 인증, 사용량 집계, 백엔드 장애 조치를 각 서비스가 따로 처리해야 합니다. LiteLLM Proxy는 이 앞단에 하나의 OpenAI 호환 엔드포인트를 만들고 UI에서 소비자별 Virtual Key를 발급하며 PostgreSQL에 운영 정보를 저장합니다. nginx는 TLS를 맡고 systemd는 프로세스와 재시작을 관리해 모델 엔진과 외부 접속 계층을 분리합니다.
bash
LITELLM=~/.local/share/uv/tools/litellm PATH="$LITELLM/bin:$PATH" "$LITELLM/bin/python" -m prisma generate \
 --schema="$LITELLM/lib/python3.12/site-packages/litellm_proxy_extras/schema.prisma"

설치된 LiteLLM 패키지 안의 Prisma 스키마를 지정해 데이터베이스 클라이언트를 생성합니다.

yaml
model_list:
- model_name: glm-5.2
  litellm_params:
    model: openai/glm-5.2
    api_base: http://:8000/v1
    api_key:
    stream_timeout: 900
  model_info:
    health_check_timeout: 5
    input_cost_per_token: 0.00000035
    output_cost_per_token: 0.00000175
- model_name: glm-5.2 # same name, second backend
...
general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true
  health_check_ignore_transient_errors: true
router_settings:
  routing_strategy: simple-shuffle
  enable_weighted_failover: true
  num_retries: 2
  retry_after: 1
  timeout: 5
  cooldown_time: 60
  allowed_fails_policy:
    AuthenticationErrorAllowedFails: 0
    TimeoutErrorAllowedFails: 2
    RateLimitErrorAllowedFails: 5

같은 model_name을 가진 두 백엔드를 하나의 모델 이름으로 묶고 오류 유형별 장애 조치 기준을 설정합니다.

ini
[Service]
User=litellm
EnvironmentFile=/home/litellm/.config/litellm/litellm.env
Environment="PATH=/home/litellm/.local/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/home/litellm/.local/bin/litellm --config /home/litellm/.config/litellm/config.yml
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/home/litellm
PrivateTmp=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
LockPersonality=true
RestrictSUIDSGID=true
CapabilityBoundingSet=
Restart=on-failure
RestartSec=5s
TimeoutStartSec=180

systemd에서 LiteLLM 프로세스의 실행 경로와 권한 제한, 재시작 정책, 초기 마이그레이션 시간을 지정합니다.

nginx
location /v1 {
 proxy_pass http://litellm_backend;
 proxy_http_version 1.1;
 proxy_set_header Connection "";
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_buffering off;
 proxy_request_buffering off;
 proxy_cache off;
 gzip off;
 proxy_connect_timeout 60s;
 proxy_send_timeout 1800s;
 proxy_read_timeout 1800s;
 proxy_next_upstream off;
 proxy_intercept_errors off;
 send_timeout 1800s;
 reset_timedout_connection on;
 lingering_close always;
 lingering_timeout 30s;
}

nginx가 LiteLLM의 SSE 스트림을 버퍼링하거나 중복 재시도하지 않도록 HTTP와 타임아웃을 설정합니다.

nginx
proxy_hide_header x-litellm-model-api-base;
proxy_hide_header x-litellm-model-id;
proxy_hide_header x-litellm-model-name;
proxy_hide_header x-litellm-response-cost;
proxy_hide_header x-litellm-key-spend;
proxy_hide_header x-litellm-key-max-budget;
# ... the rest of the x-litellm-* family
location = /openapi.json { return 404; }
location ^~ /swagger { return 404; }
location = /redoc { return 404; }
location ^~ /docs { return 404; }
location = / { return 404; }

백엔드 주소와 비용 관련 헤더를 숨기고 인증되지 않은 API 문서 및 Swagger 경로를 외부에서 차단합니다.

02
같은 model_name에 두 백엔드를 등록하면 LiteLLM이 하나의 모델 이름 뒤에서 백엔드를 섞어 선택하고 헬스 체크 결과에 따라 문제가 있는 대상을 cooldown 상태로 전환합니다. background_health_checks와 30초 간격의 상태 확인을 켜며, 재시도는 LiteLLM이 담당하도록 설정합니다. AuthenticationError는 허용 횟수를 0으로 두고 TimeoutError는 2회, RateLimitError는 5회로 두어 잘못된 인증 정보와 일시적인 용량 문제를 다르게 처리합니다.
03
LiteLLM은 시작할 때 Prisma를 호출해 데이터베이스 마이그레이션을 수행하지만 번들 스키마 생성이 기본 상태에서 깨질 수 있습니다. 따라서 uv로 설치한 LiteLLM의 Python 실행 파일과 schema.prisma 경로를 명시해 prisma generate를 실행하고, systemd 환경에는 Prisma가 있는 ~/.local/bin을 PATH에 넣어야 합니다. 서비스에는 초기 마이그레이션과 엔진 구동을 고려해 TimeoutStartSec=180을 주고, 실패 시 5초 뒤 재시작하도록 구성합니다.
04
LLM 스트리밍에서 nginx가 응답을 버퍼링하면 SSE 데이터가 배치로 몰려 도착해 정상 연결도 멈춘 것처럼 보입니다. proxy_http_version 1.1, proxy_set_header Connection "", proxy_buffering off, proxy_request_buffering off, gzip off를 함께 적용하고 proxy_read_timeout과 send_timeout을 1800초로 설정해야 합니다. proxy_next_upstream은 끄고 LiteLLM의 stream_timeout보다 nginx 타임아웃을 길게 두어 중복 호출과 비용 집계 오류를 피합니다.
05
LiteLLM 응답에는 x-litellm-model-api-base와 비용·키 사용량 관련 헤더가 포함될 수 있어 백엔드 주소와 내부 운영 정보가 노출됩니다. nginx의 proxy_hide_header로 x-litellm-* 계열을 제거하고 /openapi.json, /swagger, /redoc, /docs, 루트 경로를 404로 막으면 약 1.2 MB 규모의 문서와 504개 엔드포인트가 비인증 상태로 노출되는 문제를 줄일 수 있습니다. /health/readiness는 db 연결 상태를 외부에 반환하므로 loopback으로 제한하고 외부 모니터링에는 /health/liveliness를 사용합니다.
06
Certbot의 webroot 방식은 nginx의 80번 포트에서 /.well-known/acme-challenge/ 검증 파일을 제공할 때 동작하며, 나머지 요청은 HTTPS로 리디렉션할 수 있습니다. 첫 DNS 영역에서 전파 문제로 ACME 검증이 실패한 사례가 있어 발급 오류가 nginx 설정만의 문제인지 DNS 전파 문제인지 분리해 확인해야 합니다. 인증서 갱신 후에는 renewal hook에서 systemctl restart litellm을 실행해 포트를 점유한 LiteLLM이 새 인증서를 사용하게 합니다.

용어 해설

서버 전송 이벤트(SSE)
서버가 하나의 HTTP 연결을 유지하면서 생성 중인 응답을 클라이언트로 조금씩 보내는 방식입니다. LLM 스트리밍에 쓰이지만 프록시 버퍼링이나 HTTP 버전 설정이 맞지 않으면 응답이 한꺼번에 도착하거나 중단된 것처럼 보일 수 있습니다.
가상 키(Virtual Key)
공통 API 자격 증명 대신 소비자별로 발급하는 LiteLLM용 인증 키입니다. UI에서 키를 만들고 소비자별 사용량과 지출을 추적할 수 있어 백엔드 모델 서버의 실제 인증 정보를 외부에 노출하지 않습니다.
장애 조치 라우팅(Failover Routing)
동일한 모델 이름에 연결된 여러 백엔드 중 하나가 실패하면 다른 백엔드로 요청을 넘기는 방식입니다. 오류 유형별 허용 실패 횟수와 cooldown을 함께 설정해 잘못된 인증 키와 일시적 장애를 구분합니다.
Prisma
LiteLLM Proxy가 PostgreSQL 데이터베이스 스키마를 적용하고 생성할 때 호출하는 데이터베이스 도구입니다. 기본 설치만으로는 번들 스키마 생성이 정상 작동하지 않아 설치된 패키지의 schema.prisma를 지정해 별도로 실행해야 합니다.
ACME 인증(ACME)
Certbot이 인증 기관과 통신해 TLS 인증서 발급 및 갱신을 처리하는 프로토콜입니다. 이 구성에서는 nginx의 80번 포트가 webroot 경로의 검증 파일을 제공하고, DNS 전파 문제가 발급 실패 원인이 될 수 있습니다.

기술

  • LiteLLM
  • vLLM
  • PostgreSQL
  • nginx
  • systemd
  • uv
  • Prisma
  • Certbot

활용 사례

  • 여러 vLLM 백엔드를 하나의 OpenAI 호환 API로 제공하는 내부 플랫폼
  • 소비자별 Virtual Key와 지출을 관리하는 공용 LLM 게이트웨이
  • SSE 기반 LLM 스트리밍을 nginx 뒤에서 운영하는 서비스
  • 백엔드 장애 시 자동으로 다른 모델 서버로 전환하는 추론 인프라
AI 분석 전체 내용 보기

AI 요약 · 북마크 · 개인 피드 설정 — 무료

출처 · 인용 안내

원문 발행 2026. 09. 09.수집 2026. 09. 10.출처 타입 RSS

인용 시 "요약 출처: AI Trends (aitrends.kr)"를 표기하고, 사실 확인은 원문 보기 기준으로 진행해 주세요. 자세한 기준은 운영 정책을 참고해 주세요.