Usar uma base de conhecimento em um workflow

Um bloco Knowledge pesquisa uma base de conhecimento e entrega os trechos correspondentes a um bloco posterior, para que um Agent responda a partir dos seus documentos, e não apenas da memória do modelo. Funciona como pedir a um bibliotecário os extratos mais relevantes sobre um tema: você faz uma pergunta e recebe uma lista ranqueada, com a fonte identificada. Esta página cobre a pesquisa, o refinamento por tags, o reranking e a leitura dos resultados.

Neste workflow, o bloco Knowledge pesquisa uma base de documentação de produto usando a pergunta do cliente, e o Agent responde com base nos trechos retornados.

Search

Um bloco Knowledge configurado como Search recebe uma consulta, compara com os chunks de uma base e retorna as correspondências mais próximas. (O bloco também gerencia documentos e chunks, mas é o Search que um workflow usa para recuperar contexto.) Você aponta o bloco para uma base de conhecimento e informa uma consulta; no nosso exemplo, a consulta é <start.input>, a pergunta do cliente.

A pesquisa é semântica, não por palavra-chave. O bloco transforma a consulta em um vetor e encontra os chunks cujo significado é mais próximo, então "prazos de reembolso" pode corresponder a um trecho que diz "processamos devoluções em até 14 dias", sem nenhuma palavra em comum.

Number of Results (topK) define quantos chunks voltam, 10 por padrão. Valores menores dão ao agente um conjunto enxuto e focado; valores maiores ampliam o alcance, ao custo de ruído e tokens.

Você também pode pesquisar por tags, no lugar de uma consulta ou junto com ela:

Tag Filters

Os Tag Filters restringem uma pesquisa aos documentos que carregam tags específicas. Cada filtro tem três partes: uma Tag (uma tag definida na base, como Department), um Operator (equals, contains, greater than e outros, conforme o tipo da tag) e um Value a ser comparado.

No nosso exemplo, adicionar Department equals "Billing" faz a pesquisa considerar apenas documentos de cobrança. Adicione mais filtros com o botão +; múltiplos filtros combinam com AND, então um documento precisa satisfazer todos eles. O valor de um filtro pode ser um texto fixo ou uma referência como <start.department>, de modo que o escopo mude a cada execução.

Os filtros rodam antes da comparação vetorial, então tornam a pesquisa mais precisa e mais barata. Veja Tags e filtragem para a lista completa de operadores por tipo de tag.

Retrieval Mode

Retrieval Mode é uma configuração avançada que escolhe como as correspondências são encontradas.

A pesquisa semântica é forte em paráfrases e fraca em cadeias literais: um código de erro, uma chave de ticket como PROJ-1234, um SKU ou o nome raro de um produto carregam pouco significado para o modelo, então o chunk que os contém pode não ficar no topo. O Hybrid adiciona uma passada por palavra-chave que corresponde a esses tokens exatamente e depois mescla as duas listas, para que um chunk encontrado por qualquer um dos sinais possa aparecer.

Ative quando seus documentos forem cheios de identificadores, códigos ou nomes que as pessoas pesquisam literalmente. Deixe desativado em bases com muito texto corrido, onde as perguntas são feitas em linguagem natural. O Hybrid não custa chamadas de API extras — a passada por palavra-chave roda inteiramente no banco de dados.

Rerank Results

Rerank Results é uma segunda passada opcional. A pesquisa vetorial ranqueia por similaridade bruta; o reranking reavalia as melhores correspondências com um modelo dedicado de relevância (os modelos de rerank da Cohere) e as reordena, o que apura a ordenação quando a melhor resposta não é o vetor literalmente mais próximo.

Deixe desativado na maioria das pesquisas. Ative quando a recuperação traz aproximadamente os documentos certos, mas na ordem errada. Quando habilitado, você escolhe um Rerank Model; implantações com auto-hospedagem também precisam fornecer uma chave de API da Cohere.

Chunks retornados

A operação Search produz uma saída armazenada sob o nome do bloco, como qualquer outro bloco. Seu valor principal é results: um array com os chunks correspondentes, ranqueados do melhor para o pior. Um bloco posterior lê esse valor por referência, por exemplo <knowledge.results>.

Cada resultado do array é um objeto com estes campos:

A saída também traz query (o texto pesquisado) e totalResults (a contagem).

Para fundamentar uma resposta, ligue o bloco Knowledge antes de um bloco Agent e referencie os chunks no prompt do Agent com <knowledge.results>. O agente lê o content de cada resultado e pode citar documentName e sourceUrl. Veja como os blocks referenciam saídas para entender como um block lê a saída de outro pelo nome.

Quando a recuperação parece errada

Quando a resposta do agente sai errada, a causa geralmente está na recuperação, não no agente. Leia a saída do bloco Knowledge nos logs de execução e verifique os chunks que ele realmente retornou:

• Nenhum resultado, ou documentos errados. Um tag filter pode estar excluindo o que você quer, ou os documentos ainda não foram indexados. Um documento só é pesquisável quando o status de processamento é completed; enquanto estiver em pending, processing ou failed, seus chunks não aparecem.
• Notas de similaridade baixas em todos os resultados. A consulta está vaga demais, ou a informação simplesmente não está na base. Reescreva a consulta para se aproximar de como os documentos formulam as coisas.
• Documentos certos, ordem errada. Ative Rerank Results, ou aumente Number of Results para que o chunk relevante seja incluído.
• Um código, ID ou nome exato não é encontrado. Mude Retrieval Mode para Hybrid, para que uma passada por palavra-chave rode junto com a semântica.

Veja depuração da recuperação para o caminho completo de diagnóstico, e estratégias de chunking para entender como os limites dos chunks moldam o que uma pesquisa pode retornar.

Próximos passos