이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

모델 선택과 복구

상태: 활성 범위: 현재 상태 최종 검토: 2026-10-10 담당: ax-code 런타임

AX Code는 공급자와 모델 선택을 정확히 보존합니다. 공급자를 연결해도 자동 복구 풀에 들어가지 않습니다. 구성된 폴백이 없으면, 일시적 실패는 기존 재시도 한도 안에서 선택한 대상을 다시 시도한 뒤 멈춥니다.

순서가 있는 폴백 구성

llm_routing.fallback을 사용자 구성에 두거나, AX_CODE_CONFIG로 고른 사용자 지정 구성에 두거나, 명시적인 AX_CODE_CONFIG_CONTENT에 둡니다. 대상은 정확한 쌍입니다. 모델 ID에는 슬래시가 들어갈 수 있습니다. 예를 들면 다음과 같습니다.

{
  "model": "my-gateway/openai/gpt-oss-120b",
  "llm_routing": {
    "fallback": [
      { "providerID": "my-gateway", "modelID": "my-backup-model" },
      { "providerID": "my-other-provider", "modelID": "my-approved-model" }
    ]
  }
}

이 예시를 구성한 공급자의 정확한 ID로 바꿉니다. 목록은 서로 다른 대상을 최대 여덟 개까지 허용합니다. 비어 있거나 없으면 대상이 바뀌지 않는다는 뜻입니다. 프로젝트 구성과 원격 구성은 사용자 허가를 좁힐 수 있지만, 추가하거나 순서를 바꿀 수는 없습니다. 관리형 제한이 최종 상한을 제공합니다. 구성된 다음 대상이 없으면 복구가 멈춥니다. AX Code는 다른 카탈로그 항목으로 바꾸지 않습니다.

일반적인 일시적 속도 제한, 인식된 과부하, 서버 오류는 같은 대상에 대한 재시도 뒤에 이 목록으로 진행할 수 있습니다. 인증, 권한, 영구 할당량, 잘못된 요청 실패는 전환을 허가하지 않습니다. 로컬 공급자 세션은 원격 추론으로 자동 이전되지 않습니다. 취소하면 순서가 멈춥니다. 현재 요청이 출력을 게시하거나 도구를 시작한 뒤의 복구도 멈춥니다. 효과를 다시 재생하지 않고 부분 진행을 보존합니다.

프로세서는 보통 첫 시도 뒤에 같은 대상 재시도를 다섯 번 허용합니다. 동시성 제한 오류의 재시도 한도는 여덟 번입니다. 공급자 회로 차단기와 바깥 오류 한계가 더 일찍 멈출 수 있습니다. 성공한 도구 루프 단계는 이전 작업의 재시도가 아니라 새 요청입니다. 제어되는 직접 생성 지점에서는 AI SDK 재시도가 꺼집니다. 외부 CLI와 게이트웨이의 내부 시도는 밖에서는 보이지 않을 수 있습니다.

보조 작업과 기존 구성

small_model가 없으면 제목, 재요약, 컴팩션은 기본 모델을 물려받습니다. 명시적인 small_model나 역할별 에이전트 모델은 여전히 그 정확한 대상을 선택합니다. 잘못된 고정은 다른 공급자나 모델로 옮기지 않고 실패합니다. 선택적인 제목과 재요약 작업은 로컬 제목 및 건너뛰기 동작을 유지합니다. 컴팩션은 실패하면 대화 기록을 보존하고, 구성된 복구를 통해서만 모델을 바꿉니다.

구성된 기본 모델, 작업과 에이전트와 명령의 고정, 저장한 최근 선택도 정확한 값으로 남습니다. 사용할 수 없는 고정은 명시적으로 제거하거나 고칩니다. 구성이나 최근 선택이 없는 헤드리스 실행에는 --model가 필요합니다. 보이는 모델 선택기는 추천을 줄 수 있지만, 그 제안이 복구 목록이 되지는 않습니다.

선택적 복잡도 분류기에는 명시적인 보조 모델이 필요합니다. 없으면 분류를 건너뜁니다. 기본 모델이 주어지면 요청한 공급자에 묶입니다. 명시적인 기본 선택은 에이전트 주제 라우팅 뒤에도 유지됩니다.

유효 구성 검사

ax-code debug routing
ax-code debug routing --model my-gateway/openai/gpt-oss-120b

정확한 기본 모델, 순서가 있는 폴백, 보조 선택, 에이전트 고정, 재시도 한도를 출력합니다. 모델 요청을 보내거나 모델이 사용 가능한지 탐지하지는 않습니다. 일반적인 구성 로드는 구성된 원격 설정을 가져올 수 있습니다. 이것은 구성에 대한 설명이며, 과거의 게이트웨이 동작을 다시 구성한 것이 아닙니다.

사용자 메시지는 선택이 요청, 에이전트 고정, 복잡도 또는 하이브리드 라우팅, 세션이나 구성 기본값 중 어디에서 왔는지를 기록합니다. 이 원천은 로컬 진입을 설명합니다. request는 API 클라이언트를 누가 조작했는지 증명하지 않습니다. 요청 증거는 선택한 목적과 대상을 기록합니다. 모델이 만든 자기 설명과, 메모리나 도구 예시에 있는 모델 이름은 라우팅 증거가 아닙니다. 업스트림 라우팅과 인가에 대한 책임은 AX Trust와 외부 공급자에게 남아 있습니다.