Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал
Интеграция локального движка (AX Code)
Статус: активно Область: текущее состояние Последняя проверка: 2026-09-19 Владелец: среда выполнения ax-code Связанное: ax-engine LOCAL-ENGINE-CLIENTS
Настройка локальной среды выполнения
Выберите среду выполнения AX-Engine в /connect, затем Выбрать модель. AX Code
настраивает локальную среду выполнения и запускает её, когда выбранная модель нужна.
Формы URL конечной точки и ключа API нет. Показать статус, Остановить локальную среду
(когда она работает) и Отключить управляют локальным процессом.
AX Code использует бэкенд sidecar HTTP для AX Engine. Он запускает
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 не связывает SDK AX Engine внутри процесса. 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 делает до трёх проб здоровья, каждая не дольше двух секунд и с паузой 250 миллисекунд, прежде чем перезапустить процесс, который не отвечает. Отмена запроса сохраняет существующий процесс.
Почему sidecar
| Фактор | Выбор sidecar |
|---|---|
| Язык хоста | Среда агента Node/Bun с явной границей нативного процесса |
| Изоляция | Модели на много гигабайт и нативные сбои остаются вне процесса агента |
| Обновление | Нижняя граница комплекта с проверкой версии плюс необязательное управляемое наложение, без пересборки 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 |
Блокировки сбоя здоровья или запуска на идущей попытке |
Порядок серьёзности совпадает с docs/LOCAL-ENGINE-CLIENTS.md ax-engine.
Связанный код
| Область | Путь |
|---|---|
| Порождение сервера / здоровье | 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 |
Управляемое предоставление закреплённого sidecar — не встраивание в процесс. Выпуски Darwin-arm64
кладут engine/<version>/ рядом с CLI; ax-code providers ax-engine install
— наложение и средство обновления, когда публикуется более новое закрепление.
Вне целей
- Замена sidecar встраиванием SDK в процесс внутри AX Code
- Принятие gRPC как основного транспорта чата
- Пользовательский сокет Unix или обрамление чата не в стиле OpenAI для собственных клиентов
- Запекание весов модели в установщик AX Code