모델 폴백

기본 모델이 rate limit, 오류, 또는 다른 구성된 상태 코드를 반환할 때 백업 모델에 대해 요청을 자동으로 재시도하는 방법을 알려드릴게요.

참고: LLM Gateway는 베타 상태입니다.

모델 폴백은 기본 모델이 rate limit이나 프로바이더 중단 같은 구성된 오류를 반환할 때 하나 이상의 백업 모델에 대해 요청을 재시도합니다. LangSmith에서 폴백 순서를 한 번 정의한 뒤 애플리케이션에서 표준 LLM Gateway 엔드포인트와 모델 ID를 계속 사용하세요.

출처: 문서

본문

동작 방식

폴백 체인은 다음으로 구성됩니다:

기본 모델(primary model): 요청이 실패할 때 체인을 트리거하는 프로바이더와 모델.
하나에서 다섯 개의 폴백: 직접 프로바이더 모델 또는 저장된 모델 구성의 정렬된 목록.
트리거(triggers): 요청을 다음 모델로 이동시키는 업스트림 HTTP 상태 코드. 예: rate limit용 429, 프로바이더 오류용 500, 502, 503, 504.

각 요청에 대해 게이트웨이는:

요청의 프로바이더 접두사 모델 ID로 선택된 기본 모델을 호출합니다.
요청이 구성된 트리거 상태 또는 전송 오류로 실패하면 일치하는 폴백 체인을 로드합니다.
성공하거나, 다른 폴백을 트리거하지 않는 상태를 반환하거나, 체인이 소진될 때까지 각 폴백을 순서대로 호출합니다.
클라이언트가 사용하는 API 형식으로 최종 응답을 반환합니다.

폴백은 기본 모델과 다른 프로바이더와 API 형식을 사용할 수 있습니다. 게이트웨이는 지원되는 API 형식 사이에서 요청·응답을 변환하므로 클라이언트 측 변경 없이 Anthropic 기본 모델이 OpenAI 모델로 폴백할 수 있습니다.

각 시도는 별도로 트레이싱되고 spend 정책에 계산됩니다. 두 개의 폴백을 사용하는 요청은 세 개의 모델 호출(기본 시도와 두 폴백 시도)을 기록합니다.

폴백 체인 만들기

경고: 폴백 체인 생성·관리에는 organization:manage 권한이 필요합니다. 전체 권한 분석은 접근 제어를 참고하세요.

폴백 체인을 만들려면:

LLM Gateway로 이동해 Model Fallbacks 탭을 선택합니다.
Create fallback chain을 클릭합니다.
체인이 적용되는 워크스페이스(Workspace) 를 선택합니다.
기본 프로바이더와 모델을 선택합니다. 이 프로바이더 접두사 모델 ID에 대한 요청은 기본 시도가 실패할 때 체인을 사용합니다.
Fallbacks 아래에 게이트웨이가 시도할 순서로 하나에서 다섯 개의 백업 모델을 추가합니다. 프로바이더와 모델을 직접 선택하거나, 기존 모델 구성을 선택하거나, 커스텀 모델 구성을 만듭니다.
Configure fallback triggers (advanced) 아래에서 다음 폴백을 트리거해야 하는 HTTP 상태 코드를 검토합니다. 필요에 따라 상태 코드를 추가·제거합니다.
Create chain을 클릭합니다.

프로바이더와 모델은 각 워크스페이스에서 하나의 폴백 체인을 가질 수 있습니다. 동작을 변경하려면 기존 체인을 편집하세요.

호출하기

기본 프로바이더 접두사 모델 ID로 표준 LLM Gateway 엔드포인트를 호출합니다. 경로별 URL이나 추가 요청 필드는 필요 없습니다:

curl https://gateway.smith.langchain.com/v1/chat/completions \
    -H "Authorization: Bearer $LANGS..._KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"anthropic/claude-opus-5","messages":[{"role":"user","content":"Hello!"}]}'

curl https://<data_plane_host>/gateway/v1/chat/completions \
    -H "Authorization: Bearer $LANGS..._KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"anthropic/claude-opus-5","messages":[{"role":"user","content":"Hello!"}]}'

게이트웨이는 API 키의 워크스페이스에서 anthropic/claude-opus-5용으로 구성된 폴백 체인을 적용합니다. 일치하는 체인이 없으면 게이트웨이는 폴백을 시도하지 않고 기본 모델의 응답을 반환합니다.

프롬프트에 폴백 설정하기

프롬프트에 자체 폴백 체인을 부여하려면 저장된 모델 구성을 통해 라우팅하세요. 프롬프트는 이름으로 구성을 참조하고, 게이트웨이는 그 폴백 체인을 관리합니다.

구성 생성에는 워크스페이스 관리자 권한이 필요합니다. 폴백 체인 생성에는 organization:manage 권한이 필요합니다.

프롬프트에 폴백을 구성하려면:

프롬프트가 사용할 프로바이더와 모델을 가리키는 모델 구성을 만듭니다.
같은 워크스페이스에서 폴백 체인을 만듭니다. 기본 모델을 선택할 때 기본이 되는 프로바이더·모델을 직접 선택하는 대신 저장된 구성을 선택합니다. 백업 모델을 추가하고, 트리거를 구성하고, 체인을 저장합니다.
Playground에서 프롬프트를 만듭니다. Model Configuration을 열고 Provider로 LangSmith Gateway를 선택한 다음 Model 필드에 custom/<my_config_name>을 입력합니다. <my_config_name>을 저장된 구성의 이름으로 바꿉니다(꺾쇠 괄호 제외). 목록에 없어도 값을 입력할 수 있습니다. Apply를 클릭합니다.
프롬프트를 저장한 다음 모델과 함께 풀링합니다. Python에서 client.pull_prompt 호출 시 include_model=True를 설정해 저장된 Gateway 모델 구성을 포함시킵니다.

저장된 모델과 함께 풀링된 프롬프트를 호출하면 게이트웨이를 통해 요청을 보내고 구성의 폴백 체인을 적용합니다. 프롬프트 템플릿만 풀링하면 모델 구성이 포함되지 않습니다.

폴백 체인은 프롬프트 자체가 아니라 모델 구성에 속합니다. 동일한 구성을 참조하는 프롬프트는 그 폴백을 공유합니다. 다른 폴백 동작이 필요한 각 프롬프트에는 별도의 구성을 사용하세요.

폴백 후보 선택

두 가지 유형의 폴백 후보를 추가할 수 있습니다:

직접 프로바이더 모델: 지원되는 게이트웨이 프로바이더와 모델을 선택합니다. 이 옵션은 해당 프로바이더의 워크스페이스 시크릿을 사용하거나, 자격 있는 호스팅 모델은 Gateway Credits를 사용합니다.
모델 구성: 저장된 워크스페이스 모델 구성을 선택합니다. 커스텀 OpenAI 호환 또는 Anthropic 엔드포인트, 커스텀 모델 이름, 구성별 파라미터에 이 옵션을 사용하세요.

모델 구성은 워크스페이스 범위입니다. 폴백 체인은 선택한 워크스페이스의 구성만 사용할 수 있습니다.

예를 들어 anthropic/claude-opus-5를 기본 모델로, openai/gpt-5.4-mini를 첫 폴백으로, 저장된 OpenAI 호환 모델 구성을 두 번째 폴백으로 구성합니다. 애플리케이션은 계속 anthropic/claude-opus-5를 요청합니다. 필요할 때 게이트웨이가 폴백 호출을 선택하고 변환합니다.

함께 보기

API 형식: 지원되는 요청 형식과 변환 동작 검토.
Spend 정책: 폴백 라우팅과 함께 비용 한도 적용.

더 알아보기

API 형식 — 지원 요청 형식.
Spend 정책 — 비용 한도.