Didacticiel Dify sur la connexion aux bases de connaissances externes

Pour faciliter la distinction, le présent document Dify Les référentiels de connaissances extérieurs à la plate-forme sont collectivement appelés "référentiels de connaissances externes".

Introduction à la fonction

La fonctionnalité de base de connaissances et les mécanismes de recherche de texte intégrés à Dify peuvent ne pas répondre aux besoins de certains développeurs avancés qui peuvent exiger un contrôle plus précis des résultats de la recherche de texte.

Certaines équipes choisissent d'effectuer des recherches par elles-mêmes RAG et maintenir un système de rappel de texte de manière indépendante, ou utiliser un service de base de connaissances fourni par un prestataire de services en nuage (par exemple, AWS Bedrock).

Dify, en tant que plateforme ouverte de développement d'applications LLM, souhaite offrir davantage d'options aux développeurs.

Dify peut se connecter à des bases de connaissances externes grâce à la fonction "Connect to External Knowledge Bases". Cela permet aux applications d'intelligence artificielle d'accéder à davantage de sources d'information.

Plus précisément, les avantages sont les suivants :

• Dify peut accéder directement au texte hébergé dans la base de connaissances du fournisseur de services en nuage, ce qui évite aux développeurs de copier le contenu dans la base de connaissances de Dify.
• Dify peut accéder directement au texte traité par algorithme dans la base de connaissances créée par l'entreprise, et les développeurs n'ont plus qu'à se concentrer sur l'optimisation du mécanisme de recherche d'informations afin d'améliorer la précision de la mémorisation.
• Par rapport à l'utilisation directe des services de base de connaissances des fournisseurs de cloud, Dify offre des capacités d'intégration de la couche applicative plus souples, ce qui permet aux développeurs de créer facilement diverses applications d'IA.

La figure suivante illustre le principe de connexion à une base de connaissances externe :

Étapes de connexion

1. mise en place d'une base de connaissances externe conforme à l'API

Veillez à lire attentivement les spécifications de l'API de la base de connaissances externe rédigées par Dify avant de mettre en place votre service API.

2. les API de bases de connaissances externes associées

Veuillez noter que Dify ne permet actuellement que de récupérer des bases de connaissances externes, et non de les modifier. Les développeurs doivent gérer eux-mêmes les bases de connaissances externes.

Allez sur la page "Base de connaissances", cliquez sur "API de base de connaissances externe" dans le coin supérieur droit, puis cliquez sur "Ajouter une API de base de connaissances externe".

Suivez les instructions de la page pour remplir le formulaire :

• Nom de la base de connaissances : Peut être personnalisé pour différencier les différentes API de bases de connaissances externes.
• Adresse de l'interface API : L'adresse du lien vers la base de connaissances externe, par exemple api-endpoint/retrieval. Reportez-vous à la base de connaissances externe API pour obtenir des instructions détaillées.
• Clé API : La clé de connexion pour la base de connaissances externe, voir API Base de connaissances externe pour plus de détails.

3. se connecter à des bases de connaissances externes

Dans l'écran "Base de connaissances", cliquez sur "Connecter à une base de connaissances externe" sous "Ajouter une base de connaissances" pour accéder à l'écran de configuration des paramètres.

Complétez les paramètres suivants :

• Nom et description de la base de connaissances
• Base de connaissances externe API : Sélectionnez l'API de la base de connaissances externe associée à l'étape 2. Dify appellera le contenu textuel de la base de connaissances externe par le biais de la connexion API.
• Base de connaissances externe ID : Spécifiez l'ID de la base de connaissances externe à laquelle vous souhaitez être associé. Pour plus d'informations, reportez-vous à l'API Base de connaissances externe.
• Ajuster les paramètres de rappel :
  • Top K : Plus la valeur est élevée, plus le nombre de fragments de texte rappelés est important. Il est recommandé de commencer par expérimenter avec des valeurs plus petites et de les augmenter progressivement jusqu'à ce que l'équilibre optimal soit trouvé.
  • Seuil de score : Plus la valeur est élevée, plus les segments de texte rappelés sont pertinents par rapport à la question, mais le nombre diminue. Il est recommandé de commencer par une valeur élevée et de la diminuer progressivement pour obtenir un nombre suffisant de textes pertinents.

4. tester les connexions et les rappels

Une fois la connexion établie, vous pouvez simuler les mots-clés problématiques dans le "Test de rappel" et prévisualiser les fragments de texte rappelés à partir de la base de connaissances externe. Si vous n'êtes pas satisfait des résultats, vous pouvez essayer de modifier les paramètres de rappel ou d'ajuster les paramètres de recherche de la base de connaissances externe.

5. intégration dans les applications

• Application de type Chatbot / Agent : Dans la page Contexte de l'arrangement, sélectionnez l'écran avec l'icône EXTERNAL Base de connaissances externe étiquetée.

• Application de type Chatflow / Workflow : Ajouter le nœud Knowledge Retrieval et sélectionner le nœud avec l'icône EXTERNAL Base de connaissances externe étiquetée.

6. gérer la base de connaissances externe

Sur la page Base de connaissances, la carte Base de connaissances externe comporte le texte suivant dans le coin supérieur droit de la carte EXTERNAL Onglet. Saisissez la base de connaissances que vous souhaitez modifier et cliquez sur "Paramètres" pour la modifier :

• Nom et description de la base de connaissances
• Étendue de la visibilité ("Seulement moi", "Tous les membres de l'équipe" et "Certains membres de l'équipe"). Les membres sans autorisation ne peuvent pas accéder à la base de connaissances.
• Paramètres de rappel (seuils Top K et Score)

Remarque : il n'est pas possible de modifier l'API de la base de connaissances externe et l'ID de la base de connaissances externe associés. Si vous souhaitez les modifier, veuillez associer une nouvelle API de la base de connaissances externe et la reconnecter.

Exemple de connexion : Comment puis-je me connecter à la base de connaissances AWS Bedrock ?

Cet article explique comment la plateforme Dify peut être connectée à la base de connaissances AWS Bedrock via une API de base de connaissances externe, ce qui permet aux applications d'IA au sein de la plateforme Dify d'accéder directement au contenu stocké dans la base de connaissances AWS Bedrock, élargissant ainsi l'accès à de nouvelles sources d'information.

prépositionnement

• Base de connaissances AWS Bedrock
• Dify SaaS Services / Dify Community Edition
• Principes de base du développement d'API dorsales

1. s'inscrire et créer la base de connaissances AWS Bedrock

Visitez AWS Bedrock pour créer un service de base de connaissances.

2. créer des services d'API back-end

La plateforme Dify ne peut pas encore se connecter directement à la base de connaissances AWS Bedrock. L'équipe de développement doit se référer à la définition de l'API de Dify sur la connexion à la base de connaissances externe et créer manuellement le service API dorsal pour établir la connexion avec AWS Bedrock. Veuillez vous référer au diagramme d'architecture :

Vous pouvez vous référer aux deux fichiers de code suivants pour construire l'API du service backend.

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
        }

Au cours de ce processus, vous pouvez créer l'adresse de l'interface API et la clé API pour l'authentification et les connexions ultérieures.

3. obtenir un identifiant pour la base de connaissances AWS Bedrock

Connectez-vous au backend AWS Bedrock Knowledge et obtenez l'ID de la base de connaissances qui a été créée. Ce paramètre sera utilisé dans les étapes suivantes pour se connecter à la plateforme Dify.

4. l'API sur les connaissances externes liées

Accéder à la plateforme Dify "Base de connaissances" cliquez sur le coin supérieur droit de la page "Base de connaissances externe API"Détendez-vous. "Ajouter une API de base de connaissances externe".

Suivez les instructions de la page et remplissez les champs suivants dans l'ordre :

• Le nom de la base de connaissances, permettant un nom personnalisé pour distinguer les différentes API de connaissances externes connectées au sein de la plateforme Dify ;
• L'adresse de l'interface API, l'adresse de connexion de la base de connaissances externe, peut être personnalisée dans la deuxième étape. Exemple de l'adresse de l'interface API api-endpoint/retrieval. ;
• La clé API, la clé de connexion à la base de connaissances externe, peut être personnalisée dans la deuxième étape.

5. se connecter à des bases de connaissances externes

partir pour "Base de connaissances" page, cliquez sur la carte Ajouter une base de connaissances sous la rubrique "Connexion à des bases de connaissances externes Passer à la page de configuration des paramètres.

Complétez les paramètres suivants :

• Nom et description de la base de connaissances
• Base de connaissances externe APISélectionnez l'API de la base de connaissances externe associée à l'étape 4
• ID de la base de connaissances externeRenseignez l'identifiant de la base de connaissances AWS Bedrock obtenu à l'étape 3.
• Réglage des paramètres de rappelTop K : lorsqu'un utilisateur pose une question, une API de connaissances externe est sollicitée pour obtenir des segments de contenu très pertinents. Ce paramètre est utilisé pour filtrer les segments de texte qui présentent un degré élevé de similitude avec la question de l'utilisateur. La valeur par défaut est 3. Plus la valeur est élevée, plus les segments de texte pertinents seront rappelés.

  Seuil de score : le seuil de similarité pour le filtrage des fragments de texte, seuls les fragments de texte dépassant le score défini seront rappelés, la valeur par défaut est de 0,5. Plus la valeur est élevée, plus la similarité entre le texte et la question est importante, plus le nombre de textes à rappeler est faible, et le résultat sera relativement plus précis.

Une fois la configuration établie, vous pouvez établir une connexion avec l'API externe de la base de connaissances.

6. tester les connexions et les rappels de bases de connaissances externes

Après avoir établi une connexion avec une base de connaissances externe, le développeur peut "Test de rappel". Imaginer des mots-clés susceptibles de poser problème dans l'aperçu des segments de texte extraits de la base de connaissances AWS Bedrock.

Si vous n'êtes pas satisfait des résultats du rappel, vous pouvez essayer de modifier les paramètres de rappel ou d'ajuster vous-même les paramètres de recherche de la base de connaissances AWS Bedrock.

problèmes courants

Que faire si j'obtiens une erreur de connexion à l'API externe de la base de connaissances ?

Vous trouverez ci-dessous les codes d'erreur et les solutions correspondantes :

Spécification de l'API de la base de connaissances externe

point de départ ou point d'arrivée (dans les histoires, etc.)

POST <your-endpoint>/retrieval

en-tête de la demande

Cette API est utilisée pour se connecter à des bases de connaissances gérées indépendamment au sein d'une équipe. Pour plus d'informations sur la manière de procéder, voir Connexion à des bases de connaissances externes.

peut être trouvée dans l'en-tête de la requête HTTP, dans la section Authorization à l'aide de l'option API-Key pour authentifier les autorisations. La logique d'authentification est définie par vous dans l'API de récupération, comme indiqué ci-dessous :

Authorization: Bearer {API_KEY}

demandeur

La demande accepte les données dans le format JSON suivant :

retrieval_setting contient les clés suivantes :

Exemple de demande

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
}
}

organe de réponse

Si l'opération est réussie, le service renvoie une réponse HTTP 200 avec les données suivantes au format JSON :

records est une liste d'objets contenant les clés suivantes :

Exemple de réponse

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 应用程序的创新引擎"
}
]
}

incorrect

Si l'opération échoue, le service renvoie le message d'erreur suivant (au format JSON) :

error_code Type d'attribut :

Code d'état HTTP

• AccessDeniedException : Absence de droits d'accès. (Code d'état HTTP : 403)
• InternalServerException : Erreur interne du serveur. (Code d'état HTTP : 500)