Dieser Leitfaden erklärt, wie benutzerdefinierte KI-Tools im Discourse AI-Plugin erstellt, konfiguriert und integriert werden, wodurch Administratoren die Fähigkeiten des Bots mit benutzerdefinierten JavaScript-Funktionen erweitern können.
Erforderliches Benutzerniveau: Administrator
Tools sind programmierbare Funktionalitäten, die vom KI-Bot verwendet werden können, um spezifische Aufgaben auszuführen oder Informationen abzurufen, die über reine textbasierte Antworten hinausgehen. Diese Tools sind Skripte oder Integrationen, die es dem Bot ermöglichen, mit externen APIs zu interagieren, Daten zu manipulieren oder zusätzliche Funktionen auszuführen, um seine Fähigkeiten zu erweitern.
Zusammenfassung
Diese Dokumentation behandelt:
- Erstellung eines neuen benutzerdefinierten KI-Tools
- Konfiguration von Tool-Parametern und Skripten
- Verfügbare APIs für Tool-Skripte
- Integration benutzerdefinierter Tools in KI-Personas
- Testen und Fehlerbehebung benutzerdefinierter Tools
Erstellung eines neuen benutzerdefinierten KI-Tools
Um ein neues KI-Tool zu erstellen:
- Navigieren Sie zu Admin-Panel > Plugins > Discourse AI > Tools
- Klicken Sie auf „Neues Tool“ (Sie können vorhandene Voreinstellungen verwenden, um sich über Optionen zu informieren)
- Füllen Sie die folgenden Felder aus:
- Name: Der Name des Tools, wie er der LLM präsentiert wird
- Beschreibung: Die Beschreibung des Tools, wie sie der LLM präsentiert wird
- Zusammenfassung: Zusammenfassung dessen, was das Tool zur Unterstützung der Benutzer tut (wird in Details angezeigt)
- Parameter: Definieren Sie die Eingaben, die Ihr Tool benötigt, wie sie der LLM präsentiert werden
- Skript: Der JavaScript-Code, der Ihr Tool antreibt
- Klicken Sie auf „Speichern“
Konfiguration von Tool-Skripten
Verfügbare APIs
Ihre Tool-Skripte haben Zugriff auf die folgenden APIs:
-
HTTP-Anfragen:
http.get(url, options) http.post(url, options) http.put(url, options) http.patch(url, options) http.delete(url, options)Verwenden Sie diese, um mit externen Diensten zu interagieren. Sie können
optionsverwenden, um HTTP-Header und Body anzugeben: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" })Alle HTTP-Methoden geben
{ status: number, body: string }zurück. -
LLM (Sprachmodell)-Integration:
llm.truncate(text, length)Kürzt Text auf eine angegebene Token-Länge basierend auf dem konfigurierten LLM-Tokenizer.
llm.generate(prompt, options)Generiert Text mit der konfigurierten LLM. Der Prompt kann ein einfacher String oder ein strukturiertes Objekt wie
{ messages: [{ type: "system", content: "..." }, { type: "user", content: "..." }] }sein. Optionen umfassenjson: true, um die JSON-Ausgabe anzufordern und automatisch zu parsen, sowietemperature,top_p,max_tokensundstop_sequences. -
Benutzerdefinierte Upload-Integration (RAG)
index.search(query, { filenames: ["file.pdf"], limit: 10 })Durchsucht indizierte RAG-Dokumentfragmente, die diesem Tool zugeordnet sind. Gibt
Array<{ fragment: string, metadata: string | null }>sortiert nach Relevanz zurück. Das Standardlimit beträgt 10, maximal 200.index.getFile(filename)Ruft den vollständigen Inhalt einer hochgeladenen RAG-Datei anhand ihres exakten Dateinamens ab. Gibt den vollständigen Text oder
nullzurück, falls nicht gefunden. -
Upload-Unterstützung
upload.create(filename, base_64_content)Erstellt einen neuen Upload. Gibt
{ id: number, url: string, short_url: string }zurück.upload.getUrl(shortUrl)Gibt bei einer Kurz-URL (z. B.
upload://12345) die vollständige CDN-freundliche URL zurück.upload.getBase64(uploadIdOrShortUrl, maxPixels)Ruft den Base64-kodierten Inhalt eines vorhandenen Uploads ab. Akzeptiert eine Upload-ID (Zahl) oder eine Kurz-URL (String). Optionaler Parameter
maxPixelsfür automatische Bildgrößenanpassung (Standard: 10.000.000). -
Steuerung der Ausführungskette
chain.setCustomRaw(raw)Setzt den endgültigen Rohinhalt des Beitrags des Bots und stoppt die Tool-Ausführungskette. Nützlich für Tools, die direkt den vollständigen Inhalt generieren (z. B. Bilderzeugungstools).
-
Geheimnisverwaltung
secrets.get(alias)Gibt den Credential-Wert zurück, der an den angegebenen Alias gebunden ist. Aliase werden in der Secret-Contracts-Konfiguration des Tools definiert und im Admin-Panel an AI Secrets gebunden. Löst einen Fehler aus, wenn der Alias nicht deklariert, nicht gebunden ist oder das Credential fehlt.
const apiKey = secrets.get("my_api_key"); -
Discourse-Integration
Tools können direkt mit Discourse-Daten interagieren:
discourse.baseUrl // Die Basis-URL der Website discourse.search(params) // Eine Discourse-Suche durchführen discourse.getPost(post_id) // Beitragsdetails abrufen (enthält Rohinhalt) discourse.getTopic(topic_id) // Topickdetails abrufen (Tags, Kategorie usw.) discourse.getUser(id_or_username) // Benutzerdetails abrufen discourse.createTopic(params) // Einen neuen Topic erstellen discourse.createPost(params) // Einen neuen Beitrag/eine neue Antwort erstellen discourse.editPost(post_id, raw, options) // Den Inhalt eines Beitrags bearbeiten discourse.editTopic(topic_id, updates, options) // Topiceigenschaften bearbeiten (Tags, Kategorie, Sichtbarkeit) discourse.createChatMessage(params) // Eine Chat-Nachricht senden discourse.createStagedUser(params) // Einen vorgemerkten Benutzer erstellen discourse.getAgent(name) // Einen anderen KI-Agenten abrufen (mit respondTo-Methode) discourse.updateAgent(name, updates) // Die Konfiguration eines KI-Agenten aktualisieren discourse.getCustomField(type, id, key) // Benutzerdefiniertes Feld bei Beitrag/Topic/Benutzer lesen discourse.setCustomField(type, id, key, value) // Benutzerdefiniertes Feld bei Beitrag/Topic/Benutzer setzen -
Kontextobjekt
Das
context-Objekt liefert Informationen darüber, wo das Tool ausgeführt wird:- Bot-Konversationskontext:
context.post_id,context.topic_id,context.private_message,context.participants,context.username,context.user_id - Chat-Kontext:
context.message_id,context.channel_id,context.username - Automatisierungskontext:
context.post_id,context.topic_id,context.username,context.user_id,context.feature_name,context.feature_context - Allgemeine Eigenschaften:
context.site_url,context.site_title,context.site_description
- Bot-Konversationskontext:
Erforderliche Funktionen
Ihr Skript muss Folgendes implementieren:
invoke(params): Die Hauptfunktion, die ausgeführt wird, wenn das Tool aufgerufen wird
Es kann optional Folgendes implementieren:
details(): Gibt einen String (kann einfachen HTML-Code enthalten) zurück, der die Ausführung des Tools beschreibt und in der Chat-Oberfläche angezeigt wirdcustomSystemMessage(): Wird während der Prompt-Zusammenstellung aufgerufen (nicht während der Tool-Ausführung). Gibt einen String zurück, der dem System-Prompt angehängt wird, odernull/undefined, um dies zu überspringen. Hat Zugriff auf die Objektecontext,discourseundindex.
Beispielskript:
function invoke(params) {
let result = http.get("https://api.example.com/data?query=" + params.query);
return JSON.parse(result.body);
}
function details() {
return "Daten von der Beispiel-API abgerufen";
}
Einschränkungen und Sicherheit
- Ausführungs-Timeout: Standard-Timeout von 2000 ms Skriptverarbeitungszeit. Der Timer pausiert während externer HTTP-Anfragen (
http.*) und LLM-Aufrufen (llm.generate), sodass nur die Verarbeitungszeit des Skripts selbst zählt. - Speicher: Maximal 10 MB V8-Heap-Grenze
- HTTP-Anfragen: Maximal 20 Anfragen pro Tool-Ausführung
- Sandboxed-Umgebung: Skripte laufen in einer eingeschränkten V8 JavaScript-Umgebung (über MiniRacer). Kein Zugriff auf Browser-Globale, das Host-Dateisystem oder serverseitige Bibliotheken. Netzwerkanfragen werden über das Discourse-Backend weitergeleitet.
Testen Ihres Tools
Sie sollten jedes Tool, das Sie erstellen, testen, um sicherzustellen, dass die Ergebnisse, die der LLM zur Verfügung gestellt werden, Ihren Erwartungen entsprechen.
Integration von Tools in KI-Personas
Um Ihr benutzerdefiniertes Tool zu einer KI-Persona hinzuzufügen:
- Gehen Sie zu Admin-Panel > Plugins > Discourse AI > Personas
- Bearbeiten Sie eine vorhandene Persona oder erstellen Sie eine neue
- Im Abschnitt „Tools“ sehen Sie Ihre benutzerdefinierten Tools neben den integrierten Tools aufgelistet
- Wählen Sie Ihr benutzerdefiniertes Tool aus, um es der Persona hinzuzufügen
Benutzerdefinierte Tools in Aktion
Sobald Sie der LLM das benutzerdefinierte Tool zur Verfügung stellen, kann es dieses verwenden, um das Gespräch zu verbessern.
Fehlerbehebung
Wenn Ihr Tool nicht wie erwartet funktioniert:
- Verwenden Sie die Testoberfläche, um sicherzustellen, dass es sich bei Ihren Eingaben wie erwartet verhält.
- Stellen Sie sicher, dass Ihre Gruppe in
ai_bot_debugging_allowed_groupsenthalten ist. Mitglieder dieser Gruppe haben vollen Zugriff auf die Bot-Transkripte; Sie können die KI-Protokolle dort einsehen. - Wenn etwas Unerwartetes passiert, besuchen Sie
https://SITENAME/logs, um nach Fehlern zu suchen.
