LiteLLM 예산 폴백

LiteLLM 예산 폴백 (Budget Fallbacks)

모델별로 예산이 다 소진됐을 때, 평소처럼 budget_exceeded 오류를 던지는 대신 요청을 다른 모델로 조용히 넘겨주면 서비스가 끊기지 않습니다. LiteLLM의 budget fallbacks는 키(key)의 model_max_budget이 초과됐을 때 요청을 폴백 모델로 재라우팅해 주는 기능입니다. v1.92.x 이상에서 사용할 수 있습니다.

출처: 공식문서 - Budget Fallbacks

왜 필요한가

기본적으로 model_max_budget은 키가 특정 모델에 쓴 지출이 상한을 넘으면 요청을 차단합니다. budget fallbacks를 쓰면 키 자체에 모델별 폴백 체인을 설정할 수 있고, 예산이 소진되면 요청이 조용히 예산이 남아 있는 첫 번째 폴백 모델로 넘어갑니다. 이때 지출은 소진된 모델이 아니라 폴백 모델에 귀속됩니다.

이 설정은 가상 키 설정이므로 config.yaml이나 라우터 레벨 폴백을 바꿀 필요가 없습니다.

언제 트리거되나

폴백은 다음 조건이 모두 성립할 때 적용됩니다.

키가 요청한 모델에 대해 model_max_budget을 설정했고, 그 모델의 누적 지출이 budget_limit을 넘은 경우
키가 해당 모델에 대해 budget_fallbacks 항목을 가진 경우
체인에서 첫 번째로 자기 예산 내에 있는 폴백(해당 모델에 모델 예산 항목이 없거나 상한에 도달하지 않은 경우)이 선택됨 — 모든 폴백이 예산을 초과했다면 원래의 BudgetExceededError가 발생

라우터 레벨 폴백(config.yaml의 fallbacks: [{model: [...]}])은 영향을 받지 않고, 다운스트림 프로바이더 오류 시 계속 동작합니다. budget fallbacks는 auth 레이어 내부의 키별 model_max_budget 검사에만 적용됩니다.

Quick Start

1. 모델별 예산과 폴백 체인이 있는 키 만들기

curl 'http://0.0.0.0:4000/key/generate' \
  --header 'Authorization: Bearer sk-1234' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_max_budget": {
      "anthropic-haiku-4-5": {"budget_limit": 0.01, "time_period": "1d"}
    },
    "budget_fallbacks": {
      "anthropic-haiku-4-5": ["gpt-5.6-terra"]
    }
  }'

budget_fallbacks는 주 모델 이름을 키로 하는 Dict[str, List[str]]이며, 값은 그 모델의 정렬된 폴백 체인입니다.

2. 요청 보내기

클라이언트는 평소처럼 주 모델을 가리킵니다.

curl 'http://0.0.0.0:4000/v1/chat/completions' \
  --header 'Authorization: Bearer <sk-generated-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "anthropic-haiku-4-5",
    "messages": [{"role": "user", "content": "hello"}]
  }'

키가 anthropic-haiku-4-5 상한 아래에 있는 동안 요청은 anthropic-haiku-4-5에서 실행됩니다. 상한을 넘으면 이후 요청은 호출자에게 아무런 budget_exceeded 오류를 노출하지 않고 transparent하게 gpt-5.6-terra가 처리합니다.

3. 재라우팅 확인

/spend/logs?api_key=<key>는 폴백 이후 사용량을 gpt-5.6-terra(배포와 model_group 모두)에 귀속시키므로 비용 추적·태깅·모델별 예산이 정확하게 유지됩니다.

연쇄 폴백 (Chained fallbacks)

리스트 항목은 순서대로 시도되고, 자기 model_max_budget 내에 있는 첫 번째 폴백이 선택됩니다. 점점 저렴하거나 상한이 높은 모델로 단계를 내려가는 티어형 체인을 정의할 수 있습니다.

curl 'http://0.0.0.0:4000/key/generate' \
  --header 'Authorization: Bearer sk-1234' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_max_budget": {
      "gpt-5.6-terra":   {"budget_limit": 5.0,  "time_period": "1d"},
      "claude-sonnet-5": {"budget_limit": 2.0,  "time_period": "1d"},
      "gpt-5.6-luna":    {"budget_limit": 1.0,  "time_period": "1d"}
    },
    "budget_fallbacks": {
      "gpt-5.6-terra": ["claude-sonnet-5", "gpt-5.6-luna"]
    }
  }'

gpt-5.6-terra 요청은 하루 $5를 소진할 때까지 gpt-5.6-terra에 머물고, 그 후 그 키가 $2에 도달할 때까지 claude-sonnet-5로, 이어서 gpt-5.6-luna로 넘어갑니다. gpt-5.6-luna도 하루 $1 상한을 넘었다면 마지막에 budget_exceeded를 반환합니다.

model_max_budget에 없는 폴백은 예산 검사 관점에서 무제한으로 취급되며, 도달하면 항상 선택됩니다.

기존 키 갱신하기

키를 재생성하지 않고 /key/update로 폴백 체인을 바꿀 수 있습니다.

curl 'http://0.0.0.0:4000/key/update' \
  --header 'Authorization: Bearer sk-1234' \
  --header 'Content-Type: application/json' \
  --data '{
    "key": "<key>",
    "budget_fallbacks": {"anthropic-haiku-4-5": ["gpt-5.6-terra", "gpt-5.6-luna"]}
  }'

LiteLLM 예산 폴백