AI API 장애 조치 전략: 제공자 장애 매트릭스 구축

장애 유형, 응답 단계, 멱등성과 시도 한도에 따라 재시도, 동일 계약의 대체 경로, 중단 또는 부작용 확인을 결정합니다.

AI API 장애 조치 전략: 제공자 장애 매트릭스 구축

AI API 재시도, 경로 전환, 모델 대체는 서로 다른 동작입니다. 재시도는 같은 계약에서 한 번 더 요청합니다. 경로 전환은 요청한 모델과 프로토콜을 다른 적격 채널이나 그룹으로 보냅니다. 모델 대체는 요청 모델을 바꾸므로 품질, 가격, 지연 시간, 도구 동작, 컨텍스트 한도, 출력 형식까지 달라질 수 있습니다.

신뢰할 수 있는 정책은 장애가 난 뒤 즉석에서 결정하지 않습니다. 실패 유형, 응답이 이미 전달됐는지, 전체 업무 동작이 멱등한지, 사용자 제한 시간 안에 몇 번이나 시도할 수 있는지를 사전에 정의합니다.

재시도, 경로 전환, 모델 대체 구분하기

설정, 로그, 운영 절차서에서 세 동작을 서로 다른 이름으로 기록합니다.

동작 바뀌는 항목 적절한 목적 주요 위험
같은 경로 재시도 시간과 시도 번호 같은 경로의 짧은 일시 장애 복구 비정상 의존 대상에 반복해서 부하를 줌
같은 계약의 대체 경로 상위 제공자 채널, 계정 또는 순서가 있는 그룹 한 경로가 실패해도 모델과 프로토콜 유지 동일하다고 가정한 경로 사이의 숨은 비호환
모델 대체 모델 ID 또는 명시적 모델 정책 제품이 승인한 품질·비용·가용성 절충 동작과 청구 방식의 조용한 변경

세 동작을 모두 “재시도”라고 부르면 안 됩니다. 운영자는 요청이 다시 실행됐는지, 다른 경로로 이동했는지, 다른 모델이 답했는지 알아야 합니다. 사용자의 관점에서도 모델 대체는 명시적인 제품 계약이어야 하며 보이지 않는 복구 수단이 되어서는 안 됩니다.

일부 게이트웨이는 제공자 또는 모델 단계를 순서대로 실행합니다. Cloudflare 대체 경로 문서처럼 어느 단계가 성공했는지 보여 줄 수도 있습니다. 특정 제공자의 정책을 복제하는 것보다 중요한 원칙은 경로가 바뀔 때마다 각 시도의 근거를 남기는 것입니다.

요청 재실행 전 네 가지 조건 확인하기

상태 코드 하나만으로 재시도 정책을 결정할 수 없습니다.

  1. 실패 유형: 일시적 실패, 영구적 실패, 호출자 원인, 완료 여부가 불명확한 실패 중 무엇인가?
  2. 응답 단계: 헤더 전, 유효한 출력 전, 출력 전달 후 중 언제 발생했는가?
  3. 멱등성: 애플리케이션의 전체 동작을 반복해도 외부 효과가 중복되지 않는가?
  4. 시도 예산: 남은 실제 시간과 사용 가능한 시도 횟수가 있는가?

Google Cloud 재시도 전략도 일반 API에서 같은 두 기준을 강조합니다. 응답이 재시도 가능성을 보여 주는지, 멱등성이 재실행의 안전성을 보장하는지 판단해야 합니다. 408, 429, 5xx, 소켓 시간 초과, 연결 끊김은 흔히 일시적이지만 멱등하지 않은 동작에는 더 엄격한 조건이 필요합니다.

AI 작업 흐름의 멱등성은 모델로 보내는 HTTP 요청 밖까지 이어집니다. 프롬프트를 다시 보내면 이메일, 환불, 배포, 데이터베이스 쓰기를 다시 제안할 수 있습니다. 추론 자체가 읽기 전용이어도 도구 실행에는 안정적인 멱등성 키와 영구 저장된 결과가 필요합니다.

실패 행렬에서 정책 시작하기

아래는 보수적인 애플리케이션 정책입니다. 게이트웨이가 최종 결과를 전달하기 전에 내부에서 같은 계약의 다른 채널로 전환할 수 있으므로 두 계층이 같은 실패를 중복 재시도하지 않도록 조정해야 합니다.

실패 또는 단계 같은 경로 재시도 같은 계약의 대체 경로 중단 또는 조사 이유
클라이언트 입력 검증 오류, 지원하지 않는 필드, 잘못 구성된 요청 아니요 아니요 요청 수정 같은 잘못된 계약을 반복해도 성공하지 않음
게이트웨이 인증, 권한, 할당량 또는 정책 거부 아니요 아니요 계정 또는 정책 수정 다른 제공자 경로로 게이트웨이 결정을 우회하면 안 됨
출력 전 상위 제공자 자격 증명 또는 계정 오류 실패한 경로에서는 아니요 검증된 적격 채널이 있으면 가능 채널 격리 및 조사 사용자 계약을 유지하면서 비정상 자격 증명을 제거할 수 있음
출력 전 네트워크 오류 또는 408 멱등한 경우 최대 한 번의 제한된 시도 가능 제한 시간에 도달하면 중단 일시적일 수 있지만 연결이 끊긴 뒤 완료 여부는 모호함
출력 전 429 Retry-After를 지키는 지연 재시도 같은 계약의 다른 경로에 용량이 있으면 가능 시도 예산 소진 시 중단 즉시 반복하면 요청 제한을 악화함
출력 전 500, 502, 503, 504 대기 시간을 늘리는 제한된 재시도 가능 반복되는 경로 장애 조사 흔히 일시적이지만 모든 경로가 안전하다는 증거는 아님
하위 출력 전 스키마와 맞지 않는 제공자 응답 대체로 아니요 같은 스키마로 검증한 경로만 가능 호환성 조사 또는 격리 비호환 구현을 반복해도 개선되기 어려움
모델 거부 또는 안전 정책에 맞는 응답 아니요 아니요 모델 결과 반환 정상적인 거부는 인프라 장애가 아님
호출자 취소 또는 하위 서비스의 499 아니요 아니요 즉시 중단 호출자가 더 이상 작업을 원하지 않음
표시된 내용이나 도구 인수를 전달한 뒤의 부분 스트림 투명한 재실행 금지 투명한 경로 전환 금지 부분 완료로 표시한 뒤 애플리케이션이 결정 새 스트림이 기존 출력을 반복하거나 모순될 수 있음
도구의 외부 효과 완료 여부가 불명확함 대조 전 금지 대조 전 금지 멱등성 기록 또는 외부 시스템 조회 재추론이 같은 외부 효과를 다시 제안할 수 있음

503이 출력 전에 도착한 경우와 텍스트 토큰 400개가 표시된 뒤 연결이 끊긴 경우는 같은 실패가 아닙니다.

스트림 시작을 확정 경계로 취급하기

하위 서비스로 출력이 시작되기 전에는 게이트웨이가 실패한 시도를 버리고 다른 경로를 선택해도 호출자에게 두 답을 노출하지 않을 수 있습니다. 의미 있는 첫 바이트가 전달된 뒤에는 투명한 재실행이 안전하지 않습니다.

스트림을 다시 시작하면 다음 문제가 생길 수 있습니다.

  • 답변 시작 부분 중복
  • 서로 다른 후속 내용 생성
  • 새 호출 ID를 가진 중복 함수 호출
  • 경계가 불명확한 사용량과 비용 증가
  • 클라이언트가 각 이벤트의 시도를 식별하지 못함

출력 이후 스트림이 끊기면 원래 요청 ID와 함께 부분 완료 또는 전송 오류를 반환합니다. 애플리케이션은 명시적인 “다시 시도”, 안전한 확인 지점에서 계속하기, 부분 출력 폐기를 제공할 수 있습니다. 새 모델 스트림을 기존 스트림에 몰래 이어 붙이면 안 됩니다.

함수 호출은 더 엄격합니다. 재시도가 도구 호출을 다시 만들기 전에 이미 수락한 호출 ID와 외부 효과의 결과를 저장해야 합니다. 함수 호출 형식 비교에서 호출 ID와 애플리케이션 멱등성의 관계를 확인할 수 있습니다.

시도 횟수와 실제 시간으로 대기 제한하기

지수 방식으로 대기 시간을 늘리면 반복 시도가 분산되고, 무작위 편차를 더하면 공통 장애 뒤 많은 클라이언트가 동시에 재시도하는 현상을 막을 수 있습니다.

delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)

유효한 Retry-After가 사용자 제한 시간 안에 들어오면 따릅니다. 대기 시간 자체가 재시도를 허가하는 것은 아니므로 실패 유형과 멱등성 조건을 먼저 통과해야 합니다.

재시도 횟수만이 아니라 전체 예산을 정의합니다.

  • 한 사용자 동작의 최대 시도 횟수
  • 대기열과 재시도 대기를 포함한 최대 경과 시간
  • 대체 그룹 선택 전후의 시도 상한
  • 유용한 답을 만들기 위해 남겨 둘 최소 시간
  • 호출자 취소를 모든 진행 중인 시도에 전달하는 규칙

제한 시간이 15초인 대화형 요청에 10초짜리 시도를 세 번 배정하는 것은 실현 가능한 정책이 아닙니다. 일괄 작업은 더 긴 예산을 사용할 수 있지만 최종 제한 시간과 영구적인 작업 ID가 필요합니다.

계층 간 재시도 증폭 막기

SDK가 3번 시도하고, 게이트웨이가 각 요청마다 3개 경로를 확인하며, 상위 프록시가 각 경로마다 2번 호출한다고 가정합니다.

클라이언트 3회 시도 × 게이트웨이 3회 시도 × 상위 제공자 2회 시도 = 제공자 호출 18회

한 사용자 동작이 제공자 호출 18건으로 늘어납니다. 장애 중에는 대기열, 요청 제한, 비용, 복구 시간이 모두 악화됩니다.

재시도 책임을 명시적으로 나눕니다.

  • 게이트웨이는 같은 계약의 다른 채널로 즉시 전환하는 작업을 담당합니다.
  • 애플리케이션은 전체 사용자 동작을 반복할 수 있는지 결정합니다.
  • 게이트웨이가 재시도하면 SDK 자동 재시도는 끄거나 엄격히 제한합니다.
  • 비동기 작업은 하나의 영구 작업 ID와 시도 원장을 사용합니다.
  • 호출자 취소 뒤에는 어떤 계층도 새 시도를 시작하지 않습니다.

각 계층의 시도 번호와 안정적인 종단 간 요청 ID를 함께 기록해야 합니다. 그렇지 않으면 각 계층은 두세 번만 시도한 것처럼 보이고 전체 증폭은 숨겨집니다.

대체 경로가 계약을 보존하는지 검증하기

공개 모델 이름이 같아도 경로 동작이 같다는 뜻은 아닙니다. 같은 계약의 투명한 대체 경로 집합에 채널을 추가하기 전에 다음 근거가 필요합니다.

계약 영역 필요한 증거
모델 식별 요청한 모델을 다른 모델로 몰래 매핑하지 않고 사용
엔드포인트 설정된 Responses 또는 Chat Completions 요청 수용
스트리밍 이벤트 유형, 종료, 사용량, 취소 처리
구조화된 출력 필요한 JSON Schema 하위 집합과 엄격 모드 동작
함수 호출 도구 정의, 호출 ID, 인수 스트리밍, 결과의 양방향 전달
한도 컨텍스트, 출력, 요청률, 동시성이 작업 부하에 적합
오류 비밀 값을 노출하지 않고 상태와 오류 본문을 분류할 수 있음
사용량과 비용 토큰, 캐시 필드, 서비스 등급, 가격 정책 정의
안전과 지역 필요한 정책, 데이터 경로, 데이터 저장 지역 유지

필수 영역 하나라도 실패하면 해당 경로는 그 작업 부하의 투명한 대체 경로가 아닙니다. 별도의 명시적인 제품 정책에서는 사용할 수 있습니다.

다른 모델로 변경하는 것은 항상 제품 결정입니다. 허용 모델, 최소 품질, 최대 가격, 도구 계약, 사용자에게 보일 안내를 정의해야 하며 경로 오류만으로 더 저렴하거나 성능이 낮은 모델을 조용히 사용하면 안 됩니다.

Modelflare의 현재 경로 전환 방식 이해하기

Modelflare는 API 클라이언트가 요청한 모델에 맞는 적격 경로를 찾습니다. 일반 API 키에는 기본 그룹과 순서가 있는 대체 그룹 목록을 둘 수 있습니다. 스마트 API 키는 라우팅 전략에 따라 계정이 사용할 수 있는 그룹을 평가합니다. 두 방식 모두 요청한 모델을 다른 모델로 조용히 바꾸지 않습니다.

그룹 수준 RPM 허용 판단은 과금과 상위 제공자 요청 전에 수행됩니다. 선택한 그룹이 가득 차면 순서가 있는 대체 그룹이나 스마트 라우팅 후보를 평가하고, 적격 그룹이 없으면 429를 반환합니다.

그룹 안에서는 채널 우선순위가 계정 전환 순서를 결정합니다. 상위 제공자 오류 뒤 실패한 채널을 제외하고 나머지 적격 채널을 선택합니다. 현재 채널 전환은 RetryTimes나 AutomaticRetryStatusCodes와 독립적이며 성공, 경로 소진, 호출자 취소, 또는 하위 응답이 시작돼 투명한 재실행이 불가능할 때 중단됩니다.

이는 같은 모델에 대한 내부 경로 결정이지 클라이언트가 무제한 재시도 반복문을 추가해도 된다는 뜻이 아닙니다. 그룹 및 채널 설계는 신뢰할 수 있는 AI API 라우팅, 게이트웨이 정책 오류와 상위 제공자 장애 구분은 AI API 오류 문제 해결을 참고하세요.

모든 시도의 근거 보존하기

최종 200은 첫 경로가 성공했다는 증거가 아니며 최종 채널 ID도 실패한 시도를 설명하지 못합니다. 최소한 다음을 보존합니다.

  • 안정적인 요청 ID와 호출자에게 보이는 상관관계 ID
  • 시도 순서와 그룹/채널 참조
  • 시도별 모델과 엔드포인트 계약
  • 실패 상태, 오류 유형, 스트림 단계
  • 하위 출력 시작 여부
  • 시간 지점과 취소 상태
  • 가능한 경우 입력·출력·캐시 토큰 사용량
  • 완료됐거나 청구 가능한 시도별 비용 귀속
  • 성공, 경로 소진, 취소, 부분 완료, 정책 중단 중 최종 사유

경로 전환 진단만을 위해 API 키, 원문 프롬프트, 원문 응답, 제공자 자격 증명을 저장하지 마세요. 민감 정보를 제거한 오류 유형과 시간 메타데이터로 충분한 경우가 많습니다. 요청 보관본은 명시적으로 활성화한 장애 조사에만 제한적이고 짧게 보관합니다.

운영 트래픽을 받기 전에 정책 훈련하기

실제 프로토콜 경계와 안전하고 결정적인 입력으로 사전 운영 환경에서 연습합니다.

  1. 헤더 전에 기본 채널을 비활성화하고 같은 모델의 다음 경로를 확인합니다.
  2. 요청 제한 오류를 반환해 시도 한도와 Retry-After를 확인합니다.
  3. 호출을 취소하고 이후 시도가 시작되지 않음을 증명합니다.
  4. 출력 뒤 스트림을 끊고 투명한 재실행이 없음을 확인합니다.
  5. 잘못된 요청을 보내 경로 전환이 오류를 숨기지 않는지 확인합니다.
  6. 도구 작업 흐름을 반복해 외부 효과가 하나만 기록되는지 확인합니다.
  7. 모든 경로를 소진해 명확한 최종 오류 하나를 확인합니다.
  8. 시도 원장을 점검하고 사용량과 비용을 대조합니다.

작은 작업 부하부터 적용하고 시도 횟수, 경로 전환 후 성공률, 원시 성공률을 따로 모니터링합니다. 비정상 경로를 빠르게 제거할 수 있어야 합니다. 목표는 경로 전환 횟수를 늘리는 것이 아니라 원래 모델 계약을 보존하면서 제한된 시간 안에서 안전하게 복구하고 모든 시도의 근거를 남기는 것입니다.