이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문
로컬 엔진 통합(AX Code)
상태: 활성 범위: 현재 상태 최종 검토: 2026-09-19 담당: ax-code 런타임 관련: ax-engine LOCAL-ENGINE-CLIENTS
로컬 런타임 설정
/connect에서 AX-Engine 런타임을 선택한 뒤 모델 선택을 합니다. AX Code는 로컬 런타임을 구성하고, 선택한 모델이 필요할 때 시작합니다. 엔드포인트 URL 양식이나 API 키 양식은 없습니다. 상태 보기, 실행 중일 때의 로컬 런타임 중지, 사용 안 함이 로컬 프로세스를 관리합니다.
AX Code는 AX Engine에 사이드카 HTTP 백엔드를 사용합니다. ax-engine serve를 시작하고, 소유한 프로세스를 추적하며, 루프백 주소와 포트를 자동으로 해석합니다. 사용자가 모델을 고르면 AX Code가 전송 구성을 처리합니다.
AX Code (TypeScript)
-> select local model -> ensure/prepare -> spawn ax-engine serve
-> managed loopback /v1 -> @ai-sdk/openai-compatible language model모델을 명시적으로 선택하면 관리되는 수명 주기가 저장되고, 남아 있던 레거시 연결 엔드포인트와 키 설정이 지워집니다. 남아 있는 AX_ENGINE_HOST 값도 덮어씁니다. 이전 SDK 클라이언트는 레거시 루프백 전용 연결 API와 그 자격 증명 검증을 유지합니다. 그 호환 경로는 공급자 메뉴에 들어 있지 않습니다.
AX Code는 AX Engine SDK를 프로세스 안에 링크하지 않습니다. 모델 실행은 AX Engine이 맡고, 클라이언트 쪽 프로세스 수명 주기는 AX Code가 맡습니다. 호스트 자격, 모델 준비, 실시간 도구 호출 검사는 계속 적용됩니다.
콜드 시작의 준비 한도는 600초입니다. 시작 시간은 모델 크기, 저장 장치 처리량, 사용 가능한 메모리에 따라 다릅니다. 시작 한도가 소진되면 서버 로그와 모델 경로와 함께 턴이 멈춥니다. AX Code는 다른 콜드 로드를 자동으로 다시 시작하거나 공급자를 바꾸지 않습니다. 명시적으로 다시 시도하기 전에 보고된 문제를 해결합니다. 수명 주기 잠금 대기와 능력 발견을 포함한 모델 설정 봉투의 한도는 660초입니다. 만료되면 대기 중인 설정이 취소되고 자동 재시도가 멈춥니다. 요청을 취소하면, 설정 의존성이 아직 응답하지 않았더라도 대기가 즉시 멈춥니다. 준비 기한이 지난 뒤나 소유한 프로세스가 종료된 뒤에 도착한 건강 응답으로는 준비를 확정할 수 없습니다.
준비가 되면 엔진은 대화 턴을 넘어 상주합니다. 시작을 일으킨 턴이 끝나거나 취소되어도 준비된 엔진은 멈추지 않습니다. 시작이 아직 진행 중일 때 취소하면 그 시도가 끝나고 프로세스 기록이 제거됩니다. 상주하는 엔진을 명시적으로 멈추려면 로컬 런타임 중지를 사용합니다.
AX Code는 표준 Hugging Face 캐시 위치를 따르고, 로컬 디스크, SMB, NFS 마운트를 포함한 사용자의 저장소 선택을 존중합니다. 캐시 해석 순서는 HF_HUB_CACHE, 그다음 HF_HOME/hub, 그다음 XDG_CACHE_HOME/huggingface/hub, 그다음 ~/.cache/huggingface/hub입니다. 명시적으로 구성했거나 이미 준비한 모델 경로는 캐시 발견보다 우선합니다. AX Code는 가중치를 옮기거나, 저장소 종류를 이유로 이 선택을 덮어쓰지 않습니다. 시작 진단은 실제 모델 경로를 보고하므로, 선택한 저장소에서 가용성과 읽기 성능을 살펴볼 수 있습니다.
이미 있는 엔진에 대해 AX Code는 응답하지 않는 프로세스를 다시 시작하기 전에 건강 탐지를 최대 세 번 합니다. 각 탐지는 2초로 제한되고 사이는 250밀리초입니다. 요청을 취소하면 기존 프로세스는 남습니다.
사이드카를 쓰는 이유
| 요인 | 사이드카가 선택한 것 |
|---|---|
| 호스트 언어 | 명시적인 네이티브 프로세스 경계가 있는 Node/Bun 에이전트 런타임 |
| 격리 | 수 GB 모델과 네이티브 크래시가 에이전트 프로세스 밖에 남습니다 |
| 업그레이드 | 버전으로 제한된 번들 하한과 선택적 관리 오버레이. ax-code를 다시 빌드하지 않습니다 |
| 공급자 모델 | 다른 로컬 및 클라우드 공급자와 같은 OpenAI 호환 경로 |
| 다중 클라이언트 | 서버 하나를 server.json로 건강 검사하고 중지할 수 있습니다 |
수명 주기 단계
구현: packages/ax-code/src/provider/ax-engine/lifecycle.ts
| 단계 | 시점(AX Code 대응) |
|---|---|
unavailable |
플랫폼 자격이 실패합니다 |
missing_dependency |
바이너리가 없거나, 버전이 너무 오래되었거나, 실행할 수 없습니다 |
missing_model |
모델 경로가 준비되지 않았습니다 |
starting |
서버 프로세스는 기록되었으나 아직 준비되지 않았습니다 |
ready |
server.ready와 프로세스 건강이 정상입니다 |
degraded |
준비되었으나 능력 검사가 도구 호출을 지원하지 않는다고 합니다 |
error |
실행 중인 시도에서 건강 또는 시작 실패가 막습니다 |
심각도 순서는 ax-engine docs/LOCAL-ENGINE-CLIENTS.md와 같습니다.
관련 코드
| 영역 | 경로 |
|---|---|
| 서버 생성 / 건강 | packages/ax-code/src/provider/ax-engine/server.ts |
| 공급자 로더(관리형과 연결) | packages/ax-code/src/provider/ax-engine/provider-loader.ts |
| TUI 로컬 런타임 | packages/ax-code/src/cli/tui/component/dialog-provider.tsx |
| 로컬 동작 도우미 | packages/ax-code/src/cli/tui/component/dialog-provider-options.ts |
| 집계 상태 | packages/ax-code/src/provider/ax-engine/status.ts |
| 단계 대응 | packages/ax-code/src/provider/ax-engine/lifecycle.ts |
| 모델 정책 | AX Engine 모델 선택 |
고정된 사이드카를 관리형으로 제공하는 것은 프로세스 안 임베딩이 아닙니다. Darwin-arm64 릴리스는 CLI 옆에 engine/<version>/를 배치합니다. 더 새로운 고정이 공개되면 ax-code providers ax-engine install가 오버레이이자 업데이트 프로그램입니다.
목표가 아닌 것
- AX Code에서 사이드카를 프로세스 안 SDK 임베딩으로 바꾸는 것
- gRPC를 주 채팅 전송으로 채택하는 것
- 자사 클라이언트를 위해 사용자 지정 Unix 소켓이나 OpenAI가 아닌 채팅 프레이밍을 쓰는 것
- 모델 가중치를 AX Code 설치 프로그램에 넣는 것