모델 폴백¶

모델 폴백은 요청 모델을 순서가 있는 대체 모델 목록에 매핑합니다. 설정한 HTTP 오류, 타임아웃, 연결 실패, 모델 없음 또는 비정상 백엔드 선택 실패 뒤에 이 목록을 차례로 시도할 수 있습니다.

설정¶

fallback:
  enabled: true
  mid_stream_enabled: true

  fallback_chains:
    gpt-5.4:
      - gpt-5.4-mini
      - claude-sonnet-4-6

  fallback_policy:
    trigger_conditions:
      error_codes: [429, 500, 502, 503, 504]
      timeout: true
      connection_error: true
      model_not_found: true
      backend_unhealthy: true
    max_fallback_attempts: 3
    fallback_timeout_multiplier: 1.5
    preserve_parameters: true

  model_settings:
    gpt-5.4:
      fallback_enabled: true
      notify_on_fallback: true

fallback_chains의 키는 기본 모델이고 값은 시도 순서입니다. 체인은 비어 있거나 자기 자신을 참조하거나 순환할 수 없습니다. 모델 이름은 128자 이하의 영숫자, ., _, -만 사용할 수 있습니다.

fallback_policy.max_fallback_attempts 범위는 1–10, fallback_timeout_multiplier 범위는 1.0–5.0입니다.

스키마는 trigger_conditions.circuit_breaker_open도 받습니다. 이제 프록시는 선택 시 서킷 브레이커 상태를 조회하지만, 열린 서킷에 거부된 요청은 별도의 circuit_breaker_open 사유가 아니라 backend_unhealthy 트리거로 표면화되므로 일반 LLM 트래픽에서는 이 특정 조건이 만들어지지 않습니다. 백엔드의 서킷이 열렸거나 백엔드가 비정상일 때 폴백 체인을 진행시키려면 backend_unhealthy(및 능동 상태 확인)를 활성화하세요.

스트림 시작 전 실행¶

비스트리밍 요청 또는 스트림이 시작되기 전에는 라우터가 다음 순서로 동작합니다.

1. 기본 모델과 설정된 체인을 결정합니다.
2. 기본 시도를 실행합니다.
3. 폴백 대상 실패인지 분류합니다.
4. 다음 모델을 선택하고 공급자가 달라지면 지원되는 매개변수를 변환합니다.
5. 처음 성공하거나 max_fallback_attempts에 도달하면 중단합니다.

폴백은 모델 단위입니다. 각 대체 모델은 일반 백엔드 풀, 상태 필터, 접근 정책, 선택 전략을 거쳐 해석됩니다.

교차 공급자 변환은 토큰 제한, temperature, 샘플링, stop sequence처럼 표현 가능한 필드를 처리합니다. 대응 항목이 없는 공급자 전용 필드는 제거될 수 있습니다.

스트리밍 폴백¶

fallback.mid_stream_enabled는 활성 SSE 응답을 버퍼링해 업스트림 스트림 실패 뒤 복구할지 결정합니다.

• true(기본값): 스트림 중간 폴백과 스트림별 버퍼를 허용합니다.
• false: 스트림 시작 전 폴백은 유지하지만 SSE 출력이 시작된 뒤의 실패는 스트림 오류로 반환합니다.

streaming.mid_stream_fallback.enabled는 버퍼링 스위치가 아니라 모드 선택자입니다.

• true: 충분한 내용이 누적되면 누적 출력으로 연속 요청을 만듭니다.
• false: 폴백 모델에서 원 요청을 처음부터 다시 실행합니다.

streaming.mid_stream_fallback.max_fallback_attempts, min_accumulated_tokens, fallback_delay_ms, continuation_prompt로 이 경로를 조정할 수 있습니다. 스트림 전체 및 청크 간격 제한 시간은 계속 적용됩니다.

응답 헤더¶

모델의 notify_on_fallback이 true(기본값)이고 폴백이 성공하면 응답에 다음 헤더가 포함될 수 있습니다.

X-Fallback-Used: true
X-Original-Model: gpt-5.4
X-Fallback-Model: gpt-5.4-mini
X-Fallback-Reason: error_code_429
X-Fallback-Attempts: 2

라우터가 내보내는 폴백 헤더는 X-Fallback-Used, X-Original-Model, X-Fallback-Model, X-Fallback-Reason, X-Fallback-Attempts 다섯 개입니다. 모델에 notify_on_fallback: false를 지정하면 폴백 응답은 그대로 제공하면서 이 헤더들만 억제합니다.

X-Fallback-Attempts는 요청을 처리하기 위해 시도한 모델 수를 기본 시도를 포함해 보고합니다. 이 헤더는 폴백 백엔드가 응답을 만든 경우에만 나타나므로 값은 항상 2 이상입니다. 값이 2이면 기본 모델이 한 번 실패하고 첫 폴백이 성공했다는 뜻이고, 값이 더 크면 성공 전에 실패한 홉이 더 있었다는 뜻입니다. 이를 통해 클라이언트는 한 번에 복구된 경우와 여러 모델을 거친 경우를 구분할 수 있습니다.

이 헤더들은 비스트리밍 응답에 붙습니다. 스트리밍(SSE) 요청은 본문보다 먼저 응답 헤더를 보내므로 스트림 중간 복구는 시도 횟수를 헤더로 보고할 수 없으며, 대신 streaming_fallback_* 메트릭으로 관찰합니다.

메트릭¶

metrics 기능이 활성화되면 폴백 수집기가 다음 항목을 등록합니다.

• fallback_attempts_total{original_model,fallback_model,backend}
• fallback_success_total{original_model,fallback_model,backend}
• fallback_exhausted_total{original_model}
• models_using_fallback{original_model}
• fallback_duration_seconds{original_model,success}
• fallback_triggers_by_reason{original_model,reason}

스트림 중간 복구는 streaming_fallback_* 메트릭도 제공합니다.

재적용 동작¶

fallback_chains와 fallback_policy 변경은 실행 중인 폴백 서비스가 사용합니다. 폴백 서비스의 존재 여부나 마스터 enabled 상태를 바꾸려면 재시작해야 합니다. 스트리밍 서비스 설정 변경은 /admin/config/hot-reload-status와 생성 설정의 주석을 따르세요.

관련 문서¶

• 오류 처리
• 서킷 브레이커
• 부하 분산