Konfiguration

Einführung

Mindbreeze InSpire AI Chat bietet die Möglichkeit einer Conversational Schnittstelle auf Basis einer generativen AI. Durch die Insight Services für Retrieval Augmented Generation (RAG) ist ein Large Language Model (LLM) mittels Mindbreeze InSpire in der Lage aus den Inputs des Users Antworten auf Basis der Treffer in Mindbreeze zu generieren.

Vorbereitung

Zwei Voraussetzung müssen dafür erfüllt werden:

• Freischaltung der entsprechenden Features in Mindbreeze InSpire damit die Konfiguration durchgeführt werden kann.
• Betrieb eines LLM.

Für das Freischalten der Features kontaktieren Sie bitte den Mindbreeze Support (support@mindbreeze.com) für Details zur Aktivierung der Features via Mindbreeze InSpire Feature Flags.

Für den Betrieb eines LLMs kontaktieren Sie bitte Mindbreeze Sales (sales@mindbreeze.com) um ein LLM zu nutzen. On-Premise Kunden haben die Möglichkeit GPU Appliances zu verwenden bzw. Mindbreeze SaaS Kunden können ein Remote LLM verwenden. Für die Nutzung bestehender LLM-Infrastrukturen wird aktuell das Huggingface TGI-Interface unterstützt und als Autorisierungsmöglichkeit kann OAuth genutzt werden.

Aktivieren des Features

Kontaktieren Sie bitte den Mindbreeze Support (support@mindbreeze.com), und übermitteln Sie, falls vorhanden, Ihre bestehende Feature Flag Configuration „/etc/mindbreeze/enabled_features.json“, um eine aktualisierte Version zu erhalten. Aktualisieren Sie dann das neue enabled_features.json, welches Sie vom Mindbreeze Support erhalten haben.

Starten Sie danach den InSpire Container neu. Öffnen Sie dazu im Management Center den Menüpunkt „Setup“ und klicken Sie dann auf den Untermenüpunkt „InSpire“. Im Bereich „Container Management“ können Sie InSpire neu starten.

Ist das InSpire neu gestartet und das Feature korrekt aktiviert, sollten Sie im Management Center im Menüpunkt “Insight Services” den neuen Untermenüpunkt “RAG” sehen.

Konfiguration

Insight Services für Retrieval Augmented Generation

Öffnen Sie im Mindbreeze Management Center den Menüpunkt „Configuration“. Erstellen Sie im „Indices“ Tab einen neuen Service, indem Sie auf „Add Service“ klicken. Geben Sie dem Service unter „Display Name“ einen Namen und wählen Sie bei der Einstellung „Service“ die Option „Insight Services for RAG“.

Stellen Sie sicher, dass im Abschnitt „Base Configuration“ der konfigurierte "Bind port" noch nicht belegt ist. Falls notwendig, aktivieren Sie die Einstellung „Include Prompt in app.telemetry“. Mit dieser Einstellung werden die von den Usern eingegebenen Fragen und die Prompts, die an das LLM geschickt werden in den app.telemetry Einträgen inkludiert. Dies ist aufgrund von Sicherheitsgründen standardmäßig deaktiviert.

„Log HTTP Requests in verbose Log Mode“ ist standardmäßig deaktiviert. Wenn diese Einstellung und gleichzeitig die Einstellung „Full Logging“ aktiviert sind, werden in den Logs Details zu den einzelnen Anfragen protokolliert. Die Einstellung „Full Logging“ befindet sich im Abschnitt „Support Mode“, das mit aktivierten „Advanced Settings“ sichtbar ist.

Die Einstellung „Generate with empty Results“ ist standardmäßig aktiviert. Wenn Sie diese Option deaktivieren wird im Chat nur eine Antwort generiert, wenn im Index Resultate gefunden wurden, ansonsten wird eine Fehlermeldung angezeigt, dies kann nützlich sein um zu verhindern, dass Antworten ohne Bezug zu den Indizierten Daten gegeben werden.

Mit der Einstellung „Path to Store Base“ kann optional der Pfad des Service konfiguriert werden.

Wenn die Einstellung "Path to Store Base" auf der Grundlage des Pfads definiert ist, enthält das Snapshot möglicherweise nicht die Service-Konfiguration. Wenn kein "Path to Store Base" definiert ist, werden nur die Service-Konfigurationen (Pipelines und LLMs) in den Snapshot gepackt, nicht aber die Servicedaten (Datasets). Wenn alle Daten in einen Snapshot gepackt werden sollen, sollte der "Path to Store Base" auf ein Verzeichnis gesetzt werden, dessen Inhalt vollständig in einem Snapshot enthalten ist. Weitere Informationen zur Migration mit einem Snapshot finden Sie unter Handbuch - Sichern & Wiederherstellen - Erstellen eines Snapshots.

Achtung: Ist die Einstellung "Path to Store Base" nicht gesetzt, kann dies dazu führen, dass die Servicedaten für die Pipeline und den LLM nicht mehr angezeigt werden nachdem ein Snapshot angewendet wurde. Die Lösung für dieses Problem finden Sie im Kapitel Servicedaten für die Pipeline und das LLM sind verschwunden nachdem ein Snapshot angewandt wurde.

Advanced Settings

Für die folgenden Einstellungen aktivieren Sie die „Advanced Settings“.

Self-Signed SSL-Zertifikate

Aktivieren Sie im Abschnitt „Security Configuration“ die Einstellung „Disable SSL Certificate Validation“. Standardmäßig ist diese Einstellung deaktiviert.

Abschließend speichern Sie die Änderungen mit einem Klick auf "Save".

Impersonation Configuration

Im Bereich "Impersonation Configuration" können Sie unter anderem das Endpoint Mapping Pattern eingeben. Die Endpoints werden im „Network“-Tab in der Configuration des Management Centers definiert.

Mit dieser Einstellung holt sich der Retriever das Client Zertifikat für den Client Service durch einen Abgleich mit dem dort definierten Pattern. Für das Pattern kann man den folgenden Platzhalter verwenden:

client_service_id: ID des Client Service

Das Endpoint Mapping greift nur dann, wenn kein „Trusted Peer Certificate“ ausgewählt ist und der im Impersonation Identifier Setting konfigurierte HTTP Header im Generate-Request mitgeschickt wird.

Speichern Sie schlussendlich die Änderungen, indem Sie auf „Save“ klicken.

Konfiguration des OpenAI Proxy

Im Bereich "Proxy Configuration" kann die Proxy-API für LLMs aktiviert werden. Durch die Konfiguration der Proxy-API können LLMs, die in Insight Services für RAG konfiguriert wurden, direkt über Mindbreeze InSpire verwendet werden.

Achtung: Die OpenAI-API muss vom jeweiligen LLM unterstützt werden, um eine funktionierende Proxy-API zu konfigurieren. Die folgende Tabelle liefert einen Überblick zu den verfügbaren Protokollen:

Folgende Endpunkte werden aktuell unterstützt:

• /v1/audio/transcriptions
• /v1/chat/completions

Diese sind dann folgendermaßen am Client Service erreichbar:

• /api/openai.v1.chat.completions.create/v1/chat/completions
• /api/openai.v1.audio.transcriptions.create/v1/audio/transcriptions

Mit der Einstellung "Allowed URLs Pattern for Images" können die URLs für Bilder in den Requests der Completions-API eingeschränkt werden. Standardmäßig werden nur Base64 enkodierte Data-URLs genutzt werden.

InSpire AI Chat

Wechseln Sie zum „Client Services“ Tab. Aktivieren Sie die erweiterten Einstellungen, indem Sie das Häkchen bei „Advanced Settings“ setzen.

Falls vorhanden, benutzen Sie einen bestehenden Client Service. Ist kein Client Service vorhanden, fügen Sie einen Client Service hinzu, indem Sie auf „Add Client Service“ klicken. Geben Sie dem Client Service mit der Einstellung „Display Name“ einen Namen.

Gehen Sie zum Abschnitt „Chat UI Settings“ und wählen Sie bei der Einstellung „Chat Service“ den Service den Sie im „Indices“ Tab erstellt haben.

Nach der Konfiguration, können Sie, ähnlich zum Insight App Designer, den AI Chat mit dem Pfad apps/chat erreichen. Der vollständige Pfad sieht zum Beispiel folgendermaßen aus: https://example.com/apps/chat/.

Personalisiertes Theme (Optionale Konfiguration)

Ist ein personalisiertes Theme im AI Chat gewünscht, kann dies folgendermaßen eingestellt werden:

Im Management Center im Menüpunkt „File Manager“ erstellen sie den Ordner /data/apps/chat-theme, wenn dieser noch nicht existiert, und legen Sie die folgenden Dateien darin ab:

Aktivieren Sie im “Client Services” Tab die “Advanced Settings” und legen Sie nun in Ihrem Client Service im Bereich “Web Applications Contexts Settings” einen „Additional Context“ an. Aktivieren Sie dort "Override Existing Path" und tragen Sie als “URL Path” /apps/chat/theme ein und /data/apps/chat-theme als "File Path".

Speichern Sie die Konfiguration, indem Sie auf „Save“ klicken.

Sprachen

Der Mindbreeze Inspire AI Chat ist in folgenden Sprachen standardmäßig verfügbar:

• Deutsch
• Englisch

Um die Sprache des AI Chats zu ändern, klicken Sie unten links auf die aktuell ausgewählte Sprache. Klicken Sie dann auf die Sprache, die Sie aus der Liste an verfügbaren Sprachen verwenden möchten. Der Chat wird sofort in der Sprache ihrer Wahl angezeigt.

Benutzerdefinierte Sprachen

Benutzerdefinierte Sprachen können auch zur Liste der verfügbaren Sprachen hinzugefügt werden. Um eine benutzerdefinierte Sprache zu konfigurieren, reicht ein einfacher „Hook“. Dieser Hook muss in den zusätzlichen Ressourcen im URL-Pfad apps/chat/theme/ konfiguriert werden. Die notwendigen Übersetzungen können dann zu apps/chat/theme/i18n/ hinzugefügt werden.

Hinweis: Bitte beachten Sie, dass Deutsch und Englisch reserviert sind und daher nicht geändert oder angepasst werden können.

Die nachfolgende Schritt-für-Schritt-Anleitung erklärt den vollständigen Konfigurationsprozess:

1. Im Management Center, gehen Sie zu „Configuration“ und öffnen Sie den Client Service, wo die benutzerdefinierte Sprache benötigt wird. Aktivieren Sie „Advanced Settings“ und gehen Sie zum Abschnitt „Web Applications Contexts Settings“. Fügen Sie dann einen neuen „Additional Context“ mit den folgenden Einstellungen hinzu:

Hinweis: Es wird empfohlen, zuerst den „Additional Context“ zu definieren, damit die Dateien, die in den folgenden Schritten definiert werden, sofort wirksam werden.

1. Nachdem der Additional Context vollständig konfiguriert ist, gehen Sie zum „File Manager“ im Management Center und dann zu „Local Filesystem“. Gehen Sie zum Ordner /data/apps und erstellen Sie einen neuen Ordner mit dem Namen „chat-theme“. Klicken Sie dann auf den neu erstellten Ordner und fügen Sie einen neuen Ordner mit dem Namen „i18n“ hinzu:

1. Erstellen Sie neben dem „i18n“ Ordner eine Datei mit dem Namen „custom.js“. In dieser Datei können Sie den vorher erwähnten Hook definieren.

1. Um den Hook zu erstellen, ist „getEffectiveLanguages“ die bevorzugte Sprache für den Chat und “”es”:”Espanol”” und “”fr”:”Francais”” sind zum Beispiel die benutzerdefinierten Sprachen. Speichern Sie die Änderungen.
   
   Achtung: Bitte beachten Sie, dass gültige benutzerdefinierte Ländercodes („custom locales“ z. B. es, fr, cs oder nl) verwendet werden müssen, da sonst die benutzerdefinierte Sprache nicht im AI Chat angezeigt wird. Vermeiden Sie außerdem die Ländercodes „de“ oder „en“, da Deutsch und Englisch nicht geändert oder angepasst werden können.
   
   Hinweis: Wenn Sie im AI Chat eine Liste mit Sprachen haben möchten, die Deutsch und/oder Englisch und benutzerdefinierte Sprachen enthält, können Sie die Ländercodes „de“ und/oder „en“ in den Hook einfügen, zum Beispiel „“es„:“Espanol„, “fr„:“Francais„, “de„:“German„, ‚en‘:“English„“. Das Erstellen von JSON-Dateien für Deutsch und Englisch ist in den nächsten Schritten nicht erforderlich, da die Übersetzungen automatisch bereitgestellt werden.

1. Nachdem der Hook erstellt ist, öffnen Sie den Ordner „i18n“ und erstellen Sie die JSON-Dateien mit den Schlüsselwerten, die Sie im Hook definiert haben. Zum Beispiel es.json für Spanisch und fr.json für Französisch.
   
   Hinweis: Wenn Deutsch und/oder Englisch im Hook definiert sind, ist dieser und der nächste Schritt nicht erforderlich, da die Übersetzung automatisch bereitgestellt werden.

1. Öffnen Sie anschließend die JSON-Dateien und definieren Sie die Übersetzungen, die Sie im AI Chat anzeigen möchten. Speichern Sie die Änderungen.
   
   Achtung: Bitte beachten Sie, dass gültige benutzerdefinierte Sprachumgebungen („custom locales“ z. B. es, fr, cs oder nl) verwendet werden müssen, da sonst die benutzerdefinierte Sprache nicht im AI Chat angezeigt wird. Vermeiden Sie außerdem die Sprachumgebungen „de“ oder „en“, da Deutsch und Englisch nicht geändert oder angepasst werden können.

1. Die Konfiguration der benutzerdefinierten Sprachen ist nun fertig. Durch das Neuladen des AI Chat sollten die neuen Übersetzungen sichtbar sein.

Aktivierung des NLQA Index

Aktivieren Sie „Natural Language Question Answering“ (NLQA) in den gewünschten Indizes. Für mehr Informationen über die Konfiguration, siehe NLQA Index anlegen und NLQA auf bestehendem Index aktivieren.

Einrichtung des Large Language Models (LLM)

On-Premise Kunden haben die Möglichkeit GPU Appliances zu verwenden bzw. Mindbreeze SaaS Kunden können ein Remote LLM verwenden. Kontaktieren Sie bitte sales@mindbreeze.com bezüglich Optionen für den Betrieb eines LLMs mit Mindbreeze.

Für die Nutzung bestehender, externer LLM-Modelle, wird aktuell das Huggingface Text Generation Interface (TGI) unterstützt. Wenn notwendig, kann als Autorisierungsmöglichkeit OAuth genutzt werden.  Wenn Sie ein selbst gehostetes LLM mit anderem Interface verwenden wollen, kontaktieren Sie bitte den Mindbreeze Support (support@mindbreeze.com) um die Komptabilität zu prüfen.

Zur Einrichtung des LLM, klicken Sie im Management Center auf den Menüpunkt „Insight Services“ und öffnen Sie den Untermenüpunkt „RAG“. Wählen Sie dort den Bereich „LLMs“.

Klicken Sie auf „Hinzufügen“, um ein neues LLM zu konfigurieren. Die folgenden Werte werden vom jeweiligen LLM geliefert:

Speichern Sie ihre Konfiguration, indem Sie auf „Speichern“ klicken. Mehr Details zur Administration von Modellen und Pipelines finden Sie in Handbuch - Administration von Insight Services für Retrieval Augmented Generation.

Externes LLM mit Autorisierung

Wenn Sie ein von Mindbreeze betriebenes externes LLM verwenden wollen, kontaktieren Sie bitte sales@mindbreeze.com. Das Sales-Team wird mit Ihnen die konkrete Situation besprechen und für Sie ein maßgeschneidertes Angebot erstellen.

Das Mapping von LLM in der RAG Administration zu den notwendigen Credentials erfolgt über das Endpoint Mapping. Um dies durchzuführen öffnen Sie im Management Center den Menüpunkt „Configuration“ und gehen Sie zum „Network“-Tab. Erstellen Sie ein neues Credential vom Typ „OAuth 2“ mit den von Mindbreeze bereitgestellten Informationen. Siehe folgenden Screenshot für ein Beispiel.

Erstellen Sie einen neuen Endpoint mit diesem Credential. Die „Location“ des Endpoints ist die URL des LLM.

Erstellung einer Pipeline und Nutzung des InSpire AI Chats

Um InSpire AI Chat zu nutzen, muss eine Pipeline mit einem Modell angelegt werden. Die dafür notwendigen Schritte finden Sie in Handbuch - Administration von Insight Services für Retrieval Augmented Generation.

Berechtigung von Management Center Nutzern für die RAG Administration

Für die Administration von Insight Services für RAG muss ein Nutzer die folgenden Rollen besitzen:

Ein Administrator kann einem Nutzer oder einer Gruppe diese Rollen im Management Center im Menüpunkt „Setup“ zuordnen. Klicken Sie dafür dann auf den Untermenüpunkt „Credentials“ und weisen Sie dem Nutzer oder der Gruppe die notwendigen Rollen zu. Für mehr Informationen über das Zuweisen von Rollen, siehe Konfiguration – Backend Credentials.

Troubleshooting

Servicedaten für die Pipeline und das LLM werden nicht mehr angezeigt nachdem ein Snapshot angewandt wurde

Nach der Anwendung eines Snapshots kann das Problem auftreten, dass bereits vorhandene Servicekonfigurationsdaten für eine Pipeline und LLM nicht mehr angezeigt werden. Der Grund dafür ist, dass in der Einstellung "Path to Store Base" kein Pfad definiert wurde, wodurch die Pipeline- und LLM-Daten im RAG-Service nicht mehr angezeigt werden.

Um dies zu lösen, starten Sie bitte Ihren RAG-Service neu. Nach dem Neustart sollten die Servicekonfigurationsdaten wieder angezeigt werden.