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

Provider personalizzati e gateway

Stato: attivo Ambito: stato attuale Ultima revisione: 2026-09-06 Responsabile: runtime di ax-code

AX Code parla con i modelli attraverso protocolli di provider standard. Qualsiasi endpoint che parla un’API compatibile con OpenAI (/v1/chat/completions) o compatibile con Anthropic (/v1/messages) può essere aggiunto come provider personalizzato puntando baseURL verso di esso: niente modifiche al codice e niente attesa di un preset integrato.

Questo copre aggregatori self-hosted e gateway di relay come LiteLLM, one-api, new-api e il Vercel AI Gateway, oltre a proxy aziendali privati e qualsiasi altro servizio compatibile. AX Code li tratta in modo uniforme: parla il protocollo sul filo, tu fornisci URL e chiave.

Nota di responsabilità. Un gateway sta tra AX Code e il modello upstream, quindi prompt, codice e credenziali lo attraversano. Quando punti AX Code a un relay di terze parti o di pooling di account, sei responsabile di fidarti di quell’operatore con i tuoi dati e di restare nei termini di servizio di ogni provider upstream verso cui instrada. I preset di gateway integrati come OpenRouter usano lo stesso percorso di protocollo standard; la configurazione di un gateway personalizzato non implica l’approvazione di alcun operatore di relay.

Configurazione interattiva

Usa /connect -> Provider cloud API -> Provider API personalizzato per un gateway compatibile, oppure /connect -> AX Trust -> Connetti AX Trust per un gateway AX Trust. Inserisci l’URL di base (incluso /v1 per AX Trust) e la chiave API del client. L’editor scopre gli ID dei modelli e i metadati e memorizza le credenziali nell’archivio di autenticazione cifrato. Può anche accettare ID di modello espliciti se la scoperta non è disponibile. Riconnettere un URL salvato ne conserva l’ID del provider e la chiave quando il token viene lasciato vuoto. Le connessioni AX Trust mantengono la propria categoria dopo le modifiche e gli aggiornamenti dei modelli. AX Code invia X-AX-Prompt-Cache-Key con l’ID della sessione su quelle connessioni così il gateway può tenere una sessione su un account idoneo; imposta provider.<id>.options.axTrust su false per disattivarlo. Questa intestazione non viene inoltrata upstream e non è un corpo prompt_cache_key.

I provider AX Trust connessi aggiornano in background gli elenchi dei modelli all’avvio. AX Code chiama GET /models dell’endpoint configurato con la credenziale esistente e aggiorna nomi dei modelli, limiti di contesto e output, ragionamento, chiamata di strumenti, supporto della temperatura e supporto delle immagini. I modelli capaci di immagini mostrano il marcatore di visione in /models, inclusi gli alias del gateway quando AX Trust annuncia il loro supporto alle immagini. La TUI si aggiorna quando la scoperta termina. Per gli ID esatti dei modelli DeepSeek di prima parte, i metadati mancanti vengono riempiti dal catalogo models.dev incluso. I flag di capacità e i limiti espliciti del gateway hanno la precedenza; gli alias sconosciuti non ereditano capacità per somiglianza del nome.

Un aggiornamento riuscito sostituisce l’elenco di runtime, rimuovendo i modelli non più annunciati dal gateway, e applica comunque gli elenchi di consenso e blocco configurati. Timeout, errori, risposte vuote o non valide conservano l’elenco salvato e registrano un fallimento di scoperta. L’avvio non attende la rete. Questo aggiornamento non riscrive la configurazione del provider né le credenziali; la configurazione salvata resta il ripiego di avvio. I provider API personalizzati ordinari conservano l’aggiornamento manuale.

Come viene risolto un provider

Per ogni richiesta AX Code ha bisogno di tre cose da una voce di provider:

• npm — l’adattatore AI SDK che parla il protocollo sul filo. Usa @ai-sdk/openai-compatible per gli endpoint in stile OpenAI e @ai-sdk/anthropic per gli endpoint in stile Anthropic. Solo gli adattatori @ai-sdk/* sono inclusi o installabili.
• options.baseURL — l’URL del gateway. Ripiega sul campo api del provider, poi sull’api.url proprio del modello. Supporta la sostituzione ${ENV_VAR}.
• Una credenziale — risolta in ordine da options.apiKey, poi dall’archivio di autenticazione persistente, poi dalle variabili env del provider.

Anche la configurazione manuale richiede una mappa esplicita models. L’editor interattivo popola questa mappa dall’endpoint o dagli ID di modello che fornisci.

I cloud GPU privati dedicati sono provider di prima classe sotto /connect → Cloud GPU privato. Incolla l’URL compatibile con OpenAI e il token (alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti o custom-private-gpu); AX Code chiama GET …/models e usa automaticamente gli ID dei modelli distribuiti.

I cataloghi GPU ospitati (nebius, fireworks-ai, togetherai, baseten, nvidia, deepinfra) usano una chiave API e l’istantanea dei modelli inclusa, lo stesso schema che usa OpenCode.

Gateway compatibile con OpenAI

La maggior parte degli aggregatori (LiteLLM, one-api, new-api, gateway gratuiti o self-hosted) espone una superficie compatibile con OpenAI. Aggiungi questo al tuo ax-code.json (globale in ~/.config/ax-code/ax-code.json, oppure per progetto alla radice del repository):

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-gateway": {
      "name": "My Gateway",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o (via gateway)",
          "tool_call": true,
          "reasoning": false,
          "attachment": true,
          "limit": { "context": 128000, "output": 16384 },
        },
      },
    },
  },
}

• La chiave "my-gateway" è l’id del provider che selezioni in /connect e ax-code models.
• Ogni chiave sotto models è l’ID di selezione locale. Imposta id della voce sull’ID esatto del modello che il gateway si aspetta quando differisce da quella chiave; altrimenti la chiave viene usata per i modelli dichiarati manualmente senza una mappatura di catalogo esistente.
• Preferisci ${ENV_VAR} a una chiave letterale così il segreto resta fuori dalla configurazione committata.

Alias dei modelli del gateway dopo il cambio di endpoint

Cambiare options.baseURL non traduce gli ID di modello configurati manualmente. Per esempio, un endpoint AX Trust può annunciare deepseek-flash mentre una selezione locale esistente è ax-trust/deepseek-v4-flash. Conserva la chiave locale e imposta provider.ax-trust.models.deepseek-v4-flash.id su deepseek-flash. AX Code invia allora l’ID del gateway nelle richieste API.

Vedi l’esempio di configurazione AX Trust DeepSeek Flash. Unisci i campi rilevanti del provider nella configurazione esistente, conservando gli altri modelli e le loro impostazioni di capacità. L’esempio usa {env:AX_TRUST_API_KEY}; imposta quella variabile d’ambiente prima di avviare AX Code, oppure conserva la configurazione delle credenziali esistente. Riavvia AX Code dopo la modifica.

Quando diagnostichi 403 model is not allowed, confronta l’ID del modello della richiesta con la risposta autenticata GET /models dell’endpoint. Una richiesta di elenco modelli riuscita da sola non stabilisce il permesso di eseguire un modello. Se l’ID esatto fallisce ancora, controlla i permessi di chiave e modello del gateway.

Gateway compatibile con Anthropic

I relay che espongono /v1/messages (la forma dell’API Claude) usano l’adattatore Anthropic:

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-claude-gateway": {
      "name": "My Claude Gateway",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://gateway.example.com",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet (via gateway)",
          "tool_call": true,
          "reasoning": true,
          "attachment": true,
          "limit": { "context": 200000, "output": 64000 },
        },
      },
    },
  },
}

Alcuni relay a forma Anthropic onorano anche direttamente le variabili d’ambiente di Claude. Per un’esecuzione headless rapida senza modificare la configurazione puoi impostare:

export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."

Una voce di configurazione resta consigliata quando vuoi che il gateway compaia come provider selezionabile proprio, con un elenco di modelli curato.

Campi del modello

Le voci di modello riusano lo schema del registro; per un endpoint personalizzato i campi utili sono:

Imposta i flag di capacità in modo che corrispondano a ciò che il modello upstream supporta davvero; AX Code li usa per vincolare le chiamate di strumenti, gli allegati e il budget del contesto.

Verifica

Dopo aver salvato la configurazione:

• ax-code models elenca ogni modello esposto dal tuo provider.
• /connect dentro la TUI mostra il provider e consente l’autenticazione se hai usato una chiave env invece di options.apiKey.

Se manca un modello, conferma l’id del provider, la chiave del modello e che il gateway sia raggiungibile a baseURL.

Risoluzione dei problemi

• Errori di autenticazione — conferma l’ordine di risoluzione delle credenziali: vince options.apiKey, altrimenti si usa una chiave env o dell’archivio di autenticazione.
• Flussi bloccati — i gateway a volte bufferizzano SSE. Regola options.chunkTimeout (per blocco) e options.timeout (intera richiesta) sul provider.
• Chiamate di strumenti rifiutate — imposta "tool_call": true sul modello e conferma che il modello upstream dietro il gateway supporti davvero gli strumenti.