Documentation

Connexion d'un fournisseur d'IA et enregistrement d'un modèle

Trois niveaux à ne pas confondre

La connexion d'un modèle dans Sapphire I.C.D.S. repose sur trois enregistrements distincts. Le fournisseur décrit le service externe : sa clé stable, son URL de base, l'adaptateur installé et le secret d'accès. Le modèle conserve l'identifiant du modèle chez ce fournisseur et ses limites techniques. Le profil définit le comportement opérationnel : instruction système, budget de contexte, longueur de réponse et paramètres supplémentaires. Cette séparation permet d'utiliser un même modèle dans plusieurs modes, évite de dupliquer la clé d'API et empêche de remplacer les limites réelles du modèle par les réglages d'une tâche particulière.

La configuration s'effectue dans la section administrative AI Settings. L'accès doit y être accordé via Helix. Avant de commencer, obtenez auprès du fournisseur les valeurs à jour de base URL, model ID et des limites du modèle choisi, puis vérifiez que l'adaptateur correspondant est déjà installé dans l'environnement serveur de Sapphire. Une chaîne saisie dans le formulaire n'installe pas une bibliothèque à elle seule.

Étape 1. Créer le fournisseur

Ouvrez la section des fournisseurs et créez un enregistrement. Le champ Vendor key doit contenir un identifiant machine court et stable, par exemple acme_ai. Utilisez des lettres latines minuscules, des chiffres et des traits de soulignement. N'y incluez ni domaine, ni offre, ni région, ni version du modèle : la clé relie les réglages et doit résister aux évolutions ordinaires du produit.

Display name est destiné aux opérateurs et peut être lisible par un humain. Dans Base URL, indiquez l'adresse HTTPS de base documentée de l'API du fournisseur, sans chemin propre à un modèle et sans jeton dans la query string. Ne copiez pas une URL depuis la console du navigateur et n'y ajoutez pas une route finale arbitraire. Si le fournisseur propose plusieurs API compatibles, utilisez la variante pour laquelle l'adaptateur est installé.

Vendor key doit correspondre à la variant du fournisseur installé que détecte le chargeur standard de la plateforme. Dans le runtime actuel, le champ Provider library constitue une metadata fallback compatible et, lorsque vendor key n'est pas vide, ne détermine généralement pas l'adaptateur. Ce n'est ni un chemin de fichier ni un mécanisme d'installation d'une nouvelle bibliothèque. Si la provider variant requise n'est pas installée, confiez la tâche à l'administrateur du déploiement.

Dans Secret name, on conserve normalement le nom de secret adopté pour cet adaptateur, tandis que Secret value reçoit la clé d'API délivrée. Le secret ne doit figurer ni dans le nom, ni dans l'URL, ni dans la description, ni dans une capture d'écran, un ticket ou le JSON du profil. Après l'enregistrement, l'interface indique seulement qu'un secret existe, sans afficher sa valeur d'origine. Lors d'une modification, laissez le champ de valeur vide si la clé ne doit pas changer ; une nouvelle valeur non vide entraîne une rotation du secret. Un ordre pratique consiste à créer d'abord le fournisseur désactivé, enregistrer le secret, vérifier les autres champs, puis activer l'enregistrement.

Étape 2. Enregistrer le modèle

Accédez à la section des modèles et sélectionnez le fournisseur qui vient d'être créé. Model key doit correspondre exactement à l'identifiant accepté par l'API, y compris les traits d'union, les points et le suffixe de version. Il ne s'agit pas d'un alias arbitraire. Un champ Display name distinct permet de donner un nom plus pratique.

Reportez ensuite les trois limites figurant dans la fiche officielle du modèle. Maximum context est la limite totale de la fenêtre de contexte. Maximum input est l'entrée maximale autorisée. Maximum output est la limite de la réponse générée. Toutes les valeurs sont des entiers positifs exprimés en tokens. L'entrée et la sortie ne peuvent chacune dépasser le contexte total. N'utilisez pas une valeur de contexte publicitaire si l'API ou l'offre choisie en autorise moins.

Tokenizer variant détermine la méthode d'estimation des tokens. Indiquez la variante compatible exacte si elle est connue. Si seule une estimation prudente est disponible pour une nouvelle famille, utilisez le nom convenu pour cette variante, et non le nom du modèle choisi au hasard. Le champ est obligatoire : un tokenizer incorrect ne produit pas une simple imprécision cosmétique, mais un mauvais calcul du moment de compactage et de la taille de requête autorisée.

Ordre d'activation sûr

Créez le fournisseur avec l'URL HTTPS correcte et un adaptateur installé.
Enregistrez le secret et vérifiez que la liste indique sa présence.
Créez le modèle avec le model key exact et des limites confirmées.
Créez un profil distinct pour ce modèle ; sans profil, aucune politique opérationnelle n'est définie.
Activez d'abord le modèle et le fournisseur pour un test limité, puis attribuez le profil par défaut.

Pour effectuer la vérification, ouvrez une nouvelle session d'IA, sélectionnez explicitement le profil créé et exécutez une requête courte sans outil, par exemple une demande de réponse sur une seule ligne. Une nouvelle session élimine l'influence d'un ancien choix de profil et de l'historique accumulé. Après la réponse de base, vérifiez le streaming, puis seulement les scénarios avec outils. La disponibilité des outils est gérée par le catalogue et les droits des groupes, et non par l'enregistrement du fournisseur ou du modèle.

Erreurs courantes

Erreur d'autorisation : vérifiez la présence du secret, sa date de validité et son rattachement au bon projet, puis ne le faites tourner que si nécessaire.
Model not found : comparez le model key caractère par caractère avec la documentation de l'API et assurez-vous que le compte est autorisé à utiliser le modèle.
Route incorrecte : vérifiez la base URL, l'adaptateur sélectionné et l'absence de chemin de modèle dans l'adresse de base.
Refus lors de l'enregistrement des limites : les trois valeurs doivent être positives, et input et output ne doivent pas dépasser context.
Le modèle n'apparaît pas à l'usage : le fournisseur, le modèle et le profil doivent être activés ; le profil doit référencer la même paire et être accessible à l'utilisateur actuel.

Ne modifiez pas simultanément le secret, l'URL, le model key et les limites d'un profil en service. Appliquez les changements un par un et consignez le résultat de chaque vérification. Pour changer de génération de modèle, il est plus sûr d'enregistrer un nouveau modèle et un nouveau profil, de les tester séparément, puis de changer le profil par défaut. Cette méthode conserve un chemin de retour clair sans modifier le sens des enregistrements existants.

Recette et maintenance

Après une requête minimale réussie, consignez dans la documentation de travail le vendor key, le model key, l'objectif du profil, la source des limites et la date de vérification. N'inscrivez pas le secret lui-même. Vérifiez séparément le comportement lorsque le fournisseur est temporairement désactivé : l'utilisateur doit recevoir une erreur compréhensible, et non attendre indéfiniment. Si le service possède plusieurs régions ou routes tarifaires, traitez-les comme des configurations délibérées plutôt que de modifier la base URL pendant le diagnostic.

Réexaminez périodiquement les limites en fonction de la documentation à jour du fournisseur. Un changement de nom commercial du modèle n'implique pas toujours un nouvel identifiant d'API, et un nouvel identifiant ne garantit pas la même tokenizer variant. Toute modification de ce type suit le même cycle : enregistrement séparé, profil, session de test, vérification de la réponse, puis seulement bascule des utilisateurs.