Ce guide couvre la création, la gestion et l’utilisation des identifiants IA (secrets partagés) dans les modèles de langage (LLM), les modèles d’embedding et les outils IA personnalisés du plugin Discourse AI.
Niveau utilisateur requis : Administrateur
Résumé
Les identifiants IA offrent une méthode centralisée et sécurisée pour gérer les secrets d’authentification, tels que les clés API, dans votre configuration Discourse AI. Au lieu de coller manuellement des clés API brutes dans chaque modèle LLM, définition d’embedding ou outil personnalisé, vous créez un identifiant une seule fois et vous le référez partout où il est nécessaire.
Lorsque vous faites tourner une clé (par exemple, votre clé API OpenAI), vous la mettez à jour à un seul endroit et chaque modèle LLM, embedding ou outil utilisant cet identifiant prend automatiquement en compte le changement.
Cette documentation couvre :
- La création et la gestion des identifiants
- Le lien entre les identifiants et les modèles LLM et d’embedding
- L’utilisation des identifiants dans les outils IA personnalisés
- La protection contre la suppression et le cycle de vie des identifiants
- L’API pour gérer les identifiants de manière programmatique
Qu’est-ce qu’un identifiant ?
Un identifiant est un secret nommé et réutilisable stocké de manière centralisée dans Discourse AI. Il comporte deux champs principaux :
| Champ | Description |
|---|---|
| Nom | Une étiquette unique et lisible par l’humain (par exemple, « Clé API OpenAI »). Maximum 100 caractères. |
| Valeur | Le secret réel (clé API, jeton, etc.). Maximum 10 000 caractères. |
Un identifiant peut être référencé par trois types d’entités :
- Modèles LLM — en tant que clé API principale
- Définitions d’embedding — en tant que clé API principale
- Outils IA personnalisés — en tant que liaisons de secrets nommés accessibles depuis JavaScript
De plus, certains paramètres de fournisseur LLM de type « secret » (par exemple, access_key_id pour AWS Bedrock) font également référence à des identifiants.
Création et gestion des identifiants
Accéder à la page des identifiants
Accédez à Admin → Plugins → Discourse AI → Identifiants, ou visitez directement /admin/plugins/discourse-ai/ai-secrets.
[espace réservé pour capture d’écran : page de liste des identifiants affichant les colonnes nom, utilisé par et bouton modifier]
Créer un nouvel identifiant
- Sur la page des identifiants, cliquez sur « Nouvel identifiant ».
- Saisissez un Nom pour l’identifiant (par exemple, « Clé API OpenAI »).
- Saisissez la Valeur — la clé API ou le jeton réel. Ce champ est affiché comme un champ de mot de passe.
- Cliquez sur « Enregistrer ».
[espace réservé pour capture d’écran : formulaire d’édition d’identifiant avec les champs nom et valeur]
Vous pouvez également créer des identifiants en ligne lors de la configuration d’un modèle LLM, d’un embedding ou d’un outil. Une boîte de dialogue modale vous permet d’ajouter un nouvel identifiant sans quitter la page actuelle, et l’identifiant apparaît immédiatement dans la liste déroulante de sélection.
Modifier un identifiant
- Sur la page de liste des identifiants, cliquez sur « Modifier » à côté de l’identifiant.
- Mettez à jour le Nom ou la Valeur selon les besoins.
- Cliquez sur « Enregistrer ».
Lors de l’affichage d’un identifiant existant, la valeur secrète est masquée (********) dans la vue de liste. La valeur réelle n’est affichée que sur la page de modification de l’identifiant individuel.
Supprimer un identifiant
Un identifiant ne peut pas être supprimé s’il est actuellement référencé par un modèle LLM, un embedding ou un outil. Si vous tentez de supprimer un identifiant en cours d’utilisation, l’interface affiche un message listant les entités qui le référencent, avec des liens vers leurs pages de modification.
Pour supprimer un identifiant :
- Commencez par supprimer ou réaffecter toutes les références à l’identifiant depuis tous les modèles LLM, embeddings ou outils.
- Retournez sur la page de modification de l’identifiant.
- Cliquez sur « Supprimer » et confirmez l’action.
Liaison des identifiants aux modèles LLM et aux embeddings
Modèles LLM
Lors de la configuration d’un modèle LLM sur la page des paramètres LLM, vous pouvez sélectionner un identifiant existant dans une liste déroulante au lieu de coller directement une clé API. Au moment de l’exécution, le modèle résout le secret à partir de l’identifiant lié.
Pour les secrets spécifiques au fournisseur — tels que access_key_id d’AWS Bedrock — l’ID de l’identifiant est stocké dans les paramètres du fournisseur et résolu de manière transparente lorsque le modèle effectue des requêtes API.
Définitions d’embedding
Les modèles d’embedding fonctionnent de la même manière. Lors de la configuration d’une définition d’embedding, sélectionnez un identifiant dans la liste déroulante. Le modèle d’embedding vérifie qu’un identifiant ou une clé API en ligne est présent, et utilise la valeur de l’identifiant au moment de l’exécution.
Utilisation des identifiants dans les outils IA personnalisés
Les outils IA personnalisés utilisent un modèle de contrat et liaison pour les secrets, ce qui rend la définition de l’outil portable (exportable/importable) tandis que les secrets restent locaux au site.
Étape 1 : Déclarer les contrats de secrets
Lors de la création ou de la modification d’un outil, vous déclarez les secrets requis par l’outil en ajoutant des entrées à ses contrats d’identifiants. Chaque entrée possède un alias — un identifiant simple utilisant des lettres, des chiffres et des underscores.
Sur la page d’édition de l’outil, cliquez sur « Ajouter un identifiant » pour ajouter une nouvelle entrée de contrat et lui donner un nom d’alias, par exemple external_api_key.
[espace réservé pour capture d’écran : éditeur d’outil affichant les champs d’alias d’identifiant et les sélecteurs d’identifiants]
Les noms d’alias doivent correspondre au motif [a-zA-Z0-9_] et être uniques au sein de l’outil.
Étape 2 : Lier les identifiants aux alias
À côté de chaque alias déclaré sur la page de configuration de l’outil, sélectionnez un identifiant existant dans la liste déroulante. Cela crée une liaison entre l’alias et l’identifiant.
La liaison est validée pour s’assurer que :
- L’identifiant sélectionné existe
- L’alias est déclaré dans les contrats de l’outil
Étape 3 : Accéder aux secrets au moment de l’exécution en JavaScript
Dans le JavaScript d’un outil, accédez aux secrets en utilisant l’API secrets.get() :
function invoke(params) {
const apiKey = secrets.get("external_api_key");
const result = http.get("https://api.example.com/data", {
headers: { "Authorization": "Bearer " + apiKey }
});
return JSON.parse(result.body);
}
Remplacez external_api_key par le nom d’alias que vous avez déclaré dans les contrats d’identifiants de l’outil.
Tous les alias déclarés doivent avoir des liaisons d’identifiants avant que l’outil puisse s’exécuter. Si des liaisons manquent, l’exécution est bloquée avec un message d’erreur listant les alias non liés.
Exemple : un outil avec plusieurs identifiants
Supposons que vous créiez un outil qui appelle deux API différentes. Déclarez deux contrats d’identifiants :
| Alias | Description |
|---|---|
weather_api_key |
Clé pour l’API de données météorologiques |
geocode_api_key |
Clé pour l’API de géocodage |
Liez ensuite chaque alias à l’identifiant approprié sur la page de configuration de l’outil.
Dans le script :
function invoke(params) {
const weatherKey = secrets.get("weather_api_key");
const geocodeKey = secrets.get("geocode_api_key");
const location = http.get(
"https://geocode.example.com/search?q=" + encodeURIComponent(params.city),
{ headers: { "X-Api-Key": geocodeKey } }
);
const coords = JSON.parse(location.body);
const forecast = http.get(
"https://weather.example.com/forecast?lat=" + coords.lat + "&lon=" + coords.lon,
{ headers: { "Authorization": "Bearer " + weatherKey } }
);
return JSON.parse(forecast.body);
}
Suivi de l’utilisation des identifiants
Chaque identifiant suit où il est référencé. Sur la page de liste des identifiants, la colonne « Utilisé par » affiche des liens vers chaque modèle LLM, embedding ou outil utilisant actuellement cet identifiant.
Cette visibilité vous aide à :
- Comprendre l’impact avant de faire tourner ou mettre à jour un secret
- Identifier les identifiants inutilisés qui peuvent être supprimés en toute sécurité
- Naviguer rapidement vers les entités qui dépendent d’un identifiant
Référence de l’API
Tous les points de terminaison nécessitent une authentification d’administrateur et se trouvent sous le chemin /admin/plugins/discourse-ai/ai-secrets.
| Méthode | Chemin | Description |
|---|---|---|
GET |
/ai-secrets |
Liste tous les identifiants (valeurs masquées) |
GET |
/ai-secrets/:id |
Affiche un seul identifiant (valeur non masquée) |
POST |
/ai-secrets |
Crée un nouvel identifiant |
PUT |
/ai-secrets/:id |
Met à jour un identifiant |
DELETE |
/ai-secrets/:id |
Supprime un identifiant (renvoie 409 s’il est utilisé) |
Corps de la requête pour la création et la mise à jour :
{
"ai_secret": {
"name": "Clé API OpenAI",
"secret": "sk-..."
}
}
Toutes les opérations de création, de mise à jour et de suppression sont enregistrées dans le journal des actions du personnel. Les valeurs secrètes sont traitées comme sensibles et ne sont jamais écrites dans les journaux.
Migration automatique des clés API en ligne
Les installations existantes qui utilisaient précédemment des clés API en ligne sont automatiquement migrées. La migration :
- Lit tous les modèles LLM et définitions d’embedding non initialisés qui ont une clé API en ligne.
- Déduplique par clé API et fournisseur — si deux modèles partagent la même clé et le même fournisseur, ils reçoivent un seul identifiant.
- Crée des enregistrements d’identifiants avec des noms générés automatiquement tels que « Clé API OpenAI », « Clé API AWS Bedrock », etc.
- Met à jour les enregistrements de modèles LLM et de définitions d’embedding pour référencer les nouveaux identifiants.
- Gère les valeurs
access_key_idd’AWS Bedrock dans les paramètres du fournisseur — extraction de la clé brute, création d’un identifiant et remplacement de la valeur en ligne par l’ID de l’identifiant.
Cette migration s’exécute automatiquement lors de la mise à niveau et est irréversible. Aucune action manuelle n’est requise.
Problèmes courants et solutions
« Cet identifiant est actuellement utilisé et ne peut pas être supprimé »
Cela signifie qu’un ou plusieurs modèles LLM, embeddings ou outils référencent l’identifiant. Vérifiez la colonne « Utilisé par » sur la page de liste des identifiants pour identifier et réaffecter ou supprimer ces références avant de supprimer.
« Liaisons d’identifiants requises manquantes » lors de l’exécution d’un outil
Tous les alias d’identifiants déclarés dans les contrats d’un outil doivent avoir des liaisons. Ouvrez la page de modification de l’outil, vérifiez que chaque alias a un identifiant sélectionné dans la liste déroulante, puis enregistrez.
La valeur de l’identifiant s’affiche sous la forme ********
C’est un comportement attendu. Les valeurs secrètes sont masquées dans les vues de liste pour des raisons de sécurité. Pour afficher ou modifier la valeur réelle, cliquez sur « Modifier » sur l’identifiant spécifique.
Clé tournée mais les fonctionnalités IA échouent toujours
Après avoir mis à jour la valeur d’un identifiant, vérifiez que le test LLM (sur la page des paramètres LLM) réussit. Si la nouvelle clé a des permissions différentes ou appartient à un compte différent, vérifiez les exigences de configuration du fournisseur.
FAQ
Puis-je toujours utiliser des clés API en ligne au lieu d’identifiants ?
Les clés API en ligne héritées continuent de fonctionner pour les configurations existantes. Cependant, les identifiants sont l’approche recommandée car ils simplifient la rotation des clés et réduisent la duplication.
Les valeurs d’identifiants sont-elles chiffrées au repos ?
Les valeurs d’identifiants sont stockées dans la base de données. Elles suivent le même modèle de sécurité que les autres données sensibles de Discourse. Assurez-vous que votre base de données est correctement sécurisée et que les sauvegardes sont gérées de manière appropriée.
Que se passe-t-il lorsque j’importe un outil qui utilise des identifiants ?
Les importations d’outils incluent les alias de contrat d’identifiants mais pas les valeurs secrètes réelles. Après avoir importé un outil, vous devrez créer ou sélectionner des identifiants pour chaque alias déclaré sur la page de configuration de l’outil.
Puis-je partager un seul identifiant entre plusieurs modèles LLM ?
Oui. Plusieurs modèles LLM et embeddings peuvent référencer le même identifiant. Cela est particulièrement utile lorsque vous utilisez la même clé API de fournisseur dans plusieurs configurations de modèle.