ALBERT | AI KI-Handler einrichten

Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des Plugins ALBERT | AI. Aktualisieren Sie das hier beschriebene Plugin, um die Dokumentation verwenden zu können.

Was sind KI-Handler?

KI-Handler erweitern den KI-Verarbeitungsprozess in ALBERT | AI. Sie ermöglichen es, Daten vor und nach der Verarbeitung durch das KI-Sprachmodell zu modifizieren.
KI-Handler werden in KI-Voreinstellungen eingebunden und können verschiedene Aufgaben übernehmen:

Datenfilterung: Sensible Informationen (PII - Personally Identifiable Information) können vor dem Senden an das KI-Modell gefiltert und nach der Antwort wiederhergestellt werden.
Protokollierung: KI-Aufrufe können für Debugging oder Compliance-Zwecke protokolliert werden.
Historienverwaltung: Die Chat-Historie kann bei Bedarf komprimiert werden, um das Kontextfenster optimal zu nutzen.

Funktionsweise von KI-Handlern

KI-Handler können an drei Stellen in den KI-Verarbeitungsprozess eingreifen:

Hook	Beschreibung	Typische Verwendung
`before`	Wird vor dem KI-Aufruf ausgeführt. Ermöglicht die Modifikation von Eingabedaten, Historie und Parametern.	Filtern sensibler Daten, Anreichern von Kontextinformationen
`callAi`	Wird unmittelbar vor dem Senden an das Sprachmodell ausgeführt. Ermöglicht die Inspektion des rohen Request-Bodys.	Debugging, Protokollierung des exakten Requests
`after`	Wird nach dem KI-Aufruf ausgeführt. Ermöglicht die Modifikation des Ergebnisses.	Wiederherstellen gefilterter Daten, Protokollierung der Antwort

Ausgelieferte KI-Handler

ALBERT | AI wird mit folgenden vordefinierten KI-Handlern ausgeliefert. Diese KI-Handler können Sie direkt in Ihren KI-Voreinstellungen verwenden. Wenn Handler-Einstellungen konfiguriert werden können, können Sie diese bei Bedarf in der KI-Handler-Konfiguration anpassen.

Anzeigename	Beschreibung	Link
Debug: Print AI input and output to console	Protokolliert alle Ein- und Ausgaben der KI-Verarbeitung in der Server-Konsole. Nützlich für Debugging-Zwecke.	Debug
Simple String Array Filter	Filtert Text, etwa personenbezogene Daten, durch exakte Textübereinstimmung oder anhand eines regulären Ausdrucks.	String Array Filter
PII: Filter personal information with AI	Filtert sensible personenbezogene Daten (Namen, Adressen, Geburtsdaten) mithilfe einer KI-Voreinstellung. Die KI erkennt dynamisch, welche Daten gefiltert werden sollen.	PII: Filter personal information with AI
PII: Filter personal information with CSV	Filtert sensible Daten anhand einer CSV-Datei mit vordefinierten Filtermustern. Unterstützt auch reguläre Ausdrücke.	PII: Filter personal information with CSV
Compact history on demand	Komprimiert die Chat-Historie automatisch, wenn das Kontextfenster einen konfigurierbaren Schwellenwert überschreitet.	History Compaction
Log AI calls (protocol)	Protokolliert alle KI-Aufrufe als JSON-Dateien im Workspace-Verzeichnis. Nützlich für Compliance und Nachvollziehbarkeit.	Log AI calls (protocol)
Usage protocol	Erfasst und sendet Nutzungsstatistiken per HTTP POST an einen externen Endpunkt.	Usage Protocol

KI-Handler-Einstellungen

KI-Handler-Einstellungen öffnen

Nach dem Installieren des Plugins können Sie die KI-Handler-Einstellungen in der Administration des Plugins in der Kopfleiste unter > Administration > Konfiguration > KI-Handler vornehmen.

KI-Handler-Einstellungen anpassen

Öffnen Sie die gewünschte KI-Handler-Einstellung, indem Sie > Administration > Konfiguration > KI-Handler öffnen, die Voreinstellung in der Auswahlliste wählen und Bearbeiten klicken.
Ändern Sie bei Bedarf die vorhandenen Einstellungen.
Speichern Sie die geänderte Konfiguration.
Ergebnis: Sie haben die KI-Handler-Einstellung geändert.

Allgemeine KI-Handler-Einstellungen

Im Konfigurationsfenster können Sie folgende Einstellungen vornehmen:

Allgemeine KI-Handler-Einstellungen

Einstellung	Beschreibung
Konfiguration	Der technische Name der Handler-Konfiguration. Dieser Name wird verwendet, um den Handler in KI-Voreinstellungen zu referenzieren.
Anzeigename	Der für Benutzer sichtbare Name des Handlers.
Beschreibung	Eine optionale Beschreibung, die den Zweck des Handlers erläutert.
Aktiv	Aktiviert oder deaktiviert den Handler. Nur aktive Handler können in KI-Voreinstellungen verwendet werden.
KI-Handler	Wählen Sie den Handler-Typ aus der Liste der verfügbaren Handler aus. Je nach gewähltem Handler werden unterschiedliche oder auch keine weiteren Konfigurationsoptionen angezeigt, abhängig davon, ob und wie der Handler konfiguriert werden kann.
Benutzergruppe	Wählen Sie die Benutzergruppe aus, die Zugriff auf diese Handler-Konfiguration haben soll.

KI-Handler in KI-Voreinstellungen verwenden

Um einen KI-Handler zu verwenden, richten Sie die Nutzung des Handlers in einer oder mehreren KI-Voreinstellungen ein:

Öffnen Sie ☰ > Administration > Konfiguration > KI-Voreinstellungen.
Wählen Sie die gewünschte KI-Voreinstellung aus und klicken Sie Bearbeiten.
Scrollen Sie zum Bereich KI-Handler.
Klicken Sie auf KI-Handler hinzufügen.
Wählen Sie den gewünschten KI-Handler in der Liste aus.
Speichern Sie die KI-Voreinstellung.

Hinweis: Die Reihenfolge der Handler ist wichtig. Wenn Sie mehrere KI-Handler in einer KI-Voreinstellung verwenden, werden die Handler in der angegebenen Reihenfolge ausgeführt.

Eigene KI-Handler erstellen

Sie können eigene KI-Handler entwickeln, um spezifische Anforderungen zu erfüllen. Ein KI-Handler besteht aus einer JavaScript-Datei mit einer definierten Struktur.

Die Erstellung und Verwendung eines neuen KI-Handlers besteht aus folgenden Schritten:

Erstellen Sie die JavaScript-Datei im Verzeichnis:
```
/agorum/roi/customers/<configuration project>/js/ai-handlers/
```
Für die Grundstruktur der JavaScript-Datei siehe Grundstruktur eines KI-Handlers.

Beispiel:
```
/agorum/roi/customers/agorum.doc.test/js/ai-handlers/my-test-handler.js
```
Registrieren Sie den Handler in der MetaDB unter:
```
MAIN_MODULE_MANAGEMENT/customers/agorum.ai/handlers/[ configuration project ]/<handler name>
```
Beispiel für den Pfad des neuen MetaDB-Eintrags:
```
MAIN_MODULE_MANAGEMENT/customers/agorum.ai/handlers/[ agorum.doc.test ]/agorum.doc.test.my-test-handler
```
Name: Name des KI-Handlers, am besten bestehend aus Konfigurationsprojekt und Name der JavaScript-Datei, Beispiel: agorum.doc.test.my-test-handler

Datentyp: Zeichenkette (String)

Wert: Pfad zur JavaScript-Datei, Beispiel:
```
 /agorum/roi/customers/agorum.doc.test/js/ai-handlers/my-test-handler.js
```
Erstellen Sie eine neue KI-Handler-Konfiguration über den Konfigurationsdialog, siehe Eine neue KI-Handler-Einstellung hinzufügen, und wählen Sie dort den von Ihnen neu entwicklten und registrierten Handler aus. Setzen Sie die Konfiguration aktiv, um den Handler in KI-Voreinstellungen verwenden zu können.

Grundstruktur eines KI-Handlers

/**
 * handler name: my-test-handler
 *
 * handler description
 */
let i18n = require('common/i18n');

({
  /**
   * Information about this handler
   */
  info: () => {
    return {
      description: 'Doc Test Handler', //name used in UI
      runAlways: false, // true = runs even when the handler is disabled
      encryptedFields: [], // fields with values that need to be encrypted
      configAon: {
        type: 'agorum.composite.form.basic',
        elements: [
          // configuration elements are defined here
        ],
      },
    };
  },

  /**
   * hook before the AI call 
   * @param {Object} data - input data (input, history, parameters)
   * @param {Object} parameters - handler parameter
   * @param {Object} context - context for data exchange with after hook
   */
  before: (data, parameters, context) => {
    // modify data before the AI call 
    // IMPORTANT: no return value, data is modified directly
  },

  /**
   * hook for the raw request body (optional)
   * @param {Object} requestBody - request to the language model
   * @param {Object} parameters - handler parameters
   * @param {Object} context - context
   */
  callAi: (requestBody, parameters, context) => {
    // inspire or modify requests
  },

  /**
   * hook after the ai call
   * @param {Object} result - the ai result
   * @param {Object} parameters - handler parameters
   * @param {Object} context - context from before hook
   */
  after: (result, parameters, context) => {
    // modify the result after the ai call
    // IMPORTANT: no return value, data is modified directly
  },
});

Eine neue KI-Handler-Einstellung hinzufügen

Öffnen Sie > Administration > Konfiguration > KI-Handler.

Ergebnis: Das Fenster KI-Handler einrichten öffnet sich.
Klicken Sie auf die Schaltfläche (Plus), um eine neue Konfiguration zu erstellen.

Ergebnis: Das Fenster Anlage eines neuen KI-Handlers öffnet sich.
Geben Sie den Namen ein, den Sie dem neuen KI-Handler geben wollen, und optional ein Konfigurationsprojekt und klicken Sie Speichern.

Ergebnis: Die neue Konfiguration wird in der Liste der Konfigurationen angezeigt.
Klicken Sie auf Bearbeiten.

Ergebnis: Das Fenster KI-Handler einrichten öffnet sich.
Geben Sie den Anzeigenamen an und wählen Sie die von Ihnen neu eingerichteten KI-Handler in der Auswahlliste aus.
Geben Sie optional weitere Einstellungen an. Wenn Sie den KI-Handler in KI-Voreinstellungen verwenden wollen, müssen Sie den Handler aktiv setzen.
Speichern Sie die KI-Handler-Konfiguration.

Globale KI-Handler

Zusätzlich zu den preset-spezifischen KI-Handlern unterstützt ALBERT | AI auch globale KI-Handler. Globale Handler werden bei allen KI-Aufrufen ausgeführt, unabhängig davon, welche KI-Voreinstellung verwendet wird. Sie eignen sich besonders für systemweite Anforderungen wie:

Zentrale Protokollierung: Alle KI-Aufrufe an einem Ort protokollieren
Compliance-Anforderungen: Systemweite Datenfilterung oder Audit-Trails
Monitoring: Überwachung aller KI-Interaktionen

Registrierung globaler KI-Handler

Globale Handler werden in der MetaDB unter folgendem Pfad registriert:

MAIN_MODULE_MANAGEMENT/customers/agorum.ai/global-handlers/[ <projektname> ]

Dabei ist <projektname> der Name Ihres Konfigurationsprojekts.

Namensschema und Sortierung

Die Sortierung und Aktivierung der globalen Handler erfolgt über ein spezielles Namensschema:

[#]NNNN handler.name

Element	Beschreibung	Beispiel
`#`	Optional. Wenn vorhanden, ist der Handler deaktiviert.	`#0010 my-handler` (deaktiviert)
`NNNN`	Vierstellige Zahl, die die Sortierreihenfolge bestimmt. Handler mit niedrigeren Zahlen werden zuerst ausgeführt.	`0010`, `0020`, `0100`
`handler.name`	Der Name des Handlers (frei wählbar).	`audit-logger`, `pii-filter`

Beispiele für Handler-Namen

Name	Status	Reihenfolge
`0010 audit-logger`	Aktiv	Wird als erstes ausgeführt
`0020 pii-filter`	Aktiv	Wird als zweites ausgeführt
`#0030 debug-handler`	Deaktiviert	Wird nicht ausgeführt
`0100 compliance-check`	Aktiv	Wird als drittes ausgeführt

Ausführungsreihenfolge

Die Ausführungsreihenfolge der Handler ist wie folgt:

Preset-spezifische Handler werden zuerst ausgeführt (in der Reihenfolge, wie sie in der KI-Voreinstellung konfiguriert sind)
Globale Handler werden danach ausgeführt (sortiert nach der Nummer im Namen)

Hinweis: Globale Handler verwenden dieselbe Struktur wie preset-spezifische Handler. Sie können daher bestehende Handler-Implementierungen auch als globale Handler registrieren.

Globalen KI-Handler einrichten

Gehen Sie wie folgt vor, um einen globalen KI-Handler einzurichten:

Erstellen Sie die JavaScript-Datei für den Handler im Verzeichnis:
/agorum/roi/customers/<konfigurationsprojekt>/js/ai-handlers/
Öffnen Sie links in der Seitenleiste Administration und dann MetaDB.
Navigieren Sie zum Pfad:
MAIN_MODULE_MANAGEMENT/customers/agorum.ai/global-handlers/[projektname]
Erstellen Sie die Ordner bei Bedarf.
Erstellen Sie einen neuen MetaDB-Eintrag (Property Entry) mit:
• Name: Nach dem Namensschema, z. B. 0010 audit-logger
• Datentyp: Zeichenkette (String)
• Wert: Pfad zur JavaScript-Datei, z. B.
/agorum/roi/customers/mein-projekt/js/ai-handlers/audit-logger.js