Um bloco Knowledge busca em uma base de conhecimento e entrega os trechos correspondentes a um bloco seguinte, para que um Agent responda a partir dos seus documentos em vez de depender só da memória do modelo. Funciona como pedir a um bibliotecário os trechos mais relevantes sobre um tema: você dá uma pergunta e recebe de volta uma lista ranqueada e com fonte. Esta página cobre busca, restrição por tags, reranking e leitura dos resultados.
Neste workflow, o bloco Knowledge busca em uma base de docs do produto pela pergunta do cliente, e o Agent responde a partir dos trechos que ele devolve.
Busca
Um bloco Knowledge configurado em Search recebe uma query, compara com os chunks de uma base e devolve as correspondências mais próximas. (O bloco também pode gerenciar documentos e chunks, mas Search é o que um workflow usa para recuperar contexto.) Você aponta para uma base de conhecimento e dá uma query; no nosso exemplo a query é <start.input>, a pergunta do cliente.
A busca é semântica, não por palavra-chave. O bloco transforma a query em um vetor e encontra os chunks cujo significado está mais próximo, então "prazos de reembolso" pode bater em um trecho que diz "processamos devoluções em até 14 dias" sem palavras em comum.
Number of Results (topK) define quantos chunks voltam, 10 por padrão. Menos dá ao agente um conjunto enxuto e focado; mais amplia a rede à custa de ruído e tokens.
Você também pode buscar por tags, em vez de ou junto com uma query:
| O que você fornece | O que faz |
|---|---|
| Só query | Busca semântica em todos os documentos da base. O padrão. |
| Só tags | Devolve documentos que batem nas tags, sem ranqueamento por significado. |
| Query e tags | As tags restringem o conjunto de documentos primeiro; depois a busca semântica roda dentro dele. O mais preciso. |
Tag Filters
Tag Filters restringem a busca a documentos com tags específicas. Cada filtro tem três partes: uma Tag (definida na base, como Department), um Operator (equals, contains, greater than e outros conforme o tipo da tag) e um Value a combinar.
No nosso exemplo, adicionar Department equals "Billing" faz a busca considerar só documentos de billing. Adicione mais filtros com o botão +; vários filtros combinam com AND, então o documento precisa bater em todos. O valor de um filtro pode ser uma string fixa ou uma referência como <start.department>, para o escopo mudar por execução.
Os filtros rodam antes da comparação vetorial, então tornam a busca mais precisa e mais barata. Veja Tags e filtragem para a lista completa de operadores por tipo de tag.
Rerank Results
Rerank Results é uma segunda passagem opcional. A busca vetorial ranqueia por similaridade bruta; o reranking reavalia os melhores matches com um modelo de relevância dedicado (modelos de rerank da Cohere) e reordena, o que afia a ordem quando a melhor resposta não é o vetor literalmente mais próximo.
Deixe desligado na maioria das buscas. Ligue quando a recuperação devolve documentos mais ou menos certos, mas na ordem errada. Com ele ligado, você escolhe um Rerank Model; deploys self-hosted também fornecem uma chave de API da Cohere.
Chunks recuperados
A operação Search produz uma saída guardada sob o nome do bloco, como qualquer outro bloco. O valor principal é results: um array dos chunks encontrados, do melhor para o pior. Um bloco seguinte lê por referência, por exemplo <knowledge.results>.
Cada resultado no array é um objeto com estes campos:
| Campo | O que é |
|---|---|
content | O texto do chunk. É o que o agente lê. |
documentName | O nome do arquivo de origem, para citação. |
sourceUrl | Link para o original, se o documento veio de um conector. null para arquivos enviados. |
chunkIndex | A posição do chunk dentro do documento. |
similarity | Quão próximo o chunk está da query; quanto maior, melhor. Por exemplo 0.92. |
metadata | Atributos do documento, incluindo as tags. |
documentId | Identificador do documento de origem. |
A saída também carrega query (o texto buscado) e totalResults (a contagem).
Para fundamentar uma resposta, conecte 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 blocos referenciam saída para como um bloco lê a saída de outro pelo nome.
Quando a recuperação parece errada
Quando a resposta do agente sai fora, a causa costuma estar na recuperação, não no agente. Leia a saída do bloco Knowledge nos logs da execução e confira os chunks que ele de fato devolveu:
- Sem resultados, ou documentos errados. Um filtro de tag pode estar excluindo o que você quer, ou os documentos ainda não estão indexados. Um documento só é pesquisável quando o status de processamento é
completed; enquanto estiverpending,processingoufailed, os chunks não aparecem. - Scores de similaridade baixos em geral. A query está vaga demais, ou a informação simplesmente não está na base. Reescreva a query para combinar com a forma como os documentos formulam as coisas.
- Documentos certos, ordem errada. Ligue Rerank Results, ou aumente Number of Results para o chunk relevante entrar no conjunto.
Veja depurando a recuperação para o caminho diagnóstico completo, e estratégias de chunking para como os limites dos chunks moldam o que uma busca pode devolver.
Próximos passos
Visão geral de bases de conhecimento
O que é uma base de conhecimento e como os documentos são indexados.
Tags e filtragem
Defina tags e use-as para restringir uma busca.
Depurando a recuperação
Diagnostique por que uma busca devolve os chunks errados.
Como os blocos passam dados
Como um bloco lê a saída de outro.