Gérer les canaux dans la passerelle IA

« Canal (Channel) » désigne la configuration d'un point d'accès fournisseur dans la passerelle IA — elle conserve l'adresse d'un fournisseur, sa vraie clé API, les modèles disponibles ainsi que la tarification et les quotas. C'est à partir de ces canaux que la passerelle route les requêtes envoyées par les applications vers le fournisseur correspondant. Cet article explique comment ajouter, configurer, tester et gérer des canaux.

Prérequis

• ServBay est installé et en cours d'exécution, et vous êtes connecté à un compte ServBay (la connexion est requise avant d'ajouter un canal).
• Vous disposez de la vraie clé API du fournisseur cible (les fournisseurs locaux comme Ollama / LM Studio peuvent ne pas en avoir besoin).
• Si vous ne connaissez pas l'architecture globale de la passerelle IA, il est conseillé de lire d'abord Présentation de la passerelle IA.

Ajouter un canal

Rendez-vous dans Passerelle IA → Canaux (Channels), puis cliquez sur Ajouter (Add) pour ouvrir l'assistant. L'assistant comporte trois étapes.

Étape 1 : Choisir un fournisseur

Les fournisseurs sont regroupés par catégorie ; cliquez sur une carte pour le sélectionner :

• Principaux (Mainstream) : OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• Chine (China) : DeepSeek, Qwen (Tongyi Qianwen), Zhipu GLM, Kimi, Doubao · Volcano, ERNIE Bot (Wenxin Yiyan), Hunyuan, MiniMax, 01.AI, StepFun.
• Local (Local) : Ollama, LM Studio.
• Personnalisé (Custom) : OpenAI Compatible, Custom.

Après avoir choisi un fournisseur, la passerelle renseigne automatiquement son URL de base par défaut.

Bascule entre deux régions

Les fournisseurs chinois tels que Qwen, Zhipu GLM, Kimi, Doubao · Volcano, Hunyuan, MiniMax et StepFun proposent à la fois des points de terminaison nationaux et mondiaux. Lorsque vous sélectionnez ce type de fournisseur, un sélecteur de « Région » (🇨🇳 National / 🌐 Mondial) apparaît dans l'assistant ; après bascule, l'URL de base est automatiquement mise à jour vers l'adresse de la région correspondante.

Étape 2 : Remplir la configuration

• Nom du canal (obligatoire) — sert à identifier le canal dans la liste, personnalisable.
• URL de base (obligatoire) — adresse de l'API du fournisseur. Pour la plupart des fournisseurs, elle est déjà remplie automatiquement ; Azure OpenAI et Personnalisé nécessitent une saisie manuelle.
• Clé API (facultatif) — vraie clé du fournisseur. Si elle est laissée vide, vous pourrez seulement tester si le point de terminaison est joignable, sans pouvoir valider la clé ; les fournisseurs locaux (Ollama / LM Studio) n'ont généralement pas besoin de clé.
• Modèles — deux méthodes, au choix :
  • Découverte automatique : après avoir cliqué sur Découvrir, la passerelle appelle l'API de liste des modèles du fournisseur pour récupérer les modèles disponibles, que vous sélectionnez via des puces (chip) en multi-sélection.
  • Saisie manuelle : saisissez directement le nom du modèle. Pour les canaux Azure, indiquez le nom de déploiement (Deployment name) plutôt que le nom du modèle.
• Priorité / Poids — lorsque plusieurs canaux peuvent desservir un même modèle, la passerelle s'en sert pour décider du routage et de la répartition de charge.

Attention Azure OpenAI

Pour les canaux Azure, le champ « Modèles » doit contenir le nom de déploiement (Deployment name) que vous avez créé dans le portail Azure, et non le nom du modèle sous-jacent. L'URL de base doit également correspondre au point de terminaison de votre ressource Azure.

Étape 3 : Confirmer et soumettre

Vérifiez le récapitulatif de configuration puis soumettez. Une fois soumis avec succès, le nouveau canal apparaît dans la liste des canaux, avec son état de santé en temps réel.

Détection des capacités et stratégie de routage

Après l'ajout d'un canal, la passerelle effectue une détection des capacités (capability probing) sur ce canal — c'est le mécanisme de routage intelligent le plus central de la passerelle IA. Le résultat de la détection détermine si des outils comme Claude Code peuvent l'utiliser directement, s'il faut créer un mappage de modèles, et comment choisir le modèle cible.

Les deux indicateurs clés de la détection

La passerelle détecte deux faits essentiels pour chaque canal (tous deux à trois états : true / false / non déterminé) :

Élément détecté	Signification	true	false	Non déterminé
Accepte les noms de modèles Claude (accepts_claude_names)	Le canal reconnaît-il nativement les noms de modèles claude-opus-* / claude-sonnet-* / claude-haiku-*	Connexion directe, aucun mappage nécessaire	Non reconnu, un mappage est obligatoire pour traduire les noms claude-* vers les vrais noms de modèles en amont	La détection n'a pas tourné ou a échoué, impossible de conclure
Distingue par niveau (tier_aware)	En amont, le fournisseur renvoie-t-il lui-même des modèles différents selon les niveaux opus / sonnet / haiku	L'amont gère déjà les niveaux, il suffit de lui déléguer	Pas de distinction de niveaux (même modèle renvoyé pour tous les niveaux), un mappage de la passerelle est nécessaire	Impossible à détecter ou jamais détecté

Pourquoi détecter plutôt que deviner

Le comportement varie considérablement d'un fournisseur à l'autre. OpenAI ne reconnaît pas nativement les noms de modèles claude-* ; certains fournisseurs relais les reconnaissent par transfert ; et les fournisseurs de forfaits de codage (comme l'abonnement Claude Pro/Max) peuvent ne reconnaître que des noms de modèles spécifiques liés à l'abonnement. La passerelle ne devine pas en fonction du type de canal : elle détecte réellement, puis décide de la stratégie de routage.

Décision de routage : cinq états

Lorsque vous effectuez une « prise en charge en un clic » de Claude Code dans Passerelle IA → Gestion des accès → page Client, la passerelle agrège les résultats de détection de tous les canaux candidats et produit une décision de routage :

État des canaux candidats	Décision	Signification
Aucun canal candidat disponible (aucun canal / tous en mauvaise santé / aucun canal dans le périmètre de la clé virtuelle)	Aucun canal candidat	Vous devez d'abord ajouter ou réparer des canaux
La valeur de détection d'au moins un canal candidat est non déterminée	Non détecté	Il faut d'abord lancer une détection ; impossible de créer un mappage sans vérification préalable
Tous les canaux candidats reconnaissent les noms de modèles claude	Connexion directe	Aucun mappage, la requête est transférée telle quelle
Tous les canaux candidats ne reconnaissent pas les noms de modèles claude	Mappage obligatoire	La passerelle crée un mappage à trois niveaux, traduisant claude-* vers les vrais noms de modèles en amont
Parmi les candidats, certains reconnaissent et d'autres non	Mixte	Décision humaine nécessaire (ceux qui reconnaissent passent directement, ceux qui ne reconnaissent pas passent par mappage)

Mappage de modèles : traduire claude-* vers les vrais modèles en amont

Lorsque la décision est « Mappage obligatoire », la passerelle crée trois règles de mappage de modèles pour Claude Code, couvrant chacune des trois niveaux :

Nom de modèle émis par Claude Code	Règle de mappage (caractère générique)	Mappé vers
claude-opus-*	Correspond à toutes les requêtes de niveau opus	Le modèle phare parmi les canaux candidats
claude-sonnet-*	Correspond à toutes les requêtes de niveau sonnet	Le modèle phare ou le modèle standard parmi les canaux candidats
claude-haiku-*	Correspond à toutes les requêtes de niveau haiku	Le modèle léger parmi les canaux candidats

Règles de sélection du modèle cible (repli par priorité) :

1. Préréglage de famille : si un mot-clé de famille connu apparaît parmi les modèles candidats (par ex. glm), prenez directement le modèle phare de cette famille (par ex. glm-5.2) comme cible pour les niveaux opus/sonnet, et le modèle léger de cette famille (par ex. glm-4.7-flash) comme cible pour le niveau haiku.
2. Correspondance par mots-clés : en l'absence de préréglage de famille, opus/sonnet prennent le premier modèle de la liste des candidats ; haiku prend le premier modèle candidat correspondant à un mot-clé léger (flash / mini / lite / air / small / turbo / haiku).
3. Repli : si rien ne correspond encore, les trois niveaux prennent le premier modèle de la liste des candidats.

Le niveau haiku est celui où une erreur coûte le plus cher

Le niveau haiku de Claude Code est le plus sollicité (chaque appel léger d'une conversation l'utilise). Si vous mettez par erreur un modèle phare dans le niveau haiku, la facture peut être multipliée par plusieurs. La table de correspondance par mots-clés de la passerelle couvre 7 suffixes légers (flash / mini / lite / air / small / turbo / haiku), ce qui évite d'affecter un modèle lourd au niveau haiku.

Mécanisme d'écriture des mappages

Après confirmation de la prise en charge, la passerelle écrit les enregistrements de mappage via l'API /admin/model-mappings. Chaque enregistrement de mappage contient :

• Protocole source (source_protocol) : anthropic (les requêtes émises par Claude Code sont au format Anthropic)
• Correspondance du modèle source (source_model_pattern) : caractère générique, par ex. claude-opus-*
• Protocole cible (target_protocol) : openai (conversion unifiée au format OpenAI avant envoi en amont)
• Modèle cible (target_model) : nom de modèle concret sélectionné par la détection

L'écriture est idempotente — une prise en charge répétée ne produit pas de mappages en double ; avant écriture, la liste des mappages existants est récupérée pour comparaison.

Règles de routage à l'exécution : failover et dégradation

Outre les mappages statiques écrits lors de la prise en charge, la passerelle prend en charge des règles de routage à l'exécution (routing rules), qui décident dynamiquement au passage des requêtes dans la passerelle :

Champ de règle	Rôle
Condition de déclenchement (condition_type)	Quand déclencher la dégradation, par ex. épuisement du quota d'un canal (quota_exhausted)
Seuil de coût (cost_threshold_usd)	Facultatif : déclenche lorsque le coût cumulé de ce canal dépasse le seuil
Action (action_type)	Ce qu'il faut faire après déclenchement, par ex. basculer vers un canal de secours désigné (switch_to)
Canal cible (target_channel_id)	Canal de secours vers lequel basculer
Modèle cible (target_model)	Facultatif : changer aussi de modèle lors du basculement vers le canal de secours

En combinant plusieurs règles de routage, vous pouvez par exemple : basculer automatiquement du canal A vers le point de terminaison à l'usage du canal B lorsque le quota d'abonnement de A est épuisé ; dégrader vers un modèle moins cher lorsque le coût sur 24 heures d'un canal dépasse la limite.

Équilibrage de charge et priorité

Lorsque plusieurs canaux sains peuvent desservir le même modèle, la passerelle choisit selon la stratégie suivante :

• Mode priorité (par défaut) : ne prend que le canal de priorité la plus élevée ; parmi les canaux de même priorité, la passerelle répartit selon un poids interne.
• Mode tourniquet (round_robin) : répartit les requêtes à tour de rôle entre tous les canaux candidats sains.

La priorité se règle dans la configuration du canal (plus le nombre est grand, plus la priorité est élevée), et allowed_channels de la clé virtuelle limite l'étendue des canaux sélectionnables.

Test de connectivité

Dans la liste des canaux, vous pouvez exécuter un test de connectivité sur un canal. Le test comporte deux dimensions :

• Accessibilité du point de terminaison (reachable) — vérifie si l'URL de base est joignable (réseau et adresse corrects).
• Validité de la clé (authenticated) — appelle réellement l'interface du fournisseur pour vérifier si la clé API est valide. La vérification n'a lieu que si une clé API a été renseignée.

Les résultats du test affichent : la latence aller-retour (en millisecondes), un badge d'état et les messages d'erreur.

TIP

Dans l'assistant d'ajout, si le point de terminaison n'est pas joignable, vous ne pouvez pas passer à l'étape suivante ; s'il est joignable mais que la clé est invalide, un avertissement s'affiche seulement et vous pouvez continuer (par exemple si vous prévoyez d'ajouter la clé plus tard).

Configuration avancée

Lors de l'ajout ou de la modification d'un canal, vous pouvez déplier la configuration avancée pour le calcul des coûts et le contrôle des quotas :

• Multiplicateur de tarif (Rate Multiplier) — multiplie le prix officiel du fournisseur par un coefficient, pour refléter votre coût réel ou votre prix de revente ; valeur par défaut 1.0.
• Structure de facturation — indique le mode de facturation du canal, par ex. paiement à l'usage (pay as you go), abonnement (subscription), forfait (package).
• Solde — la source du solde peut être une valeur fixe, une facture OSS ou une maintenance manuelle ; en choisissant la facture OSS, vous pouvez aussi préciser le type de facture. Le solde et la date de mise à jour sont affichés en lecture seule dans les détails du canal.
• Date d'expiration de l'abonnement — les canaux de type abonnement / forfait peuvent enregistrer une date d'expiration.
• Limite de quota — possibilité de fixer un plafond en nombre de tokens, en nombre de requêtes ou en montant, avec choix de la période (quotidienne / hebdomadaire / mensuelle / personnalisée). Une fois le quota épuisé, le canal est automatiquement exclu de la sélection de routage, ce qui en fait une soupape de sécurité contre les dépassements imprévus.

Modifier et supprimer un canal

• Modifier — ouvrez un canal dans la liste pour modifier son nom, son URL de base, sa clé API, ses modèles et sa configuration avancée.
• Supprimer — après suppression d'un canal, les clés virtuelles qui en dépendent ne peuvent plus y router ; agissez avec prudence.

État de santé

La liste des canaux et la page Vue d'ensemble affichent en temps réel l'état de santé de chaque canal (normal / dégradé / indisponible), pour vous aider à repérer rapidement les configurations fournisseur défaillantes.

FAQ

• Q : Lors de l'ajout d'un canal, il est demandé de se connecter ?
  • R : La passerelle IA est une fonctionnalité à valeur ajoutée de ServBay ; avant d'ajouter un canal / une clé, vous devez vous connecter à un compte ServBay. Suivez les indications de l'interface pour vous connecter.
• Q : Le message indique que le nombre maximal de canaux est atteint ?
  • R : Le nombre de canaux que vous pouvez créer dépend de l'offre de votre compte. Si la limite est atteinte, supprimez les canaux inutilisés ou passez à une offre supérieure.
• Q : La découverte automatique des modèles ne récupère pas la liste ?
  • R : Vérifiez d'abord que l'URL de base est correcte et que la clé API est valide (utilisez la « Validité de la clé » du test de connectivité). Certains fournisseurs exigent une clé valide pour renvoyer la liste des modèles ; vous pouvez aussi saisir manuellement les noms de modèles.
• Q : Faut-il une clé pour connecter Ollama / LM Studio en local ?
  • R : Généralement non. Assurez-vous que le service local correspondant est démarré et écoute sur le port par défaut (Ollama 11434, LM Studio 1234).

Résumé

Les canaux constituent la base du routage des requêtes de la passerelle IA. Grâce à l'assistant en trois étapes, vous pouvez connecter rapidement près de 20 fournisseurs ; avec la bascule entre deux régions, la découverte automatique des modèles et le test de connectivité à deux dimensions, vous vous assurez que la configuration est correcte ; puis, grâce à la configuration avancée (tarification, quotas, etc.), vous gérez finement les coûts. Une fois les canaux configurés, vous pouvez créer des clés virtuelles à utiliser par les applications et les outils.