Uma busca do bloco Knowledge lê uma query, a embedda como vetor e retorna os chunks dos seus documentos mais próximos dela. Quando a busca falha, ela falha de uma de três formas: não retorna nada, retorna os chunks errados ou retorna o mesmo conteúdo duas vezes. Cada uma tem uma lista curta de causas que você pode checar nos resultados da busca, na lista de documentos e nos filtros de tag.
Como é um resultado
Uma busca retorna um array results. Cada entrada é um chunk de um documento, com os campos que você usa para diagnosticar a recuperação:
| Campo | O que é |
|---|---|
documentName | O documento de origem de onde o chunk veio. |
sourceUrl | De onde o documento foi enviado ou sincronizado (null para uploads manuais). |
content | O texto do chunk que bateu. |
chunkIndex | A posição do chunk no documento (0 é o primeiro chunk). |
similarity | Quão próximo o chunk está da sua query, de 0 a 1 (maior é mais próximo). |
rerankerScore | Um score opcional de relevância, presente só quando o reranking Cohere está ligado. |
metadata | Os valores de tag do chunk, pelos nomes de exibição. |
O score de similaridade é a primeira coisa a ler. Como guia aproximado: acima de 0.8 costuma ser relevante, 0.6 a 0.8 é marginal, e abaixo de 0.6 costuma ser ruído. Uma busca com query sempre pontua chunks assim. Uma busca só por tags (filtros, sem query) retorna todo chunk correspondente com similarity: 1, porque não há query para medir distância.
Resultados vazios
Um array results vazio significa que nenhum chunk bateu. Há três causas, listadas aqui na ordem que vale checar.
Os documentos não estão prontos
Só documentos que terminaram o processamento são pesquisáveis. Todo documento carrega um processingStatus, e o bloco Knowledge ignora silenciosamente qualquer coisa que não esteja completed. Uma base de conhecimento cheia de documentos pela metade parece vazia mesmo com o upload bem-sucedido.
processingStatus | Significado | Pesquisável |
|---|---|---|
pending | Na fila, ainda não começou. | Não |
processing | Sendo chunked e embeddado. | Não |
completed | Pronto. | Sim |
failed | Chunking ou embedding deu erro. | Não |
Rode a operação List Documents do bloco e cheque o status de cada documento. Se um documento estiver pending ou processing, espere ele terminar. Se estiver failed, leia o processingError (via Get Document) e reenvie. Veja estratégias de chunking para o que acontece durante o processamento.
A query não bate com o conteúdo
Se seus documentos estão completed mas a busca ainda não retorna nada, a query pode não estar perto de nada armazenado. Confirme que o conteúdo de fato existe: rode List Chunks e leia o que está na base de conhecimento. Se a resposta está lá mas a busca erra, o problema é a formulação, não os dados. Tente uma query mais simples, ou use um termo que aparece no conteúdo. Veja resultados errados abaixo para a versão mais profunda disso.
Filtros de tag excluem tudo
Filtros de tag restringem o conjunto de documentos antes da busca vetorial rodar, e se combinam com lógica AND: um documento precisa corresponder a todos os filtros para ser buscado. Um filtro como Department equals 'engineering' não retorna nada se nenhum documento carrega esse valor de tag.
Cheque os valores de tag de fato definidos nos seus documentos (Get Document os mostra) e confirme que o valor do filtro bate exatamente. Para descartar filtros como causa, remova-os e busque só pela query.
Resultados errados ou baixa relevância
Resultados errados são chunks que voltam mas não respondem à query, mesmo havendo conteúdo melhor na base de conhecimento. A busca vetorial encontrou algo semanticamente perto da query, mas não perto o bastante para ser um bom match. Leia os scores de similarity: um resultado no topo em 0.65 é a busca dizendo que nada bom bateu.
Causas comuns:
- A query e o conteúdo usam palavras diferentes. Uma busca por
LLMnão fica perto de conteúdo escrito só comolanguage model. Reescreva a query em direção aos termos do próprio conteúdo. - Chunks são grandes demais. Um chunk de 1.024 tokens mistura muitos tópicos em um embedding, então o score é diluído entre todos. Chunks menores (256 a 512 tokens) costumam recuperar com mais precisão. Veja estratégias de chunking.
- O contexto está dividido em um limite de chunk. A frase que responde à query está em um chunk e o sujeito a que ela se refere está no anterior, então nenhum chunk pontua bem sozinho. Overlap no chunking reduz isso.
Dois consertos que não exigem re-chunking: restrinja a busca com um filtro de tag primeiro para a busca vetorial rodar sobre menos documentos, mais relevantes, ou ligue o reranking Cohere. O reranking re-pontua os resultados vetoriais iniciais com um modelo afinado para relevância e adiciona um rerankerScore a cada resultado. Vale habilitar quando você vê resultados marginais (0.6 a 0.75) que um humano chamaria de relevantes. Custa uma unidade de busca por chamada e adiciona latência, e se o reranker estiver indisponível a busca volta automaticamente à ordenação vetorial.
Um similarity alto não garante que o chunk responde à query, só que está perto em significado. Avalie os resultados do topo você mesmo, ou use reranking, antes de confiar numa busca para fundamentar a resposta de um agente.
Duplicatas
Duplicatas são o mesmo conteúdo ou conteúdo quase idêntico aparecendo mais de uma vez em results. Leia o documentName e o chunkIndex das entradas repetidas para saber qual caso você tem.
- Mesmo documento, valores de
chunkIndexadjacentes. Isso é overlap. O chunking repete alguns tokens entre chunks consecutivos (200 por padrão) para preservar contexto, então chunks vizinhos compartilham texto e podem ambos bater. Baixar o overlap reduz a repetição, ao custo de contexto nos limites dos chunks. Veja estratégias de chunking. documentNamediferente, conteúdo idêntico. O mesmo material foi enviado como dois documentos, ou sincronizado de um conector que o guarda em mais de um lugar. Consolide os documentos duplicados, ou cheque a fonte do conector.
Chunks desabilitados e slots de tag reclamados
Um chunk pode ser desabilitado com a operação Update Chunk (enabled: false), o que o remove de todas as buscas sem excluí-lo. Um chunk desabilitado nunca aparece nos resultados, mesmo quando é o melhor match. Se um chunk que você sabe ser relevante está faltando numa busca, confirme que ele não está desabilitado.
O mesmo vale para slots de tag quando você usa conectores. Documentos sincronizados preenchem valores de tag automaticamente (nome de repositório, data de última modificação), e esses ocupam os mesmos slots que tags manuais. Um filtro que não retorna nada pode estar filtrando um slot que o conector já reclamou.