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을 재시작해야 합니다.
섹션별 상세
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 스키마를 지정해 데이터베이스 클라이언트를 생성합니다.
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을 가진 두 백엔드를 하나의 모델 이름으로 묶고 오류 유형별 장애 조치 기준을 설정합니다.
[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=180systemd에서 LiteLLM 프로세스의 실행 경로와 권한 제한, 재시작 정책, 초기 마이그레이션 시간을 지정합니다.
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와 타임아웃을 설정합니다.
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 경로를 외부에서 차단합니다.
용어 해설
- 서버 전송 이벤트(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 Trends (aitrends.kr)"를 표기하고, 사실 확인은 원문 보기 기준으로 진행해 주세요. 자세한 기준은 운영 정책을 참고해 주세요.
