Version 1.0.0-alpha.1dernière version
Chapitre 2.14
Fournisseurs et modèles d'IA
Comment le routeur de fournisseurs d'intelligence artificielle (IA) sélectionne un modèle dans le pool de clés propre à l'organisation, et comment les scripts et outils d'IA accèdent à Nexus depuis l'extérieur.
Cette page a été traduite par l'IA à partir de l'original en anglais. En cas de doute, la page en anglais fait foi. Lire cette page en anglais

Harrow Port Authority exploite deux installations. Celle qui se trouve sur son réseau d'exploitation isolé (chapitre 2.10, Installation isolée) ne dispose d'aucun fournisseur hébergé. Sur l'installation d'entreprise connectée, que suit ce chapitre, la plupart des questions trouvent leur réponse auprès d'un modèle exécuté sur deux nœuds de processeurs graphiques (GPU) situés dans la propre salle des serveurs du port. Une clé Google Gemini, payée par Harrow, absorbe le surplus lorsque le modèle local est occupé, et Aoife Brennan a verrouillé le trafic d'intelligence artificielle (IA) de l'organisation sur l'UE. Personne chez Harrow n'a configuré de modèle à l'intérieur d'un service ou d'un plugin. Ils ont indiqué à un seul composant ce que Harrow possède, et ce composant décide de chaque appel.
Ce chapitre traite de ce composant, l'AI Provider Router, que la partie 1 et la console appellent le standard IA, ainsi que du pool de clés dans lequel il puise. Il se termine par les moyens dont disposent les scripts et les outils d'IA pour joindre Nexus depuis l'extérieur : les clés pour scripts, l'interface de programmation d'application (API) REST (transfert d'état représentationnel) et le Model Context Protocol (MCP).
L'AI Provider Router
Le routeur s'exécute à l'intérieur de la passerelle, nexus-gateway. C'est le seul service qui détient les identifiants de modèle d'une organisation, et il prend la décision finale quant au fournisseur et au modèle qui répondent à chaque requête. Toutes les autres parties de Nexus le sollicitent. Une étape de flux de travail indique ce qu'elle souhaiterait, et le routeur décide.
Seuls quelques services peuvent le solliciter, et chaque liste est fixée par le chart :
| Ce qui est demandé | Qui peut demander |
|---|---|
Une complétion (/internal/ai/chat et son flux) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Les appels d'outils et les autres routes d'IA internes | nexus-orchestrator, nexus-workflows |
| Les plongements lexicaux (embeddings) et le reclassement (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Chaque route interne vérifie deux éléments tour à tour : la clé de service interne de l'appelant, et l'identité de l'appelant par rapport à la liste ci-dessus. Une requête sans la clé est refusée avec MISSING_SERVICE_KEY (401), une clé erronée avec INVALID_SERVICE_KEY (403), une requête qui n'indique pas qui appelle avec MISSING_CALLER_IDENTITY (403), et un appelant hors de la liste avec UNAUTHORIZED_CALLER (403). Aucune de ces requêtes ne fait l'objet d'une nouvelle tentative, car aucune ne résulte d'une défaillance passagère.
Les applications et les plugins n'apparaissent jamais sur cette liste. Un plugin déclare ses souhaits sur les compétences qu'il enregistre et les achemine via UNO, le moteur de flux de travail. L'orchestrateur interroge ensuite le routeur au nom du plugin. C'est pourquoi la fuite d'un secret de plugin permet d'agir en tant que ce plugin, mais ne permet pas de dépenser le budget de modèles de qui que ce soit.
Le pool de clés de l'organisation
Les clés de modèle appartiennent à l'organisation. Chaque organisation apporte son propre compte de fournisseur et paie sa propre facture, et la clé réside dans le pool de l'organisation, chiffrée dans nexus-auth. Il n'y a pas de clé de plateforme partagée derrière une organisation, de sorte qu'aucune organisation ne dépense jamais le budget d'une autre. Le prix de cette règle est clair : une organisation sans clé dans son pool n'obtient aucune réponse de l'IA. L'assistant affiche MODEL_NOT_CONNECTED (503) et indique qui peut en connecter une.
Une clé peut être ajoutée au pool pour quatre fournisseurs :
| Identifiant du fournisseur | Affiché sous le nom |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Un serveur de modèle qui vous est propre
Une organisation peut également utiliser n'importe quel serveur qu'elle exploite et qui utilise l'API compatible OpenAI, tel que le modèle sur les nœuds GPU de Harrow. L'installateur le nomme dans le fichier des valeurs :
# harrow-values.yaml (Helm values): the AI part
ai:
localProvider:
baseUrl: "https://models.harrow.example/v1"
installationHosts:
- models.harrow.example
- 10.40.20.0/24
networkPolicy:
externalEgressCIDRs:
- 10.40.20.0/24ai.localProvider.baseUrl fait pointer l'adaptateur compatible OpenAI de la passerelle vers votre serveur. Sur une installation, l'emplacement scaleway du pool joint ce serveur, de sorte que la clé que vous ajoutez pour scaleway est la clé qu'attend votre propre serveur.
ai.installationHosts répertorie les noms d'hôtes qui se trouvent à l'intérieur de l'installation, en plus du propre domaine de service de la version et des trois hôtes publics. Chaque entrée est un nom d'hôte, un .suffix, une adresse IP ou une plage IPv4 de routage inter-domaines sans classe (CIDR). Le routeur utilise la liste pour distinguer un appel qui reste sur site d'un appel qui le quitte, ce que rapporte la vérification « Rien ne quitte ce site » sur la page Connecter un modèle sur votre propre matériel.
La politique réseau importe autant que le routeur. L'espace de noms refuse tout trafic sortant par défaut, de sorte que la passerelle ne peut joindre un serveur de modèle en dehors de l'espace de noms que lorsque sa plage figure dans networkPolicy.externalEgressCIDRs. Il en va de même pour un fournisseur hébergé : si Harrow veut que sa clé Gemini réponde, les plages d'adresses du fournisseur doivent également y être répertoriées, sinon l'appel ne quitte jamais le cluster. Le chapitre 2.16, Sécurité et réseau, couvre la politique dans son intégralité.
Ajouter et retirer des clés
Les propriétaires et les administrateurs d'une organisation gèrent son pool. Toute autre personne ne peut ni voir les clés ni les modifier, et toute requête de sa part est refusée avec AUTHORITY_EXCEEDED.
Dans la console
Sur Enterprise, le pool est conservé dans le standard IA, sous les moteurs. Sur Community, les mêmes clés sont conservées dans Paramètres, Modèles d'IA. Cette page est le routeur de base, où vous ajoutez des clés et une adresse de modèle local, et choisissez quel modèle effectue quelle tâche. Les deux affichent chaque clé selon la personne qui l'a définie et quand (« Définie par Aoife, 3 sept. ») et par un indice masqué de ses quatre derniers caractères au maximum, tel que ••••7f2q. La clé elle-même n'est plus jamais affichée après que vous l'avez ajoutée.
Via l'API BFF
Le backend for frontend (BFF) de la console sert trois routes pour le pool. Appelez-les avec le propre jeton d'accès d'une personne : l'organisation provient du jeton, jamais de la requête.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET renvoie les fournisseurs présents dans le pool, indique si chacun peut répondre, chaque clé par son indice, ainsi que les fournisseurs pour lesquels une clé peut être ajoutée. L'ajout d'une clé prend un corps JSON avec deux champs obligatoires et un champ facultatif :
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }La clé ne transite qu'une seule fois. nexus-auth la chiffre et informe le routeur, et la réponse ne comporte que l'indice. La réponse est 201 avec l'identifiant de la nouvelle clé et sa ligne : « Ajoutée. La clé Google Gemini ••••7f2q est dans le pool d'IA de l'organisation, et l'AI Provider Router peut désormais router vers elle. » Une étiquette comporte au maximum 100 caractères, et une clé est une chaîne unique sans espaces d'au maximum 4 096 caractères. Tout autre champ dans le corps, ou un champ nommant une organisation ou une personne, est refusé.
Le retrait prend un corps vide. Le routeur cesse immédiatement de router vers la clé, et nexus-auth la conserve, répertoriée comme retirée, afin que son historique demeure. Rien dans le pool n'est jamais supprimé.
| Refus | HTTP | Situation |
|---|---|---|
VALIDATION_FAILED |
400 | Un corps qui n'est pas {provider, api_key, label?}, un fournisseur inconnu, ou l'abonnement personnel d'un individu proposé comme clé d'organisation |
AUTHORITY_EXCEEDED |
403 | L'appelant n'est ni propriétaire ni administrateur de l'organisation |
RECORD_NOT_FOUND |
404 | Aucune clé portant cet identifiant ne se trouve dans le pool de l'organisation |
TRANSITION_NOT_PERMITTED |
409 | La clé est déjà retirée |
TENANT_NOT_A_PARAMETER |
403 | Le corps ou la requête a nommé une organisation |
États des clés
Chaque clé du pool se trouve dans l'un des six états suivants. Seule une clé en service répond à une discussion.
| État | Ce que cela signifie |
|---|---|
in_use |
La clé répond, jusqu'à sa date d'expiration si elle en a une. |
resting |
Le routeur l'a mise au repos après des échecs, jusqu'à une heure définie. Les requêtes vont vers la clé suivante entre-temps. |
exhausted |
Elle a épuisé sa limite auprès du fournisseur. |
invalid |
Le fournisseur ne l'accepte plus. |
expired |
Elle a expiré à sa date d'échéance. |
withdrawn |
Un administrateur l'a retirée. Elle reste répertoriée à titre d'historique. |
Une clé qui échoue reste au repos pendant 60 secondes. Après 5 échecs consécutifs, le routeur la désactive, transfère sa part aux autres clés et enregistre l'avis PROVIDER_KEY_SWITCHED_OFF. Personne n'essuie de refus tant qu'une autre clé peut répondre.
Lorsqu'un fournisseur n'a aucune clé en service, le pool indique pourquoi (« Aucune clé en service : 1 retirée, 1 expirée »). Lorsqu'aucun fournisseur du pool n'a de clé en service, une discussion est refusée avec NO_PROVIDER_FOR_ROLE (422) et la solution est indiquée : un propriétaire ou un administrateur ajoute une clé d'organisation. Il s'agit d'un état de configuration, qui reste affiché à l'écran jusqu'à ce que quelqu'un y remédie.
Rôles, politiques et préférences
Le routeur raisonne en rôles. Chaque requête concerne l'un des cinq suivants : default, fast, reasoning, code ou long_context. Chaque modèle appartient également à un niveau, frontier, standard ou fast, et un niveau supérieur est privilégié lorsque le rôle le permet. L'organisation décide quel fournisseur assure chaque rôle (ses attributions de rôles) et l'ordre de repli lorsqu'un fournisseur échoue (son échelle de politique de routage). Les administrateurs définissent les deux dans le standard IA. nexus-auth les sert également sur /auth/org/<organisation-id>/settings/ai-provider/role-assignments et /auth/org/<organisation-id>/settings/ai-provider/routing-policy pour une clé d'administrateur détenant ai_provider:manage.
Les appelants peuvent indiquer ce qu'ils souhaiteraient. Une ligne de compétence peut comporter un fournisseur préféré et un modèle préféré, ainsi qu'un profil de capacités. Le routeur traite chacun différemment :
- Un fournisseur préféré n'est respecté que lorsque l'organisation a activé ce fournisseur et possède une clé pour celui-ci. Sinon, le routeur procède à une substitution.
- Un modèle préféré est respecté lorsqu'il figure dans le catalogue de ce fournisseur et correspond au profil.
- Un profil de capacités est un filtre qui ne sélectionne jamais. Il peut exiger une fenêtre de contexte minimale, l'utilisation d'outils, la vision, des plongements lexicaux (embeddings), un contexte long ou une résidence des données. Tout ce qui n'y répond pas est inéligible.
Le routeur choisit dans un ordre fixe. Il respecte le souhait quand il le peut, puis essaie un autre modèle du même fournisseur, puis l'attribution de rôle et tout autre fournisseur disposant d'une clé dont le catalogue correspond. Si un profil a été fourni et qu'aucun catalogue n'y correspond, la requête est refusée avec MODEL_CAPABILITY_UNAVAILABLE (422). Si rien n'est attribué et que rien ne correspond, le résultat est NO_PROVIDER_FOR_ROLE (422). Il n'y a pas de modèle par défaut de dernier recours. Un rôle que vous n'avez pas configuré échoue explicitement, le routeur indiquant dans ses propres termes ce qu'il faut définir.
La résidence des données est la seule contrainte qui ne peut être contournée par substitution. Un profil avec eu_only est servi par un fournisseur de l'UE ou refusé. Harrow définit ce verrou pour l'ensemble de l'organisation, et le standard affiche le second fournisseur hébergé, qui se trouve dans une région américaine, comme désactivé.
Une compétence peut également épingler un modèle exact lorsqu'elle a besoin de ce modèle pour fonctionner. Même dans ce cas, le routeur utilise la propre clé de l'organisation pour celui-ci, et sans clé, rien ne répond. Un appelant ne peut jamais forcer Nexus à utiliser un fournisseur que l'organisation n'a pas configuré.
Une fois le fournisseur choisi, le basculement sur incident est une question distincte. Une erreur 429, 5xx ou une défaillance réseau fait descendre la requête le long de l'échelle vers le fournisseur suivant. Une erreur 400, 401, 403 ou 404 arrête le processus immédiatement, car les identifiants et les formats de requête ne se transfèrent pas d'un fournisseur à l'autre et une nouvelle tentative consommerait du quota pour aboutir au même échec.
Pour voir ce que le routeur choisirait avant que quiconque ne pose une question, lisez GET /api/ai/routing-policy/effective sur la passerelle avec le propre jeton d'une personne. Il renvoie le modèle pour l'organisation connectée, ou le refus formulé par le routeur lorsqu'il n'y en a aucun, et il n'envoie aucune requête à un modèle.
Surveiller le routeur
Le bandeau de chiffres au bas de chaque page affiche le modèle en service (« Modèle : local »). Sur Enterprise, Le standard IA, en direct trace le trafic du routeur en temps réel : les requêtes provenant de l'assistant, des tâches et des applications circulant à travers les rôles vers les fournisseurs et les clés, une clé dans sa période de repos de 60 secondes tracée en gris, une clé désactivée tracée en rouge, et un repli vers le fournisseur hébergé lorsque le modèle local est occupé. À côté du flux, il représente graphiquement la charge par fournisseur, les requêtes par seconde et le temps d'attente. Tomás le garde ouvert pendant la première semaine suivant toute modification de la politique de routage, car une mauvaise attribution de rôle y apparaît en quelques minutes sous la forme d'un trafic allant là où personne n'avait prévu qu'il aille.
Sur Community, la page Modèles d'IA comporte un bouton Tester chaque modèle qui vérifie chaque modèle configuré et indique s'il répond. C'est le moyen le plus rapide de prouver qu'une nouvelle clé fonctionne avant que quiconque ne s'y fie.
Plongements (embeddings)
La recherche et le graphe de connaissances transforment le texte en vecteurs. Par défaut, l'installation effectue cette opération à l'aide d'un modèle de plongement lexical (embedding) qui s'exécute à l'intérieur du cluster sur le processeur, de sorte qu'aucun texte ne quitte le site pour être vectorisé et qu'une organisation n'a besoin d'aucune clé pour cela. L'utilisation d'un fournisseur hébergé pour les plongements lexicaux est un choix que fait une organisation ; cela passe alors par le même pool et les mêmes règles.
Seuls trois services peuvent demander au routeur des plongements lexicaux ou un reclassement : nexus-graphrag, nexus-skills-engine et nexus-workflows. GraphRAG vectorise au nom de l'organisation à qui appartient le contenu, avec les paramètres de cette organisation, et ne détient aucune clé de fournisseur qui lui soit propre. Lorsqu'une organisation change son modèle de plongement lexical, nexus-workflows exécute la tâche de re-vectorisation pour les magasins de données de cette organisation.
Les identifiants individuels restent personnels
Certains identifiants appartiennent à une seule personne. Un abonnement Claude Max, connecté via le propre compte de cette personne, est le cas courant. Un tel identifiant n'est jamais une clé d'organisation : le pool le refuse avec VALIDATION_FAILED, il n'est jamais répertorié dans le tableau des clés de l'organisation, et aucun écran d'une autre personne ne l'affiche.
Les clés de modèle ne vont non plus jamais ailleurs. La page Clés de données externes, qui détient les clés pour les sources de données extérieures, refuse tout ce qui ressemble à une clé de modèle d'IA avec AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Si le lecteur de fichiers trouve des clés de modèle à l'intérieur d'un document ou d'une configuration où elles n'ont pas leur place, il enregistre CREDENTIALS_IN_WRONG_PLACE et un administrateur les retire et les remplace.
Scripts, REST et MCP
Nexus possède trois hôtes publics. Chez Harrow, il s'agit de console.harrow.example pour la console, api.harrow.example pour la passerelle et auth.harrow.example pour la connexion. Les scripts et les outils utilisent le deuxième et le troisième.
Clés pour scripts
Un script se connecte à l'aide d'une clé créée dans Paramètres, Clés pour scripts. Chaque clé possède un nom, une portée (par exemple, « Démarrer le comptage de cour par drone uniquement »), la personne qui l'a créée et une date de fin ; une organisation peut verrouiller la durée de vie maximale qu'une clé peut avoir. Le secret est affiché une seule fois lors de la création de la clé. Copiez-le dans le magasin de secrets du script, car Nexus ne conserve que ses quatre derniers caractères. Une clé est retirée, jamais supprimée : elle s'arrête immédiatement et reste répertoriée avec chaque appel qu'elle a effectué. La rotation attribue à la clé un nouveau secret et l'affiche une seule fois.
Chaque clé possède sa propre page indiquant les appels par jour, les appels par service et un journal d'activité mentionnant l'heure, l'adresse, le service et le résultat. Un appel en dehors de la portée de la clé est refusé et apparaît dans le journal.
nexus-auth sert les mêmes clés à une personne connectée sur https://auth.harrow.example/api-keys : créer et répertorier, puis lire, modifier, révoquer ou effectuer la rotation d'une clé par son identifiant.
REST via la passerelle
Envoyez des appels REST à https://api.harrow.example avec Authorization: Bearer <token-or-key>. Chaque clé doit appartenir à une organisation. Une clé qui n'en a aucune est refusée avec TOKEN_ORG_MISSING (403) par chaque service qui vérifie les clés via nexus-auth.
Un appelant qui sollicite trop souvent reçoit la réponse 429 avec RATE_LIMITED, un en-tête Retry-After, ainsi que la limite et la fenêtre dans le corps. Attendez le nombre de secondes qu'il indique. Sur Enterprise, les administrateurs définissent des limites par clé, par application et par unité dans Paramètres, Limites de débit (voir le chapitre 2.16, Sécurité et réseau).
MCP pour les outils d'IA
Les outils d'IA qui utilisent le Model Context Protocol se connectent à https://api.harrow.example/mcp. Ils se connectent via le serveur OAuth 2.1 (OAuth est le standard ouvert d'autorisation déléguée) sur https://auth.harrow.example, qui prend en charge l'enregistrement du client par l'outil lui-même, de sorte qu'un outil tel que Claude Code ou Cursor s'enregistre lui-même et ouvre le navigateur de la personne pour qu'elle se connecte. La connexion agit alors pour cette seule personne, avec les droits de cette personne et rien de plus. Une personne connectée peut récupérer une configuration prête à l'emploi pour un outil en ligne de commande depuis https://auth.harrow.example/api/v1/mcp/cli-config.
Les appels d'outils qui nécessitent un modèle passent par le routeur comme tout le reste, sous l'organisation de la personne.




