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

다중 모델 라우팅 모범 사례

상태: 활성 범위: 공개, 현재 상태 최종 검토: 2026-09-13 담당: ax-code 런타임

이 가이드는 프리미엄 추론 모델과, 같은 공급자의 더 저렴한 보조 모델로 ax-code를 실행하는 권장 방법을 적습니다.

핵심 원칙

추론 밀도가 높은 작업에는 비싼 모델을 쓰고, 기계적이거나 읽기 전용인 작업에는 싼 모델을 씁니다. 실제 절약은 맥락 거르기에서 옵니다. 프리미엄 모델은 더 싼 모델이나 서브에이전트가 준비한, 추려진 맥락만 봅니다.

권장하는 계층 분리

계층	모델 등급	일반적인 에이전트와 작업
작업자 / 실행기	연결할 수 있을 때의 flash SKU(예: DeepSeek Flash)	고정되지 않은 세션, `build`, `general`, `scout`, `test`, `devops`, `perf`
조언자 / 추론	더 강한 연결 모델(예: DeepSeek V4 Pro)	`plan`, `architect`, `security`, `debug`
저렴한 읽기 전용 보조	같은 flash SKU	`explore`, `compaction`, 제목, 재요약, 낮은 복잡도 분류

연결된 provider/model ID를 고정합니다. 꺼진 자사 플랜 ID(alibaba-token-plan, deepseek, zai-coding-plan, minimax-coding-plan)는 여전히 SKU로 해석되지만, 각 호출은 먼저 꺼진 공급자를 시도하고 경고합니다. Qwen 3.8 Max는 유효한 명시적 선택이며, 제품이나 예시의 기본값은 아닙니다. config.model가 없으면 암시적 기본값은 연결된 카탈로그를 다음 순서로 살펴봅니다. deepseek-flash, glm-5.3-flash, qwen3.8-flash, MiniMax-M3, grok-4.6, claude-sonnet-5, gpt-6, gemini-3.8-flash, qwen3.8-27b입니다.

구성 템플릿

저장소 루트의 ax-code.json.example를 보십시오. 추론 에이전트에는 Pro를 두고 DeepSeek Flash를 기본으로 하는 구체적인 예입니다.

Codex CLI 보조 모델

Codex 모델의 가용성은 계정의 로그인 방식과 클라이언트에 달려 있으며, 카탈로그의 텍스트 능력이나 도구 능력만으로 결정되지 않습니다. 그래서 AX Code는 이름이나 계열 메타데이터에서 codex-cli 소형 모델을 추론하지 않습니다. 명시적인 small_model나 컴팩션 에이전트 모델이 없으면 컴팩션은 세션 모델을 사용합니다.

보조 모델을 구성하면, 같은 Codex 로그인으로 동작하는지 확인합니다. ChatGPT 계정에서 그 모델을 지원하지 않는다는 명시적인 Codex 거부가 있으면, 컴팩션은 다른 소형 모델을 건너뛰고 세션 모델을 한 번 시도할 수 있습니다. 거부된 시도는 세션 기록에 남습니다. 그 밖의 인증, 청구, 검증, 취소, 맥락 넘침 실패는 기존 처리를 유지합니다. 로컬 공급자의 프라이버시 가드도 계속 적용됩니다.

영향을 받는 이전 설치에서는 호환되지 않는 small_model 또는 agent.compaction.model 덮어쓰기를 제거하고, 그 Codex 계정으로 이미 확인된 모델에 agent.compaction.model를 명시적으로 고정합니다. 보이는 세션 모델만 바꿔도 따로 고정된 컴팩션 모델은 덮어쓰이지 않습니다.

작업 유형별 자동 라우팅 규칙

가치가 낮은 작업을 모두 싼 모델로 자동 라우팅하지 마십시오. 실패했을 때의 비용으로 나눕니다.

자동 라우팅해도 안전합니다(읽기 전용이거나 사람이 검토할 수 있습니다).
- 저장소 탐색, grep과 검색의 분류, 파일 분류
- 코드 요약, 로그 요약, 코드 설명
- 프리미엄 모델을 위한 맥락 준비
- 문서
선택했을 때만(기계적으로 검증할 수 있지만 동작 변화를 숨길 수 있습니다).
- 상용구, lint 수정
기본적으로는 자동 라우팅하지 않습니다(조용한 오류의 비용이 큽니다).
- 단위 테스트
- 이름 바꾸기와 리팩터
- 단순한 SQL
- API 래퍼
- 단순한 CRUD

마지막 묶음은 사용자가 더 싼 모델을 명시적으로 고정하지 않는 한 세션 모델에 둡니다.

운영 절차

사소하지 않은 작업은 plan 모드에서 시작합니다. 작업자가 코드를 쓰기 전에 조언자가 설계를 검증합니다.
작업자가 같은 자리를 맴돌거나 검증에 두 번 실패하면, 실패 신호와 함께 debug로 바꿉니다.
그럴듯한 수정이 두 가지일 때의 독립된 진단에는 council를 사용합니다. 작업을 끝내는 용도가 아닙니다.
수동 모델 전환은 추론이 무거운 드문 턴에만 쓰고, 그 뒤에는 되돌립니다.

알려진 ax-code 제한

Provider.getSmallModel()는 undefined를 반환합니다. 대상은 카탈로그가 등급을 담는 family에 태그를 달지 않고, 하드코딩된 우선순위 목록과도 맞지 않는 공급자입니다. 그러면 보조 호출은 세션 모델로 돌아가며, “공급자에 소형 모델이 없음”으로 기록됩니다.
실행 도중에 막힌 작업자를 더 강한 모델로 올리는 경로는 없습니다.