Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

Integrazione del motore locale (AX Code)

Stato: Attivo Ambito: stato attuale Ultima revisione: 2026-09-19 Responsabile: runtime di ax-code Correlato: ax-engine LOCAL-ENGINE-CLIENTS

Configurazione del runtime locale

Seleziona AX-Engine runtime in /connect, poi Select a model. AX Code configura il runtime locale e lo avvia quando serve il modello selezionato. Non c’è un modulo per l’URL dell’endpoint né per la chiave API. View status, Stop local runtime (quando è in esecuzione) e Disable gestiscono il processo locale.

AX Code usa il backend HTTP sidecar per AX Engine. Avvia ax-engine serve, tiene traccia del processo di sua proprietà e risolve in automatico l’indirizzo di loopback e la porta. L’utente seleziona un modello; AX Code gestisce la configurazione del trasporto.

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

Selezionare un modello in modo esplicito salva il ciclo di vita gestito e cancella le impostazioni legacy di endpoint e chiave di attach. Questo scavalca anche un valore AX_ENGINE_HOST rimasto. I client SDK più vecchi conservano l’API di attach legacy solo su loopback e la sua validazione delle credenziali. Quel percorso di compatibilità non fa parte del menu dei provider.

AX Code non collega l’SDK di AX Engine nel processo. AX Engine possiede l’esecuzione del modello, e AX Code possiede il ciclo di vita del processo lato client. Idoneità dell’host, preparazione del modello e controlli vivi delle chiamate di strumenti si applicano comunque.

L’avvio a freddo ha un limite di prontezza di 600 secondi. Il tempo di avvio dipende dalla dimensione del modello, dal throughput dello storage e dalla memoria disponibile. Un avvio esaurito ferma il turno con il log del server e il percorso del modello; AX Code non riavvia in automatico un altro caricamento a freddo e non cambia provider. Risolvi il problema segnalato prima di ritentare in modo esplicito. La busta di configurazione del modello, inclusi l’attesa del lock del ciclo di vita e la scoperta delle capacità, è limitata a 660 secondi. La scadenza annulla la configurazione in attesa e ferma i tentativi automatici. Annullare una richiesta ferma anche l’attesa subito, anche quando una dipendenza di configurazione non ha ancora risposto. Le risposte di salute che arrivano dopo la scadenza di prontezza, o dopo l’uscita del processo posseduto, non possono stabilire la prontezza.

Una volta pronto, il motore resta residente tra i turni della conversazione. Completare o annullare il turno che lo ha avviato non ferma il motore pronto. Annullare mentre l’avvio è ancora in corso termina quel tentativo e rimuove il suo record di processo. Usa Stop local runtime per fermare in modo esplicito un motore residente.

AX Code segue la posizione standard della cache di Hugging Face e rispetta la scelta di storage dell’utente, inclusi dischi locali e montaggi SMB e NFS. La risoluzione della cache è HF_HUB_CACHE, poi HF_HOME/hub, poi XDG_CACHE_HOME/huggingface/hub, poi ~/.cache/huggingface/hub. Un percorso di modello configurato in modo esplicito, o già preparato, ha la precedenza sulla scoperta della cache. AX Code non sposta i pesi e non scavalca queste scelte in base al tipo di storage. La diagnostica di avvio riporta il percorso reale del modello, così gli utenti possono indagare disponibilità e prestazioni di lettura nello storage scelto.

Per un motore esistente, AX Code fa fino a tre sonde di salute, ciascuna limitata a due secondi e separate da 250 millisecondi, prima di riavviare un processo che non risponde. Annullare la richiesta conserva il processo esistente.

Perché il sidecar

Fasi del ciclo di vita

Implementazione: packages/ax-code/src/provider/ax-engine/lifecycle.ts

L’ordine di gravità corrisponde a docs/LOCAL-ENGINE-CLIENTS.md di ax-engine.

Codice correlato

Il provisioning gestito di un sidecar fissato non è un incorporamento nel processo. I rilasci Darwin-arm64 preparano engine/<version>/ accanto alla CLI; ax-code providers ax-engine install è l’overlay o l’aggiornatore quando viene pubblicato un pin più nuovo.

Non obiettivi

• Sostituire il sidecar con l’incorporamento nel processo dell’SDK dentro AX Code
• Adottare gRPC come trasporto di chat primario
• Framing di chat su socket Unix personalizzato, o non OpenAI, per i client di prima parte
• Incorporare i pesi del modello nell’installer di AX Code