LiteLLM 프록시

quant-ai의 LLM 분석 워커는 OpenAI 호환 인터페이스로만 통신합니다 — 즉, OpenAI / Azure OpenAI / Anthropic / 로컬 vLLM 등 어떤 프로바이더든 앞단에 LiteLLM proxy를 두면 코드 변경 없이 라우팅이 가능합니다.

사전 요구 사항

• LiteLLM proxy 호스트 (Docker / k8s / managed)
• 프로바이더 API 키 (OpenAI, Anthropic 등) — proxy 측에서 보관
• quant-ai 측은 OPENAI_BASE_URL + OPENAI_API_KEY 두 개만 알면 됨

1. LiteLLM proxy 셋업 (예시)

litellm_config.yaml:

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-haiku
    litellm_params:
      model: anthropic/claude-3-5-haiku-20241022
      api_key: os.environ/ANTHROPIC_API_KEY

litellm_settings:
  set_verbose: false
  drop_params: true
  num_retries: 3
  request_timeout: 60

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL  # 예산 추적
  max_budget: 100.0
  budget_duration: 30d

# 도커로 띄우기
docker run -d \
  --name litellm-proxy \
  -p 4000:4000 \
  -e OPENAI_API_KEY=sk-... \
  -e ANTHROPIC_API_KEY=... \
  -e LITELLM_MASTER_KEY=sk-1234 \
  -v $(pwd)/litellm_config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml --port 4000

2. quant-ai 연결

.env에 다음을 설정합니다.

OPENAI_BASE_URL=http://litellm-proxy:4000        # docker compose 네트워크 내부
OPENAI_API_KEY=sk-1234                            # litellm master key
OPENAI_MODEL_DEFAULT=gpt-4o-mini                  # 기본 모델
OPENAI_MODEL_DECISION=gpt-4o                      # 의사결정 모델
LLM_TIMEOUT_SECONDS=60
LLM_MAX_RETRIES=3
LLM_DAILY_BUDGET_USD=5.00

OPENAI_BASE_URL이 비어 있으면 OpenAI 직결이 됩니다 — proxy를 끼지 않고도 동작은 합니다. 운영 환경에서는 항상 proxy를 권장합니다.

3. 모델 라우팅 패턴

quant-ai의 분석 워커는 두 단계로 모델을 호출합니다.

단계	모델 변수	의도
1차 컨텍스트 요약	OPENAI_MODEL_DEFAULT	싸고 빠른 모델로 입력 정제
2차 의사결정	OPENAI_MODEL_DECISION	더 큰 모델로 최종 추천 / 신뢰도 산출

비용 절감을 위해 1차에 mini를, 2차에 large를 두는 패턴이 표준입니다. Claude/Gemini로 라우팅 변경은 litellm_config.yaml에서만 바꾸고 quant-ai 코드는 건드리지 않습니다.

4. 예산 한도

LLM_DAILY_BUDGET_USD는 클라이언트 측 가드 입니다 (분석 워커가 analysis_reports.cost_usd의 일일 합산이 임계를 넘으면 큐 적재 자체를 거부). LiteLLM 측의 max_budget 은 서버 측 가드로 더 강력합니다 — proxy가 429를 반환합니다.

위치	효과	권장 사용
LLM_DAILY_BUDGET_USD (quant-ai)	사용자 친화 메시지	사용자별 / 스택별
litellm_config.yaml max_budget	강제 차단	인프라 보호

서버 측 한도가 더 작으면 클라이언트에 429가 오고, quant-ai는 자동으로 analysis_reports.status='failed'로 마킹합니다 — LLM 예산 초과에서 다룹니다.

5. 검증

# 1. proxy 직접 호출
curl -s -X POST http://localhost:4000/chat/completions \
  -H "Authorization: Bearer sk-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role":"user","content":"ping"}],
    "max_tokens": 5
  }' | jq .

# 2. quant-ai 워커 경로
docker compose exec api python -c "
import os
from openai import OpenAI
c = OpenAI(base_url=os.environ['OPENAI_BASE_URL'], api_key=os.environ['OPENAI_API_KEY'])
r = c.chat.completions.create(
    model=os.environ.get('OPENAI_MODEL_DEFAULT','gpt-4o-mini'),
    messages=[{'role':'user','content':'ping'}],
    max_tokens=5,
)
print(r.choices[0].message.content)"

6. 트러블슈팅

증상	원인 / 조치
401 Unauthorized	OPENAI_API_KEY(=master_key) 불일치 → proxy의 LITELLM_MASTER_KEY와 일치시키기
404 model not found	litellm_config.yaml의 model_list에 OPENAI_MODEL_DEFAULT/DECISION 이름이 없음. 추가 후 proxy 재시작
429 Budget exceeded	LiteLLM 서버측 예산 도달. quant-ai는 자동으로 큐 거부. 한도 조정 또는 익일 대기 → LLM 예산 초과
응답이 매우 느림	proxy retry / 모델 응답 시간. LLM_TIMEOUT_SECONDS 상향 또는 OPENAI_MODEL_DEFAULT를 더 작은 모델로
모든 호출이 timeout	proxy 호스트 도달 불가. docker compose exec api curl http://litellm-proxy:4000/health 로 네트워크 확인

관련 페이지

• 환경변수 카탈로그
• LLM 예산 초과
• Grafana — LLM Cost Tracking