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

폴백

provider.fallback에는 대체 모델을 나열합니다. 주 모델이 업스트림에서 실패하면 목록 순서대로 시도합니다.

설정 방법

fallback은 모델 ID 배열을 받으며 type과 같은 층위에서 provider 아래에 놓입니다. 최대 3개 모델이며 초과하면 400을 반환합니다.

Terminal
curl https://api.ofox.run/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": "..." }],
    "extra_body": {
      "provider": {
        "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"]
      }
    }
  }'

공식 OpenAI SDK를 사용할 때 extra_body는 요청 본문에 문자 그대로의 키로 존재해야 합니다. TypeScript SDK는 파라미터 객체에 작성한 그대로 전송합니다. Python SDK의 extra_body= 인자는 내용을 본문 최상위로 병합하므로, 키를 한 단계 더 중첩하거나 요청 헤더로 전달해야 합니다.

폴백이 발생하는 경우

폴백은 라우팅이 채널을 고른 뒤에 발생한 실패만 커버합니다:

상황동작
업스트림 공급자가 오류를 반환폴백 — 목록의 모델을 순서대로 시도하고 처음 성공한 응답을 반환합니다
라우팅 단계 실패(모델이 없거나, 지정한 공급자가 그 모델을 제공하지 않음)폴백하지 않음 — 요청이 즉시 종료됩니다

두 번째 행은 분명히 적어둘 만합니다: 해당 모델을 제공하지 않는 공급자를 provider.type으로 지정하면 400 provider_type_unavailable, 존재하지 않는 모델을 지정하면 404 model_not_found가 반환되며 둘 다 fallback 목록까지 가지 않습니다.어떤 업스트림 오류가 폴백을 발생시키는지는 고정된 목록이 아니라 게이트웨이의 실제 동작을 따릅니다.

공급자 지정과의 조합

fallback과 type은 함께 보낼 수 있습니다. type은 주 모델이 어느 공급자에서 실행될지를 제약하고, fallback은 주 모델이 실패한 뒤를 담당합니다:

{
  "model": "anthropic/claude-sonnet-5",
  "messages": [{ "role": "user", "content": "..." }],
  "extra_body": {
    "provider": {
      "type": "bedrock",
      "fallback": ["openai/gpt-5.5"]
    }
  }
}

필드 전체 설명은 공급자 라우팅을 참고하세요.

자주 발생하는 오류

error.type발생 조건
invalid_request_errorfallback 목록의 모델이 3개를 넘었습니다.

권장 사항

  1. 능력이 비슷한 대체 모델을 고르세요 — 폴백 이후에도 출력 품질이 일정하도록.
  2. 공급사를 넘나드는 대체 모델 — 같은 공급사의 모델은 함께 사용 불가가 되기 쉽습니다.
  3. 발생 빈도를 모니터링하세요 — 자주 발생한다면 주 모델을 교체할 때입니다.
Last updated on
공급자 라우팅프롬프트 캐싱