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:
código de erro | falso | método para resolver um problema |
---|---|---|
1001 | Formato de cabeçalho de autorização inválido | Verificar o formato do cabeçalho de autorização da solicitação |
1002 | validar anomalias | Verifique se a chave de API está correta |
2001 | A base de conhecimento não existe | Verificação da base de conhecimento externa |
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:
causalidade | campo obrigatório | tipologia | descrições | exemplo de valor |
---|---|---|---|---|
knowledge_id | ser | string (ciência da computação) | ID exclusiva da base de conhecimento | AAA-BBB-CCC |
consulta | ser | string (ciência da computação) | Consultas de usuários | O que é a Dify? |
configuração de recuperação | ser | namorado | Parâmetros de recuperação de conhecimento | veja abaixo |
configuração de recuperação
contém as seguintes chaves:
causalidade | campo obrigatório | tipologia | descrições | exemplo de valor |
---|---|---|---|---|
top_k | ser | inteiro (matemática) | Número máximo de resultados de pesquisa | 5 |
limite de pontuação | ser | ponto flutuante | Limite de pontuação para relevância dos resultados para a consulta, intervalo: 0~1 | 0.5 |
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:
causalidade | campo obrigatório | tipologia | descrições | exemplo de valor |
---|---|---|---|---|
registros | ser | lista de objetos | Lista de registros consultados na base de conhecimento | veja abaixo |
registros
é uma lista de objetos que contém as seguintes chaves:
causalidade | campo obrigatório | tipologia | descrições | exemplo de valor |
---|---|---|---|---|
conteúdo | ser | string (ciência da computação) | Blocos de texto na base de conhecimento | Dify: plataforma de desenvolvimento de aplicativos GenAI |
pontuação | ser | ponto flutuante | Pontuação de correlação entre os resultados e a consulta, intervalo: 0~1 | 0.98 |
título | ser | string (ciência da computação) | Título do documento | Introdução à Dify |
metadados | entupido | JSON | Atributos de metadados e seus valores para documentos na fonte de dados | Veja o exemplo |
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):
causalidade | campo obrigatório | tipologia | descrições | exemplo de valor |
---|---|---|---|---|
código_de_erro | ser | inteiro (matemática) | código de erro | 1001 |
mensagem_de_erro | ser | string (ciência da computação) | Descrição da exceção de API | Formato de cabeçalho de autorização inválido. |
código_de_erro
Tipo de atributo:
codificação | descrições |
---|---|
1001 | Formato de cabeçalho de autorização inválido |
1002 | Falha na autorização |
2001 | A base de conhecimento não existe |
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)