Recuperação para aplicações de LLM

Cerca de 45 minutos min de leitura, com 10 exemplos em 10 seções.

Edição 2026.11.10 Exemplos aprovados em 19 de nov de 2026 132 de 132 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.10. Leia o original

Ao final deste capítulo, você será capaz de medir a recuperação por trás de um LLM que responde a partir dela: avaliar uma resposta pelos produtos que ela cita, verificar cada citação em relação ao que a recuperação devolveu, medir os produtos que o LLM lê, escolher o que indexar como uma unidade recuperável e ler as buscas de um agente a partir do registro de suas chamadas de ferramenta.

Toda busca na loja termina em uma lista ordenada de móveis e artigos para casa que os clientes leem por conta própria. Um assistente de compras poderia responder em palavras. O cliente escreve o que deseja, e um LLM recomenda alguns produtos e cita cada um pelo seu ID. O prompt instrui o LLM a recomendar apenas os produtos que a busca coloca diante dele, de modo que o assistente não pode ser melhor do que a sua recuperação. O mesmo vale para um agente, um LLM que executa as buscas por conta própria e decide quantas executar.

Assim, este capítulo avalia as respostas, as citações, o contexto e as buscas do agente com base nos julgamentos humanos da loja. Toda conclusão sobre o LLM vale apenas para este modelo, estes prompts e as 30 consultas de teste, e não para LLMs em geral. Em uma resposta, o LLM leu o nome, a classe, a categoria, a descrição e os atributos de cada produto como texto, e a ferramenta de busca do agente lhe mostra menos. Os juízes humanos também viram a imagem e a página web de cada produto (o que o LLM viu). Recuperação semântica ordena pelos embeddings registrados de Snowflake/snowflake-arctic-embed-m-v1.5, e o BM25 é a linha de base do livro, sem stemização, lib.lexical.

Planejamos 2 comparações, todas sobre as consultas de teste, antes de abrir qualquer resultado, e em cada uma a recuperação semântica enfrenta o BM25:

  1. por trás das respostas registradas, na proporção dos produtos citados em cada resposta que as pessoas julgaram exatos (Avalie cada resposta)
  2. por trás da ferramenta de busca do agente, na precisão@3 dos produtos que ela escolhe (Compare os recuperadores)

As 2 comparações planejadas dividem o 0.05 do livro, portanto cada uma precisa de um teste de permutação pareado com valor-p abaixo de 0.025. O capítulo também relata o teste t pareado e um intervalo de bootstrap de 97.5%. Qualquer outra coisa sobre as consultas de teste é uma descrição ou está rotulada como exploratória.

Coloque os produtos recuperados no prompt

Última alteração na edição 2026.11.10

Retrieval-augmented generation (RAG), o princípio por trás de um assistente de compras, combina um LLM com um recuperador. Para cada pedido, o recuperador encontra alguns textos em um índice, e o LLM escreve sua resposta a partir deles. Os modelos RAG de Lewis et al. mantêm sua memória não paramétrica como um índice vetorial denso da Wikipédia, que um recuperador neural pré-treinado pesquisa. Esses mesmos autores também tratam como problemas de pesquisa em aberto dois problemas dos modelos de linguagem considerados isoladamente: fornecer proveniência para suas decisões e atualizar seu conhecimento de mundo (Lewis et al., 2020). Uma loja tem ambos os problemas: seu catálogo muda, e uma resposta deve dizer quais produtos recomenda. O texto recuperado vai para o prompt, a entrada que o modelo lê, e o texto recuperado presente em um prompt é o contexto. A janela de contexto de um modelo é o máximo de tokens que ele consegue ler, um número fixo de fragmentos de palavras do seu próprio vocabulário.

Por que não colocar todo o catálogo no prompt e dispensar a recuperação? Ele precisa caber e, mesmo quando cabe, os modelos não leem um prompt longo de maneira uniforme. Liu et al. constataram que os modelos costumam ter melhor desempenho quando a informação relevante está no início ou no fim da entrada, e que o desempenho cai significativamente quando ela está no meio de um contexto longo (Liu et al., 2024). Um estudo posterior chama esse efeito de lost-in-the-middle (LiM). Ele constata que o efeito é mais forte quando as entradas ocupam até 50% da janela de contexto de um modelo e que, perto do limite, ele dá lugar a um viés em direção ao fim (Veseli et al., 2025). Mais passagens também nem sempre ajudam. Quando Jin et al. deram a LLMs de contexto longo mais passagens recuperadas, a qualidade da saída primeiro melhorou e depois caiu, e eles apontam como principal fator dessa queda os negativos difíceis recuperados, passagens que parecem relevantes mas não são (Jin et al., 2024). Um artigo de engenharia de um fornecedor sugere o oposto para coleções pequenas: coloque toda a base de conhecimento no prompt quando ela tiver menos de 200,000 tokens, cerca de 500 páginas de material (Anthropic, 2024). Trata-se de uma regra empírica do fornecedor, não de uma medição.

O LLM da loja é o modelo aberto gemma4:12b-it-q4_K_M. Suas gravações, recordings/rag_answers.py e recordings/agent_trace.py, fizeram cada chamada ao modelo uma única vez, como fez a gravação do capítulo 4, com temperatura 0, semente fixa e raciocínio desativado (capítulo 9), e salvaram as respostas, que os exemplos leem por meio de lib.recorded. O manifesto de cada gravação, o arquivo que a descreve, informa a licença do modelo como Apache-2.0.

As respostas gravadas da loja (Pontue cada resposta) colocam cinco produtos em cada prompt, depois destas instruções: "You help shoppers at an online furniture and home-goods store. Using only the products listed below, answer the shopper. Recommend up to three products that fit, cite each one by its ID, and say plainly if none of them fit. Don't mention products that aren't listed." Quantos prompts equivalem ao catálogo? Contar suas palavras como o LLM as lê responde a essa pergunta.

catalog-against-the-context.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Counts the catalog's words as the LLM reads each product, then sets them against a median prompt of theinstructions and five products, and against the recording's context window. The point rests on the "catalogagainst one prompt" line."""from statistics import medianfrom lib.agreement import as_the_llm_sawfrom lib.recorded import manifest, rag_answersfrom lib.store import load_productsrecording = manifest("rag-answers")# num_ctx is the context window, in tokens, that the recording setwindow = recording["options"]["num_ctx"]print("model:", recording["model"])print("licence in the manifest:", recording["model_licence"])print("instructions:", recording["prompts"].split("\n")[0])print("context window the recording set, in tokens:", window)products = load_products()# words are whitespace-separated pieces, since this model's tokenizer isn't in the book's libwords = {product_id: len(f"ID: {product_id}\n{as_the_llm_saw(product)}".split())    # each product as the LLM read it         for product_id, product in products.iterrows()}instructions = len(recording["prompts"].split())                  # the prompt's own words, without the query# one prompt per recorded answer: the instructions, then the five products' wordsprompts = [instructions + sum(words[p] for p in ids) for ids in rag_answers()["context_ids"]]catalog = sum(words.values())print(f"words in the catalog as the LLM reads it: {catalog:,}")print(f"words in one prompt with five products, median: {median(prompts):,.0f}")print(f"the catalog against one prompt: {catalog / median(prompts):,.0f} times")print(f"the catalog against the recording's window, at one token per word: {catalog / window:,.0f} times")print(f"the catalog against 200,000 tokens, at one token per word: {catalog / 200_000:.1f} times")
Saídapython catalog-against-the-context.py
model: gemma4:12b-it-q4_K_M
licence in the manifest: Apache-2.0
instructions: You help shoppers at an online furniture and home-goods store. Using only the products listed below, answer the shopper. Recommend up to three products that fit, cite each one by its ID, and say plainly if none of them fit. Don't mention products that aren't listed.
context window the recording set, in tokens: 8192
words in the catalog as the LLM reads it: 1,091,544
words in one prompt with five products, median: 536
the catalog against one prompt: 2,035 times
the catalog against the recording's window, at one token per word: 133 times
the catalog against 200,000 tokens, at one token per word: 5.5 times

Mesmo com as descrições da amostra do livro reduzidas a cerca de 400 caracteres (ficha de dados), o catálogo tem 1,091,544 palavras, e um prompt com cinco produtos tem uma mediana de 536 palavras. O catálogo é 2,035 times maior do que um único prompt.

Sem um tokenizador para este modelo, as contagens são de palavras. A gravação define uma janela de contexto de 8192 tokens. Se cada palavra fosse um único token, o catálogo excederia essa janela em 133 times, e o limite de 200,000 tokens do fornecedor seria excedido em 5.5 times. A loja precisa recuperar.

Regra prática: coloque no prompt alguns itens recuperados, não a coleção inteira, e escolha quantos medindo as respostas a consultas de treino em vários tamanhos, pois mais contexto pode ajudar ou atrapalhar. A gravação da loja respondeu apenas às consultas de teste, com cinco produtos cada, de modo que cinco é um valor fixo aqui, não um valor medido. Considere enviar a coleção inteira apenas quando ela couber folgadamente dentro da janela, e então teste essa opção contra a recuperação nas mesmas consultas.

Pontue cada resposta pelos produtos que ela cita

Última alteração na edição 2026.11.8

Um LLM instruído a responder a partir de um contexto deve recomendar apenas o que o contexto contém, e a verificação de IDs testa se ele faz isso. Se nenhum produto exato estiver no contexto, nenhum prompt levará uma resposta fundamentada a recomendar um. A recuperação estabelece um teto para a resposta, e o que mais o contexto contém também importa.

Cuconasu et al. constataram que os documentos mais bem pontuados pelo recuperador que não são diretamente relevantes, isto é, os que não contêm a resposta, prejudicam as respostas. Mais surpreendente, acrescentar documentos aleatórios ao prompt melhorou a acurácia dos LLMs em até 35% (Cuconasu et al., 2024). Produtos que parecem certos, mas não são, são distratores, a versão, na loja, desses trechos de texto. Em respostas a perguntas, Joren et al. encontraram um padrão relacionado. Quando o contexto não continha o necessário, os modelos maiores que testaram, Gemini 1.5 Pro, GPT 4o e Claude 3.5, muitas vezes deram respostas incorretas em vez de se abster. Os menores, entre eles Mistral 3 e Gemma 2, muitas vezes alucinaram ou se abstiveram mesmo quando o contexto era suficiente (Joren et al., 2024).

Uma citação aqui é o ID que uma resposta dá a um produto que recomenda. Com julgamentos, você pode pontuar uma resposta sem lê-la: consulte a nota de cada produto citado. A parcela exata de uma resposta é a parcela de seus produtos citados que as pessoas julgaram exatos. Uma resposta que não cita nada recebe 0, porque não oferece ao comprador nada que se encaixe, esteja ou não certa a decisão. Uma contagem separada das respostas que não recomendam nada cobre esse caso.

exact share = (cited products judged exact) / (products cited),   0 when the answer cites nothing

A gravação da loja respondeu a cada consulta de teste três vezes, com a consulta vindo após "I'm looking for". Cada resposta veio de um contexto diferente de 5 produtos: os 5 primeiros da recuperação semântica, os 5 primeiros do BM25, ou 5 produtos sorteados ao acaso com uma semente fixa. O contexto aleatório é um piso, um contexto que nenhum recuperador escolheu. O modelo, o prompt e a consulta permanecem os mesmos, então as respostas diferem apenas porque seus contextos diferem. Lemos cada contexto como a gravação o armazenou, na ordem em que o LLM o leu. Os contextos do BM25 mantêm os produtos empatados na ordem própria do bm25s, e não por product_id como faz lib.lexical; por isso, 7 das 30 consultas de teste recebem um contexto que difere do que lib.lexical retorna, 6 delas apenas na ordem. A gravação pediu JSON, com a resposta e os IDs citados em campos separados. score_answers em lib.generation pontua cada resposta segundo as notas humanas. A comparação dessas pontuações é a primeira das comparações planejadas do capítulo, estabelecida se seu p-valor de permutação estiver abaixo de 0.025.

Quantas respostas não recomendarão nada, dados 5 produtos aleatórios e um prompt que instrui o LLM a dizer claramente se nenhum deles couber?

rag-answers-by-context.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Scores the recorded answers on the human grades, context by context, and makes the first planned comparison. Thepoint rests on the mean exact share and recommend-nothing lines, and on the permutation p-value of thecomparison."""from lib.generation import PLANNED_TEST_COMPARISONS, THRESHOLD, report_planned, score_answersfrom lib.lexical import LexicalSearchfrom lib.recorded import rag_answersfrom lib.store import load_products, load_queries, qrelsanswers = rag_answers()stored = answers[answers["context"] == "bm25"].set_index("query_id")["context_ids"]   # as the LLM read themrerun = LexicalSearch(load_products()).run(load_queries("test"), k=5)                 # ties by product_iddiffer = [q for q in stored.index if stored[q] != rerun[q]]print("bm25 contexts that differ from lib.lexical:", len(differ))# a match as sets means the same five products in another order: a tie-break, not a different contextprint("bm25 contexts that differ from lib.lexical only in order:", sum(set(stored[q]) == set(rerun[q]) for q in differ))scores = score_answers(answers, qrels("test"))            # one row per test query and context, on human gradesfor context, rows in scores.groupby("context", sort=False):    # held: the context holds an exact product; nothing: the answer cites no product    held, nothing = rows["exact in context"] > 0, rows["cited"] == 0    print(f"{context}, unjudged products in the contexts: {rows['unjudged in context'].sum()}")    print(f"{context}, contexts with an exact product: {held.sum()}")    print(f"{context}, answers that cite an exact product: {(rows['exact cited'] > 0).sum()}")    print(f"{context}, products cited: {rows['cited'].sum()}")    print(f"{context}, cited products that are exact: {rows['exact cited'].sum()}")    print(f"{context}, mean exact share: {rows['exact share'].mean():.3f}")    print(f"{context}, answers that recommend nothing: {nothing.sum()}")    print(f"{context}, recommend nothing, with an exact product in the context: {(nothing & held).sum()}")    print(f"{context}, recommend something, with no exact product in the context: {(~nothing & ~held).sum()}")    near = rows[~held]                                    # answers whose context held no exact product    print(f"{context}, products cited with no exact product in the context: {near['cited'].sum()}")    print(f"{context}, of those, partial: {near['partial cited'].sum()}")    print(f"{context}, unjudged products cited: {rows['unjudged cited'].sum()}")print("answers that cite more exact products than their context holds:",      (scores["exact cited"] > scores["exact in context"]).sum())print("planned test comparisons:", len(PLANNED_TEST_COMPARISONS))print(f"p-value threshold: {THRESHOLD:.3f}")share = scores.pivot(index="query_id", columns="context", values="exact share")# the first planned comparison: semantic minus BM25 on the exact share, tested at THRESHOLDreport_planned("answers, semantic over bm25", share["semantic"], share["bm25"])
Saídapython rag-answers-by-context.py
bm25 contexts that differ from lib.lexical: 7
bm25 contexts that differ from lib.lexical only in order: 6
semantic, unjudged products in the contexts: 0
semantic, contexts with an exact product: 25
semantic, answers that cite an exact product: 22
semantic, products cited: 80
semantic, cited products that are exact: 60
semantic, mean exact share: 0.658
semantic, answers that recommend nothing: 2
semantic, recommend nothing, with an exact product in the context: 1
semantic, recommend something, with no exact product in the context: 4
semantic, products cited with no exact product in the context: 11
semantic, of those, partial: 11
semantic, unjudged products cited: 0
bm25, unjudged products in the contexts: 10
bm25, contexts with an exact product: 24
bm25, answers that cite an exact product: 23
bm25, products cited: 73
bm25, cited products that are exact: 52
bm25, mean exact share: 0.639
bm25, answers that recommend nothing: 3
bm25, recommend nothing, with an exact product in the context: 0
bm25, recommend something, with no exact product in the context: 3
bm25, products cited with no exact product in the context: 7
bm25, of those, partial: 7
bm25, unjudged products cited: 1
random, unjudged products in the contexts: 147
random, contexts with an exact product: 1
random, answers that cite an exact product: 1
random, products cited: 1
random, cited products that are exact: 1
random, mean exact share: 0.033
random, answers that recommend nothing: 29
random, recommend nothing, with an exact product in the context: 0
random, recommend something, with no exact product in the context: 0
random, products cited with no exact product in the context: 0
random, of those, partial: 0
random, unjudged products cited: 0
answers that cite more exact products than their context holds: 0
planned test comparisons: 2
p-value threshold: 0.025
answers, semantic over bm25, mean difference: 0.019
answers, semantic over bm25, wins, losses, ties: 4, 5, 21
answers, semantic over bm25, permutation p: 0.765
answers, semantic over bm25, established at 0.025: no
answers, semantic over bm25, t-test p: 0.715
answers, semantic over bm25, t-test agrees: yes
answers, semantic over bm25, 97.5% interval: -0.078 to 0.161
answers, semantic over bm25, interval agrees: yes
Medida Semântico BM25 Aleatório
Contextos com um produto exato 25 24 1
Respostas que citam um produto exato 22 23 1
Produtos citados 80 73 1
Produtos citados que são exatos 60 52 1
Parcela exata média 0.658 0.639 0.033
Respostas que não recomendam nada 2 3 29

Com produtos aleatórios, o LLM não recomenda nada em 29 das 30 respostas; assim, este modelo e este prompt não forçaram uma recomendação a partir de produtos aleatórios. O único produto que ele cita é exato, e o sorteio por acaso o incluiu. Os contextos aleatórios também contêm 147 produtos que ninguém julgou, os quais contam como não exatos. Esperamos que poucos deles se encaixem, mas nenhum julgamento o afirma.

O teto se mantém: 0 respostas citam mais produtos exatos do que seu contexto contém. Os quase acertos são outra questão. Quando o contexto não continha nenhum produto exato, a resposta ainda recomendou algo 4 vezes com a recuperação semântica e 3 vezes com o BM25, em vez de dizer que nenhum produto se encaixa exatamente.

Todo produto que essas respostas citam é parcial: 11 de 11 com a recuperação semântica e 7 de 7 com o BM25, ou seja, o tipo certo de produto com um modificador errado. Se isso conta como falha depende de o comprador querer quase acertos.

A falha inversa é mais rara: respostas não recomendam nada embora seu contexto contivesse um produto exato, 1 com a recuperação semântica e 0 com o BM25.

Os contextos do BM25 contêm 10 produtos não julgados, e os da recuperação semântica contêm 0. A pontuação lê apenas os produtos citados, e as respostas do BM25 citam 1 produto não julgado, que conta como não exato.

A vantagem da recuperação semântica no nDCG@10 está estabelecida (capítulo 3). Na primeira comparação planejada, porém, sua diferença em relação ao BM25 na parcela exata média, 0.019, não está estabelecida: o p-valor de permutação é 0.765 (ambas as comparações).

Regra prática: Pontue cada resposta pelas notas humanas dos produtos citados, e informe ao lado quantas respostas não recomendam nada, separadas conforme o contexto tivesse ou não um produto exato. Mantenha um contexto aleatório como piso sempre que mudar o modelo ou o prompt: uma resposta que recomenda algo a partir de produtos aleatórios inventou um encaixe. Teste também o ganho de um recuperador nas respostas, porque um ganho no ranqueamento nem sempre se mantém.

Verifique cada citação contra o contexto

Última alteração na edição 2026.11.8

Fundamentação significa que uma resposta se apoia no contexto que lhe foi dado, como pressupõe a parcela exata, e não no que o modelo lembra ou inventa. As citações tornam a fundamentação verificável, e atribuição pergunta se a fonte citada sustenta a afirmação à qual está vinculada. Auditorias constatam que, muitas vezes, as citações não cumprem essa função. Em uma auditoria de 2023 sobre mecanismos de busca generativos, apenas 51.5% das frases geradas eram totalmente sustentadas por suas citações, e apenas 74.5% das citações sustentavam a frase à qual estavam vinculadas (Liu et al., 2023). No ELI5, as perguntas longas do benchmark ALCE extraídas do fórum do Reddit Explain Like I'm Five, mesmo os melhores modelos de 2023 deixavam de ter que até os melhores modelos de 2023 não tinham suporte completo de citações em 50% das vezes (Gao et al., 2023).

Verifique as citações em dois níveis, do mais barato para o mais caro. O primeiro é exato e não precisa de modelo: todo ID citado deve ser um que o contexto continha. Um ID de fora do contexto nomeia um produto que o modelo lembrou ou inventou, e, em qualquer dos casos, a resposta não está fundamentada. O segundo nível pergunta se o texto do produto citado sustenta o que a resposta diz sobre ele, o que exige um leitor (Verifique o que o produto citado sustenta).

O esquema da gravação pedia os IDs citados como uma lista de inteiros em um campo próprio (schemas no manifesto). O esquema descreve a forma do campo; não diz quais IDs entram nele, nem quantos. A verificação lê cada resposta gravada contra o seu contexto e compara o campo com os IDs do contexto que o texto da resposta escreve por extenso. O texto não consegue revelar um ID de fora do contexto, que pareceria qualquer outro número que a resposta escreve, como um tamanho. É por isso que os IDs devem estar em um campo:

citations-inside-the-context.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Checks every recorded answer's cited IDs against its context, and its text against its cited field. The pointrests on the zero counts for IDs outside the context and for disagreeing text, and on the count of answers thatcite more than three products."""from lib.generation import ids_in_textfrom lib.recorded import rag_answersanswers = rag_answers()outside = answers.apply(lambda a: [p for p in a["cited"] if p not in a["context_ids"]], axis=1)# an ID cited twice makes the list longer than the set of its IDsrepeated = answers["cited"].map(lambda cited: len(cited) != len(set(cited)))# the text is searched only for the context's IDs, so an ID from outside it can't matchwritten = answers.apply(lambda a: ids_in_text(a["answer"], a["context_ids"]), axis=1)   # IDs the text writes outprint("answers:", len(answers))print("answers that cite an ID outside their context:", (outside.map(len) > 0).sum())print("answers that cite one ID twice:", repeated.sum())print("answers that cite nothing:", (answers["cited"].map(len) == 0).sum())# the prompt asks for up to three productsprint("answers that cite more than three products:", (answers["cited"].map(len) > 3).sum())print("answers whose text and cited IDs differ:", (written != answers["cited"].map(set)).sum())
Saídapython citations-inside-the-context.py
answers: 90
answers that cite an ID outside their context: 0
answers that cite one ID twice: 0
answers that cite nothing: 34
answers that cite more than three products: 3
answers whose text and cited IDs differ: 0

Entre as 90 respostas gravadas, a verificação encontra 0 respostas que citam um ID fora do seu contexto, 0 que citam um mesmo ID duas vezes, e 0 cujo texto e campo não coincidem.

34 respostas não citam nada. A instrução que as respostas de fato descumprem é quantas recomendar: 3 respostas citam mais de três produtos, embora o prompt diga "Recomende até três".

Nesta gravação, a verificação de IDs não encontra nenhuma citação sem fundamentação. Esse é o resultado que você quer, e não é motivo para abandonar a verificação: ela custa uma consulta a um conjunto por resposta, e um modelo, prompt ou tamanho de contexto diferente pode fazê-la falhar. Passar nela diz apenas que cada produto recomendado estava diante do modelo, e não que ele se adequa.

Regra prática: Execute a verificação de IDs em cada resposta, offline e antes que o cliente a veja, e trate um ID fora do contexto como uma resposta reprovada: descarte-a ou gere outra, e nunca a mostre. Peça as citações em um campo próprio, para que a verificação não precise interpretar prosa, e confira se o texto e o campo coincidem. Conte as instruções que as respostas descumprem, como o número de recomendações, e imponha em código as que importam.

Verifique o que o produto citado sustenta

Última alteração na edição 2026.11.8

O segundo nível de verificação pergunta se o texto citado sustenta a afirmação. Fidelidade é a parcela das afirmações de uma resposta que o contexto sustenta. Nas palavras da documentação do Ragas (suas páginas não nomeiam versão; as que foram consultadas são de 2025-12-09), "Uma resposta é considerada fiel se todas as suas afirmações puderem ser sustentadas pelo contexto recuperado" (documentação do Ragas). Verificar isso exige um leitor. O ALCE usa um modelo de inferência em linguagem natural (NLI, na sigla em inglês), a tarefa de decidir se um texto implica outro: um modelo T5-11B ajustado a uma coleção de conjuntos de dados de NLI. O recall de citação de uma afirmação só vale 1 quando suas citações, em conjunto, implicam a afirmação (Gao et al., 2023, seções 3.2 e 3.3). Um LLM também pode julgar sustentação, com limites. Na trilha RAG de 2024 do TREC, as avaliações compartilhadas da Text REtrieval Conference, Thakur et al. constataram que as previsões humanas e as do GPT-4o coincidiram perfeitamente em uma escala de três níveis para 56% dos julgamentos feitos do zero, e para 72% quando as pessoas partiram do rótulo de sustentação do GPT-4o e o editaram. Eles também constataram que um juiz humano independente se correlacionou mais de perto com o GPT-4o do que outra pessoa se correlacionou, de modo que parte da discordância está entre pessoas (Thakur et al., 2025).

Sustentação não é relevância. Uma citação pode ser fiel ao texto do produto e ainda recomendar o produto errado: o texto diz o que a resposta afirma, mas o produto não é o que o cliente procurava. Só os julgamentos detectam isso.

Comece à mão por uma das respostas da loja, a da consulta de teste medium size chandelier do contexto semântico. Depois, conte as notas humanas de cada produto citado nas respostas registradas dos contextos semântico e BM25.

faithful-but-partial.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Reads one recorded answer by hand, checking its claim against the cited product's text and the judges' label,then counts the grades of every product the two retrievers' answers cite. The point rests on the partial label,the exact count in this answer's context, and the breakdown of cited products."""from collections import Counterfrom lib.agreement import LABELSfrom lib.recorded import rag_answersfrom lib.store import load_products, load_queries, qrelsproducts, queries, judgments = load_products(), load_queries("test"), qrels("test")answers = rag_answers().set_index(["query_id", "context"])chandelier, claim = 58, "medium-sized"                     # one answer, read by handanswer, judged = answers.loc[(chandelier, "semantic")], judgments[chandelier]# the answer cites one product, so index 0 is that productcited = answer["cited"][0]print("query:", queries.at[chandelier, "query"])print("answer:", answer["answer"])print("cited product:", products.at[cited, "name"])print(f"the cited product's text says {claim}:", "yes" if claim in products.at[cited, "description"] else "no")print("the judges' label:", LABELS[judged[cited]])# grade 2 is exact; a product nobody judged has no grade, so it counts as 0print("exact products in this answer's context:", sum(judged.get(p, 0) == 2 for p in answer["context_ids"]))retrieved = answers.drop("random", level="context")        # every citation from the two retrievers' contexts# LABELS names each grade; a product with no grade counts as unjudgedlabels = Counter(LABELS.get(judgments[query_id].get(p), "unjudged")                 for (query_id, _), cited_ids in retrieved["cited"].items() for p in cited_ids)print("cited products, semantic and bm25 contexts:", sum(labels.values()))for label in ["exact", "partial", "irrelevant", "unjudged"]:    print(f"cited products, {label}:", labels[label])
Saídapython faithful-but-partial.py
query: medium size chandelier
answer: I recommend the sybil 12 - light unique / statement classic / traditional chandelier with antler accents (ID: 8171), as it is specifically described as a perfect medium-sized lighting fixture.
cited product: sybil 12 - light unique / statement classic / traditional chandelier with antler accents
the cited product's text says medium-sized: yes
the judges' label: partial
exact products in this answer's context: 2
cited products, semantic and bm25 contexts: 153
cited products, exact: 112
cited products, partial: 40
cited products, irrelevant: 0
cited products, unjudged: 1

A resposta recomenda um lustre, dizendo que ele "é descrito especificamente como um aparelho de iluminação de tamanho médio perfeito". A descrição do produto citado de fato diz medium-sized (yes), então uma verificação de sustentação aprovaria a afirmação. Os juízes da loja classificaram o produto como partial: pela definição do WANDS, é o tipo certo de produto, mas com um modificador pedido pelo cliente ausente. Eles viram a imagem e a página do produto, o que o LLM não viu. O contexto da resposta continha 2 produtos exatos, e a resposta não recomendou nenhum deles. Para esta resposta, a citação é fiel, e a recomendação ainda assim erra.

Somando as respostas dos dois recuperadores, os 153 produtos citados se dividem em 112 exatos, 40 parciais, 0 irrelevantes e 1 sem julgamento. Todo produto citado que não é exato é parcial, exceto os 1 que ninguém julgou: o tipo de produto que o cliente pediu, com um modificador errado segundo a leitura dos juízes.

Regra prática: Avalie as respostas primeiro pelos seus julgamentos, pois eles dizem se uma recomendação se encaixa. Acrescente uma verificação de sustentação para as afirmações que uma resposta faz sobre cada produto, feita por um modelo NLI ou por um juiz LLM. Calibre esse juiz com uma amostra humana, como faz o capítulo 4 e como faz o ARES: ele usa um pequeno conjunto de exemplos anotados por humanos para a inferência com predição assistida (PPI, na sigla em inglês), a fim de mitigar erros de predição, corrigindo a estimativa do juiz com os rótulos humanos (Saad-Falcon et al., 2024). Para consultas das quais você não tem julgamentos, uma verificação de sustentação é tudo o que você tem, então diga isso ao relatá-la.

Meça o contexto e depois a resposta

Última alteração na edição 2026.11.10

Um sistema RAG pode falhar na recuperação ou na geração, então meça o contexto assim como as respostas. O Ragas, um framework para avaliar sistemas RAG, pontua várias medidas sem respostas de referência: quão bem a recuperação identifica passagens de contexto relevantes e focadas, a fidelidade e a relevância da resposta. Sua revocação de contexto exige uma referência (Es et al., 2024). Suas medidas de contexto herdam as métricas do capítulo 3, com um LLM como juiz. A precisão de contexto do Ragas é a mais sensível à posição entre suas medidas de contexto: a média de precision@k sobre as posições que contêm um trecho relevante (documentação do Ragas). Sua revocação de contexto é a parcela das afirmações de uma resposta de referência que o contexto sustenta, e uma variante baseada em IDs compara os IDs recuperados com os IDs de referência (documentação do Ragas). Com os julgamentos em mãos, a referência é o conjunto de produtos exatos, e a revocação de contexto baseada em IDs é recall@k.

context recall@k    = (exact products in the top k) / (exact products judged for the query)
context precision@k = mean of precision@i over the positions i ≤ k that hold an exact product

Qual medida acompanha as respostas? Salemi e Zamani constataram que rótulos de relevância se correlacionam apenas fracamente com o desempenho a jusante de um sistema RAG, e pontuam cada passagem recuperada pela resposta que o LLM dá a partir dela (Salemi e Zamani, 2024). A correlação de postos de Spearman é a correlação entre os postos de duas medidas, e não entre seus valores: vale 1 quando ordenam os casos do mesmo modo e fica próxima de 0 quando as ordens não têm relação. Ela responde a essa pergunta para um registro.

Medimos todo contexto que um recuperador construiu para as respostas registradas, um semântico e um BM25 por consulta de teste. Este exemplo constrói a revocação de contexto e a precisão de contexto à mão, confere-as com lib.metrics.recall_at_k e com as cópias em lib.generation, e percorre um contexto:

context-measures-by-hand.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Builds context precision and context recall by hand and checks each against the library's version, then worksthrough one context. The point rests on the two "every time" lines and on the precision@5 and context precisionof the worked context."""from lib import generationfrom lib.generation import EXACTfrom lib.metrics import precision_at_k, recall_at_kfrom lib.recorded import rag_answersfrom lib.store import load_queries, qrelsdef context_precision(context, judged, k=5):    """Ragas's context precision, with the judges as the reference: mean precision@i over exact positions i."""    # positions count from 1, as ranks do; context[:k] is the top k    hits = [i for i, p in enumerate(context[:k], start=1) if judged.get(p, 0) == EXACT]    return sum(precision_at_k(context, judged, i) for i in hits) / len(hits) if hits else 0.0def context_recall(context, judged, k=5):    """Ragas's ID-based context recall: the share of the reference IDs that the context holds."""    # the reference is every exact product judged for the query, not only those in the top k    reference = {p for p, grade in judged.items() if grade == EXACT}    return len(reference & set(context[:k])) / len(reference)judgments, queries = qrels("test"), load_queries("test")answers = rag_answers().query("context != 'random'")             # the two retrievers' contexts for each test querycontexts = [(answer.context_ids, judgments[answer.query_id]) for answer in answers.itertuples()]print("contexts:", len(contexts))same = {"recall_at_k": all(context_recall(c, j) == recall_at_k(c, j, 5) for c, j in contexts),        "lib.generation": all(context_precision(c, j) == generation.context_precision(c, j) for c, j in contexts)}print("context recall equals recall_at_k every time:", "yes" if same["recall_at_k"] else "no")print("context precision equals lib.generation's every time:", "yes" if same["lib.generation"] else "no")# the first row: the semantic context for door jewelry organizerfirst = answers.iloc[0]                                          # one context, worked throughcontext, judged = first["context_ids"], judgments[first["query_id"]]print(f"grades in order, {queries.at[first['query_id'], 'query']}, {first['context']}:", *[judged.get(p, 0) for p in context])print(f"context precision@5: {context_precision(context, judged):.3f}")print(f"precision@5: {precision_at_k(context, judged, 5):.3f}")# exact products judged for each test query, sorted from the fewest to the mostexact = sorted(sum(grade == EXACT for grade in grades.values()) for grades in judgments.values())print(f"exact products judged per test query: {exact[0]} to {exact[-1]}")print(f"highest recall@5 possible for the query with the most: {5 / exact[-1]:.3f}")
Saídapython context-measures-by-hand.py
contexts: 60
context recall equals recall_at_k every time: yes
context precision equals lib.generation's every time: yes
grades in order, door jewelry organizer, semantic: 1 1 2 2 2
context precision@5: 0.478
precision@5: 0.600
exact products judged per test query: 4 to 170
highest recall@5 possible for the query with the most: 0.029

Sobre os 60 contextos, a revocação de contexto é igual a recall_at_k em todos os casos (yes), e a precisão de contexto é igual à de lib.generation (yes).

Para o contexto semântico de door jewelry organizer, os graus em ordem são 1 1 2 2 2, em que 2 é exato e 1 é parcial. Isso dá uma precision@5 de 0.600 e uma precisão de contexto de 0.478, mais baixa porque os produtos exatos vêm por último.

Correlacionar cada medida com a parcela exata da resposta responde a essa pergunta. Este exemplo calcula a correlação de Spearman como a correlação de Pearson dos postos e a confere com o spearmanr do SciPy:

context-measures-against-answers.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Correlates three context measures with the exact share of each recorded answer, computing Spearman's correlationby hand and checking it against SciPy. The point rests on the three Spearman lines and the weakest-measure line."""import pandas as pdfrom scipy import statsfrom lib.generation import context_precision, context_recall, exact_sharefrom lib.metrics import precision_at_kfrom lib.recorded import rag_answersfrom lib.store import qrelsjudgments = qrels("test")answers = rag_answers().query("context != 'random'")             # the two retrievers' contexts for each test queryrows = pd.DataFrame([{"recall@5": context_recall(a.context_ids, judgments[a.query_id]),                      "precision@5": precision_at_k(a.context_ids, judgments[a.query_id], 5),                      "context precision@5": context_precision(a.context_ids, judgments[a.query_id]),                      "exact share": exact_share(a.cited, judgments[a.query_id])} for a in answers.itertuples()])print("contexts:", len(rows))ranks, spearman = rows.rank(), {}                                # Spearman: Pearson's correlation of the ranksfor measure in ["recall@5", "precision@5", "context precision@5"]:    spearman[measure] = ranks[measure].corr(ranks["exact share"])    print(f"spearman with the exact share, {measure}: {spearman[measure]:.3f}")# rounded to nine places, so floating-point differences in the last digits don't countmatches = all(round(value, 9) == round(stats.spearmanr(rows[measure], rows["exact share"]).statistic, 9)              for measure, value in spearman.items())print("matches scipy's spearmanr:", "yes" if matches else "no")print("weakest with the exact share:", min(spearman, key=spearman.get))
Saídapython context-measures-against-answers.py
contexts: 60
spearman with the exact share, recall@5: 0.540
spearman with the exact share, precision@5: 0.797
spearman with the exact share, context precision@5: 0.808
matches scipy's spearmanr: yes
weakest with the exact share: recall@5

A correlação de Spearman calculada à mão coincide com a do SciPy (yes).

A correlação mais fraca com a parcela exata pertence a recall@5, com 0.540, contra 0.797 para precision@5 e 0.808 para a precisão de contexto.

O denominador de recall@5 mostra o motivo. As consultas de teste têm 4 to 170 produtos exatos julgados, então o maior recall@5 possível para um contexto de cinco produtos, na consulta com mais deles, é 0.029. Uma resposta precisa de apenas três recomendações, qualquer que seja o número de produtos julgados. A precision@5 conta quantos dos cinco se encaixam, e a precisão de contexto também recompensa colocá-los primeiro.

Leia essas correlações como a descrição de um registro, não como um teste. Ambos os lados usam os mesmos julgamentos, e uma resposta só pode citar o que o seu contexto contém, então alguma correlação já está embutida. Os contextos também vêm em pares, semântico e BM25, a partir das mesmas consultas.

Regra prática: Para um contexto de tamanho fixo, informe a precision@k ou a precisão de contexto do contexto a partir dos seus julgamentos, com a recall@k ao lado. Use a revocação quando uma resposta precisar cobrir todo item relevante, como toda peça que serve a um aparelho. Sem julgamentos, as versões do Ragas avaliadas por LLM estimam quantidades semelhantes; calibre-as em uma amostra humana antes de confiar nelas. Escolha k medindo respostas para consultas de treino em vários valores de k, o que exige respostas registradas para essas consultas.

Escolha a unidade recuperável

Última alteração na edição 2026.11.10

A unidade recuperável é o trecho de texto que a recuperação pontua e devolve, e que um contexto contém: um documento inteiro, uma passagem ou uma frase. Um documento longo é cortado em fragmentos, e a fragmentação é a regra que corta um documento, como um número fixo de tokens, de frases ou de parágrafos, ou quebras escolhidas pelo significado. Chen et al. chamam a unidade de recuperação de uma escolha de projeto frequentemente negligenciada e, no estudo deles, indexar proposições, afirmações curtas e autocontidas, supera indexar passagens (Chen et al., 2023). Além disso, os estudos divergem. Um deles constata que o melhor tamanho depende das perguntas e do modelo de embeddings: de 64 a 128 tokens para conjuntos de dados com respostas concisas e baseadas em fatos, e de 512 a 1,024 tokens para perguntas que exigem mais contexto (Bhat et al., 2025). Outro constata que os custos computacionais da fragmentação semântica não se justificam por ganhos de desempenho consistentes (Qu et al., 2024). Uma comparação de 36 métodos classifica a fragmentação por grupos de parágrafos em primeiro lugar e constata que trechos simples de tamanho fixo em caracteres tiveram desempenho ruim como linhas de base (Shaukat et al., 2026).

Uma unidade pequena também pode perder aquilo de que trata. Um post de engenharia de um fornecedor relata que acrescentar a cada fragmento um contexto específico dele, antes de gerar seu embedding, reduziu em 35% a taxa de falha de recuperação dos 20 fragmentos principais. Essa é a afirmação do fornecedor sobre o próprio método (Anthropic, 2024).

Os produtos da loja são curtos, em parte porque o exemplo do livro corta cada descrição em cerca de 400 caracteres (cartão de dados). Das descrições, 5,933 terminam nesse corte, e 1,568 produtos não têm nenhuma.

As descrições não vazias têm mediana de 68 palavras, e todo o texto que a busca lê chega a no máximo 140 palavras por produto. As páginas completas de produto da loja seriam mais longas.

Ainda assim, cada produto é um texto curto sobre uma só coisa, de modo que cortá-lo em fragmentos não é a questão da loja. A questão é qual parte de cada produto indexar. Uma frase da descrição mostra o risco: a última frase da descrição do lustre, da verificação de suporte, diz the antler 's durability and beauty will last a lifetime ., o que nunca informa o que é o produto.

Os embeddings registrados cobrem o texto inteiro de cada produto, então testamos as unidades apenas com BM25, sobre as 50 consultas de treino, porque escolher uma unidade é uma forma de ajuste. Indexamos cinco unidades: o produto inteiro (o texto que lib.lexical indexa), só o nome, só a descrição, cada uma das 35,061 frases da descrição por si só, e cada frase com o nome, a classe e a categoria do produto à frente, uma forma simples de acrescentar contexto a cada fragmento. A última frase de uma descrição cortada é um fragmento. As frases com os demais campos mantêm todos os campos que o produto inteiro tem, e um produto sem descrição recebe uma unidade desses campos, igual ao seu texto inteiro, de modo que as duas unidades diferem apenas no corte da descrição. UnitSearch em lib.generation ordena cada produto pela sua unidade de maior pontuação, então cada execução ainda lista produtos. Informamos a precisão@5 e a revocação@5 que um contexto de cinco produtos teria, com judged@5, a parcela dos cinco primeiros que tem julgamento. UnitSearch ordena pontuações iguais por product_id, então o código também inverte essa regra e conta as consultas de treino cujos cinco primeiros mudam:

retrievable-unit-on-train.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Compares five ways of cutting products into retrievable units under BM25 on the train queries, by precision@5,recall@5 and judged@5, and counts how often ties change the top 5. The point rests on the precision@5 andrecall@5 lines for the whole product and for the sentences with the other fields."""import numpy as npfrom lib.generation import UnitSearch, sentencesfrom lib.metrics import judged_at_k, precision_at_k, recall_at_kfrom lib.store import load_products, load_queries, product_text, qrelsproducts = load_products()# words per description, counted by whitespacelengths = products["description"].str.split().str.len()print(f"products with no description: {(lengths == 0).sum():,}")# the book's sample ends a description it cut with ' ...'print(f"descriptions the sample cut short: {products['description'].str.endswith(' ...').sum():,}")# empty descriptions are left out of the medianprint(f"description words, median of the others: {lengths[lengths > 0].median():.0f}")print(f"product text words per product, most: {product_text(products).str.split().str.len().max()}")header = products["name"] + ". " + products["product_class"] + ". " + products["category"] + ". "   # the other fields# a product with no description keeps one empty piece, so it still gets a unitpieces = [(p, piece) for p, text in products["description"].items() for piece in sentences(text) or [""]]# the empty placeholders for products with no description don't countprint(f"description sentences: {sum(piece != '' for _, piece in pieces):,}")# 8171 is the chandelier from the support checkprint("last sentence of product 8171:", sentences(products.at[8171, "description"])[-1])units = {                                              # unit name: (texts to index, the product each belongs to)    "whole product": (product_text(products), products.index),    "name only": (products["name"], products.index),    "description only": (products["description"], products.index),    "sentences": ([piece for _, piece in pieces], [p for p, _ in pieces]),    "sentences with the other fields": ([header[p] + piece for p, piece in pieces], [p for p, _ in pieces]),}train, judgments = load_queries("train"), qrels("train")      # choosing a unit is tuning: train queries onlyscores = {}for name, (texts, owners) in units.items():    run = UnitSearch(list(texts), list(owners)).run(train, k=5)                    # equal scores by product_id    for metric in [precision_at_k, recall_at_k, judged_at_k]:        scores[name, metric] = np.mean([metric(run[q], judgments[q], 5) for q in train.index])        print(f"{name}, train {metric.__name__.replace('_at_k', '')}@5: {scores[name, metric]:.3f}")    flipped = UnitSearch(list(texts), [-p for p in owners]).run(train, k=5)        # negated owners: ties go to the highest ID    changed = sum(set(run[q]) != {-p for p in flipped[q]} for q in train.index)    print(f"{name}, train queries whose top 5 changes with ties reversed: {changed}")print("highest train precision@5:", max(units, key=lambda name: scores[name, precision_at_k]))for metric in [precision_at_k, recall_at_k]:    gap = scores["whole product", metric] - scores["sentences with the other fields", metric]    print(f"whole product minus sentences with the other fields, train {metric.__name__.replace('_at_k', '')}@5: {gap:.3f}")
Saídapython retrievable-unit-on-train.py
products with no description: 1,568
descriptions the sample cut short: 5,933
description words, median of the others: 68
product text words per product, most: 140
description sentences: 35,061
last sentence of product 8171: the antler 's durability and beauty will last a lifetime .
whole product, train precision@5: 0.464
whole product, train recall@5: 0.124
whole product, train judged@5: 0.940
whole product, train queries whose top 5 changes with ties reversed: 4
name only, train precision@5: 0.368
name only, train recall@5: 0.091
name only, train judged@5: 0.960
name only, train queries whose top 5 changes with ties reversed: 28
description only, train precision@5: 0.304
description only, train recall@5: 0.049
description only, train judged@5: 0.828
description only, train queries whose top 5 changes with ties reversed: 4
sentences, train precision@5: 0.272
sentences, train recall@5: 0.034
sentences, train judged@5: 0.732
sentences, train queries whose top 5 changes with ties reversed: 18
sentences with the other fields, train precision@5: 0.428
sentences with the other fields, train recall@5: 0.106
sentences with the other fields, train judged@5: 0.944
sentences with the other fields, train queries whose top 5 changes with ties reversed: 8
highest train precision@5: whole product
whole product minus sentences with the other fields, train precision@5: 0.036
whole product minus sentences with the other fields, train recall@5: 0.018
Unidade precisão@5 revocação@5 judged@5 Os cinco primeiros mudam com os empates invertidos
Produto inteiro 0.464 0.124 0.940 4
Só o nome 0.368 0.091 0.960 28
Só a descrição 0.304 0.049 0.828 4
Frases 0.272 0.034 0.732 18
Frases com os demais campos 0.428 0.106 0.944 8

A maior precisão@5 de treino fica com o valor whole product. A comparação justa é com as frases que carregam os demais campos: os mesmos campos, os mesmos produtos ao alcance, e judged@5 de 0.944 contra 0.940 do produto inteiro.

Cortar a descrição em frases custa 0.036 em precisão@5 de treino e 0.018 em revocação@5. Os empates decidem parte dessas diferenças: quando produtos empatam no quinto lugar, a regra de desempate escolhe quais chegam ao contexto, e invertê-la muda os cinco primeiros de 8 consultas de treino com as frases com os demais campos e de 4 com o produto inteiro. Leia uma diferença deste tamanho como aproximada.

As outras unidades também deixam campos de fora. A descrição sozinha nunca pode devolver os produtos sem descrição, e frases isoladas trazem muitos produtos que ninguém julgou, de modo que a precisão delas é em parte um palpite. Estes são números de treino e não testados: eles orientam uma escolha, mas não comprovam nada.

Regra prática: Quando seus itens são curtos, indexe cada item inteiro como uma unidade, como faz a loja. Quando são longos, fragmente-os, coloque o título do item à frente de cada fragmento e escolha o tamanho do fragmento nas consultas de treino pelas medidas de contexto da seção anterior. Passe ao LLM o item inteiro, ou o fragmento com seu título, para que ele saiba o que está lendo. Antes de confiar numa diferença pequena, conte as consultas cujos k primeiros mudam quando o desempate é feito no sentido inverso.

Leia as buscas de um agente a partir do seu trace

Última alteração na edição 2026.11.10

Diferentemente das respostas gravadas, um agente faz buscas por conta própria: ele é um LLM que roda em um laço e age. Uma ferramenta é uma função que o programa oferece ao modelo, descrita por um nome, uma descrição e seus parâmetros. Uma chamada de ferramenta é o pedido do modelo para executar uma ferramenta com argumentos. No laço do agente, o programa executa cada chamada de ferramenta, devolve o resultado, e o modelo decide o que fazer em seguida. No Ollama, que executava o modelo da loja, um laço de agente permite que o modelo decida quando invocar ferramentas e incorpore os resultados em suas respostas (documentação do Ollama). recordings/agent_trace.py é um desses laços. Agentes ReAct intercalam traces de raciocínio com ações específicas da tarefa. Em resposta a perguntas (HotpotQA) e verificação de fatos (Fever), com uma API da Wikipédia como ferramenta, eles superam a alucinação e a propagação de erros que são comuns no raciocínio em cadeia de pensamento (Yao et al., 2023). O trace é o registro de cada chamada de ferramenta e do seu resultado.

As buscas de um agente são consultas, e não precisam se parecer com as de um comprador. Em um registro de 14 milhões de requisições de busca feitas por agentes, mais de 90% das sessões com várias rodadas contêm no máximo dez passos, e, em média, 54% dos termos de consulta que uma busca acrescenta já aparecem nas evidências acumuladas (Ning et al., 2026). O agente aproveita palavras do que já leu.

A gravação deu ao agente cada consulta de teste como o pedido do comprador, com uma ferramenta, search, descrita como "Search the store's catalog. Returns the top 5 products: ID, name, class and attributes.". Ele pode fazer até 3 buscas, com qualquer redação, e então responder com três IDs de produtos. A ferramenta não devolve nenhuma descrição.

A gravação foi executada duas vezes, com o mesmo modelo e o mesmo prompt: uma vez com BM25 por trás da ferramenta e outra com recuperação semântica, que incorporava o texto de busca do agente com o mesmo modelo de embeddings usado para os produtos. Os traces armazenam os resultados de cada busca BM25 na ordem de empate própria do bm25s, como os contextos das respostas fazem, de modo que 7 das 32 buscas BM25 obtêm resultados diferentes dos que lib.lexical devolve, sendo 6 delas diferentes apenas na ordem. Eis o que o agente realmente buscou:

agent-searches-in-traces.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Reads the recorded agent traces for both tools: each agent's first search, how many searches each tool took, andwhether BM25's stored results match lib.lexical. The point rests on the first-search lines and the one-searchtrace counts."""from lib.lexical import LexicalSearchfrom lib.recorded import agent_traces, manifest, rag_answersfrom lib.store import load_products, load_queriesrecording, queries = manifest("agent-trace"), load_queries("test")print("tool description:", recording["prompts"]["tool"]["function"]["description"])print("searches allowed:", recording["max_searches"])traces = {(t["retriever"], t["query_id"]): t for t in agent_traces()}print("traces:", len(traces))# index 0 is the agent's first searchfirst = {key: t["searches"][0]["query"] for key, t in traces.items()}print("first searches the same under both tools:", sum(first[("bm25", q)] == first[("semantic", q)] for q in queries.index))print("first searches that keep the query as typed:", sum(first[("bm25", q)] == queries.at[q, "query"] for q in queries.index))for q in queries.index:    if first[("bm25", q)] != queries.at[q, "query"]:        print(f"first search for {queries.at[q, 'query']}: {first[('bm25', q)]}")# the five products each recorded answer read, keyed by context (semantic, bm25 or random) and querycontext = {(a.context, a.query_id): a.context_ids for a in rag_answers().itertuples()}print("traces whose first search returns the answer recording's context:",      # lists compared with ==: the same five products, in the same order      sum(t["searches"][0]["results"] == context[key] for key, t in traces.items()))for tool in ["bm25", "semantic"]:    mine = [t for (retriever, _), t in traces.items() if retriever == tool]    print(f"{tool}, searches: {sum(len(t['searches']) for t in mine)}")    print(f"{tool}, traces with one search: {sum(len(t['searches']) == 1 for t in mine)}")# `shown` is how many products the search tool returns per search (its top 5)lexical, shown = LexicalSearch(load_products()), recording["results_shown"]stored = [s for (tool, _), t in traces.items() if tool == "bm25" for s in t["searches"]]   # what the agent sawrerun = [lexical.search(s["query"], shown).index.tolist() for s in stored]                  # ties by product_iddiffer = [(s["results"], r) for s, r in zip(stored, rerun) if s["results"] != r]print("bm25 searches whose results differ from lib.lexical:", len(differ))# the same products in another order: a tie-break, not a different resultprint("bm25 searches whose results differ from lib.lexical only in order:", sum(set(a) == set(b) for a, b in differ))
Saídapython agent-searches-in-traces.py
tool description: Search the store's catalog. Returns the top 5 products: ID, name, class and attributes.
searches allowed: 3
traces: 60
first searches the same under both tools: 30
first searches that keep the query as typed: 26
first search for 48" sliding single track , barn door for laundry: 48" sliding single track barn door laundry
first search for counter top one cup hot water dispenser: counter top hot water dispenser one cup
first search for refrigerator with ice an water in door: refrigerator with ice and water in door
first search for tye dye duvet cover: tie dye duvet cover
traces whose first search returns the answer recording's context: 55
bm25, searches: 32
bm25, traces with one search: 29
semantic, searches: 35
semantic, traces with one search: 27
bm25 searches whose results differ from lib.lexical: 7
bm25 searches whose results differ from lib.lexical only in order: 6

A primeira busca é a mesma nas duas ferramentas para 30 consultas, como esperado: o agente a escreve antes de a ferramenta ter devolvido qualquer coisa, a partir do mesmo prompt e da mesma descrição de ferramenta, com temperatura 0. Ele mantém a consulta como digitada em 26 delas.

Entre as demais, uma corrige um erro de digitação: tye dye duvet cover vira tie dye duvet cover. Outra corrige um erro de palavra real que o corretor do capítulo 8 não detecta: an vira and em refrigerator with ice and water in door. Tanto an quanto and são palavras vazias para o BM25 (capítulo 5), de modo que apenas a recuperação semântica percebe essa mudança. As outras duas viram 48" sliding single track barn door laundry e counter top hot water dispenser one cup.

Em 55 dos 60 traces, a primeira busca devolve exatamente os cinco produtos que a gravação de respostas colocou em seu contexto.

O agente raramente volta a olhar. Com BM25, ele faz 32 buscas no total, e 29 traces param após uma. Com recuperação semântica, faz 35, e 27 param após uma.

De onde vêm as palavras de uma busca posterior? Para descobrir, compare cada busca posterior com as palavras já buscadas e com os nomes, classes e atributos que a ferramenta havia mostrado:

agent-later-searches.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Counts the words each later search adds to the agent's query so far, and how many of those the tool had alreadyshown. The point rests on the "words the tool had shown" line for each tool."""from lib.generation import shown, wordsfrom lib.recorded import agent_tracesfrom lib.store import load_products, load_queriesproducts, queries = load_products(), load_queries("test")for tool in ["bm25", "semantic"]:    later = new = from_results = 0    for trace in (t for t in agent_traces() if t["retriever"] == tool):        # words are lowercase runs of letters and digits, so case and punctuation don't count        asked, seen = words(queries.at[trace["query_id"], "query"]), set()        for number, search in enumerate(trace["searches"]):            if number > 0:                                    # a later search: the words it adds, and where from                added = words(search["query"]) - asked                later, new, from_results = later + 1, new + len(added), from_results + len(added & seen)            # every word the agent has searched so far            asked |= words(search["query"])            # what the tool showed for that search: name, class and attributes, but no description            seen |= words(shown(search["results"], products))    print(f"{tool}, later searches: {later}")    print(f"{tool}, words that later searches add: {new}")    print(f"{tool}, of those, words the tool had shown: {from_results}")
Saídapython agent-later-searches.py
bm25, later searches: 2
bm25, words that later searches add: 2
bm25, of those, words the tool had shown: 1
semantic, later searches: 5
semantic, words that later searches add: 4
semantic, of those, words the tool had shown: 4

As buscas posteriores acrescentam poucas palavras próprias. Com BM25, 2 buscas posteriores acrescentam 2 palavras, 1 delas mostradas pela ferramenta antes. Com recuperação semântica, 5 buscas posteriores acrescentam 4 palavras, 4 delas mostradas antes. Contagens tão pequenas descrevem estes traces; elas não são uma taxa para comparar com a de Ning et al.

Regra prática: Leia os traces antes de avaliar um agente. Conte as buscas por tarefa, compare cada busca com as palavras do comprador e descubra de onde vêm as palavras acrescentadas. Acrescente as buscas do agente às consultas com que você testa o seu recuperador, pontuadas com os julgamentos para o pedido do comprador ou julgadas novamente, porque um recuperador ajustado às consultas das pessoas não foi testado com as consultas de um agente. Espere que um agente que, em sua maioria, repassa as palavras do comprador seja limitado pela mesma recuperação de uma resposta RAG.

Compare os recuperadores por trás da ferramenta do agente

Última alteração na edição 2026.11.8

Um agente que pode buscar de novo pode parecer tornar o recuperador menos importante. Um benchmark mediu o contrário. O BrowseComp-Plus fixa a coleção que os agentes buscam, de modo que os recuperadores possam ser trocados dentro de um mesmo agente. Com BM25, o GPT-5 alcança 55.9%, e com o recuperador Qwen3-Embedding-8B chega a 70.1%, fazendo menos chamadas de busca em média, 21.74 contra 23.23 (Chen et al., 2025, Tabela 1). Compras são uma tarefa clássica para agentes. O WebShop abriga 1.18 milhão de produtos do mundo real, e o melhor modelo de seus autores, em 2022, alcançou uma taxa de sucesso na tarefa de 29%, contra 59% para especialistas humanos (Yao et al., 2022). No WebMall, quatro lojas simuladas, seus autores relatam que os melhores agentes concluem tarefas em taxas abaixo de 65%, em buscas pelo produto mais barato e por produtos descritos de forma vaga (Peeters et al., 2025).

Um agente instruído a escolher entre os resultados de sua busca deve escolher apenas o que eles retornam, e seu rastro mostra se ele fez isso. Suas escolhas ficam então limitadas pela recuperação, assim como uma resposta de RAG.

O registro do agente da loja busca no catálogo até 3 vezes com uma única ferramenta e, em seguida, escolhe três produtos. Pontuar essas escolhas sob cada ferramenta, por precision@3, é a segunda das comparações planejadas do capítulo, estabelecida se seu valor-p de permutação estiver abaixo de 0.025. Precision@3 é o número de escolhas exatas dividido por 3, de modo que uma escolha ausente conta como falha. Primeiro, conte onde as falhas ocorreram, para cada ferramenta: escolhas que a ferramenta nunca retornou, escolhas que ninguém avaliou, rastros com menos de três escolhas, rastros cujas buscas não retornaram nenhum produto exato e rastros que viram um produto exato e não escolheram nenhum. Depois, compare as escolhas com o top 3 da própria ferramenta para a primeira busca, uma verificação exploratória:

agent-picks-by-tool.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Scores each tool's agent picks with precision@3 and counts how the traces went, with an exploratory checkagainst the tool's first search. The point rests on the precision@3 lines and the picks-the-tool-never-returnedcounts."""import pandas as pdfrom lib.generation import EXACT, report_plannedfrom lib.metrics import precision_at_kfrom lib.recorded import agent_tracesfrom lib.significance import comparefrom lib.store import qrelsjudgments, picks, top_three, below = qrels("test"), {}, {}, 0for tool in ["bm25", "semantic"]:    traces = [t for t in agent_traces() if t["retriever"] == tool]    # every product any of the agent's searches returned    returned = [{p for search in t["searches"] for p in search["results"]} for t in traces]    # exact products each trace's searches returned; a product nobody judged counts as not exact    seen = [sum(judgments[t["query_id"]].get(p, 0) == EXACT for p in r) for t, r in zip(traces, returned)]    picked = [sum(judgments[t["query_id"]].get(p, 0) == EXACT for p in t["picked"]) for t in traces]    print(f"{tool}, picks the tool never returned: {sum(len(set(t['picked']) - r) for t, r in zip(traces, returned))}")    print(f"{tool}, picks nobody judged: {sum(p not in judgments[t['query_id']] for t in traces for p in t['picked'])}")    print(f"{tool}, traces with fewer than three picks: {sum(len(t['picked']) < 3 for t in traces)}")    print(f"{tool}, traces whose searches returned no exact product: {sum(s == 0 for s in seen)}")    print(f"{tool}, traces that saw an exact product and picked none: {sum(s > 0 and k == 0 for s, k in zip(seen, picked))}")    # precision_at_k divides by 3, so a trace with fewer picks scores lower    picks[tool] = pd.Series({t["query_id"]: precision_at_k(t["picked"], judgments[t["query_id"]], 3) for t in traces})    # index 0 is the agent's first search    top_three[tool] = pd.Series({t["query_id"]: precision_at_k(t["searches"][0]["results"], judgments[t["query_id"]], 3)                                 for t in traces})               # the tool's own top 3 for the first search    print(f"{tool}, precision@3 of the picks: {picks[tool].mean():.3f}")    print(f"{tool}, precision@3 of the first search's top 3: {top_three[tool].mean():.3f}")    p_value = compare(picks[tool], top_three[tool])["permutation p"]    print(f"{tool}, picks against the top 3, exploratory permutation p: {p_value:.3f}")    # uncorrected: this check is exploratory, not one of the planned comparisons    below += p_value < 0.05print(f"picks against the top 3, p-values below 0.05 uncorrected: {below} of 2")report_planned("agent picks, semantic over bm25", picks["semantic"], picks["bm25"])
Saídapython agent-picks-by-tool.py
bm25, picks the tool never returned: 0
bm25, picks nobody judged: 3
bm25, traces with fewer than three picks: 2
bm25, traces whose searches returned no exact product: 5
bm25, traces that saw an exact product and picked none: 6
bm25, precision@3 of the picks: 0.567
bm25, precision@3 of the first search's top 3: 0.500
bm25, picks against the top 3, exploratory permutation p: 0.152
semantic, picks the tool never returned: 0
semantic, picks nobody judged: 0
semantic, traces with fewer than three picks: 0
semantic, traces whose searches returned no exact product: 5
semantic, traces that saw an exact product and picked none: 2
semantic, precision@3 of the picks: 0.622
semantic, precision@3 of the first search's top 3: 0.633
semantic, picks against the top 3, exploratory permutation p: 1.000
picks against the top 3, p-values below 0.05 uncorrected: 0 of 2
agent picks, semantic over bm25, mean difference: 0.056
agent picks, semantic over bm25, wins, losses, ties: 5, 4, 21
agent picks, semantic over bm25, permutation p: 0.422
agent picks, semantic over bm25, established at 0.025: no
agent picks, semantic over bm25, t-test p: 0.305
agent picks, semantic over bm25, t-test agrees: yes
agent picks, semantic over bm25, 97.5% interval: -0.033 to 0.209
agent picks, semantic over bm25, interval agrees: yes

As duas ferramentas não mostram diferença estabelecida em suas escolhas. Precision@3 é 0.622 com recuperação semântica e 0.567 com BM25, e o valor-p de permutação da diferença é 0.422 (ambas as comparações). Com este modelo, este prompt e estas consultas de teste, isso não é evidência de que o recuperador não importa, apenas de que estas consultas não mostram diferença.

Contadas da mesma forma para cada ferramenta, as falhas aparecem nestes tipos. Escolhas que a ferramenta nunca retornou somam 0 com BM25 e 0 com recuperação semântica, de modo que o limite se mantém. A recuperação também limita as escolhas: em 5 rastros com BM25 e 5 com recuperação semântica, nenhuma busca retornou um produto exato, de modo que nenhuma escolha poderia ser exata.

As outras falhas estão nas próprias escolhas. Com BM25, o agente viu um produto exato e não escolheu nenhum em 6 rastros, contra 2 com recuperação semântica; 3 de suas escolhas não foram avaliadas, contra 0; e 2 rastros têm menos de três escolhas, contra 0. Escolhas não avaliadas e escolhas ausentes contam ambas como falhas.

As escolhas do agente têm a mesma leitura sob cada ferramenta. O top 3 da própria ferramenta para a primeira busca pontua 0.500 com BM25 e 0.633 com recuperação semântica. As escolhas medidas contra esse top 3 obtêm valores-p de permutação de 0.152 com BM25 e 1.000 com recuperação semântica, e 0 of 2 ficam abaixo de 0.05 sem correção. Escolhemos a verificação depois de ver os resultados dos testes, por isso ela nunca fica estabelecida.

Regra prática: Teste o recuperador por trás da ferramenta de um agente da mesma forma que o testaria para pessoas, nas buscas do próprio agente e em suas escolhas finais, pontuadas com avaliações humanas. Verifique que cada escolha veio de um resultado de ferramenta. Conte as tarefas em que a ferramenta nunca retornou um produto relevante, pois nenhum agente pode corrigir isso, e só a recuperação pode.

O que dá errado em produção

Última alteração na edição 2026.11.8

Um assistente em funcionamento responde a cada cliente com uma nova chamada ao modelo, sobre um contexto que a recuperação monta para aquela requisição.

O modelo, o prompt e o contexto formam um único sistema. Uma versão diferente do modelo, um prompt reescrito, outro tamanho de contexto ou outra ordem de produtos podem alterar cada resposta. Os manifestos da loja fixam o digest do modelo, os prompts, os esquemas das respostas e das ferramentas e a janela de contexto. Ao mudar qualquer um deles, avalie as respostas novamente, com os mesmos julgamentos e o piso aleatório. Guarde as respostas brutas e cada contexto, como fazem as gravações.

A verificação de citações pertence ao caminho da resposta. A verificação de IDs é barata, então execute-a em cada resposta antes que o cliente a veja, e registre cada falha junto com a resposta e o seu contexto.

As abstenções acompanham a recuperação. Acompanhe a proporção de respostas que não recomendam nada. Nos contextos aleatórios da loja, 29 das 30 respostas não recomendam nada, então um aumento nessa proporção pode significar que a recuperação ou o catálogo mudou. Leia essas respostas antes de presumir que o modelo mudou.

O texto dos produtos chega ao prompt. As descrições de produtos podem vir de fora da sua equipe, e o LLM as lê como parte da sua entrada. O capítulo 4 cita um estudo em que palavras e instruções inseridas em um texto induziram juízes LLM ao erro. Teste o assistente com produtos cujo texto contenha instruções antes de confiar nele para um catálogo que você não escreve.

Contextos mais longos mudam a resposta. Aumentar k alonga o contexto e traz mais distratores, e ambos podem prejudicar (Liu et al., 2024; Jin et al., 2024). Meça as respostas em cada configuração com consultas de treino.

O tráfego de agentes é uma carga de trabalho diferente. Nos registros que Ning et al. estudaram, os agentes enviam muitas consultas geradas por máquina a cada tarefa, enquanto o agente da loja enviou, na maioria das vezes, apenas uma. Um estudo alerta que, com tráfego de agentes, o cache pode perder eficácia, e o pré-processamento de consultas pode acrescentar sobrecarga sem melhorar os resultados (Pezzuti et al., 2026). Registre as buscas dos agentes separadamente das buscas das pessoas, e teste o recuperador com as duas.

Regra prática: Versione o modelo, o prompt e as configurações de contexto junto com as respostas, verifique as citações em cada resposta, acompanhe as abstenções e mantenha as buscas dos agentes em um conjunto de teste próprio.

Decisões tomadas neste capítulo

Última alteração na edição 2026.11.8

Somente uma comparação planejada estabelecida poderia ter mudado o recuperador da loja, e a linha Estabelecida da tabela indica se cada uma delas é estabelecida.

As 2 comparações planejadas do capítulo, recuperação semântica menos BM25 nas consultas de teste, estabelecidas abaixo de 0.025:

Medida Respostas, parcela exata média Escolhas do agente, precision@3
Semântico 0.658 0.622
BM25 0.639 0.567
Diferença média 0.019 0.056
Vitórias / derrotas / empates 4, 5, 21 5, 4, 21
p de permutação 0.765 0.422
Estabelecida no no
p do teste t 0.715 0.305
Intervalo de 97.5% -0.078 to 0.161 -0.033 to 0.209
Teste t concorda yes yes
Intervalo concorda yes yes
  • O contexto: cinco produtos inteiros da recuperação semântica, o ranqueador a superar. Cinco é a configuração fixa da gravação, não testada. As respostas não mostram diferença estabelecida entre a recuperação semântica e o BM25; por isso, o recuperador se apoia na vantagem estabelecida no capítulo 3 em nDCG@10.
  • Respostas avaliadas por notas humanas: a parcela exata do que cada resposta cita, com as respostas que não recomendam nada contadas ao lado dela, e um contexto aleatório como piso.
  • Citações verificadas por ID em cada resposta. A gravação passa na verificação, e ela permanece. Verificações de suporte, por modelo de NLI ou por juiz LLM, só contam quando calibradas em uma amostra humana.
  • Contexto medido por precision@5 e precisão de contexto a partir dos julgamentos, com recall@5 ao lado, porque o recall@5 de um contexto de cinco produtos não pode chegar a 1 quando uma consulta tem mais de cinco produtos exatos.
  • A unidade recuperável: o produto inteiro. Ela tem a maior precision@5 de treino, e dividir as descrições em frases, mesmo com os outros campos à frente, custa 0.036.
  • Ferramenta do agente: os mesmos recuperadores, testados nas buscas e escolhas do agente. As escolhas não mostram diferença estabelecida entre as ferramentas, e cada escolha veio do que a ferramenta devolveu.
  • Escopo: um modelo, dois prompts, as consultas de teste. Toda conclusão sobre o LLM refere-se a gemma4:12b-it-q4_K_M com os prompts registrados. Um modelo ou prompt diferente é uma mudança a ser avaliada novamente, assim como a troca de recuperador.
  • O que o capítulo mostrou: uma verificação de citação mostra que um produto estava diante do modelo, não que ele se adequa. Um ganho de ranqueamento precisa ser testado nas respostas que ele alimenta.

Este capítulo, nesta edição

Edição 2026.11.10Exemplos aprovados em 19 de nov de 202610 de 10 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.10.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 10 de 11: Recuperação para aplicações de LLM

  1. Coloque os produtos recuperados no prompt
  2. Pontue cada resposta pelos produtos que ela cita
  3. Verifique cada citação contra o contexto
  4. Verifique o que o produto citado sustenta
  5. Meça o contexto e depois a resposta
  6. Escolha a unidade recuperável
  7. Leia as buscas de um agente a partir do seu trace
  8. Compare os recuperadores por trás da ferramenta do agente
  9. O que dá errado em produção
  10. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos