Obter AX Code · GrátisDocumentação
AX Code.
pt-BR
English繁體中文简体中文日本語한국어FrançaisDeutschBahasa IndonesiaItalianoPortuguês (Brasil)РусскийEspañolTürkçeTiếng Việt
Começar

Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Integração do motor local (AX Code)

Status: Ativo Escopo: estado atual Última revisão: 2026-09-19 Responsável: ax-code runtime Relacionado: ax-engine LOCAL-ENGINE-CLIENTS

Configuração do runtime local

Selecione runtime AX-Engine em /connect e depois Selecionar um modelo. O AX Code configura o runtime local e o inicia quando o modelo selecionado é necessário. Não há formulário de URL de endpoint nem de chave de API. Ver status, Parar runtime local (quando estiver em execução) e Desativar administram o processo local.

O AX Code usa o backend HTTP sidecar do AX Engine. Ele inicia ax-engine serve, acompanha o processo de que é dono e resolve o endereço de loopback e a porta de forma automática. O usuário seleciona um modelo; o AX Code trata da configuração de transporte.

AX Code (TypeScript)
  -> select local model -> ensure/prepare -> spawn ax-engine serve
  -> managed loopback /v1 -> @ai-sdk/openai-compatible language model

Selecionar um modelo salva de forma explícita o ciclo de vida gerenciado e limpa os ajustes legados de endpoint e de chave de anexação. Isso também substitui um valor residual de AX_ENGINE_HOST. Clientes mais antigos do SDK conservam a API legada de anexação só em loopback e a validação de credencial dela. Esse caminho de compatibilidade não faz parte do menu de provedores.

O AX Code não liga o SDK do AX Engine no mesmo processo. O AX Engine é dono da execução do modelo, e o AX Code é dono do ciclo de vida do processo no cliente. Elegibilidade do host, preparação do modelo e checagens ao vivo de chamada de ferramenta continuam valendo.

A partida a frio tem um limite de prontidão de 600 segundos. O tempo de partida depende do tamanho do modelo, da vazão de armazenamento e da memória disponível. Uma partida esgotada interrompe o turno com o log do servidor e o caminho do modelo; o AX Code não reinicia sozinho outra carga a frio nem troca de provedor. Resolva o problema informado antes de tentar de novo de forma explícita. O envelope de preparação do modelo, inclusive a espera do bloqueio de ciclo de vida e a descoberta de capacidade, é limitado a 660 segundos. A expiração cancela a preparação pendente e interrompe novas tentativas automáticas. Cancelar uma solicitação também interrompe a espera na hora, mesmo quando uma dependência de preparação ainda não respondeu. Respostas de saúde que chegam depois do prazo de prontidão, ou depois que o processo de que se é dono sai, não podem estabelecer prontidão.

Quando fica pronto, o motor permanece residente entre os turnos da conversa. Concluir ou cancelar o turno que iniciou não para o motor pronto. Cancelar enquanto a partida ainda está em curso encerra essa tentativa e remove o registro do processo. Use Parar runtime local para parar de forma explícita um motor residente.

O AX Code segue o local padrão de cache da Hugging Face e respeita a escolha de armazenamento do usuário, inclusive discos locais e montagens SMB e NFS. A resolução do cache é HF_HUB_CACHE, depois HF_HOME/hub, depois XDG_CACHE_HOME/huggingface/hub e depois ~/.cache/huggingface/hub. Um caminho de modelo configurado de forma explícita, ou já preparado, tem precedência sobre a descoberta de cache. O AX Code não realoca pesos nem substitui essas escolhas com base no tipo de armazenamento. O diagnóstico de partida informa o caminho real do modelo para que se possa investigar disponibilidade e desempenho de leitura no armazenamento escolhido.

Para um motor já existente, o AX Code faz até três sondas de saúde, cada uma limitada a dois segundos e separadas por 250 milissegundos, antes de reiniciar um processo que não responde. Cancelar a solicitação preserva o processo existente.

Por que sidecar

Fator Escolha do sidecar
Linguagem do host Runtime de agente em Node/Bun, com uma fronteira explícita de processo nativo
Isolamento Modelos de vários GB e falhas nativas ficam fora do processo do agente
Atualização Piso empacotado limitado por versão, mais uma sobreposição gerenciada opcional, sem recompilar o ax-code
Modelo de provedor O mesmo caminho compatível com a OpenAI dos outros provedores locais e de nuvem
Vários clientes Um servidor pode ter a saúde conferida e ser parado por server.json

Fases do ciclo de vida

Implementação: packages/ax-code/src/provider/ax-engine/lifecycle.ts

Fase Quando (mapeamento do AX Code)
unavailable A elegibilidade da plataforma falha
missing_dependency Binário ausente, versão antiga demais ou não executável
missing_model Caminho do modelo não preparado
starting Processo do servidor registrado, mas ainda não pronto
ready server.ready e a saúde do processo em ordem
degraded Pronto, mas a inspeção de capacidade diz que toolcall não tem suporte
error Bloqueios de falha de saúde ou de partida numa tentativa em execução

A ordem de severidade acompanha docs/LOCAL-ENGINE-CLIENTS.md do ax-engine.

Área Caminho
Criação e saúde do servidor packages/ax-code/src/provider/ax-engine/server.ts
Carregador de provedor (gerenciado e anexado) packages/ax-code/src/provider/ax-engine/provider-loader.ts
Runtime local da TUI packages/ax-code/src/cli/tui/component/dialog-provider.tsx
Ajudantes de ação local packages/ax-code/src/cli/tui/component/dialog-provider-options.ts
Status agregado packages/ax-code/src/provider/ax-engine/status.ts
Mapeamento de fase packages/ax-code/src/provider/ax-engine/lifecycle.ts
Política de modelo Seleção de modelo do AX Engine

O provisionamento gerenciado de um sidecar fixado não é incorporação no mesmo processo. As versões Darwin-arm64 preparam engine/<version>/ ao lado da CLI; ax-code providers ax-engine install é a sobreposição ou o atualizador quando um pino mais novo é publicado.

O que não é objetivo

  • Substituir o sidecar por incorporação do SDK no mesmo processo, dentro do AX Code
  • Adotar gRPC como transporte principal de chat
  • Enquadramento personalizado de soquete Unix ou de chat que não seja OpenAI para clientes de primeira parte
  • Embutir pesos de modelo no instalador do AX Code