LiteLLM 폴백과 재시도: 장애 극복의 신뢰성 설계
LiteLLM 폴백과 재시도: 장애 극복의 신뢰성 설계
프로덕션에서 LLM을 쓸 때 '요청이 100% 성공한다'는 건 환상이에요. 제공자가 일시적으로 429(속도 제한)나 500(서버 오류)을 내는 일은 일상이고, 모델이 컨텍스트 윈도우를 넘겨서 실패하는 일도 잦죠. 이때 '그냥 실패를 돌려주는' 대신 자동 폴백(fallback) 으로 다른 건강한 모델로 넘어가면, 사용자는 아무 일도 없었던 것처럼 응답을 받습니다.
LiteLLM의 폴백은 이렇게 동작해요. 호출이 num_retries만큼 재시도 후에도 실패하면, LiteLLM이 다른 모델 그룹으로 폴백합니다. 그래서 실패한 모델이나 제공자가 자동으로 건강한 백업 모델로 장애 조치(failover)돼요. "provider failover"나 "model failover"를 찾고 있다면 바로 이 페이지가 답입니다.
폴백의 기본 형태
폴백은 보통 한 model_name에서 다른 model_name으로 이뤄져요. 핵심 변경점은 단 하나, fallbacks 파라미터입니다.
fallbacks=[{"gpt-3.5-turbo": ["gpt-4"]}]
SDK에서는 Router(fallbacks=...)로, 프록시에서는 litellm_settings 아래에 둡니다. 요청이 zephyr-beta로 가서 실패하면, LiteLLM이 fallbacks에 지정된 gpt-3.5-turbo 그룹을 순서대로 시도하고, 그쪽이 성공하면 클라이언트는 gpt-3.5-turbo의 응답을 받아요.
litellm_settings:
fallbacks: [{"zephyr-beta": ["gpt-3.5-turbo"]}]
폴백 목록은 순서대로 시도됩니다. ["gpt-3.5-turbo", "gpt-4", "gpt-4-32k"]라면 gpt-3.5-turbo→gpt-4→gpt-4-32k 순으로 하나씩 시도해요.
세 가지 폴백 유형
모든 오류가 같지 않으니, LiteLLM은 오류 종류별로 폴백을 다르게 지정합니다. 세 가지가 있어요.
fallbacks— 나머지 모든 오류용. 예:litellm.RateLimitError. 429, 500 등 전부를 커버해요.content_policy_fallbacks—litellm.ContentPolicyViolationError용. LiteLLM이 각 제공자의 콘텐츠 정책 위반 오류를 매핑해요.context_window_fallbacks—litellm.ContextWindowExceededError용. 컨텍스트 윈도우 초과 오류를 매핑해요.
프록시 config에서는 각각 이렇게 넣어요.
litellm_settings:
fallbacks: [{"gpt-3.5-turbo-small": ["claude-opus"]}]
content_policy_fallbacks: [{"gpt-3.5-turbo-small": ["claude-opus"]}]
context_window_fallbacks: [{"gpt-3.5-turbo-small": ["gpt-3.5-turbo-large", "claude-opus"]}]
default_fallbacks: 특정 그룹이 망가졌을 때의 안전망
특정 모델 그룹이 설정 오류로 완전히 못 쓰게 됐을 때를 대비해 default_fallbacks를 둘 수 있어요. 어떤 모델이 실패하든 기본적으로 claude-opus로 넘어가게 하는 설정입니다. 모델별 지정 폴백(예: {"gpt-3.5-turbo-small": ["claude-opus"]})이 있으면 그게 기본 폴백보다 우선해요.
model_list:
- model_name: gpt-3.5-turbo-small
litellm_params:
model: azure/chatgpt-v-2
api_base: os.environ/AZURE_API_BASE
api_key: os.environ/AZURE_API_KEY
api_version: "2023-07-01-preview"
- model_name: claude-opus
litellm_params:
model: claude-3-opus-20240229
api_key: os.environ/ANTHROPIC_API_KEY
litellm_settings:
default_fallbacks: ["claude-opus"]
재시도와 쿨다운: 실패를 감당하는 기준
모델이 실패했을 때 얼마나 다시 시도하고, 얼마나 자주 실패하면 잠시 관둘 지를 정하는 게 litellm_settings의 핵심 값들이에요. 아래가 전형적인 조합입니다.
litellm_settings:
num_retries: 3 # 각 model_name(예: zephyr-beta)에서 호출을 3번 재시도
request_timeout: 10 # 10초 이상 걸리면 Timeout 오류. litellm.request_timeout 설정
fallbacks: [{"zephyr-beta": ["gpt-3.5-turbo"]}] # num_retries 후에도 실패하면 폴백
allowed_fails: 3 # 1분 안에 이 횟수 이상 실패하면 쿨다운
cooldown_time: 30 # 실패 수가 allowed_fails를 넘으면 쿨다운 시간(초)
동작을 정리하면, 같은 모델에 재시도를 몇 번 하고(재시도), 그래도 계속 실패하면 잠시 멈추는(쿨다운) 기준을 맞춰 두는 거예요. allowed_fails와 cooldown_time이 그 기준을 정합니다.
컨텍스트 윈도우 폴백과 사전 검사
컨텍스트 윈도우를 넘는 요청을 실제로 보내기 전에 막고 싶다면 enable_pre_call_checks: true를 router_settings에 켜야 해요. 이것 없이는 입력 토큰 수와 무관하게 요청이 제공자에 그대로 전송됩니다.
router_settings:
enable_pre_call_checks: true # 컨텍스트 윈도우 강제에 필수
model_list:
- model_name: gpt-4o
litellm_params:
model: openai/gpt-4o
api_key: os.environ/OPENAI_API_KEY
model_info:
max_input_tokens: 10 # 오버라이드: 10 토큰 초과 프롬프트 거부
사전 검사와 model_info.max_input_tokens가 함께 있을 때, 한도를 넘는 요청은 ContextWindowExceededError(Model=gpt-4o, Max Input Tokens=10, Got=306 형태)로 처리됩니다. 그룹 안에서 더 작은 컨텍스트를 가진 구형 모델을 걸러낼 때는 Azure 배포에 base_model을 지정해 컨텍스트 계산 기준을 명확히 해야 해요.
쿨다운 중 특정 모델로 폴백
그룹 안의 모든 모델이 쿨다운 상태(예: 모두 속도 제한)에 빠지면, LiteLLM은 특정 model_id가 있는 배포로 폴백할 수 있어요. 이때 폴백 대상은 쿨다운 검사를 건너뜁니다. model_info.id로 대상 모델을 지정하면 됩니다.
model_list:
- model_name: gpt-4
litellm_params:
model: openai/gpt-4
model_info:
id: my-specific-model-id # 👈 폴백 대상으로 쓸 특정 모델 ID
litellm_settings:
fallbacks: [{"gpt-4": ["my-specific-model-id"]}]
이 설정은 해당 특정 모델 ID로만 폴백해요. 다른 모델 그룹으로 폴백하고 싶다면 fallbacks=[{"gpt-4": ["anthropic-claude"]}]처럼 그룹을 지정하면 됩니다. 응답 헤더 x-litellm-model-id: my-specific-model-id로 실제 어떤 배포가 서빙했는지 확인할 수 있어요.
폴백 검증 방법
폴백이 실제로 동작하는지는 운영 환경이 아닌 데서 관련 제공자 오류를 일부러 발생시켜 확인할 수 있어요. 기본 배포를 재시도 가능한 오류(속도 제한·서버 오류)를 반환하게 만들고 정상 요청을 보내 폴백을 확인하고, 콘텐츠 정책 오류로 거부되는 테스트 요청, 그리고 enable_pre_call_checks를 켠 상태에서 컨텍스트 윈도우를 초과하는 테스트 요청으로 각각 검증합니다.