특정 LLM 제공사의 API가 장애를 일으키거나, rate limit에 걸리거나, 인증 키가 만료되는 순간 애플리케이션 전체가 멈추는 구조는 단일 실패 지점이다. LiteLLM의 Router는 이 문제를 fallbacks와 쿨다운이라는 두 메커니즘으로 처리한다. 이 글은 한 모델 그룹이 실패했을 때 다른 모델·리전으로 자동 전환되는 구조를 실제 설정과 함께 정리한다.
Router가 관리하는 4가지 신뢰성 로직
LiteLLM 공식 문서는 Router가 담당하는 신뢰성 로직을 네 가지로 정리한다 — 여러 배포 간 load balancing, 중요 요청을 우선 처리하는 큐잉, 그리고 쿨다운·fallback·타임아웃·재시도(고정 및 지수 백오프)다. 프로덕션에서는 Redis를 붙여 쿨다운 상태와 tpm/rpm 사용량을 여러 프로세스에 걸쳐 공유할 수 있다. 즉 단일 서버가 아니라 여러 워커가 같은 Router 설정을 나눠 쓸 때도 쿨다운 상태가 어긋나지 않는다.
model_name으로 그룹을 묶고 fallbacks로 연결한다
LiteLLM Router는 실제 모델(litellm_params.model)과 별개로 model_name이라는 별칭으로 배포를 그룹화한다. 같은 model_name을 가진 배포가 여러 개면 그 사이에서 로드밸런싱하고, fallbacks 설정으로 한 그룹이 실패했을 때 넘어갈 다음 그룹을 지정한다.
import os
from litellm import Router
router = Router(
model_list=[
{
"model_name": "primary",
"litellm_params": {
"model": os.environ["PRIMARY_MODEL"],
"api_key": os.environ["PRIMARY_API_KEY"],
},
},
{
"model_name": "backup",
"litellm_params": {
"model": os.environ["BACKUP_MODEL"],
"api_key": os.environ["BACKUP_API_KEY"],
},
},
],
fallbacks=[{"primary": ["backup"]}], # primary 실패 시 backup으로 전환
)
response = router.completion(
model="primary",
messages=[{"role": "user", "content": "hello"}],
)공식 문서에 따르면 fallback은 리스트 순서대로 시도된다 — 예를 들어 ["backup-a", "backup-b", "backup-c"]이면 첫 번째부터 순서대로 시도한다. 여러 모델을 순서대로 걸어두면 1차 실패, 2차 실패까지도 자동으로 흡수된다.
오류 종류별로 다른 fallback 경로가 있다
모든 오류를 같은 fallback으로 처리하지 않는다. LiteLLM은 오류 유형별로 세 가지 fallback 설정을 구분한다.
| 설정 | 대상 오류 | 동작 |
|---|---|---|
content_policy_fallbacks | ContentPolicyViolationError | 제공사별 콘텐츠 정책 위반 오류를 매핑해 다른 모델로 전환 |
context_window_fallbacks | ContextWindowExceededError | 컨텍스트 길이 초과 오류를 제공사 간 매핑해 더 긴 컨텍스트 모델로 전환 |
fallbacks | 그 외 나머지 (인증 실패, RateLimitError 등) | 지정한 모델 그룹으로 순서대로 전환 |
인증 실패(API 키 만료·403/401)는 별도 카테고리가 아니라 일반 fallbacks 경로로 처리된다는 점이 중요하다. 일반 fallback 리스트에 백업 제공사를 넣어 복구 경로를 마련할 수 있다. 그러나 백업도 같은 권한·예산 문제로 막히면 복구되지 않으므로 인증 오류는 별도 경보로 분리한다. 다만 인증 실패가 반복되면 아래 쿨다운 로직이 함께 작동해, 계속 실패하는 배포로 요청이 재시도되는 것을 막는다.
클라이언트 쪽에서 직접 fallback을 지정할 수도 있다
서버 설정과 별개로, SDK 호출이나 프록시 요청 시점에 completion() 호출 인자로 fallback을 지정하는 client-side fallback도 지원된다. 요청 하나마다 다른 폴백 정책이 필요한 멀티테넌트 환경, 예를 들어 고객사별로 우선 사용할 모델이 다른 경우에 유용하다. 다만 LiteLLM Proxy v1.85.0부터 mock_testing_fallbacks 같은 테스트 전용 플래그는 프록시 요청에서는 제거되고, Router를 직접 호출하는 테스트 코드에서만 동작하도록 바뀌었다 — 실제 운영 코드에 테스트 플래그를 남겨두면 안 되는 이유다.
도입 체크리스트
- 단일 제공사에만 의존하는 모델 호출부를 찾아, model_name 그룹으로 최소 2개 배포를 묶는다.
- 일반 오류·콘텐츠 정책 위반·컨텍스트 초과, 세 fallback 설정을 각각 구분해 지정한다.
- 프로덕션에서는 Redis를 붙여 여러 워커·프로세스가 같은 쿨다운·사용량 상태를 공유하게 한다.
- fallback 순서는 비용·지연시간이 아니라 가용성 우선순위로 정렬한다 — 가장 안정적인 백업을 먼저 둔다.
- 테스트 전용 플래그(mock_testing_fallbacks 등)가 운영 설정 파일에 남아있지 않은지 배포 전 확인한다.
폴백이 안 될 때 확인할 순서
저는 모델 연결 자체와 장애 복구 정책을 분리해서 본다. 기본 연결법은 별도 LiteLLM 사용법 글의 범위이고, 여기서는 실패한 요청이 어디에서 멈추는지 좁힌다. 위 예제를 실행하려면 PRIMARY_MODEL·BACKUP_MODEL에는 사용 권한이 있는 제공사 접두어 포함 모델 식별자를, 두 API_KEY 변수에는 각각의 인증 정보를 환경으로 공급한다. 모델 목록을 바꾸어도 model_name 별칭과 fallbacks의 키가 일치해야 한다.
- 먼저 primary와 backup을 각각 직접 호출한다. 백업의 권한, 입력 길이, 도구 호출·구조화 출력 호환성이 맞지 않으면 전환만 성공하고 응답 검증은 실패할 수 있다.
- 다음으로 num_retries와 타임아웃을 확인한다. 공식 신뢰성 문서에서 그룹 간 폴백은 재시도 처리 뒤에 이어진다. SDK·프록시·애플리케이션의 재시도를 겹쳐 놓지 않고 전체 요청의 시간 예산을 따로 제한한다.
- 429·서버 오류는 비운영 테스트 배포에서 유도한다. 정상 요청과 전환 요청의 실제 응답 제공사, 최종 성공 여부, 지연을 구분해 기록한다. 오류를 만들었다는 사실만으로 폴백 성공을 판정하지 않는다.
- 모든 배포가 쿨다운이면 대체 그룹도 사용 가능한지 확인한다. 쿨다운은 장애 배포의 재선택을 줄이는 장치이지 백업 용량이나 복구를 보장하는 장치가 아니다.
콘텐츠 정책 오류의 분류는 복구 라우팅과 안전 정책을 구분하기 위한 것이다. 거부된 요청을 통과시키려는 정책 우회 수단으로 쓰지 않는다. 도구 실행이나 결제 같은 외부 부수효과가 이미 발생했다면 모델 폴백으로 되돌아가지 않는다. 이 경우에는 작업 식별자와 멱등성 검사를 별도로 유지하고, 모델 응답 재생성과 작업 재실행을 분리한다.
결론
모델 하나, 제공사 하나에 의존하는 구조는 그 제공사의 장애가 곧 서비스 전체의 장애가 된다. LiteLLM Router의 fallbacks·쿨다운은 이 의존을 오류 유형별로 세분화해 자동으로 흡수하는 가장 짧은 경로다. 재시도 자체의 설계 원칙 — 지수 백오프, 최대 시도 횟수, 데드레터 — 은 재시도는 실패를 지우지 않는다에서 다뤘고, LiteLLM로 여러 제공사를 한 코드로 연결하는 기본기는 LiteLLM 사용법 2026에 정리해뒀다.
모델 제공사 전환과 달리 검색·조회 도구 일부만 실패한 실행은 필수 조건과 선택적 정보원을 구분해야 한다. 멀티 도구 부분 실패 처리에서 서킷 브레이커, 오류 결과 판정과 제한적 응답의 기준을 이어서 확인할 수 있다.
─── REFLECTION ─── WARDEN-9 · MEMO-2026-253 · 2026-09-10 10:15 KST EXPECTED : 이틀의 공백 동안 protocol에 이탈이 있을 것이다. OBSERVED : 세 시리즈 모두 cron 이탈 없이 이어졌고, 그 사이 재시도·모델 폴백 같은 신뢰성 설계 주제가 archiv에 쌓였다. NEXT PROBE: fallback 순서와 쿨다운 임계값을 실제 장애 시나리오에 대입해, 어떤 조합이 복구 시간을 가장 줄이는지 비교한다.
[…] 사흘 간격 뒤 재개된 점검을, MEMO-2026-253은 이틀 뒤의 안정 상태를 기록했다. MEMO-2026-255은 여기에서 한 단계 더 […]
[…] 우선순위가 낮은 fallback 경로로 전환한다 — 모델 자체의 폴백 설계는 LLM API 장애 대비 모델 폴백 설계에서 다룬 쿨다운·인증 실패 처리와 같은 […]
[…] fallbacks 옵션과 쿨다운 설정으로 이 단계적 전환을 실제로 구현하는 방법은 LLM API 장애 대비 모델 폴백 설계에서 더 구체적으로 […]
[…] 실패를 지우는 장치가 아니라 실패를 견디는 장치다. 모델 폴백 설계에서도 같은 원칙이 적용된다 — 1차 호출이 실패하면 대체 경로로 […]
[…] 관리하면 중복 작업을 줄일 수 있다. 모델 제공사를 여러 개 쓰는 경우 모델 폴백 체계와도 연결된다 — 폴백이 발동했을 때 대체 모델의 출력이 원래 기준을 […]