SSD Nodes Learn 🎉 VPS $4.99/월부터
가이드 Matt Connor작성자 Matt Connor

LiteLLM 자체 호스팅으로 통합 LLM 게이트웨이 구축하기

LiteLLM을 사용하여 여러 LLM 공급자를 하나의 OpenAI 호환 엔드포인트로 통합하는 방법을 알아봅니다. VPS 환경에서 가상 키 관리, 예산 설정, 모델 폴백 및 요청 로그 기록을 구현하여 LLM 인프라를 효율적으로 운영하는 구체적인 가이드를 제공합니다.

자체 호스팅 LLM 게이트웨이의 역할

LiteLLM은 직접 호스팅하는 오픈 소스 LLM 게이트웨이입니다. 모든 애플리케이션이 하나의 HTTP 엔드포인트로 요청을 보내면, 게이트웨이가 이를 적절한 공급자에게 전달합니다. LLM은 거대 언어 모델(Large Language Model)을 의미합니다. 이 게이트웨이는 OpenAI의 Chat Completions API(애플리케이션 프로그래밍 인터페이스)를 지원하므로, 기존에 OpenAI와 통신하던 모든 클라이언트 라이브러리는 베이스 URL과 키라는 두 가지만 변경하면 바로 사용할 수 있습니다.

이러한 간접 계층을 두는 것이 핵심입니다. 애플리케이션이 직접 공급자의 자격 증명을 관리할 필요가 없습니다. 모델을 교체할 때 5개의 서비스 코드를 수정하는 대신, 서버의 설정 파일 한 줄만 바꾸면 됩니다. 모든 호출이 하나의 프로세스를 거치므로, 예산을 설정하고 사용량을 기록할 수 있는 중앙 지점이 생깁니다.

게이트웨이를 실행하면 다음과 같은 기능을 활용할 수 있습니다.

  • 단일 엔드포인트. 애플리케이션은 https://gateway.example.com/v1을 대상으로 요청을 보내며, bulk이나 strong과 같이 사용자가 정의한 모델 이름을 호출합니다.
  • 가상 키. 각 애플리케이션은 고유한 모델 허용 목록과 지출 한도가 설정된 개별 키를 발급받습니다. 다른 애플리케이션에 영향을 주지 않고 특정 키만 취소할 수 있습니다.
  • 폴백(Fallback). 호출 실패나 프롬프트 크기 초과 시 다른 모델로 자동으로 재시도합니다.
  • 로그 기록. 모든 요청은 비용 정보를 포함하여 기록되므로, 어떤 애플리케이션이 비용을 발생시켰는지 명확히 파악할 수 있습니다.

게이트웨이를 직접 운영해야 하는 이유

관리형 라우터는 사용자와 동일한 형태를 띠지만, 모든 요청의 중간에 타인의 프로세스가 개입합니다. 직접 운영하면 공급자의 키와 프롬프트 텍스트를 사용자가 제어하는 서버에 보관할 수 있습니다. 물론 그에 따른 비용은 실재합니다. 이제 모든 애플리케이션이 의존하는 구성 요소를 직접 운영해야 하기 때문입니다. 이 가이드의 마지막 섹션에서는 그 비용에 대해 다룹니다. 대부분의 문서에서 간과하는 부분이기 때문입니다.

준비 사항

  • Ubuntu 24.04가 설치된 VPS(가상 사설 서버)와 Docker 및 Compose 플러그인.
  • 외부 기기가 TLS(전송 계층 보안)를 통해 게이트웨이에 접근할 경우, 해당 서버를 가리키는 도메인 이름.
  • 최소 하나 이상의 공급자 API 키.

게이트웨이는 추론을 수행하지 않습니다. 요청을 전달하고 응답을 스트리밍으로 반환하므로, CPU 부하는 모델 크기가 아닌 요청량에 따라 결정됩니다. 1 vCPU 사양의 서버로도 내부 애플리케이션 몇 개는 무리 없이 운영할 수 있습니다. 데이터베이스는 요청마다 사용량 행을 기록하므로 데이터가 계속 증가합니다.

config.yaml 먼저 작성하기

설정 파일은 클라이언트가 요청할 수 있는 모델을 결정합니다. model_list, litellm_settings, router_settings, general_settings라는 4개의 최상위 섹션이 중요합니다.

model_list:
  - model_name: bulk
    litellm_params:
      model: anthropic/claude-haiku-4-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: strong
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: strong
    litellm_params:
      model: openai/gpt-5.5
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  num_retries: 2
  request_timeout: 120
  allowed_fails: 3
  cooldown_time: 30
  json_logs: true
  set_verbose: false

router_settings:
  fallbacks: [{"bulk": ["strong"]}]
  context_window_fallbacks: [{"bulk": ["strong"]}]

general_settings:
  background_health_checks: true
  health_check_interval: 300

model_name은 클라이언트가 전송하는 이름입니다. litellm_params.model는 provider/model로 작성된 실제 모델입니다. 모델 이름은 공급업체 이름이 아닌 작업 용도에 따라 지정하십시오. bulk을 요청하는 애플리케이션은 다음 달에 bulk을 다른 모델로 변경하기로 결정하더라도 계속 정상적으로 작동합니다.

api_key: os.environ/ANTHROPIC_API_KEY은 LiteLLM에게 런타임에 해당 변수를 읽도록 지시합니다. 리터럴 키는 파일에 나타나지 않으며, 이는 config.yaml을 커밋해야 하므로 중요한 부분입니다.

두 개의 항목이 의도적으로 strong라는 이름을 공유합니다. 둘 이상의 배포가 동일한 model_name을 가지면, 라우터는 이를 상호 교환 가능한 것으로 간주하고 첫 번째 배포가 실패할 경우 다른 배포를 시도합니다. 이것이 strong이 특정 공급자의 일시적인 장애 상황에서도 살아남는 방식입니다.

num_retries: 2는 재시도 가능한 오류 발생 시 동일한 배포에 대해 재시도를 수행합니다. 폴백(fallback)은 해당 재시도 횟수를 모두 소진한 후에만 작동합니다. cooldown_time: 30가 포함된 allowed_fails: 3은 배포가 3회 실패하면 30초 동안 해당 배포를 로테이션에서 제외하므로, 500 오류를 반환하는 공급자에게 모든 요청이 시도되는 것을 방지합니다.

fallbacks와 context_window_fallbacks은 트리거 조건이 다르며, 두 번째 항목은 사람들이 자주 간과하지만 유용한 기능입니다.

  • fallbacks은 기본 호출이 실패할 때 작동합니다.
  • context_window_fallbacks은 공급자가 해당 모델의 컨텍스트 윈도우보다 요청이 길다는 이유로 거부할 때 작동합니다. 따라서 크기가 너무 큰 프롬프트는 호출자에게 오류를 반환하는 대신 여유 공간이 있는 모델로 전달됩니다.

공급자가 콘텐츠 정책을 이유로 거부하는 경우를 위한 content_policy_fallbacks도 있습니다. 해당 호출을 보낼 적절한 대상이 있는 경우에만 설정하십시오.

Docker Compose를 사용하여 VPS에 LiteLLM 배포하기

세 개의 파일인 config.yaml, docker-compose.yml, .env를 담을 디렉터리를 생성합니다. 공식 퀵스타트 가이드는 latest 태그를 가져오도록 되어 있습니다. 대신 특정 릴리스 태그를 고정하십시오. 그래야 다음 달에 docker compose up -d를 실행해도 오늘과 동일한 게이트웨이가 유지되며, 롤백 또한 한 줄의 명령어로 가능해집니다.

services:
  litellm:
    image: ghcr.io/berriai/litellm:v1.95.0
    restart: unless-stopped
    command: ["--config", "/app/config.yaml", "--num_workers", "1"]
    ports:
      - "127.0.0.1:4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    env_file: .env
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: litellm
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Compose는 여기서 .env를 두 번 읽습니다. 한 번은 compose 파일 내부의 ${POSTGRES_PASSWORD}을 치환하기 위함이고, 다른 한 번은 env_file을 통해 모든 변수를 컨테이너 내부로 전달하기 위함입니다.

v1.95.0은 2026년 8월 기준 최신 릴리스였습니다. 프로젝트의 릴리스 페이지를 확인하고 배포 시점의 최신 버전을 고정하십시오. 각 릴리스는 서명을 게시하므로, 이미지를 신뢰하기 전에 검증할 수 있습니다.

cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0

포트 설정 줄은 127.0.0.1:4000:4000이며, 이는 루프백 인터페이스에만 포트를 게시합니다. 대신 4000:4000으로 작성하면 게이트웨이가 인터넷 전체에서 접근 가능해집니다. Docker는 iptables의 FORWARD 체인에 자체 규칙을 추가하는데, 이 규칙은 ufw보다 먼저 평가되므로 ufw deny 4000로는 이를 차단할 수 없기 때문입니다. 이는 자가 호스팅 게이트웨이가 외부로 노출되는 가장 흔한 경로입니다. Docker가 ufw를 우회하여 컨테이너 포트를 게시하는 방식을 참조하십시오. 외부 트래픽은 리버스 프록시를 통해서만 유입되어야 합니다.

공급자 키를 이미지에 포함하지 않기

.env 파일은 모든 비밀 정보를 담고 있습니다. 이 파일은 런타임에 환경 변수로 전달되므로 이미지에 포함되지 않으며, 저장소에 커밋되지도 않습니다.

LITELLM_MASTER_KEY=sk-REPLACE_ME
LITELLM_SALT_KEY=sk-REPLACE_ME_TOO
POSTGRES_PASSWORD=REPLACE_ME_AS_WELL
DATABASE_URL=postgresql://litellm:REPLACE_ME_AS_WELL@db:5432/litellm
STORE_MODEL_IN_DB=True
LITELLM_MODE=PRODUCTION
LITELLM_LOG=ERROR
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...

무작위 값을 사용하여 두 개의 LiteLLM 키를 생성한 다음, 파일 권한을 제한합니다.

printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .env

LITELLM_MASTER_KEY은 관리자 자격 증명입니다. 이 값은 관리 API를 인증하며 /ui의 관리자 UI 비밀번호로 사용됩니다. 어떠한 애플리케이션도 이 값을 보유해서는 안 됩니다.

LITELLM_SALT_KEY는 데이터베이스에 저장된 공급자 자격 증명을 암호화합니다. 이 값은 한 번 설정한 뒤 그대로 유지해야 합니다. 나중에 이 값을 변경하면 이미 저장된 자격 증명을 복호화할 수 없게 됩니다. 이 경우 게이트웨이는 정상적으로 시작되지만, 해당 공급자를 호출할 때마다 인증 오류가 발생합니다.

STORE_MODEL_IN_DB=True을 사용하면 config.yaml을 수정하지 않고도 관리자 UI에서 모델을 추가하거나 편집할 수 있습니다. 이는 편리하지만, 진실의 원천(source of truth)이 두 곳으로 나뉘게 됩니다. 어느 쪽을 우선할지 결정하고, 그 내용을 설정 파일 옆에 기록해 두십시오.

키를 설정 파일에 포함하지 않는 논리는 에이전트에 제공하는 도구에서 키를 제외하는 논리와 같습니다. AI 에이전트에서 공급자 비밀 정보 제외하기에서 해당 패턴을 다루며, Docker Compose의 env 파일과 비밀 정보에서 구체적인 구현 방법을 설명합니다.

서비스를 실행하고 첫 부팅 과정을 확인합니다.

docker compose up -d
docker compose logs -f litellm

작동 여부 확인

인증이 필요 없는 프로브 2개와 인증이 필요한 프로브 1개가 있으며, 각각 실패하는 원인이 다릅니다.

curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness

/health/liveliness은(는) 인증이 필요 없으며 프로세스가 실행 중일 때 "I'm alive!"을(를) 반환합니다. /health/readiness 또한 인증이 필요 없습니다. 이 프로브는 "status": "healthy" 및 db 필드가 포함된 JSON 객체를 반환하거나, 데이터베이스에 연결할 수 없는 경우 503 오류를 반환합니다. 단일 가상 키를 조회할 수 없는 게이트웨이에서도 liveliness는 정상(green)으로 유지되므로, 모니터링 대상을 readiness로 설정하십시오.

인증이 필요한 체크는 공급자(provider)와 통신하는 프로브입니다.

curl -s http://127.0.0.1:4000/health \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

이 프로브는 healthy_endpoints 및 unhealthy_endpoints 배열로 응답합니다. unhealthy_endpoints에 있는 모델에서 인증 오류가 발생한다면 .env의 공급자 키가 잘못되었거나 누락된 것이며, 이는 현재 찾아내야 할 실패 원인입니다. background_health_checks: true이(가) 설정되어 있으므로 프록시는 health_check_interval초마다 자체적으로 이러한 프로브를 실행하고 /health은(는) 마지막 결과를 반환합니다. 따라서 폴링을 수행할 때마다 공급자에게 테스트 요청을 보내지는 않습니다.

가상 키와 키별 예산

모든 애플리케이션은 마스터 키를 기반으로 생성된 고유의 키를 할당받습니다.

curl -s http://127.0.0.1:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "key_alias": "nightly-summariser",
    "models": ["bulk"],
    "max_budget": 5,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "tpm_limit": 200000
  }'

응답에는 sk-으로 시작하는 key 필드가 포함됩니다. 이 문자열이 애플리케이션에 전달되며, 애플리케이션이 접근할 수 있는 유일한 정보입니다.

  • models은 해당 키가 요청할 수 있는 작업의 허용 목록입니다. 위 키는 bulk만 요청할 수 있으며 다른 작업은 불가능합니다.
  • max_budget: 5과 budget_duration: "30d"를 설정하면 30일 주기로 5달러의 예산이 적용되며, 이를 초과하면 키가 작동을 멈춥니다.
  • rpm_limit와 tpm_limit은 해당 키에 대한 분당 요청 수와 분당 토큰 수를 제한합니다.
  • key_alias은 6주 뒤 지출 로그에서 확인할 식별자입니다. 항상 설정하십시오.

예산이 소진되면 호출은 HTTP 401 오류를 반환하며, 응답 본문은 다음과 같은 형태를 띱니다.

ExceededBudget: Current spend for token: 7.2e-05; Max Budget for Token: 2e-07

상태 코드로 인해 혼란이 발생할 수 있습니다. 클라이언트 라이브러리는 401을 인증 문제로 보고하므로, 스택 트레이스를 확인하는 개발자는 키의 유효성부터 점검하게 됩니다. 상태 코드와 함께 응답 본문을 로그에 기록하십시오. 그렇지 않으면 예산 소진이 매번 자격 증명 오류로 보일 것입니다.

동일한 관리 API를 통해 키를 조회하고 조정할 수 있습니다.

curl -s "http://127.0.0.1:4000/key/info?key=sk-..." \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

curl -s -X POST http://127.0.0.1:4000/key/update \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"key": "sk-...", "max_budget": 25}'

게이트웨이에서 강제되는 예산은 에이전트 자체에 문제가 발생한 경우에도 유지됩니다. 이것이 바로 VPS에서 AI 에이전트 비용을 제어하는 방법의 핵심인 이유입니다.

저렴한 모델로 대량 작업 전송

클라이언트를 게이트웨이로 지정합니다. 기본 URL, 키, 모델 이름은 다음과 같습니다.

curl -s http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-<the virtual key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "bulk",
    "messages": [{"role": "user", "content": "Say hello in five words."}]
  }'

모든 OpenAI 클라이언트 라이브러리는 동일하게 동작합니다. base_url을 https://gateway.example.com/v1로, api_key을 가상 키로 설정하십시오.

이제 호출자가 알지 못하는 사이에 config.yaml의 라우팅 정책이 적용됩니다. bulk에 대한 요청은 저렴한 모델로 전달됩니다. 해당 호출이 재시도 후에도 실패하면, 요청은 strong를 대상으로 다시 시도됩니다. 프롬프트가 bulk에 비해 너무 길면, context_window_fallbacks는 오류를 반환하는 대신 이를 strong로 보냅니다. 분류 작업이나 요약 백로그와 같은 대량 작업은 기본적으로 저렴하게 실행되며, 어려운 요청에 대해서만 더 많은 비용이 발생합니다.

이 지점이 바로 게이트웨이가 도구를 사용하는 에이전트와 함께 그 가치를 증명하는 곳입니다. 동일한 VPS의 MCP (model context protocol) 서버와 이를 구동하는 에이전트 모두 하나의 엔드포인트를 가리킬 수 있으므로, 둘 중 어느 것도 재배포할 필요 없이 배후의 모델을 변경할 수 있습니다.

폴백(fallback) 발생 여부를 확인하는 방법

이것은 아무것도 고장 난 것처럼 보이지 않기 때문에 비용을 발생시키는 실패 유형입니다. 성공적인 폴백은 일반적인 응답 본문과 함께 HTTP 200을 반환합니다. 저렴한 모델이 하루 종일 중단되어 모든 호출이 비싼 모델에 의해 조용히 처리되더라도, 첫 번째 증거는 청구서에서 나타납니다.

증거는 응답 헤더에 존재합니다. 다음 헤더를 확인하십시오.

curl -s -D - -o /dev/null http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-<the virtual key>" \
  -H 'Content-Type: application/json' \
  -d '{"model":"bulk","messages":[{"role":"user","content":"ping"}]}' \
  | grep -i '^x-litellm'
  • x-litellm-model-group은 클라이언트가 요청한 모델입니다. x-litellm-model-id은 응답한 배포 모델입니다. 이 두 값이 일치하지 않으면 폴백이 발생한 것입니다.
  • x-litellm-attempted-fallbacks과 x-litellm-attempted-retries는 폴백 횟수를 집계합니다. 정상적인 호출에서는 둘 다 0입니다.
  • x-litellm-response-cost은 해당 호출 한 건에 대한 미국 달러 기준 비용입니다.
  • x-litellm-call-id은 로그에서 동일한 호출을 찾을 때 사용하는 식별자입니다.

모든 요청에 대해 x-litellm-attempted-fallbacks를 기록하고, 이 값이 0이 아닐 때 알림을 설정하십시오. 이 숫자 하나가 정상적으로 작동하는 라우팅 정책과 "항상 비싼 모델을 사용"하도록 조용히 변경된 라우팅 정책을 구분 짓는 차이입니다.

이 과정의 완전한 버전은 트레이싱(tracing)이며, 별도의 설정이 필요합니다: 에이전트 호출 트레이싱을 위한 자체 호스팅 Langfuse. LiteLLM은 콜백을 제공하므로, 자격 증명과 두 줄의 코드만 추가하면 연결할 수 있습니다.

litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.com

failure_callback와 success_callback를 모두 설정하십시오. 이를 건너뛰면 아무런 문제가 발생하지 않은 요청에 대한 트레이스만 남게 됩니다. 이와 별도로, LiteLLM은 요청당 비용 행을 Postgres에 기록하며 /ui의 관리자 UI가 해당 테이블을 읽습니다. 트래픽이 증가함에 따라 테이블 크기도 커지므로 작은 디스크 공간을 사용할 때는 주의 깊게 모니터링하십시오.

게이트웨이를 리버스 프록시 뒤에 배치하기

외부에서 포트 4000에 직접 접근할 수 없어야 합니다. nginx나 Caddy에서 TLS를 종료하고 루프백 주소로 전달하십시오.

location / {
    proxy_pass http://127.0.0.1:4000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 600s;
}

이 줄들 중 두 가지는 사용자들이 흔히 누락하는 설정입니다. proxy_buffering off은 스트리밍 완료가 서버 전송 이벤트(server-sent events)의 연속이기 때문에 중요합니다. nginx에서 버퍼링이 활성화되어 있으면 응답이 끝날 때까지 청크를 보관하므로, 클라이언트는 아무런 응답을 받지 못하다가 한꺼번에 모든 데이터를 받게 됩니다. proxy_read_timeout 600s은 긴 생성 작업이 nginx의 기본값인 60초를 초과할 수 있기 때문에 중요합니다. 이 시간이 지나면 클라이언트는 504 오류를 받게 되며, 오류 로그에는 upstream timed out (110: Connection timed out) while reading response header from upstream이 기록됩니다.

인증서의 경우, nginx에서 Certbot과 Let's Encrypt 사용하기가 가장 빠른 방법입니다. 이미 여러 컨테이너를 운영 중이라면, 여러 Compose 앱 앞단에 Traefik 배치하기를 통해 라우팅과 인증서를 한곳에서 관리할 수 있습니다.

게이트웨이가 단일 장애 지점이 되었습니다

구축한 시스템의 현실을 직시해야 합니다. 이제 모든 애플리케이션이 단일 VPS의 컨테이너 하나에 의존합니다. 해당 컨테이너가 중단되면, 정상 상태인 공급자를 포함하여 그 어떤 모델도 호출할 수 없습니다. 이로 인해 다음 네 가지 사항이 발생합니다.

  • 잘못된 설정은 모든 서비스를 한 번에 중단시킵니다. restart: unless-stopped는 충돌을 재시작하며, config.yaml을 파싱할 수 없는 컨테이너를 계속해서 재시작합니다. 설정 변경 후에는 반드시 docker compose logs litellm을 읽어야 하며, 변경 사항을 모니터링할 시간이 있을 때 설정을 수정하십시오.
  • Postgres가 요청 경로에 위치합니다. 가상 키 조회와 사용량 기록 모두 데이터베이스를 사용합니다. /health/readiness이 503 오류를 반환한다면, 게이트웨이는 실행 중이지만 두 작업 모두 수행할 수 없다는 경고입니다.
  • 인스턴스를 늘려 확장하고, 단일 인스턴스를 키우지 마십시오. 이 프로젝트의 자체 지침은 여러 인스턴스가 하나의 데이터베이스를 공유하는 환경에서 인스턴스당 하나의 워커를 두는 것입니다(--num_workers 1). 로드 밸런서 뒤에 두 개의 작은 게이트웨이를 배치하면 단일 컨테이너 문제를 해결할 수 있습니다. 단, 데이터베이스 문제는 해결되지 않습니다.
  • 재생성할 수 없는 데이터는 백업하십시오. 이는 config.yaml 및 .env, 그리고 데이터베이스의 pg_dump를 의미합니다. LITELLM_SALT_KEY을 분실하면 덤프 내의 암호화된 공급자 자격 증명을 사용할 수 없게 되므로, env 파일과 덤프는 동일한 백업 작업에 포함해야 합니다: restic을 이용한 외부 저장소 백업.

업그레이드는 이미지 태그를 수정하고 docker compose up -d을 실행하는 과정입니다. LiteLLM은 기본적으로 시작 시 prisma migrate deploy을 실행하므로, 새 컨테이너는 첫 부팅 시 데이터베이스 스키마를 마이그레이션합니다. 태그를 변경하기 전에 덤프를 생성하십시오. 이전 이미지로 되돌려도 이미 실행된 마이그레이션은 취소되지 않기 때문입니다.

FAQ

LiteLLM은 모든 호출에 눈에 띄는 지연 시간을 추가합니까?

이 프로젝트는 2026년 8월 README에서 초당 1000건의 요청 시 95번째 백분위수에서 8 ms의 지연 시간이 발생한다고 명시했습니다. 이는 공급업체의 수치로 간주하십시오. 실제로 지연 시간에 영향을 주는 수치는 애플리케이션과 게이트웨이 사이의 네트워크 거리입니다. 모든 호출에 왕복 시간이 한 번 추가되기 때문입니다. 게이트웨이를 호출하는 애플리케이션과 동일한 리전에서 실행하고, 실제 응답에서 x-litellm-overhead-duration-ms 헤더를 사용하여 직접 오버헤드를 측정하십시오.

nginx를 앞에 두었더니 스트리밍이 작동하지 않는 이유는 무엇입니까?

nginx는 기본적으로 업스트림 응답을 버퍼링하며, 스트리밍 완료는 서버 전송 이벤트(server-sent events)의 연속이기 때문입니다. proxy_buffering이 켜져 있으면 nginx는 청크를 수집했다가 응답이 완료될 때만 한꺼번에 전달하므로, 클라이언트는 아무런 응답을 받지 못하고 대기하다가 전체 답변을 한 번에 받게 됩니다. location 블록에 proxy_buffering off;을 설정하십시오. 또한 동일한 블록에서 proxy_read_timeout 값을 높이십시오. 긴 생성 작업은 nginx의 기본값인 60초를 초과하여 클라이언트가 504 오류를 받을 수 있기 때문입니다.

가상 키의 예산이 소진되면 어떻게 됩니까?

호출은 HTTP 401 오류와 함께 ExceededBudget: Current spend for token: 7.2e-05; Max Budget for Token: 2e-07 형식의 본문을 반환하며 실패합니다. 401 오류는 함정입니다. 클라이언트 라이브러리는 이를 인증 실패로 보고하므로, 사용자들은 메시지를 읽는 대신 키가 유효한지 확인하기 시작합니다. 상태 코드와 함께 응답 본문을 로그에 기록하십시오. 마스터 키를 사용하여 /key/info?key=sk-...로 키의 실제 상태를 확인하고, 예산이 너무 낮게 설정되었다면 /key/update로 한도를 높이십시오.

게이트웨이가 호스팅된 모델뿐만 아니라 로컬 모델로도 라우팅할 수 있습니까?

네, 가능하며 model_list에 항목을 하나 더 추가하면 됩니다. ollama_chat/ 접두사와 api_base을 사용하십시오. 예를 들어 api_base: http://ollama:11434과 함께 model: ollama_chat/llama3.1를 사용할 수 있습니다. 컨테이너 내부에서 localhost은 해당 컨테이너를 의미하므로, Compose 서비스 이름이나 Docker 네트워크상의 호스트 주소를 사용하십시오. 127.0.0.1는 절대 사용하지 마십시오. 로컬 모델을 구축하는 것은 별도의 작업입니다. Ollama를 사용하여 VPS에서 LLM 직접 호스팅하기를 참조하십시오.

#litellm#llm-gateway#self-hosted-ai#docker#cost-control