Tutorial da Dify sobre como se conectar a bases de conhecimento externas

Para facilitar a distinção, este documento Dify Os repositórios de conhecimento fora da Plataforma são coletivamente chamados de "repositórios de conhecimento externos".

Introdução à função

A funcionalidade integrada da base de conhecimento e os mecanismos de recuperação de texto da Dify podem não atender às necessidades de alguns desenvolvedores avançados que podem exigir um controle mais preciso sobre os resultados da recuperação de texto.

Algumas equipes optam pela autopesquisa RAG algoritmos e manter um sistema de recuperação de texto de forma independente ou usar um serviço de base de conhecimento fornecido por um provedor de nuvem (por exemplo, AWS Bedrock).

A Dify, como uma plataforma aberta de desenvolvimento de aplicativos LLM, quer dar mais opções aos desenvolvedores.

A Dify pode se conectar a bases de conhecimento externas por meio do recurso "Connect to External Knowledge Bases". Isso dá aos aplicativos de IA acesso a mais fontes de informação.

Especificamente, há as seguintes vantagens:

• A Dify pode acessar diretamente o texto hospedado na base de conhecimento do provedor de nuvem, eliminando a necessidade de os desenvolvedores copiarem o conteúdo para a base de conhecimento da Dify.
• A Dify pode acessar diretamente o texto processado por algoritmos na base de conhecimento autoconstruída, e os desenvolvedores só precisam se concentrar na otimização do mecanismo de recuperação de informações para melhorar a precisão da recuperação.
• Em comparação com o uso direto dos serviços de base de conhecimento dos fornecedores de nuvem, a Dify oferece recursos mais flexíveis de integração da camada de aplicativos, facilitando aos desenvolvedores a criação de diversos aplicativos de IA.

A figura a seguir ilustra o princípio de conexão com uma base de conhecimento externa:

Etapas de conexão

1. estabelecimento de uma API de base de conhecimento externa compatível

Certifique-se de ler atentamente a especificação da API da Base de Conhecimento Externa escrita pela Dify antes de configurar seu serviço de API.

2. APIs de bases de conhecimento externas associadas

Observe que, no momento, a Dify suporta apenas a recuperação de bases de conhecimento externas, não a modificação delas. Os desenvolvedores precisam manter as bases de conhecimento externas por conta própria.

Vá para a página "Knowledge Base", clique em "External Knowledge Base API" no canto superior direito e, em seguida, clique em "Add External Knowledge Base API".

Siga as instruções da página para preencher o formulário:

• Nome da base de conhecimento: Pode ser personalizado para diferenciar entre diferentes APIs de bases de conhecimento externas.
• Endereço da interface da API: O endereço do link para a base de conhecimento externa, por exemplo. ponto final da API/recuperação. Consulte a API da Base de Conhecimento Externa para obter instruções detalhadas.
• Chave de API: A chave de conexão para a base de conhecimento externa, consulte API da base de conhecimento externa para obter detalhes.

3. conexão com bases de conhecimento externas

Na tela "Knowledge Base" (Base de conhecimento), clique em "Connect to external knowledge base" (Conectar à base de conhecimento externa) em "Add knowledge base" (Adicionar base de conhecimento) para entrar na tela de configuração de parâmetros.

Preencha os seguintes parâmetros:

• Nome e descrição da base de conhecimento
• API da base de conhecimento externa: Selecione a API da base de conhecimento externa associada na etapa 2. A Dify chamará o conteúdo de texto da base de conhecimento externa por meio da conexão da API.
• ID da base de conhecimento externa: Especifique a ID da base de conhecimento externa a ser associada; consulte API da base de conhecimento externa para obter detalhes.
• Ajustar as configurações de chamada:
  • Top K: Quanto maior o valor, mais fragmentos de texto são recuperados. Recomenda-se começar a experimentar com valores menores e aumentá-los gradualmente até encontrar o equilíbrio ideal.
  • Limite de pontuação: Quanto maior o valor, mais relevantes são os segmentos de texto recuperados para a pergunta, mas o número diminui. Recomenda-se começar com um valor mais alto e diminuí-lo gradualmente para obter uma quantidade suficiente de texto relevante.

4. teste as conexões e os recalls

Depois que a conexão for estabelecida, você poderá simular as palavras-chave do problema em "Recall Test" e visualizar os fragmentos de texto recuperados da base de conhecimento externa. Se não estiver satisfeito com os resultados, você pode tentar modificar os parâmetros de recuperação ou ajustar as configurações de pesquisa da base de conhecimento externa.

5. integração nos aplicativos

• Aplicativo do tipo chatbot/agente: No Contexto da página Arranjo, selecione a tela com o ícone EXTERNO Base de conhecimento externa com tags.

• Aplicativo do tipo fluxo de bate-papo/fluxo de trabalho: Adicione o nó Knowledge Retrieval e selecione o nó com o símbolo EXTERNO Base de conhecimento externa com tags.

6. gerenciar a base de conhecimento externa

Na página Base de conhecimento, o cartão Base de conhecimento externa terá o seguinte texto no canto superior direito do cartão EXTERNO Guia. Digite a base de conhecimento que deseja modificar e clique em "Settings" (Configurações) para modificá-la:

• Nome e descrição da base de conhecimento
• Escopo de visibilidade ("Somente eu", "Todos os membros da equipe" e "Alguns membros da equipe"). Os membros sem permissões não podem acessar a base de conhecimento.
• Configurações de recall (limiares de Top K e Score)

Observação: Não é possível modificar a API da Base de Conhecimento Externa e o ID do Conhecimento Externo associados. Se quiser modificá-los, associe uma nova API da Base de Conhecimento Externa e reconecte-a.

Exemplo de conexão: Como faço para me conectar à base de conhecimento do AWS Bedrock?

Este documento descreverá como a plataforma Dify pode ser conectada à AWS Bedrock Knowledge Base por meio de uma API de base de conhecimento externa, permitindo que os aplicativos de IA na plataforma Dify acessem diretamente o conteúdo armazenado na AWS Bedrock Knowledge Base, expandindo o acesso a novas fontes de informações.

pré-posicionamento

• Base de conhecimento do AWS Bedrock
• Serviços SaaS da Dify / Dify Community Edition
• Noções básicas de desenvolvimento de API de back-end

1. registre-se e crie a base de conhecimento do AWS Bedrock

Visite o AWS Bedrock para criar um serviço de Base de Conhecimento.

2. criar serviços de API de back-end

A plataforma Dify ainda não pode se conectar diretamente à Base de Conhecimento do AWS Bedrock; é necessário que a equipe de desenvolvimento consulte a definição da API da Dify sobre a conexão da base de conhecimento externa e crie manualmente o serviço de API de back-end para estabelecer a conexão com o AWS Bedrock. Consulte o diagrama de arquitetura:

Você pode consultar os dois arquivos de código a seguir para criar a API do serviço de backend.

conhecimento.py

from flask import request
from flask_restful import Resource, reqparse

de bedrock.knowledge_service import ExternalDatasetService

class BedrockRetrievalApi(Resource).
    # url : /retrieval
    def post(self): parser = reqparse
        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()

        Verificação de autorização #
        auth_header = request.headers.get("Authorisation")
        se " " não estiver no auth_header.
            return {
                "error_code": 1001, "error_msg": 1001, "error_code": 1001, "error_msg": 1001
                "error_msg": "Formato de cabeçalho de autorização inválido. Formato 'Bearer ' esperado".
            }, 403
        auth_scheme, auth_token = auth_header.split(None, 1)
        auth_scheme = auth_scheme.lower()
        se auth_scheme ! = "bearer".
            return {
                "error_code": 1001, "error_msg": 1001
                "error_msg": "Formato de cabeçalho de autorização inválido. Formato 'Bearer ' esperado".
            }, 403
        if auth_token: "Formato 'Bearer ' esperado.
            # processe sua lógica de autorização aqui
            passe

        # Chame o conhecimento recuperação resultado = ExternalDatasetService.knowledge_retrieval()
        resultado = ExternalDatasetService.knowledge_retrieval(
            args["retrieval_setting"], args["query"], args["knowledge_id"]
        )
        return result, 200

knowledge_service.py

importar boto3

class ExternalDatasetService.
    @staticmethod
    def knowledge_retrieval(retrieval_setting: dict, query: str, knowledge_id: str):
        # get bedrock client
        cliente = boto3.client(
            "bedrock-agent-runtime",
            aws_secret_access_key="AWS_SECRET_ACCESS_KEY",
            aws_access_key_id="AWS_ACCESS_KEY_ID",
            Exemplo de #: us-east-1
            region_name="AWS_REGION_NAME",
        )
        Recuperação de conhecimento externo do # fetch
        response = client.retrieve(
            knowledgeBaseId=knowledge_id,
            retrievalConfiguration={
                "vectorSearchConfiguration": {"numberOfResults": retrieval_setting.get("top_k"), "overrideSearchType": "HYBRID"}
            },
            retrievalQuery={"text": query},
        )
        Resposta de análise do #
        resultados = []
        if response.get("ResponseMetadata") and response.get("ResponseMetadata").get("HTTPStatusCode") == 200:: if response.get("ResponseResults"): if response.get("ResponseMetadata").get("HTTPStatusCode") == 200
            if response.get("retrievalResults")::
                retrieval_results = response.get("retrievalResults")
                for retrieval_result in retrieval_results: # filtrar os resultados com
                    # filtra os resultados com pontuação menor que o limite
                    if retrieval_result.get("score") < retrieval_setting.get("score_threshold", .0):: # filtrar os resultados com pontuação menor que o limite
                        continuar
                    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
        }

Nesse processo, você pode criar o endereço da interface da API e a chave da API para autenticação e conexões subsequentes.

3. obtenha um ID da base de conhecimento do AWS Bedrock

Faça login no back-end do AWS Bedrock Knowledge e obtenha a ID da Base de Conhecimento que foi criada. Esse parâmetro será usado nas etapas subsequentes para se conectar à plataforma Dify.

4. API de conhecimento externo vinculado

Acesse a plataforma Dify "Base de conhecimento" clique no canto superior direito da página "API da base de conhecimento externa"Descontraia-se. "Adicionar API de base de conhecimento externa".

Siga as instruções da página e preencha os seguintes campos em ordem:

• O nome da base de conhecimento, permitindo um nome personalizado para distinguir entre as diferentes APIs de conhecimento externo conectadas na plataforma Dify;
• O endereço da interface API, o endereço de conexão da base de conhecimento externa, pode ser personalizado na segunda etapa. Exemplo ponto final da API/recuperação.;
• API Key, a chave de conexão da base de conhecimento externa, pode ser personalizada na segunda etapa.

5. conexão com bases de conhecimento externas

partir para "Base de conhecimento" página, clique no cartão Adicionar base de conhecimento abaixo do "Conexão com bases de conhecimento externas" Ir para a página de configuração de parâmetros.

Preencha os seguintes parâmetros:

• Nome e descrição da base de conhecimento
• API da base de conhecimento externaSelecione a API da base de conhecimento externa associada na etapa 4
• ID da base de conhecimento externaPreencha o ID da base de conhecimento do AWS Bedrock obtido na etapa 3
• Ajuste das configurações de rechamadaTop K: quando um usuário inicia uma pergunta, uma API de conhecimento externo é solicitada para obter segmentos de conteúdo altamente relevantes. Esse parâmetro é usado para filtrar segmentos de texto que tenham um alto grau de similaridade com a pergunta do usuário. O valor padrão é 3. Quanto maior o valor, mais segmentos de texto relevantes serão recuperados.

  Limite de pontuação: o limite de similaridade para a filtragem de fragmentos de texto; somente os fragmentos de texto que excederem a pontuação definida serão recuperados; o valor padrão é 0,5. Quanto maior o valor, maior a similaridade entre o texto e a pergunta, menor o número de textos que se espera recuperar e o resultado será relativamente mais preciso.

Depois de configurado, você pode estabelecer uma conexão com a API externa da Base de Conhecimento.

6. teste de conexões e recuperações de bases de conhecimento externas

Depois de estabelecer uma conexão com uma base de conhecimento externa, o desenvolvedor pode "Teste de recall". Simule possíveis palavras-chave de problemas na visualização de segmentos de texto recuperados da Base de Conhecimento do AWS Bedrock.

Se não estiver satisfeito com os resultados da recuperação, você pode tentar modificar os parâmetros de recuperação ou ajustar as configurações de pesquisa da AWS Bedrock Knowledge Base por conta própria.

problemas comuns

E se eu receber um erro ao me conectar à API externa da Base de Conhecimento?

Abaixo estão os códigos de erro e as soluções correspondentes:

Especificação da API da base de conhecimento externa

ponto de partida ou ponto de chegada (em histórias etc.)

POST /retrieval

cabeçalho da solicitação

Essa API é usada para conectar-se a bases de conhecimento mantidas de forma independente dentro de uma equipe. Para obter mais orientações sobre como fazer isso, consulte Conexão com bases de conhecimento externas.

pode ser encontrado no cabeçalho da solicitação HTTP Autorização usando os campos Chave API para autenticar as permissões. A lógica de autenticação é definida por você na API de recuperação, conforme mostrado abaixo:

Autorização: Portador {API_KEY}

solicitante

A solicitação aceita dados no seguinte formato JSON:

configuração de recuperação contém as seguintes chaves:

Exemplo de uma solicitação

POST /retrieval HTTP/1.1
Content-Type: application/json
Autorização: Portador your-api-key
{
"knowledge_id": "your-knowledge-id",

"retrieval_setting": {
"top_k": 2, "score_threshold": {
"score_threshold": 0,5
}
}

corpo da resposta

Se a operação for bem-sucedida, o serviço retornará uma resposta HTTP 200 com os seguintes dados no formato JSON:

registros é uma lista de objetos que contém as seguintes chaves:

Exemplo de resposta

HTTP/1.1 200
Content-Type: application/json
{
"records": [
{
"metadata": {

"description": "documento de conhecimento difícil"
},
"score": 0,98, "title": "knowledge.txt".
"title": "knowledge.txt", "content": "Este é um documento externo".
"content": "Este é o documento de conhecimento externo".
},
{
"metadata": {
"path": "s3://dify/introduce.txt", {
"description": "Introducing dify."
},

"title": "introduce.txt", "content": "Aplicativos GenAI": "Aplicativos GenAI".
"content": "Mecanismo de inovação para aplicativos de GenAI"
}
]
}

incorreto

Se a operação falhar, o serviço retornará a seguinte mensagem de erro (no formato JSON):

código_de_erro Tipo de atributo:

Código de status HTTP

• AccessDeniedException: Falta de direitos de acesso. (Código de status HTTP: 403)
• InternalServerException: Erro interno do servidor. (Código de status HTTP: 500)