Depurar a recuperação

Uma busca do bloco Knowledge recebe uma consulta, transforma essa consulta em um vetor e retorna os chunks dos seus documentos mais próximos dela. Quando a busca não se comporta bem, ela falha de uma destas três formas: não retorna nada, retorna os chunks errados ou retorna o mesmo conteúdo duas vezes. Cada caso tem uma lista curta de causas que você pode verificar nos resultados da busca, na lista de documentos e nos seus filtros de tag.

Como é um resultado

A busca retorna um array results. Cada entrada é um chunk de um documento, com os campos que você usa para diagnosticar a recuperação:

A pontuação de similaridade é a primeira coisa a olhar. Como referência aproximada: acima de 0.8 geralmente é relevante, de 0.6 a 0.8 é marginal e abaixo de 0.6 costuma ser ruído. Uma busca com consulta sempre pontua os chunks dessa forma. Uma busca apenas por tags (filtros, sem consulta) retorna todo chunk correspondente com similarity: 1, porque não há consulta para medir distância.

Resultados vazios

Um array results vazio significa que nenhum chunk teve correspondência. Há três causas, listadas na ordem em que vale a pena verificar.

Os documentos não estão prontos

Só documentos que terminaram o processamento são pesquisáveis. Todo documento tem um processingStatus, e o bloco Knowledge ignora silenciosamente qualquer um que não esteja completed. Uma base de conhecimento cheia de documentos processados pela metade parece vazia, mesmo que o upload tenha dado certo.

Execute a operação List Documents do bloco e verifique o status de cada documento. Se um documento estiver pending ou processing, espere terminar. Se estiver failed, leia o processingError (via Get Document) e faça o upload novamente. Veja estratégias de chunking para entender o que acontece durante o processamento.

A consulta não combina com o conteúdo

Se os seus documentos estão completed mas a busca continua sem retornar nada, talvez a consulta não esteja próxima de nada armazenado. Confirme que o conteúdo existe de fato: execute List Chunks e leia o que está na base de conhecimento. Se a resposta está lá mas a busca não a encontra, o problema é a formulação, não os dados. Tente uma consulta mais simples ou use um termo que apareça no conteúdo. Veja resultados errados abaixo para a versão mais profunda desse caso.

Os filtros de tag excluem tudo

Filtros de tag restringem o conjunto de documentos antes de a busca vetorial rodar, e eles se combinam com lógica AND: um documento precisa atender a todos os filtros para ser pesquisado. Um filtro como Department equals 'engineering' não retorna nada se nenhum documento tiver esse valor de tag.

Verifique os valores de tag realmente definidos nos seus documentos (Get Document mostra isso) e confirme que o valor do filtro corresponde exatamente. Para descartar os filtros como causa, remova-os e busque só pela consulta.

Resultados errados ou de baixa relevância

Resultados errados são chunks que voltam mas não respondem à consulta, mesmo existindo conteúdo melhor na base de conhecimento. A busca vetorial encontrou algo semanticamente próximo da consulta, mas não próximo o suficiente para ser uma boa correspondência. Leia as pontuações de similarity: um primeiro resultado em 0.65 é a busca dizendo que nada de bom foi encontrado.

Causas comuns:

• A consulta e o conteúdo usam palavras diferentes. Uma busca por LLM não fica próxima de conteúdo escrito inteiramente como language model. Reformule a consulta usando os termos do próprio conteúdo.
• Os chunks são grandes demais. Um chunk de 1,024 tokens mistura muitos assuntos em um único embedding, então a pontuação se dilui entre todos eles. Chunks menores (de 256 a 512 tokens) costumam recuperar com mais precisão. Veja estratégias de chunking.
• O contexto está partido no limite entre chunks. A frase que responde à consulta está em um chunk e o assunto a que ela se refere está no anterior, então nenhum dos dois pontua bem sozinho. O overlap no chunking reduz isso.

Duas soluções que não exigem refazer o chunking: restrinja a busca com um filtro de tag primeiro, para que a busca vetorial rode sobre menos documentos e mais relevantes, ou ative o Cohere reranking. O reranking repontua os resultados vetoriais iniciais com um modelo ajustado para relevância e adiciona um rerankerScore a cada resultado. Vale ativar quando você vê resultados marginais (de 0.6 a 0.75) que um humano consideraria relevantes. Custa uma unidade de busca por chamada e adiciona latência; se o reranker estiver indisponível, a busca volta automaticamente à ordenação vetorial.

Duplicados

Duplicados são conteúdos iguais ou quase idênticos aparecendo mais de uma vez em results. Leia o documentName e o chunkIndex das entradas repetidas para identificar o caso.

• Mesmo documento, valores de chunkIndex adjacentes. Isso é overlap. O chunking repete alguns tokens entre chunks consecutivos (200 por padrão) para preservar o contexto, então chunks vizinhos compartilham texto e os dois podem ter correspondência. Reduzir o overlap diminui a repetição, ao custo de contexto nos limites entre chunks. Veja estratégias de chunking.
• documentName diferente, conteúdo idêntico. O mesmo material foi enviado como dois documentos, ou sincronizado por um connector que o mantém em mais de um lugar. Consolide os documentos duplicados ou verifique a fonte do connector.

Chunks desativados e slots de tag ocupados

Um chunk pode ser desativado com a operação Update Chunk (enabled: false), o que o remove de todas as buscas sem excluí-lo. Um chunk desativado nunca aparece nos resultados, mesmo sendo a melhor correspondência. Se um chunk que você sabe ser relevante está faltando em uma busca, confirme que ele não está desativado.

O mesmo vale para os slots de tag quando você usa connectors. Documentos sincronizados preenchem valores de tag automaticamente (o nome de um repositório, uma data de última modificação), e eles ocupam os mesmos slots que as tags manuais usariam. Um filtro que não retorna nada pode estar filtrando por um slot que o connector já ocupou.

Próximos passos