Tutorial de Dify sobre la conexión a bases de conocimiento externas

Para facilitar la distinción, este documento Dify Los depósitos de conocimientos externos a la Plataforma se denominan colectivamente "depósitos de conocimientos externos".

Función Introducción

La funcionalidad de la base de conocimientos integrada en Dify y los mecanismos de recuperación de texto pueden no satisfacer las necesidades de algunos desarrolladores avanzados que pueden requerir un control más preciso sobre los resultados de recuperación de texto.

Algunos equipos optan por la autoinvestigación RAG algoritmos y mantener un sistema de recuperación de texto de forma independiente, o utilizar un servicio de base de conocimientos proporcionado por un proveedor en la nube (por ejemplo, AWS Bedrock).

Dify, como plataforma abierta de desarrollo de aplicaciones LLM, quiere dar más opciones a los desarrolladores.

Dify puede conectarse a bases de conocimiento externas a través de la función "Conectar a bases de conocimiento externas". Esto permite a las aplicaciones de IA acceder a más fuentes de información.

En concreto, las ventajas son las siguientes:

• Dify puede acceder directamente al texto alojado en la base de conocimientos del proveedor de la nube, eliminando la necesidad de que los desarrolladores copien el contenido en la base de conocimientos de Dify.
• Dify puede acceder directamente al texto procesado algorítmicamente en la base de conocimientos autoconstruida, y los desarrolladores sólo tienen que centrarse en optimizar el mecanismo de recuperación de la información para mejorar la precisión de la recuperación.
• En comparación con el uso directo de los servicios de base de conocimientos de los proveedores de la nube, Dify proporciona capacidades de integración de la capa de aplicaciones más flexibles, lo que facilita a los desarrolladores la creación de diversas aplicaciones de IA.

La siguiente figura ilustra el principio de conexión a una base de conocimientos externa:

Pasos de conexión

1. Establecimiento de una API de base de conocimientos externa compatible

Asegúrese de leer cuidadosamente la especificación API de la Base de Conocimiento Externa escrita por Dify antes de configurar su servicio API.

2. API de bases de conocimiento externas asociadas

Tenga en cuenta que Dify actualmente sólo soporta la recuperación de bases de conocimiento externas, no su modificación. Los desarrolladores necesitan mantener bases de conocimiento externas por su cuenta.

Vaya a la página "Base de conocimientos", haga clic en "API de base de conocimientos externa" en la esquina superior derecha y, a continuación, haga clic en "Añadir API de base de conocimientos externa".

Siga las instrucciones de la página para rellenar el formulario:

• Nombre de la base de conocimientos: Puede personalizarse para diferenciar entre distintas API de bases de conocimiento externas.
• Dirección de la interfaz API: La dirección del enlace a la base de conocimientos externa, por ejemplo api-endpoint/retrieval. Consulte la API de la base de conocimientos externa para obtener instrucciones detalladas.
• Clave API: La clave de conexión para la base de conocimientos externa, véase API de base de conocimientos externa para más detalles.

3. Conexión a bases de conocimiento externas

En la pantalla "Base de conocimientos", haga clic en "Conectar con base de conocimientos externa" en "Añadir base de conocimientos" para acceder a la pantalla de configuración de parámetros.

Rellene los siguientes parámetros:

• Nombre y descripción de la base de conocimientos
• API externa de la base de conocimientos: Seleccione la API de la base de conocimiento externa asociada en el paso 2. Dify llamará al contenido de texto de la base de conocimiento externa a través de la conexión API.
• ID de la base de conocimientos externa: Especifique el ID de la base de conocimientos externa a la que se asociará, consulte API de base de conocimientos externa para obtener más detalles.
• Ajusta la configuración de la rellamada:
  • Arriba K: Cuanto mayor sea el valor, más fragmentos de texto se recuperarán. Se recomienda empezar a experimentar con valores más pequeños e ir aumentándolos gradualmente hasta encontrar el equilibrio óptimo.
  • Umbral de puntuación: Cuanto mayor sea el valor, más relevantes serán los segmentos de texto recuperados para la pregunta, pero el número disminuye. Se recomienda empezar con un valor más alto e ir reduciéndolo gradualmente para obtener una cantidad suficiente de texto relevante.

4. Prueba de conexiones y rellamadas

Una vez establecida la conexión, puede simular las palabras clave del problema en la "Prueba de recuperación" y previsualizar los fragmentos de texto recuperados de la base de conocimientos externa. Si no está satisfecho con los resultados, puede intentar modificar los parámetros de recuperación o ajustar la configuración de búsqueda de la base de conocimientos externa.

5. Integración en las aplicaciones

• Aplicación tipo Chatbot / Agente: En el Contexto de la página Disposición, seleccione la pantalla con el icono EXTERNAL Etiquetado base de conocimientos externa.

• Aplicación tipo Chatflow / Workflow: Añada el nodo Knowledge Retrieval y seleccione el nodo con el icono EXTERNAL Etiquetado base de conocimientos externa.

6. Gestión de la base de conocimientos externa

En la página Base de conocimientos, la ficha Base de conocimientos externa tendrá el siguiente texto en la esquina superior derecha de la ficha EXTERNAL Pestaña. Introduzca la base de conocimientos que desea modificar y haga clic en "Configuración" para modificarla:

• Nombre y descripción de la base de conocimientos
• Alcance de la visibilidad ("Sólo yo", "Todos los miembros del equipo" y "Algunos miembros del equipo"). Los miembros sin permisos no pueden acceder a la base de conocimientos.
• Ajustes de recuperación (Top K y Umbrales de puntuación)

Nota: No es posible modificar la API de la Base de Conocimientos Externa asociada y el ID de Conocimiento Externo, si desea modificarlos, por favor asocie una nueva API de la Base de Conocimientos Externa y vuelva a conectarla.

Ejemplo de conexión: ¿Cómo me conecto a la base de conocimientos de AWS Bedrock?

Este documento describirá cómo la plataforma Dify puede conectarse a la base de conocimientos AWS Bedrock a través de una API de base de conocimientos externa, lo que permite a las aplicaciones de IA dentro de la plataforma Dify acceder directamente al contenido almacenado en la base de conocimientos AWS Bedrock, ampliando el acceso a nuevas fuentes de información.

preposicionamiento

• Base de conocimientos de AWS Bedrock
• Dify SaaS Services / Dify Edición Comunidad
• Conceptos básicos de desarrollo de API de backend

1. Regístrese y cree AWS Bedrock Knowledge Base

Visite AWS Bedrock para crear un servicio de base de conocimientos.

2. Construir servicios API back-end

La plataforma de Dify aún no puede conectarse directamente a la base de conocimientos de AWS Bedrock, por lo que el equipo de desarrollo debe consultar la definición de la API de Dify sobre la conexión a la base de conocimientos externa y crear manualmente el servicio API back-end para establecer la conexión con AWS Bedrock. Por favor, consulte el diagrama de arquitectura:

Puede consultar los 2 archivos de código siguientes para crear la API del servicio 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
        }

En este proceso, puede crear la dirección de la interfaz API y la clave API para la autenticación y las conexiones posteriores.

3. Obtener un ID de la base de conocimientos de AWS Bedrock

Inicie sesión en el backend de AWS Bedrock Knowledge y obtenga el ID de la Base de Conocimiento que se ha creado. este parámetro se utilizará en los pasos posteriores para conectarse a la plataforma de Dify.

4. API de conocimiento externo vinculado

Ir a la plataforma Dify "Base de conocimientos" haga clic en la esquina superior derecha de la página "API externa de la base de conocimientos"Alégrate. "Añadir API de base de conocimientos externa".

Siga las instrucciones de la página y rellene lo siguiente en orden:

• El nombre de la base de conocimiento, permitiendo un nombre personalizado para distinguir entre las diferentes APIs de conocimiento externas conectadas dentro de la plataforma Dify;
• La dirección de la interfaz API, la dirección de conexión de la base de conocimientos externa, puede personalizarse en el segundo paso. Ejemplo api-endpoint/retrieval.;
• API Key, la clave de conexión a la base de conocimientos externa, puede personalizarse en el segundo paso.

5. Conexión a bases de conocimiento externas

salir para "Base de conocimientos" haga clic en la tarjeta Añadir base de conocimientos situada debajo de la página "Conexión a bases de conocimiento externas" Salta a la página de configuración de parámetros.

Rellene los siguientes parámetros:

• Nombre y descripción de la base de conocimientos
• API externa de la base de conocimientosSeleccione la API de la base de conocimientos externa asociada en el paso 4
• ID de la base de conocimientos externaIntroduzca el ID de la base de conocimientos de AWS Bedrock obtenido en el paso 3
• Ajuste de la configuración de recuperaciónTop K: Cuando un usuario inicia una pregunta, se solicitará una API de conocimiento externa para obtener segmentos de contenido altamente relevantes. Este parámetro se utiliza para filtrar los segmentos de texto que tienen un alto grado de similitud con la pregunta del usuario. El valor por defecto es 3. Cuanto mayor sea el valor, más segmentos de texto relevantes se recuperarán.

  Umbral de puntuación: umbral de similitud para el filtrado de fragmentos de texto; sólo se recuperarán los fragmentos de texto que superen la puntuación establecida; el valor por defecto es 0,5. Cuanto mayor sea el valor, mayor será la similitud entre el texto y la pregunta, menor será el número de textos que se espera recuperar y el resultado será relativamente más preciso.

Una vez configurado, puede establecer una conexión con la API externa de Knowledge Base.

6. Comprobación de las conexiones y recuperaciones de bases de conocimiento externas

Tras establecer una conexión con una base de conocimientos externa, el desarrollador puede "Prueba de retirada". Muestre posibles palabras clave del problema en la vista previa de los segmentos de texto recuperados de la base de conocimientos de AWS Bedrock.

Si no está satisfecho con los resultados de la recuperación, puede intentar modificar los parámetros de recuperación o ajustar usted mismo la configuración de búsqueda de la Base de conocimientos de AWS Bedrock.

problemas comunes

¿Qué ocurre si obtengo un error al conectarme a la API externa de Knowledge Base?

A continuación se indican los códigos de error y las soluciones correspondientes:

Especificación de la API de la base de conocimientos externa

punto de partida o de llegada (en historias, etc.)

POST <your-endpoint>/retrieval

encabezado de la solicitud

Esta API se utiliza para conectarse a bases de conocimientos mantenidas de forma independiente dentro de un equipo. Para obtener más información sobre cómo hacerlo, consulte Conexión a bases de conocimientos externas.

puede encontrarse en la cabecera de la petición HTTP Authorization campos utilizando el API-Key para autenticar permisos. Usted define la lógica de autenticación en la API de recuperación, como se muestra a continuación:

Authorization: Bearer {API_KEY}

solicitante

La solicitud acepta datos en el siguiente formato JSON:

retrieval_setting contiene las siguientes claves:

Ejemplo de solicitud

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

cuerpo de la respuesta

Si la operación tiene éxito, el servicio devuelve una respuesta HTTP 200 con los siguientes datos en formato JSON:

records es una lista de objetos que contiene las siguientes claves:

Ejemplo de respuesta

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

incorrecto

Si la operación falla, el servicio devuelve el siguiente mensaje de error (en formato JSON):

error_code Tipo de atributo:

Código de estado HTTP

• Excepción de acceso denegado: Falta de derechos de acceso. (Código de estado HTTP: 403)
• InternalServerException: Error interno del servidor. (Código de estado HTTP: 500)