REST-API-Datenverbindung

Die REST-API-Datenverbindung ermöglicht es Alan, nahtlos mit externen Diensten zu interagieren, die eine bestimmte RESTful-API implementieren. Dieser Verbindungstyp bietet eine flexible Möglichkeit, dynamisch auf Daten verschiedener Dienste zuzugreifen, wodurch neue Möglichkeiten für datengetriebene Anwendungen eröffnet werden.

Wenn Sie einen Anwendungsfall identifiziert haben, bei dem Sie auf externe Dienste zugreifen und Daten dynamisch abrufen möchten, kann die REST-API-Datenverbindung die Lösung sein, die Sie benötigen. Dazu muss zunächst ein Adapter-Service implementiert werden, der das gewünschte System anspricht und die Antwort in einem für Alan verständlichen Format zurückgibt. Anschließend kann die REST-API-Datenverbindung in Alan konfiguriert werden, um auf den Adapter-Service zuzugreifen und die Daten in Wissensdatenbanken zu verwenden.

Mögliche Anwendungsfälle

Die REST-API-Datenverbindung kann beispielsweise für folgende Anwendungsfälle verwendet werden:

• Abfrage aktueller Daten: z.B. Wetter, Verkehr, Finanzen, Aktienkurse, Nachrichten, Immobilien, Sportergebnisse
• Anbindung an interne Systeme: z.B. Customer Relationship Management (CRM), E-Commerce, Dokumentenverwaltungssystem (DMS), Content-Management-System (CMS), Terminverwaltung, Veranstaltungsmanagement, IoT-Geräte, Support-Ticket-System
• Anbindung von Nutzerdaten: z.B. Benutzerprofile, Gesundheitsdaten, Fitnessdaten
• Integration eines KI-Services der die Nutzeranfrage analysiert und anreichert (z.B. Textanalyse, Wissensgraphen, Empfehlungssysteme)

Erstellen eines REST-API-Adapters

Um eine REST-API-Datenverbindung zu erstellen, muss zunächst ein REST-API-Adapter erstellt werden. In diesem müssen Sie die erforderlichen Modelle definieren und den notwendigen API-Endpunkt implementieren.

Erforderliche Modelle

Ihr Endpunkt muss eine POST-Anfrage mit einer JSON-Payload akzeptieren, die die folgenden Eigenschaften enthält:

{
  "input_schema": "basic", // optional, kann derzeit nur "basic" sein
  "summary": "", // optional, ist derzeit immer leer
  "message": "string" // erforderlich, rohe Benutzereingabe
}

Als Antwort muss Ihr Endpunkt ein JSON-Objekt mit der folgenden Struktur zurückgeben:

{
  "documents": [
    {
      "title": "string", // optional, Titel des Dokuments zur Anzeige
      "external_link": "string", // optional, URL mit der der Nutzer auf das Dokument zugreifen kann
      "content": "string" // erforderlich, dieser Text wird an das LLM übergeben
    }
  ]
}

Authentifizierung

Der Zugriff auf den Endpunkt kann durch die Verwendung eines individuellen API-Schlüssels geschützt werden. Dazu muss der Endpunkt den API-Schlüssel in der Anfrage im Headerfeld X-API-KEY erwarten und überprüfen. Der erwartete API-Schlüssel kann in der Konfiguration der REST-API-Datenverbindung in Alan angegeben werden.

OpenAPI-Schema

Um den Entwicklungsprozess zu vereinfachen, stellen wir ein OpenAPI-Schema (openapi.json) für den relevanten API-Endpunkt zur Verfügung. Dieses Schema kann verwendet werden, um Client-Bibliotheken, API-Dokumentationen und andere Tools zu generieren, die mit der REST-API-Datenverbindung arbeiten.

OpenAPI-Schema

Beispielimplementierung

Zur Orientierung stellen wir Ihnen eine Beispielimplementierung in Python eines REST-API-Adapters für die REST-API-Datenverbindung zur Verfügung. Hier wird ein einfacher REST-API-Adapter vorgestellt, der eine statische Antwort zurückgibt und sowohl die richtigen Datenmodelle als auch die Authentifizierung mit einem API-Schlüssel demonstriert.

Alan Data Connector Template

Bereitstellen eines REST-API-Adapters

Hosten Sie Ihre REST-API-Adapter-Implementierung auf einem Server, der für das Alan-Backend zugänglich ist. Stellen Sie sicher, dass der Server eingehende Anfragen bearbeiten und die entsprechenden Antworten basierend auf den definierten Modellen zurückgeben kann. Der Zugriff auf den Endpunkt muss über HTTPS erfolgen und setzt ein gültiges Zertifikat voraus.

Debuggen der REST-API-Datenverbindung

Wenn ein REST-API-Adapter implementiert und deployed wurde, können Sie diesen testen, um dessen Funktionalität sicherzustellen. Dafür bietet die Alan-API einen Debugging-Endpunkt an. Beim Aufruf sendet Alan eine Testanfrage an Ihren REST-API-Adapter. Dabei wird die Erreichbarkeit sowie das Antwortformat getestet.

Um diesen Endpunkt aufzurufen, können Sie eine POST-Anfrage an den Debugging-Endpunkt (/connectors/validate-restapi) mit einem Payload der folgenden Form stellen:

{
  "url": "string",
  "api_key": "string | null",
  "message": "string"
}

Eine einfache Möglichkeit dazu bietet die Alan Swagger-Dokumentation.

Der Payload ist wie folgt aufgebaut:

• url: Die URL zu Ihrem REST-API-Adapter. Stellen Sie sicher, dass es sich dabei um einen gültigen Endpunkt handelt auf den Alan zugreifen darf.
• api_key: Falls erforderlich, der API-Schlüssel zu Ihrem REST-API-Adapter, ansonsten null. Wird nicht von Alan gespeichert.
• message: Befüllt das message-Feld der Anfrage an den REST-API-Adapter.

Als Antwort wird ein JSON-Objekt mit der folgenden Struktur zurückgegeben:

{
  "success": boolean,
  "raw_response": "string | null",
  "result": "string"
}

Aufbau der Antwort:

• success: Gibt an, ob die Testanfrage an den Adapter erfolgreich gesendet und die erhaltene Antwort von Alan erfolgreich verarbeitet werden konnte.
• raw_response: Beinhaltet die rohe Antwort, die Alan von dem Adapter empfangen hat. Falls keine Verbindung möglich war, beinhaltet dieses Feld den Wert null.
• result: War die Anfrage erfolgreich, beinhaltet dieses Feld die Antwort, die an das LLM weitergegeben werden würde. War die Anfrage nicht erfolgreich, beinhaltet dieses Feld Informationen über den aufgetretenen Fehler.

Mit diesen Informationen können Sie Ihren REST-API-Adapter testen und bei Bedarf Verbesserungen vornehmen.

Konfigurieren einer REST-API-Datenverbindung in Alan

Um eine REST-API-Datenverbindung in Alan zu konfigurieren, gehen Sie wie folgt vor:

1. Navigieren Sie zum Abschnitt Datenverbindungen im Adminbereich.
2. Klicken Sie auf die Schaltfläche Neu und wählen Sie die Option REST.
3. Klicken Sie auf Weiter und geben Sie die erforderlichen Details zur Konfiguration der Verbindung an, einschließlich:
   • Titel: Ein beschreibender Name für die Verbindung.
   • Beschreibung: Eine kurze Beschreibung der Verbindung.
   • URL: Die URL des REST-API-Adapter-Endpunkts (z.B. https://example.com:8000/query). Dabei muss es sich um eine HTTPS-URL handeln.
   • REST-API-Schlüssel: Der API-Schlüssel, der für den Zugriff auf den Endpunkt erforderlich ist. Falls kein API-Schlüssel erforderlich ist, kann dieses Feld deaktiviert bleiben. Es ist nicht möglich, den API-Schlüssel nach dem Speichern auszulesen, er kann jedoch neu gesetzt oder gelöscht werden.
4. Klicken Sie auf Speichern, um die Konfiguration zu speichern.

Nun können Wissensdatenbanken basierend auf der REST-API-Datenverbindung erstellt werden, um auf externe Dienste zuzugreifen und Daten dynamisch abzurufen.