Dify Tutorial zur Anbindung an externe Wissensdatenbanken

Zur besseren Unterscheidung wird in diesem Papier Dify Wissensspeicher außerhalb der Plattform werden zusammenfassend als "externe Wissensspeicher" bezeichnet.

Funktion Einführung

Die in Dify eingebaute Wissensdatenbankfunktionalität und die Mechanismen zur Textsuche erfüllen möglicherweise nicht die Anforderungen einiger fortgeschrittener Entwickler, die eine präzisere Kontrolle über die Ergebnisse des Textabrufs benötigen.

Einige Teams entscheiden sich für die Selbstforschung RAG Algorithmen zu verwenden und ein Texterkennungssystem eigenständig zu pflegen oder einen von einem Cloud-Anbieter bereitgestellten Wissensdatenbankdienst (z. B. AWS Bedrock) zu nutzen.

Dify, als offene LLM-Anwendungsentwicklungsplattform, möchte Entwicklern mehr Möglichkeiten bieten.

Dify kann über die Funktion "Connect to External Knowledge Bases" mit externen Wissensdatenbanken verbunden werden. Dadurch erhalten KI-Anwendungen Zugang zu mehr Informationsquellen.

Im Einzelnen ergeben sich die folgenden Vorteile:

• Dify kann direkt auf Text zugreifen, der in der Wissensdatenbank des Cloud-Anbieters gehostet wird, so dass die Entwickler keine Inhalte in die Wissensdatenbank von Dify kopieren müssen.
• Dify kann direkt auf den algorithmisch verarbeiteten Text in der selbst erstellten Wissensdatenbank zugreifen, und die Entwickler müssen sich nur darauf konzentrieren, den Mechanismus der Informationsbeschaffung zu optimieren, um die Abrufgenauigkeit zu verbessern.
• Im Vergleich zur direkten Nutzung der Wissensdatenbank-Services von Cloud-Anbietern bietet Dify flexiblere Integrationsmöglichkeiten auf der Anwendungsebene, die es Entwicklern leicht machen, verschiedene KI-Anwendungen zu erstellen.

Die folgende Abbildung veranschaulicht das Prinzip der Verbindung mit einer externen Wissensbasis:

Schritte zur Verbindung

1. eine konforme externe Wissensdatenbank-API einzurichten

Lesen Sie die von Dify verfasste Spezifikation der externen Wissensdatenbank-API sorgfältig durch, bevor Sie Ihren API-Dienst einrichten.

2. assoziierte externe Wissensdatenbank-APIs

Bitte beachten Sie, dass Dify derzeit nur das Abrufen von externen Wissensdatenbanken unterstützt, nicht aber deren Änderung. Die Entwickler müssen externe Wissensdatenbanken selbst pflegen.

Gehen Sie zur Seite "Wissensdatenbank", klicken Sie auf "Externe Wissensdatenbank-API" in der oberen rechten Ecke und dann auf "Externe Wissensdatenbank-API hinzufügen".

Folgen Sie den Aufforderungen auf der Seite, um das Formular auszufüllen:

• Name der Wissensdatenbank: Kann angepasst werden, um zwischen verschiedenen externen Wissensdatenbank-APIs zu unterscheiden.
• Adresse der API-Schnittstelle: Die Adresse des Links zur externen Wissensdatenbank, z. B. api-endpoint/retrieval. Ausführliche Anweisungen finden Sie in der externen Wissensdatenbank API.
• API-Schlüssel: Der Verbindungsschlüssel für die externe Wissensdatenbank, siehe Externe Wissensdatenbank-API für Details.

3. die Verbindung zu externen Wissensdatenbanken

Klicken Sie auf dem Bildschirm "Wissensdatenbank" unter "Wissensdatenbank hinzufügen" auf "Mit externer Wissensdatenbank verbinden", um den Bildschirm zur Konfiguration der Parameter aufzurufen.

Füllen Sie die folgenden Parameter aus:

• Wissensdatenbank Name und Beschreibung
• Externe Wissensdatenbank-API: Wählen Sie die in Schritt 2 verknüpfte externe Wissensdatenbank-API aus. Dify wird den Textinhalt der externen Wissensdatenbank über die API-Verbindung aufrufen.
• Externe Wissensdatenbank ID: Geben Sie die ID der externen Wissensdatenbank an, mit der Sie verknüpft werden sollen. Einzelheiten finden Sie unter Externe Wissensdatenbank-API.
• Passen Sie die Abrufeinstellungen an:
  • Top K: Je größer der Wert, desto mehr Textfragmente werden abgerufen. Es wird empfohlen, mit kleineren Werten zu beginnen und diese schrittweise zu erhöhen, bis die optimale Balance gefunden ist.
  • Schwellenwert für die Punktzahl: Je höher der Wert, desto relevanter sind die abgerufenen Textsegmente für die Frage, aber die Anzahl nimmt ab. Es wird empfohlen, mit einem höheren Wert zu beginnen und diesen schrittweise zu verringern, um eine ausreichende Menge an relevantem Text zu erhalten.

4. testet Verbindungen und Rückrufe

Nachdem die Verbindung hergestellt wurde, können Sie die problematischen Schlüsselwörter im "Abruftest" simulieren und eine Vorschau der aus der externen Wissensdatenbank abgerufenen Textfragmente anzeigen. Wenn Sie mit den Ergebnissen nicht zufrieden sind, können Sie versuchen, die Abrufparameter zu ändern oder die Sucheinstellungen der externen Wissensdatenbank anzupassen.

5. die Integration in Anwendungen

• Anwendung vom Typ Chatbot/Agent: Wählen Sie im Kontext auf der Seite Arrangement das Bild mit dem EXTERNAL Markiert als externe Wissensdatenbank.

• Anwendung vom Typ Chatflow/Workflow: Fügen Sie den Knoten Knowledge Retrieval hinzu und wählen Sie den Knoten mit dem EXTERNAL Markiert als externe Wissensdatenbank.

6. die Verwaltung der externen Wissensbasis

Auf der Seite Wissensdatenbank wird die Karte Externe Wissensdatenbank in der oberen rechten Ecke der Karte mit folgendem Text versehen EXTERNAL Registerkarte. Geben Sie die Wissensbasis ein, die Sie ändern möchten, und klicken Sie auf "Einstellungen", um sie zu ändern:

• Name und Beschreibung der Wissensdatenbank
• Umfang der Sichtbarkeit ("Nur ich", "Alle Teammitglieder" und "Einige Teammitglieder"). Mitglieder ohne Berechtigungen können nicht auf die Wissensdatenbank zugreifen.
• Abrufeinstellungen (Schwellenwerte für Top K und Score)

Hinweis: Es ist nicht möglich, die verknüpfte externe Wissensdatenbank-API und die externe Wissens-ID zu ändern. Wenn Sie sie ändern möchten, verknüpfen Sie bitte eine neue externe Wissensdatenbank-API und stellen Sie sie erneut her.

Verbindungsbeispiel: Wie stelle ich eine Verbindung mit der AWS Bedrock Knowledge Base her?

In diesem Beitrag wird erläutert, wie die Dify-Plattform über eine externe Wissensdatenbank-API mit der AWS Bedrock Knowledge Base verbunden werden kann. Dadurch können KI-Anwendungen innerhalb der Dify-Plattform direkt auf die in der AWS Bedrock Knowledge Base gespeicherten Inhalte zugreifen und den Zugang zu neuen Informationsquellen erweitern.

Vorab-Positionierung

• AWS Bedrock Wissensdatenbank
• Dify SaaS Dienstleistungen / Dify Community Edition
• Grundlagen der Backend-API-Entwicklung

1. registrieren und AWS Bedrock Knowledge Base erstellen

Besuchen Sie AWS Bedrock, um einen Knowledge Base-Service zu erstellen.

2. back-end API-Dienste aufbauen

Die Dify-Plattform kann sich noch nicht direkt mit der AWS Bedrock Knowledge Base verbinden. Das Entwicklungsteam muss sich auf die API-Definition von Dify für die externe Wissensdatenbank-Verbindung beziehen und den Back-End-API-Service manuell erstellen, um die Verbindung mit AWS Bedrock herzustellen. Bitte sehen Sie sich das Architekturdiagramm an:

Sie können sich auf die folgenden 2 Codedateien beziehen, um die Backend-Service-API zu erstellen.

knowledge.py

from flask import request
from flask_restful import Resource, reqparse

from bedrock.knowledge_service import ExternalDatasetService

class BedrockRetrievalApi(Resource):
    # url : <your-endpoint>/retrieval
    def post(self):
        parser = reqparse.RequestParser()
        parser.add_argument("retrieval_setting", nullable=False, required=True, type=dict, location="json")
        parser.add_argument("query", nullable=False, required=True, type=str,)
        parser.add_argument("knowledge_id", nullable=False, required=True, type=str)
        args = parser.parse_args()

        # Authorization check
        auth_header = request.headers.get("Authorization")
        if " " not in auth_header:
            return {
                "error_code": 1001,
                "error_msg": "Invalid Authorization header format. Expected 'Bearer <api-key>' format."
            }, 403
        auth_scheme, auth_token = auth_header.split(None, 1)
        auth_scheme = auth_scheme.lower()
        if auth_scheme != "bearer":
            return {
                "error_code": 1001,
                "error_msg": "Invalid Authorization header format. Expected 'Bearer <api-key>' format."
            }, 403
        if auth_token:
            # process your authorization logic here
            pass

        # Call the knowledge retrieval service
        result = ExternalDatasetService.knowledge_retrieval(
            args["retrieval_setting"], args["query"], args["knowledge_id"]
        )
        return result, 200

knowledge_service.py

import boto3

class ExternalDatasetService:
    @staticmethod
    def knowledge_retrieval(retrieval_setting: dict, query: str, knowledge_id: str):
        # get bedrock client
        client = boto3.client(
            "bedrock-agent-runtime",
            aws_secret_access_key="AWS_SECRET_ACCESS_KEY",
            aws_access_key_id="AWS_ACCESS_KEY_ID",
            # example: us-east-1
            region_name="AWS_REGION_NAME",
        )
        # fetch external knowledge retrieval
        response = client.retrieve(
            knowledgeBaseId=knowledge_id,
            retrievalConfiguration={
                "vectorSearchConfiguration": {"numberOfResults": retrieval_setting.get("top_k"), "overrideSearchType": "HYBRID"}
            },
            retrievalQuery={"text": query},
        )
        # parse response
        results = []
        if response.get("ResponseMetadata") and response.get("ResponseMetadata").get("HTTPStatusCode") == 200:
            if response.get("retrievalResults"):
                retrieval_results = response.get("retrievalResults")
                for retrieval_result in retrieval_results:
                    # filter out results with score less than threshold
                    if retrieval_result.get("score") < retrieval_setting.get("score_threshold", .0):
                        continue
                    result = {
                        "metadata": retrieval_result.get("metadata"),
                        "score": retrieval_result.get("score"),
                        "title": retrieval_result.get("metadata").get("x-amz-bedrock-kb-source-uri"),
                        "content": retrieval_result.get("content").get("text"),
                    }
                    results.append(result)
        return {
            "records": results
        }

In diesem Prozess können Sie die API-Schnittstellenadresse und den API-Schlüssel für die Authentifizierung und nachfolgende Verbindungen erstellen.

3. eine AWS Bedrock Knowledge Base ID zu erhalten

Melden Sie sich am AWS Bedrock Knowledge Backend an und rufen Sie die ID der erstellten Knowledge Base ab. Dieser Parameter wird in den folgenden Schritten verwendet, um eine Verbindung zur Dify-Plattform herzustellen.

4. verlinkte externe Wissens-API

Gehen Sie zur Dify Plattform "Wissensbasis" Seite, klicken Sie auf die obere rechte Ecke der "Externe Wissensdatenbank-API"Entspannen Sie sich. "Externe Wissensdatenbank-API hinzufügen".

Folgen Sie den Anweisungen auf der Seite und füllen Sie die folgenden Felder der Reihe nach aus:

• Der Name der Wissensdatenbank, der einen individuellen Namen zur Unterscheidung zwischen den verschiedenen externen Wissens-APIs ermöglicht, die mit der Dify-Plattform verbunden sind;
• Die API-Schnittstellenadresse, also die Verbindungsadresse der externen Wissensdatenbank, kann im zweiten Schritt angepasst werden. Beispiel api-endpoint/retrieval.;
• Der API-Schlüssel, der Verbindungsschlüssel zur externen Wissensdatenbank, kann im zweiten Schritt angepasst werden.

5. die Verbindung zu externen Wissensdatenbanken

Urlaub für "Wissensbasis" Seite, klicken Sie auf die Karte Wissensdatenbank hinzufügen unter dem "Verbindung zu externen Wissensdatenbanken" Springen Sie zur Seite für die Parameterkonfiguration.

Füllen Sie die folgenden Parameter aus:

• Wissensdatenbank Name und Beschreibung
• Externe Wissensdatenbank-APIWählen Sie die in Schritt 4 zugeordnete externe Wissensdatenbank-API
• Externe Wissensdatenbank-IDGeben Sie die in Schritt 3 erhaltene AWS Bedrock Knowledge Base ID ein
• Anpassen der AbrufeinstellungenTop K: Wenn ein Nutzer eine Frage stellt, wird eine externe Wissens-API angefordert, um hochrelevante Inhaltssegmente zu erhalten. Mit diesem Parameter werden Textsegmente gefiltert, die einen hohen Ähnlichkeitsgrad mit der Frage des Benutzers aufweisen. Der Standardwert ist 3. Je höher der Wert, desto mehr relevante Textsegmente werden abgerufen.

  Score Threshold: der Ähnlichkeitsschwellenwert für das Filtern von Textfragmenten, nur Textfragmente, die den eingestellten Score überschreiten, werden abgerufen, der Standardwert ist 0,5. Je höher der Wert, desto höher die Ähnlichkeit zwischen dem Text und der Frage, desto geringer die Anzahl der Texte, die abgerufen werden sollen, und desto genauer ist das Ergebnis.

Nach dem Einrichten können Sie eine Verbindung zur externen Wissensdatenbank-API herstellen.

6. das Testen von Verbindungen zu externen Wissensdatenbanken und von Abrufen

Nachdem eine Verbindung zu einer externen Wissensdatenbank hergestellt wurde, kann der Entwickler "Rückrufaktion". Entwerfen Sie mögliche Problemschlüsselwörter in der Vorschau von Textsegmenten, die aus der AWS Bedrock Knowledge Base abgerufen werden.

Wenn Sie mit den Ergebnissen des Abrufs nicht zufrieden sind, können Sie versuchen, die Abrufparameter zu ändern oder die Sucheinstellungen der AWS Bedrock Knowledge Base selbst anzupassen.

allgemeine Probleme

Was ist, wenn ich einen Fehler beim Verbinden mit der externen Wissensdatenbank-API erhalte?

Nachstehend finden Sie die Fehlercodes und die entsprechenden Lösungen:

Externe Wissensdatenbank API-Spezifikation

Anfangs- oder Endpunkt (in Geschichten usw.)

POST <your-endpoint>/retrieval

Anfragekopf

Diese API wird verwendet, um eine Verbindung zu unabhängig verwalteten Wissensdatenbanken innerhalb eines Teams herzustellen. Weitere Anleitungen dazu finden Sie unter Verbindung zu externen Wissensdatenbanken herstellen.

kann in der Kopfzeile der HTTP-Anfrage gefunden werden Authorization Felder unter Verwendung der API-Key um Berechtigungen zu authentifizieren. Die Authentifizierungslogik wird von Ihnen in der Retrieval-API definiert, wie unten dargestellt:

Authorization: Bearer {API_KEY}

Antragsteller

Die Anfrage nimmt Daten im folgenden JSON-Format entgegen:

retrieval_setting Das Attribut enthält die folgenden Schlüssel:

Beispiel für einen Antrag

POST <your-endpoint>/retrieval HTTP/1.1
Content-Type: application/json
Authorization: Bearer your-api-key
{
"knowledge_id": "your-knowledge-id",
"query": "你的问题",
"retrieval_setting": {
"top_k": 2,
"score_threshold": 0.5
}
}

Antwortkörper

Wenn der Vorgang erfolgreich ist, gibt der Dienst eine HTTP 200-Antwort mit den folgenden Daten im JSON-Format zurück:

records ist eine Liste von Objekten mit den folgenden Schlüsseln:

Beispielhafte Antwort

HTTP/1.1 200
Content-Type: application/json
{
"records": [
{
"metadata": {
"path": "s3://dify/knowledge.txt",
"description": "dify 知识文档"
},
"score": 0.98,
"title": "knowledge.txt",
"content": "这是外部知识的文档。"
},
{
"metadata": {
"path": "s3://dify/introduce.txt",
"description": "dify 介绍"
},
"score": 0.66,
"title": "introduce.txt",
"content": "GenAI 应用程序的创新引擎"
}
]
}

falsch

Wenn der Vorgang fehlschlägt, gibt der Dienst die folgende Fehlermeldung (im JSON-Format) zurück:

error_code Attribut Typ:

HTTP Status Code

• AccessDeniedException: Fehlende Zugriffsrechte. (HTTP-Statuscode: 403)
• InternalServerException: Interner Serverfehler. (HTTP-Statuscode: 500)