[New] 폴백 관리 엔드포인트

[New] 폴백 관리 엔드포인트 (Fallback Management Endpoints)

일반 구성과 별도로 모델 폴백을 관리하기 위한 전용 엔드포인트예요.

출처: 문서

본문

개요 (Overview)

이 엔드포인트들은 전체 프록시 구성을 수정하지 않고 폴백 모델을 구성, 검색, 삭제할 수 있게 해줘요. /config/update 엔드포인트를 사용하는 것보다 폴백을 관리하는 더 깨끗하고 안전한 방법을 제공해요.

사전 요구사항 (Prerequisites)

데이터베이스 저장 활성화: 환경에 STORE_MODEL_IN_DB=True 설정
폴백을 구성하기 전에 모델이 라우터에 존재해야 함

엔드포인트 (Endpoints)

POST /fallback

특정 모델에 대한 폴백을 생성하거나 업데이트해요.

요청 본문:

{
  "model": "gpt-5.6-luna",
  "fallback_models": ["gpt-5.6-terra", "claude-sonnet-5"],
  "fallback_type": "general"
}

파라미터:

model (string, 필수): 폴백을 구성할 프라이머리 모델 이름
fallback_models (string 배열, 필수): 우선 순위 순서의 폴백 모델 이름 목록
fallback_type (string, 선택): 폴백 유형. 옵션:
- "general" (기본): 모든 오류에 대한 표준 폴백
- "context_window": 컨텍스트 창 초과 오류에 대한 폴백
- "content_policy": 콘텐츠 정책 위반에 대한 폴백

응답:

{
  "model": "gpt-5.6-luna",
  "fallback_models": ["gpt-5.6-terra", "claude-sonnet-5"],
  "fallback_type": "general",
  "message": "Fallback configuration created successfully"
}

cURL 사용 예시:

curl -X POST "http://localhost:4000/fallback" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "fallback_models": ["gpt-5.6-terra", "claude-sonnet-5"],
    "fallback_type": "general"
  }'

Python 사용 예시:

import requests
response = requests.post(
    "http://localhost:4000/fallback",
    headers={
        "Authorization": "Bearer sk-<your-litellm-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "model": "gpt-5.6-luna",
        "fallback_models": ["gpt-5.6-terra", "claude-sonnet-5"],
        "fallback_type": "general"
    })
print(response.json())

GET /fallback/{model}

특정 모델에 대한 폴백 구성을 가져와요.

파라미터:

model (path 파라미터, 필수): 폴백을 가져올 모델 이름
fallback_type (query 파라미터, 선택): 검색할 폴백 유형 (기본: "general")

응답:

{
  "model": "gpt-5.6-luna",
  "fallback_models": ["gpt-5.6-terra", "claude-sonnet-5"],
  "fallback_type": "general"
}

cURL 사용 예시:

curl -X GET "http://localhost:4000/fallback/gpt-5.6-luna?fallback_type=general" \
  -H "Authorization: Bearer ***"

Python 사용 예시:

import requests
response = requests.get(
    "http://localhost:4000/fallback/gpt-5.6-luna",
    headers={"Authorization": "Bearer sk-<your-litellm-api-key>"},
    params={"fallback_type": "general"})
print(response.json())

DELETE /fallback/{model}

특정 모델에 대한 폴백 구성을 삭제해요.

파라미터:

model (path 파라미터, 필수): 폴백을 삭제할 모델 이름
fallback_type (query 파라미터, 선택): 삭제할 폴백 유형 (기본: "general")

응답:

{
  "model": "gpt-5.6-luna",
  "fallback_type": "general",
  "message": "Fallback configuration deleted successfully"
}

cURL 사용 예시:

curl -X DELETE "http://localhost:4000/fallback/gpt-5.6-luna?fallback_type=general" \
  -H "Authorization: Bearer ***"

Python 사용 예시:

import requests
response = requests.delete(
    "http://localhost:4000/fallback/gpt-5.6-luna",
    headers={"Authorization": "Bearer sk-<your-litellm-api-key>"},
    params={"fallback_type": "general"})
print(response.json())

폴백 테스트 (Test fallback)

Proxy 요청에서는 Deprecated

LiteLLM Proxy v1.85.0부터 mock_testing_fallbacks는 수신 Proxy 요청에서 제거되며 효과가 없어요. 테스트에서 직접 litellm.Router 호출에 대해서만 지원돼요.

프록시를 통해 폴백을 검증하려면 비프로덕션 환경에서 프라이머리 배포를 사용 불가로 만들고 일반 요청을 보내세요:

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ***" \
-d '{
  "model": "gpt-5.6-luna",
  "messages": [
    {
      "role": "user",
      "content": "ping"
    }
  ]
}'

검증 (Validation)

엔드포인트는 다음 검증을 수행해요:

모델 존재: 프라이머리 모델이 라우터에 존재하는지 확인
폴백 모델 존재: 모든 폴백 모델이 라우터에 존재하는지 보장
자체 폴백 없음: 모델이 자신의 폴백이 되는 것을 방지
중복 없음: 폴백 목록에 중복 모델이 없도록 보장
데이터베이스 활성화: STORE_MODEL_IN_DB=True 설정 필요

오류 응답 (Error Responses)

400 Bad Request:

{
  "detail": {
    "error": "Invalid fallback models: ['non-existent-model']",
    "available_models": ["gpt-5.6-luna", "gpt-5.6-terra", "claude-sonnet-5"]
  }
}

404 Not Found:

{
  "detail": {
    "error": "Model 'gpt-5.6-luna' not found in router",
    "available_models": ["gpt-5.6-terra", "claude-sonnet-5"]
  }
}

500 Internal Server Error:

{
  "detail": {
    "error": "Router not initialized"
  }
}

폴백 유형 설명 (Fallback Types Explained)

일반 폴백 (General Fallbacks)

모델 호출 중 발생하는 모든 유형의 오류에 사용돼요. 가장 일반적인 폴백 유형이에요.

사용 사례: 모델이 사용 불가, 요율 제한, 또는 오류를 반환할 때.

{
  "model": "gpt-5.6-luna",
  "fallback_models": ["gpt-5.6-terra", "claude-sonnet-5"],
  "fallback_type": "general"
}

컨텍스트 창 폴백 (Context Window Fallbacks)

컨텍스트 창 초과 오류가 발생할 때 특별히 트리거돼요.

사용 사례: 입력이 프라이머리 모델에 너무 길 때, 더 큰 컨텍스트 창을 가진 모델로 폴백. 아래 id는 예시이며 컨텍스트 창 크기로 유지된 것이에요.

{
  "model": "gpt-3.5-turbo",
  "fallback_models": ["gpt-4-32k", "claude-3-opus"],
  "fallback_type": "context_window"
}

콘텐츠 정책 폴백 (Content Policy Fallbacks)

콘텐츠 정책 위반이 발생할 때 특별히 트리거돼요.

사용 사례: 프라이머리 모델이 안전 필터로 인해 콘텐츠를 거부할 때, 다른 콘텐츠 정책을 가진 모델로 폴백.

{
  "model": "gpt-5.6-terra",
  "fallback_models": ["claude-sonnet-5"],
  "fallback_type": "content_policy"
}

/config/update보다 나은 점 (Benefits Over /config/update)

안전성 (Safety): 폴백 구성만 수정하므로 다른 설정을 우연히 바꾸지 않음
단순성 (Simplicity): 명확한 검증 메시지가 있는 집중된 API
세분성 (Granularity): 모델별, 유형별로 폴백 관리
검증 (Validation): 적용 전에 구성이 유효한지 확인
명확성 (Clarity): 사용 가능한 모델이 나열된 명확한 오류 메시지

참고 사항 (Notes)

폴백은 구성된 재시도 횟수가 실패한 후에 트리거돼요
폴백은 fallback_models에 지정된 순서대로 시도돼요
시도되는 최대 폴백 수는 라우터의 max_fallbacks 설정이 제어해요
변경은 즉시 적용되고 데이터베이스에 보존돼요

예산 폴백 (Budget Fallbacks)

예산 폴백은 per-key model_max_budget이 초과되었을 때 budget_exceeded를 반환하는 대신 요청을 다른 모델로 재라우팅해요.