헬스 체크 기반 라우팅

헬스 체크 기반 라우팅 (Health Check Driven Routing)

사용자가 오류를 겪기 전에 비정상 배포에서 트래픽을 돌려보내요. 백그라운드 헬스 체크가 구성 가능한 간격으로 실행되며, 실패한 배포는 사용자 요청이 이미 실패한 뒤가 아니라 사전에 라우팅 풀에서 제거돼요.

출처: 문서

본문

아키텍처 (Architecture)

백그라운드 루프가 health_check_interval 초마다 모든 배포를 검사해요. 각 배포에 health_check() → 200(정상), 401(비정상), 429(일시적) 같은 결과가 나와요. ignore_transient_errors: true면 429/408은 무시되고 캐시에 기록되지 않아요. allowed_fails_policy가 있으면 401 같은 경우 카운터를 증가시키고, 임계값을 넘으면 쿨다운(cooldown)을 트리거해요. 공유 상태(DeploymentHealthCache, Cooldown Cache)는 health 상태와 쿨다운을 추적해요.

들어오는 요청은 ① 헬스 체크 필터(정책이 있으면 우회, 없으면 비정상 제거) → ② 쿨다운 필터(쿨다운 중인 배포 제거) → ③ 안전망(모두 제거되면 전부 반환) → ④ 로드 밸런서가 최종 선택합니다.

이게 해결하는 문제 (What problem does this solve?)

기본적으로 LiteLLM은 모든 배포에 트래픽을 라우팅하고, 고장난 배포는 사용자 요청이 이미 실패한 뒤에야 보내기를 멈춰요. 쿨다운 시스템은 반응적(reactive)이에요.

헬스 체크 기반 라우팅은 이를 능동적(proactive)으로 만들어요. 백그라운드 루프가 구성 가능한 간격으로 모든 배포를 핑하고, 배포가 헬스 체크에 실패하면 사용자 요청이 도달하기 전에 즉시 라우팅 풀에서 제거해요.

allowed_fails_policy를 설정하면 각 오류 유형(인증 오류, 레이트 리밋, 타임아웃)의 헬스 체크 실패가 몇 번 있어야 배포가 쿨다운에 들어가는지 정확히 제어할 수 있어요. 이는 일시적 노이즈로 인한 오탐을 피하게 해줘요.

설정 (Setup)

1단계: 백그라운드 헬스 체크 활성화

백그라운드 헬스 체크는 기본적으로 꺼져 있어요. general_settings에서 켜요.

general_settings:
  background_health_checks: true
  health_check_interval: 60    # seconds between each full check cycle

2단계: 헬스 체크 라우팅 활성화

general_settings:
  background_health_checks: true
  health_check_interval: 60
  enable_health_check_routing: true  # ← route away from unhealthy deployments

이 시점부터 헬스 체크에 실패한 어떤 배포든 다음 체크 주기가 정리할 때까지 즉시 라우팅에서 제외돼요.

3단계: 쿨다운을 트리거하는 실패 횟수를 제어하는 정책 추가

정책이 없으면 첫 헬스 체크 실패가 배포를 비정상으로 표시해요. 더 관대하게(예: 인증 실패가 연속 2번일 때만 조치) 하려면 allowed_fails_policy를 사용해요.

model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY_SECONDARY

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true

router_settings:
  cooldown_time: 60              # how long a deployment stays in cooldown
  allowed_fails_policy:
    AuthenticationErrorAllowedFails: 1   # cooldown after 2nd auth failure
    TimeoutErrorAllowedFails: 3          # cooldown after 4th timeout

allowed_fails_policy를 설정하면 이진(binary) 헬스 체크 필터가 우회돼요. 오직 쿨다운 시스템만이 라우팅 제외를 제어하며, 설정한 임계값을 넘은 뒤에만 발동해요. 예외는 background_health_check_model_groups도 설정된 경우(5단계 참조)로, 목록에 있는 그룹은 정책이 있어도 이진 필터를 유지해요.

4단계 (선택): 일시적 오류 무시

헬스 체크의 429(레이트 리밋)와 408(타임아웃)은 보통 배포가 고장난 게 아니라 일시적으로 과부하 상태임을 뜻해요. 이것이 라우팅에 전혀 영향을 주지 않게 하려면:

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true
  health_check_ignore_transient_errors: true  # 429 and 408 never affect routing

이 옵션을 켜면 헬스 체크의 하드 실패(401, 404, 5xx)만 쿨다운에 기여해요.

5단계 (선택): 헬스 체크를 특정 모델 그룹으로 범위 제한

기본적으로 백그라운드 루프는 모든 모델 그룹을 프로브해요. 관리하려는 그룹만 선택하려면 background_health_check_model_groups에 나열해요.

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true
  background_health_check_model_groups: ["prod-openai"]

허용 목록(allowlist)을 설정하면:

• 목록에 있는 그룹의 배포만 프로브되므로, 목록에 없는 그룹은 백그라운드 프로브 트래픽·비용이 발생하지 않음
• GET /health가 백그라운드 결과를 서빙하므로 목록에 있는 그룹만 보고함
• 헬스 체크 라우팅은 목록에 있는 그룹 내에서만 트래픽을 조정하며, 목록에 없는 그룹은 구성된 라우팅 전략과 일반 요청 시 재시도 동작을 유지함
• 나중에 추가된 모델 그룹은 목록에 추가하기 전까지 제외됨
• 목록에 있는 그룹은 allowed_fails_policy가 설정돼도 이진 헬스 필터를 유지함
• 문자열 목록이 아닌 값은 조용히 무시되는 대신 프록시 시작 시 실패함

전체 예시 (Full example)

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY

  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY_SECONDARY

  - model_name: gpt-5.6-terra
    litellm_params:
      model: azure/gpt-5.6-terra
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true
  health_check_ignore_transient_errors: true

router_settings:
  cooldown_time: 60
  allowed_fails_policy:
    AuthenticationErrorAllowedFails: 0   # cooldown immediately on auth failure
    TimeoutErrorAllowedFails: 2          # cooldown after 3 timeouts
    RateLimitErrorAllowedFails: 5        # cooldown after 6 rate limits (if not ignoring transients)

구성 참조 (Configuration reference)

주의할 점 (Things to keep in mind)

• 헬스 체크 실패와 요청 실패는 같은 카운터를 공유해요. allowed_fails_policy가 설정되면 두 출처 모두 같은 failed_calls 카운터를 증가시켜요. 헬스 체크 실패 1회 상태의 배포가 실패 요청 1건을 더 받으면 AllowedFails: 1 임계값에 도달해 쿨다운에 들어가요.

디버깅 (Debugging)

프록시를 --detailed_debug로 실행하고 다음 로그 줄을 찾아보세요.

각 헬스 체크 주기 후(DEBUG 레벨로 기록):

health_check_routing_state_updated healthy=2 unhealthy=1

헬스 체크 실패가 카운터를 증가시키고 쿨다운을 트리거할 때(DEBUG 레벨):

checks 'should_run_cooldown_logic'
Attempting to add <deployment_id> to cooldown list

모든 배포가 쿨다운이라 안전망이 발동할 때:

All deployments in cooldown via health-check routing, bypassing cooldown filter

모든 배포가 비정상일 때(이진 필터, allowed_fails_policy 없음) 안전망이 발동할 때:

All deployments marked unhealthy by health checks, bypassing health filter

더 알아보기 (Learn more)

• 헬스 체크 문서
• 공유 헬스 체크 상태