Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

Fournisseurs personnalisés et passerelles

Statut : Actif Portée : état actuel Dernière revue : 2026-09-06 Responsable : runtime ax-code

AX Code parle aux modèles par des protocoles de fournisseur standard. Tout point de terminaison qui parle une API compatible OpenAI (/v1/chat/completions) ou compatible Anthropic (/v1/messages) peut être ajouté comme fournisseur personnalisé en pointant baseURL vers lui — sans changement de code et sans attendre un préréglage intégré.

Cela couvre les agrégateurs auto-hébergés et les passerelles relais telles que LiteLLM, one-api, new-api et la Vercel AI Gateway, ainsi que les proxys d’entreprise privés et tout autre service compatible. AX Code les traite de façon uniforme : il parle le protocole de liaison, vous fournissez l’URL et la clé.

Note de responsabilité. Une passerelle se place entre AX Code et le modèle en amont, donc vos invites, votre code et vos identifiants la traversent. Lorsque vous pointez AX Code vers un relais tiers ou de mise en commun de comptes, vous êtes responsable de faire confiance à cet opérateur pour vos données et de rester dans les conditions d’utilisation de chaque fournisseur en amont vers lequel il route. Les préréglages de passerelle intégrés tels qu’OpenRouter utilisent le même chemin de protocole standard ; la configuration d’une passerelle personnalisée n’implique pas l’aval d’un opérateur de relais.

Configuration interactive

Utilisez /connect -> Fournisseur API cloud -> Fournisseur API personnalisé pour une passerelle compatible, ou /connect -> AX Trust -> Connecter AX Trust pour une passerelle AX Trust. Saisissez son URL de base (y compris /v1 pour AX Trust) et la clé d’API client. L’éditeur découvre les identifiants de modèle et les métadonnées, et stocke les identifiants dans un stockage d’authentification chiffré. Il peut aussi accepter des identifiants de modèle explicites si la découverte est indisponible. Reconnecter une URL enregistrée conserve son identifiant de fournisseur et sa clé lorsque le jeton est laissé vide. Les connexions AX Trust gardent leur catégorie après les modifications et les rafraîchissements de modèles. AX Code envoie X-AX-Prompt-Cache-Key avec l’identifiant de session sur ces connexions afin que la passerelle puisse garder une session sur un compte éligible ; réglez provider.<id>.options.axTrust sur false pour le désactiver. Cet en-tête n’est pas transmis en amont et n’est pas un corps prompt_cache_key.

Les fournisseurs AX Trust connectés rafraîchissent leurs listes de modèles en arrière-plan au démarrage. AX Code appelle GET /models du point de terminaison configuré avec l’identifiant existant et met à jour les noms de modèles, les limites de contexte et de sortie, le raisonnement, l’appel d’outils, la prise en charge de la température et la prise en charge des images. Les modèles capables d’images affichent le marqueur de vision dans /models, y compris les alias de passerelle lorsque AX Trust annonce leur prise en charge d’images. Le TUI se met à jour lorsque la découverte s’achève. Pour les identifiants exacts des modèles DeepSeek de première partie, les métadonnées manquantes sont complétées depuis le catalogue models.dev embarqué. Les drapeaux de capacité et les limites explicites de la passerelle ont la préséance ; les alias inconnus n’héritent pas de capacités par similarité de nom.

Un rafraîchissement réussi remplace la liste d’exécution, en retirant les modèles que la passerelle n’annonce plus, et applique encore les listes d’autorisation et de blocage configurées. Les délais, les erreurs et les réponses vides ou invalides conservent la liste enregistrée et journalisent un échec de découverte. Le démarrage n’attend pas le réseau. Ce rafraîchissement ne réécrit pas la configuration du fournisseur ni les identifiants ; la configuration enregistrée reste le repli de démarrage. Les fournisseurs d’API personnalisés ordinaires conservent le rafraîchissement manuel.

Comment un fournisseur est résolu

Pour chaque requête, AX Code a besoin de trois choses d’une entrée de fournisseur :

• npm — l’adaptateur du SDK d’IA qui parle le protocole de liaison. Utilisez @ai-sdk/openai-compatible pour les points de terminaison de style OpenAI et @ai-sdk/anthropic pour les points de terminaison de style Anthropic. Seuls les adaptateurs @ai-sdk/* sont embarqués ou installables.
• options.baseURL — l’URL de la passerelle. Repli vers le champ api du fournisseur, puis vers le api.url propre du modèle. Prend en charge la substitution ${ENV_VAR}.
• Un identifiant — résolu dans l’ordre depuis options.apiKey, puis le magasin d’authentification persistant, puis les variables env du fournisseur.

La configuration manuelle a aussi besoin d’une carte models explicite. L’éditeur interactif remplit cette carte depuis le point de terminaison ou depuis les identifiants de modèle que vous fournissez.

Les clouds GPU privés dédiés sont des fournisseurs de premier plan sous /connect → Cloud GPU privé. Collez l’URL compatible OpenAI et le jeton (alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti ou custom-private-gpu) ; AX Code appelle GET …/models et utilise automatiquement les identifiants de modèles déployés.

Les catalogues GPU hébergés (nebius, fireworks-ai, togetherai, baseten, nvidia, deepinfra) utilisent une clé d’API et l’instantané de modèles embarqué, le même schéma qu’OpenCode.

Passerelle compatible OpenAI

La plupart des agrégateurs (LiteLLM, one-api, new-api, passerelles gratuites ou auto-hébergées) exposent une surface compatible OpenAI. Ajoutez ceci à votre ax-code.json (global à ~/.config/ax-code/ax-code.json, ou par projet à la racine du dépôt) :

{
  "$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 clé "my-gateway" est l’identifiant de fournisseur que vous sélectionnez dans /connect et ax-code models.
• Chaque clé sous models est l’identifiant de sélection local. Réglez le id de l’entrée sur l’identifiant de modèle exact attendu par la passerelle lorsqu’il diffère de cette clé ; sinon la clé est utilisée pour les modèles déclarés manuellement sans correspondance de catalogue existante.
• Préférez ${ENV_VAR} à une clé littérale afin que le secret reste hors de la configuration validée.

Alias de modèles de passerelle après un changement de point de terminaison

Changer options.baseURL ne traduit pas les identifiants de modèle configurés manuellement. Par exemple, un point de terminaison AX Trust peut annoncer deepseek-flash tandis qu’une sélection locale existante est ax-trust/deepseek-v4-flash. Conservez la clé locale et réglez provider.ax-trust.models.deepseek-v4-flash.id sur deepseek-flash. AX Code envoie alors l’identifiant de la passerelle dans les requêtes API.

Voir l’exemple de configuration AX Trust DeepSeek Flash. Fusionnez les champs de fournisseur pertinents dans votre configuration existante, en préservant les autres modèles et leurs réglages de capacité. L’exemple utilise {env:AX_TRUST_API_KEY} ; définissez cette variable d’environnement avant de démarrer AX Code, ou conservez votre configuration d’identifiants existante. Redémarrez AX Code après la modification.

Lorsque vous diagnostiquez 403 model is not allowed, comparez l’identifiant de modèle de la requête avec la réponse authentifiée GET /models du point de terminaison. Une requête de liste de modèles réussie seule n’établit pas la permission d’exécuter un modèle. Si l’identifiant exact échoue encore, vérifiez les permissions de clé et de modèle de la passerelle.

Passerelle compatible Anthropic

Les relais qui exposent /v1/messages (la forme de l’API Claude) utilisent l’adaptateur 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 },
        },
      },
    },
  },
}

Certains relais de forme Anthropic honorent aussi directement les variables d’environnement Claude. Pour une exécution rapide sans interface, sans modifier la configuration, vous pouvez définir :

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

Une entrée de configuration reste recommandée lorsque vous voulez que la passerelle apparaisse comme son propre fournisseur sélectionnable, avec une liste de modèles choisie.

Champs de modèle

Les entrées de modèle réutilisent le schéma du registre ; pour un point de terminaison personnalisé, les champs utiles sont :

Réglez les drapeaux de capacité pour correspondre à ce que le modèle en amont prend réellement en charge ; AX Code les utilise pour gater les appels d’outils, les pièces jointes et le budget de contexte.

Vérification

Après avoir enregistré la configuration :

• ax-code models liste chaque modèle que votre fournisseur expose.
• /connect dans le TUI montre le fournisseur et vous permet de vous authentifier si vous avez utilisé une clé env au lieu de options.apiKey.

Si un modèle manque, confirmez l’identifiant du fournisseur, la clé du modèle, et que la passerelle est joignable à baseURL.

Dépannage

• Erreurs d’authentification — confirmez l’ordre de résolution des identifiants : options.apiKey l’emporte, sinon une clé env ou du magasin d’authentification est utilisée.
• Flux bloqués — les passerelles mettent parfois SSE en tampon. Réglez options.chunkTimeout (par fragment) et options.timeout (requête entière) sur le fournisseur.
• Appels d’outils rejetés — définissez "tool_call": true sur le modèle et confirmez que le modèle en amont derrière la passerelle prend réellement en charge les outils.