Skip to Content
개발 문서고급 기능장애 복구

장애 복구

OfoxAI의 장애 복구 메커니즘은 주 모델을 사용할 수 없을 때 자동으로 백업 모델로 전환하여 서비스가 중단되지 않도록 합니다.

동작 원리

  1. 주 모델로 요청을 전송합니다
  2. 주 모델이 오류를 반환하면 (5xx, 타임아웃, 속도 제한 등)
  3. fallback 목록의 모델을 순서대로 자동 시도합니다
  4. 첫 번째로 성공한 응답을 반환합니다

단일 요청 장애 복구

provider.fallback 파라미터를 통해 개별 요청에 대한 장애 복구를 설정합니다:

fallback.py
from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<OFOXAI_API_KEY>"
)
 
response = client.chat.completions.create(
    model="openai/gpt-4o",  # 주 모델
    messages=[{"role": "user", "content": "안녕하세요"}],
    extra_body={
        "provider": {
            "fallback": [
                "anthropic/claude-sonnet-4.5",  # 첫 번째 대체
                "google/gemini-3-flash-preview"              # 두 번째 대체
            ]
        }
    }
)
 
# 실제 사용된 모델 확인
print(response.model)
fallback.ts
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: '안녕하세요' }],
  // @ts-ignore OfoxAI 확장 파라미터
  provider: {
    fallback: [
      'anthropic/claude-sonnet-4.5',
      'google/gemini-3-flash-preview'
    ]
  }
})

전역 장애 복구 설정

OfoxAI 콘솔에서 전역 장애 복구 전략을 설정하면, 매 요청마다 지정할 필요가 없습니다:

  1. OfoxAI 콘솔 에 로그인합니다
  2. 설정 → 라우팅 전략으로 이동합니다
  3. 기본 장애 복구 모델 목록을 설정합니다

개별 요청의 fallback 파라미터는 전역 설정을 덮어씁니다.

장애 복구 트리거 조건

다음 상황에서 장애 복구가 트리거됩니다:

조건설명
HTTP 5xx서버 오류
요청 타임아웃모델 응답 타임아웃
429 속도 제한업스트림 모델이 속도 제한에 도달
모델 사용 불가공급자 유지보수 또는 서비스 중단

다음 상황에서는 장애 복구가 트리거되지 않습니다:

조건설명
HTTP 4xx (429 제외)클라이언트 오류, 요청 수정 필요
콘텐츠 필터링모델이 생성을 거부한 콘텐츠

라우팅과 함께 사용

장애 복구 메커니즘은 공급자 라우팅과 결합하여 사용할 수 있습니다:

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "안녕하세요"}],
    extra_body={
        "provider": {
            "routing": "latency",    # 지연 시간 우선 라우팅
            "fallback": [             # 장애 복구 목록
                "anthropic/claude-sonnet-4.5",
                "google/gemini-3-flash-preview"
            ]
        }
    }
)

추천 장애 복구 방안

범용 대화

"provider": {
    "fallback": ["anthropic/claude-sonnet-4.5", "google/gemini-3-flash-preview"]
}

코드 생성

"provider": {
    "fallback": ["anthropic/claude-sonnet-4.5", "deepseek/deepseek-chat"]
}

가성비

"provider": {
    "fallback": ["openai/gpt-4o-mini", "google/gemini-3-flash-preview", "deepseek/deepseek-chat"]
}

모범 사례

  1. 능력이 비슷한 대체 모델 선택 — 장애 복구 후에도 출력 품질이 일관되도록 보장
  2. 크로스 공급자 장애 복구 — 동일 공급자의 모델이 동시에 사용 불가한 상황 방지
  3. 2-3개의 대체 모델 설정 — 대부분의 장애 시나리오에 대응하기에 충분
  4. 장애 복구 빈도 모니터링 — 빈번한 장애 복구 발생 시 주 모델 교체를 고려
Last updated on
공급자 라우팅프롬프트 캐싱