Ce guide explique comment créer, configurer et intégrer des outils d’IA personnalisés dans le plugin Discourse AI, permettant aux administrateurs d’étendre les capacités du bot avec des fonctions JavaScript définies par l’utilisateur.
Niveau d’utilisateur requis : Administrateur
Les outils sont des fonctionnalités programmables que le bot d’IA peut utiliser pour effectuer des tâches spécifiques ou récupérer des informations au-delà de simples réponses textuelles. Ces outils sont des scripts ou des intégrations qui permettent au bot d’interagir avec des API externes, de manipuler des données ou d’exécuter des fonctions supplémentaires pour étendre ses capacités.
Résumé
Cette documentation couvre :
- Création d’un nouvel outil d’IA personnalisé
- Configuration des paramètres et des scripts de l’outil
- API disponibles pour les scripts d’outils
- Intégration des outils personnalisés avec les personas d’IA
- Test et dépannage des outils personnalisés
Création d’un nouvel outil d’IA personnalisé
Pour créer un nouvel outil d’IA :
- Naviguez vers Panneau d’administration > Plugins > Discourse AI > Outils
- Cliquez sur « Nouvel Outil » (vous pouvez utiliser des préréglages existants pour découvrir les options)
- Remplissez les champs suivants :
- Nom : Le nom de l’outil tel que présenté au LLM
- Description : La description de l’outil telle que présentée au LLM
- Résumé : Résumé de ce que fait l’outil pour aider les utilisateurs (affiché dans les détails)
- Paramètres : Définissez les entrées dont votre outil a besoin, telles que présentées au LLM
- Script : Le code JavaScript qui alimente votre outil
- Cliquez sur « Enregistrer »
Configuration des scripts d’outils
API disponibles
Vos scripts d’outils ont accès aux API suivantes :
-
Requêtes HTTP :
http.get(url, options) http.post(url, options) http.put(url, options) http.patch(url, options) http.delete(url, options)Utilisez-les pour interagir avec des services externes. Vous pouvez utiliser
optionspour spécifier les en-têtes HTTP et le corps :http.get(url, { headers: { "Authorization": "Bearer key" } }) http.post(url, { headers: { "Content-Type": "application/json" }, body: { key: "value" } }) http.patch(url, { headers: { "Authorization": "Bearer key" }, body: "some body" }) http.delete(url, { headers: { "Authorization": "Bearer key" } }) http.put(url, { headers: { "Authorization": "Bearer key" }, body: "some body" })Toutes les méthodes HTTP retournent
{ status: number, body: string }. -
Intégration LLM (Modèle de Langage) :
llm.truncate(text, length)Tronque le texte à une longueur de jeton spécifiée en fonction du tokenizer du LLM configuré.
llm.generate(prompt, options)Génère du texte en utilisant le LLM configuré. L’invite peut être une chaîne simple ou un objet structuré tel que
{ messages: [{ type: "system", content: "..." }, { type: "user", content: "..." }] }. Les options incluentjson: truepour demander et analyser automatiquement la sortie JSON, ainsi quetemperature,top_p,max_tokensetstop_sequences. -
Intégration de téléchargement personnalisé (RAG)
index.search(query, { filenames: ["file.pdf"], limit: 10 })Recherche les fragments de documents RAG indexés attachés à cet outil. Renvoie
Array<{ fragment: string, metadata: string | null }>ordonné par pertinence. La limite par défaut est de 10, maximum 200.index.getFile(filename)Récupère le contenu complet d’un fichier RAG téléchargé par son nom de fichier exact. Renvoie le texte complet ou
nulls’il n’est pas trouvé. -
Prise en charge des téléchargements
upload.create(filename, base_64_content)Crée un nouveau téléchargement. Renvoie
{ id: number, url: string, short_url: string }.upload.getUrl(shortUrl)Étant donné une URL courte (par exemple,
upload://12345), renvoie l’URL complète conviviale CDN.upload.getBase64(uploadIdOrShortUrl, maxPixels)Récupère le contenu encodé en base64 d’un téléchargement existant. Accepte un identifiant de téléchargement (nombre) ou une URL courte (chaîne). Paramètre
maxPixelsoptionnel pour le redimensionnement automatique des images (défaut : 10 000 000). -
Contrôle de la chaîne d’exécution
chain.setCustomRaw(raw)Définit le contenu brut final de la publication du bot et arrête la chaîne d’exécution de l’outil. Utile pour les outils qui génèrent directement la réponse complète (par exemple, les outils de génération d’images).
-
Gestion des secrets
secrets.get(alias)Renvoie la valeur de l’identifiant lié à l’alias donné. Les alias sont définis dans la configuration des contrats secrets de l’outil et liés aux Secrets IA dans le panneau d’administration. Lève une erreur si l’alias n’est pas déclaré, non lié ou si l’identifiant est manquant.
const apiKey = secrets.get("my_api_key"); -
Intégration Discourse
Les outils peuvent interagir directement avec les données Discourse :
discourse.baseUrl // L'URL de base du site discourse.search(params) // Effectuer une recherche Discourse discourse.getPost(post_id) // Obtenir les détails de la publication (inclut le contenu brut) discourse.getTopic(topic_id) // Obtenir les détails du sujet (tags, catégorie, etc.) discourse.getUser(id_or_username) // Obtenir les détails de l'utilisateur discourse.createTopic(params) // Créer un nouveau sujet discourse.createPost(params) // Créer une nouvelle publication/réponse discourse.editPost(post_id, raw, options) // Modifier le contenu d'une publication discourse.editTopic(topic_id, updates, options) // Modifier les propriétés du sujet (tags, catégorie, visibilité) discourse.createChatMessage(params) // Envoyer un message de chat discourse.createStagedUser(params) // Créer un utilisateur "staged" discourse.getAgent(name) // Obtenir un autre agent IA (avec la méthode respondTo) discourse.updateAgent(name, updates) // Mettre à jour la configuration d'un agent IA discourse.getCustomField(type, id, key) // Lire le champ personnalisé sur la publication/le sujet/l'utilisateur discourse.setCustomField(type, id, key, value) // Définir le champ personnalisé sur la publication/le sujet/l'utilisateur -
Objet Contexte
L’objet
contextfournit des informations sur l’endroit où l’outil est exécuté :- Contexte de conversation du bot :
context.post_id,context.topic_id,context.private_message,context.participants,context.username,context.user_id - Contexte de discussion :
context.message_id,context.channel_id,context.username - Contexte d’automatisation :
context.post_id,context.topic_id,context.username,context.user_id,context.feature_name,context.feature_context - Propriétés communes :
context.site_url,context.site_title,context.site_description
- Contexte de conversation du bot :
Fonctions requises
Votre script doit implémenter :
invoke(params): La fonction principale qui s’exécute lorsque l’outil est appelé
Il peut implémenter en option :
details(): Renvoie une chaîne (peut inclure du HTML de base) décrivant l’exécution de l’outil, affichée dans l’interface de discussioncustomSystemMessage(): Appelée lors de l’assemblage de l’invite (pas pendant l’invocation de l’outil). Renvoie une chaîne ajoutée à l’invite système, ounull/undefinedpour ignorer. A accès aux objetscontext,discourseetindex.
Exemple de script :
function invoke(params) {
let result = http.get("https://api.example.com/data?query=" + params.query);
return JSON.parse(result.body);
}
function details() {
return "Données récupérées depuis l'API Example";
}
Limitations et sécurité
- Délai d’exécution : Délai par défaut de 2000 ms de temps de traitement du script. La minuterie s’arrête pendant les requêtes HTTP externes (
http.*) et les appels LLM (llm.generate), donc seul le temps de traitement du script lui-même est comptabilisé. - Mémoire : Limite maximale de tas V8 de 10 Mo
- Requêtes HTTP : Maximum de 20 requêtes par exécution d’outil
- Environnement Sandboxed : Les scripts s’exécutent dans un environnement JavaScript V8 restreint (via MiniRacer). Pas d’accès aux globaux du navigateur, au système de fichiers de l’hôte ou aux bibliothèques côté serveur. Les requêtes réseau sont proxifiées via le backend Discourse.
Test de votre outil
Vous devez tester chaque outil que vous construisez pour vous assurer que les résultats fournis au LLM correspondent à vos attentes.
Intégration des outils avec les personas d’IA
Pour ajouter votre outil personnalisé à un Persona d’IA :
- Accédez à Panneau d’administration > Plugins > Discourse AI > Personas
- Modifiez un persona existant ou créez-en un nouveau
- Dans la section « Outils », vous verrez vos outils personnalisés répertoriés à côté des outils intégrés
- Sélectionnez votre outil personnalisé pour l’ajouter au persona
Outils personnalisés en action
Une fois que vous avez fourni l’outil personnalisé à votre LLM, celui-ci peut l’utiliser pour améliorer la conversation.
Dépannage
Si votre outil ne fonctionne pas comme prévu :
- Utilisez l’interface de test pour vous assurer qu’il se comporte comme prévu pour vos entrées.
- Assurez-vous que votre groupe est dans
ai_bot_debugging_allowed_groups. Les membres de ce groupe ont un accès complet aux transcriptions du bot ; vous pouvez y consulter les journaux de l’IA. - Si quelque chose d’inattendu se produit, visitez
https://NOM_DU_SITE/logspour vérifier les erreurs.
