Compreendendo consultas

Cerca de 45 minutos min de leitura, com 12 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 alterar a consulta de um comprador antes da recuperação: corrigir sua grafia, escrever suas unidades de um único modo, expandi-la com sinônimos, prever sua classe de produto, reescrevê-la com um modelo de linguagem grande, buscar com um produto que esse modelo imagina e transformar uma consulta de acompanhamento em uma consulta independente. Você também poderá decidir, a partir de julgamentos humanos, se cada alteração ajuda o recuperador que a recebe.

Algumas das consultas curtas que os compradores digitam na caixa de busca da loja não conseguem encontrar os produtos que eles querem. ligth bulb tem uma palavra grafada errada. 7qt slow cooker escreve o tamanho com um termo que aparece em 0 produtos. Para midcentury tv unit, o capítulo 7 conta 25 produtos exatos, dos quais 0 contêm midcentury e 0 contêm unit.

Um comprador que digita in white depois de buscar uma mesa quer dizer uma mesa branca, mas as palavras, por si sós, não dizem isso. Compreensão de consultas é tudo o que um sistema de busca faz com a consulta antes da recuperação para fechar lacunas como essas: ele corrige, normaliza, expande, classifica e reescreve. Os capítulos 5 a 7 alteraram os recuperadores. Este capítulo altera a consulta e mantém os recuperadores fixos: BM25, a linha de base sem radicalização do livro em lib.lexical, e recuperação semântica, que compara o embedding da consulta com o de cada produto, ambos calculados antecipadamente por Snowflake/snowflake-arctic-embed-m-v1.5.

Três das técnicas usam o LLM da loja. Trata-se de gemma4:12b-it-q4_K_M, um modelo aberto que o Google publica sob a licença Apache 2.0 (cartão do modelo). Nenhum exemplo o chama. Dois scripts, recordings/llm_rewrites.py e recordings/llm_conversations.py, o executaram uma vez, com temperatura 0 e semente fixa, e salvaram suas saídas como gravações, que os exemplos leem por meio de lib.recorded. O manifest.json de cada gravação contém os prompts completos. As gravações usam o mesmo modelo aberto e as mesmas configurações do capítulo 4. O LLM vê apenas as palavras do comprador, nunca um produto. Todas as pontuações do capítulo usam os julgamentos humanos.

Toda configuração é escolhida nas 50 consultas de treino, e as 30 consultas de teste são reservadas para o relato dos resultados. O capítulo fixou suas 5 comparações planejadas sobre as consultas de teste antes de ler qualquer um dos seus resultados. Cada uma é um recuperador com uma única mudança, medido contra o mesmo recuperador com a consulta como foi digitada:

  1. BM25 com uma lista de sinônimos
  2. recuperação semântica com um reforço para a classe prevista
  3. BM25 sobre a reescrita do LLM
  4. recuperação semântica sobre a reescrita do LLM
  5. recuperação semântica com HyDE, que calcula a média entre o embedding da consulta e o de um produto que o LLM imagina

Cada comparação planejada deve atender à regra do livro: um valor-p abaixo de 0.01 no seu teste de permutação pareado, que é 0.05 dividido pelo número de comparações planejadas. O teste t pareado e um intervalo de bootstrap de 99% a acompanham. A correção ortográfica, a normalização de unidades e a reescrita de consultas de acompanhamento atingem cada uma consultas em número insuficiente para serem testadas, por isso suas seções são exploratórias.

Corrija a ortografia com base nas palavras do catálogo

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

A primeira lacuna é um erro de digitação, como em ligth bulb. No BM25, uma palavra com grafia errada só casa com produtos que tenham o mesmo erro de grafia, e ela pode afastar o embedding da consulta dos produtos que ela pretende dizer, como o capítulo 6 mostra. As consultas de busca trazem muitos desses erros. Um estudo sobre busca na web, Cucerzan and Brill (2004), relata que cerca de 10 a 15 por cento das consultas enviadas a máquinas de busca contêm erros. O corretor clássico é o modelo de canal ruidoso: para uma palavra digitada t, escolha a correção c que maximiza P(c) × P(t | c) (Kernighan et al., 1990). P(c) indica quão comum é a palavra candidata. P(t | c), o modelo de erro, indica quão provável é que um comprador que quis dizer c digite t. Kernighan et al. tomam como candidatas as palavras a uma edição do erro de digitação: a remoção, a inserção, a substituição ou a troca de duas letras vizinhas. O número de inserções, remoções e substituições que transformam uma cadeia em outra é a sua distância de edição (Manning et al., 2008), e o corretor aqui também conta uma troca como uma edição. Um livro-texto enuncia os dois princípios em termos simples: entre as grafias corretas, escolha a mais próxima e, entre empates próximos, escolha a mais comum (Manning et al., 2008). Norvig escreve esse tipo de corretor em poucas linhas (Norvig).

correction(t) = argmax over candidates c of  P(c) × P(t | c)

O léxico, a lista de palavras que valem como corretas, decide o que será corrigido. As máquinas de busca na web constroem os seus a partir de registros de consultas, de modo que a correção que escolhem é a mais comum entre as consultas de outros usuários (Manning et al.). A loja não tem registro, então o seu léxico vem do texto do catálogo. A origem do léxico importa para nomes de marcas, porque um corretor em busca de produtos precisa distinguir erros de grafia genuínos de marcas novas escritas de forma não convencional (Guo et al., 2024).

O corretor aqui usa o modelo de erro mais simples: uma palavra que está no léxico permanece, uma edição vence duas, e P(c), o quanto cada candidata é comum, desempata entre candidatas à mesma distância de edições. Execute-o sobre todas as 80 consultas e veja quais ele altera:

catalog-spelling-corrector.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""A spelling corrector built from the catalog's word counts, run on every query and checked againstlib.queries.correct_query. The prose's point rests on the "queries changed" line and on the line that says whether both correctors agree."""import refrom collections import Counterfrom lib.queries import correct_queryfrom lib.store import load_products, load_queries, product_texttexts = product_text(load_products()).str.lower()counts = Counter(re.findall(r"[a-z]+", " ".join(texts)))       # the lexicon, and how common each word isdef edits1(word):    """Every string one edit away: a deletion, a swap of two neighbouring letters, a replacement or an insertion."""    splits = [(word[:cut], word[cut:]) for cut in range(len(word) + 1)]    letters = "abcdefghijklmnopqrstuvwxyz"    return ({left + right[1:] for left, right in splits if right}            | {left + right[1] + right[0] + right[2:] for left, right in splits if len(right) > 1}            | {left + letter + right[1:] for left, right in splits if right for letter in letters}            | {left + letter + right for left, right in splits for letter in letters})def correct(word):    """Keep a word the catalog uses. Otherwise take the commonest catalog word one edit away, else two."""    if not word.isalpha() or word in counts:        return word    candidates = {edit for edit in edits1(word) if edit in counts} or {        two for edit in edits1(word) for two in edits1(edit) if two in counts}    # the most common candidate; on a tie in counts, the alphabetically first one    return max(sorted(candidates), key=counts.get) if candidates else wordqueries = load_queries()corrected = queries["query"].map(lambda query: " ".join(correct(word) for word in query.lower().split()))changed = queries[corrected != queries["query"].str.lower()]print(f"catalog words: {len(counts):,}")print("queries changed:", len(changed))print("of them, train queries:", (changed["split"] == "train").sum())for query_id, query in changed["query"].items():    print(f"  {query} ({changed.at[query_id, 'split']}), corrected: {corrected[query_id]}")same = corrected.equals(queries["query"].map(lambda query: correct_query(query, counts)))print("same as lib.queries.correct_query:", same)for word in ["tye", "tie", "the", "kohler", "whitehaven", "malachi", "luau"]:      # P(c), as counts    print(f"catalog count of {word}:", counts[word])
Saídapython catalog-spelling-corrector.py
catalog words: 19,680
queries changed: 4
of them, train queries: 3
  foutains with brick look (train), corrected: fountains with brick look
  twin over full bunk beds cool desins (train), corrected: twin over full bunk beds cool designs
  ligth bulb (train), corrected: light bulb
  tye dye duvet cover (test), corrected: the dye duvet cover
same as lib.queries.correct_query: True
catalog count of tye: 0
catalog count of tie: 45
catalog count of the: 20389
catalog count of kohler: 71
catalog count of whitehaven: 60
catalog count of malachi: 5
catalog count of luau: 4

O catálogo usa 19,680 palavras distintas, e o corretor altera 4 consultas. Dessas, 3 são consultas de treino. A função compartilhada lib.queries.correct_query faz as mesmas correções, e o corretor grafa cada consulta de treino como fazem as sondagens de ortografia do capítulo 6: as cópias com grafia correta das consultas com erro de digitação que o capítulo 6 escreveu para o livro.

O corretor não mexe nas marcas, porque o catálogo as usa: kohler 71 vezes e whitehaven 60. Algumas palavras que ele mantém são raras, como malachi, usada 5 vezes, e luau, usada 4. Um léxico que deixasse de fora as palavras raras trataria as duas como erros de digitação.

As falhas do corretor estão nas consultas de teste. tye dye duvet cover vira the dye duvet cover: tye está a uma edição de tie (45 vezes no catálogo) e de the (20389), e P(c) escolhe a palavra comum. E refrigerator with ice an water in door mantém o seu an. Esse an é um erro de palavra real, um erro de digitação em que todas as palavras estão escritas corretamente, como em "flew form Heathrow" (Manning et al., 2008). Os dois casos precisam de contexto. Para tye e para an, conte com que frequência cada palavra do catálogo a uma edição dele vem logo antes da palavra seguinte da consulta, dye ou water:

spelling-context-counts.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""For the misspelled word in two test queries, `tye` and the real-word error `an`, counts how often each nearby catalog word comes before the query's nextword, and shows the context-free corrector's choice. The prose's point rests on the "catalog count of ... thecorrector's choice" lines."""import refrom collections import Counterfrom lib.queries import correct_word, edits1, word_countsfrom lib.store import load_products, product_texttexts = product_text(load_products()).str.lower()counts = word_counts(texts)                                   # the corrector's lexiconwords_per_product = [re.findall(r"[a-z]+", text) for text in texts]pairs = Counter(pair for words in words_per_product for pair in zip(words, words[1:]))      # neighbouring words# tye in "tye dye duvet cover", an in "refrigerator with ice an water in door": each word, the word after itfor word, after in [("tye", "dye"), ("an", "water")]:    # the typed word and each catalog word one edit away, ranked by how often each comes before the next word    options = sorted(((pairs[(edit, after)], edit) for edit in edits1(word) | {word} if edit in counts), reverse=True)    for count, edit in options[:3]:        print(f"catalog count of {edit} {after}:", count)    choice = correct_word(word, counts)                        # what the corrector without context picks    print(f"the corrector's choice for {word}: {choice}")    print(f"catalog count of {choice} {after}, the corrector's choice:", pairs[(choice, after)])
Saídapython spelling-context-counts.py
catalog count of tie dye: 18
catalog count of type dye: 0
catalog count of tyke dye: 0
the corrector's choice for tye: the
catalog count of the dye, the corrector's choice: 0
catalog count of and water: 59
catalog count of a water: 20
catalog count of in water: 9
the corrector's choice for an: an
catalog count of an water, the corrector's choice: 0

Antes de dye, o texto do catálogo tem tie 18 vezes, e a escolha do corretor, the, 0. Antes de water, and aparece 59 vezes, à frente de a com 20, enquanto an, a escolha do corretor, tem 0. Para essas duas consultas, um corretor que pontuasse cada candidata com a palavra vizinha escolheria tie e and. Cada consulta corrigida agora pode ser pontuada com os seus próprios julgamentos, o que mostra se a mudança ajuda:

measure-spelling-corrections.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Scores each typo query, and the variant spelling tye dye, with BM25, and with recorded embeddings where the correctedtext has one, as typed and as corrected. The prose's point rests on the nDCG@10 lines for queries 20 and 224 (train) and the corrected BM25 line for 459 (test)."""from lib.lexical import LexicalSearchfrom lib.metrics import ndcg_at_kfrom lib.queries import correct_query, word_countsfrom lib.recorded import probesfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, product_text, qrelsproducts, queries, judgments = load_products(), load_queries(), qrels()counts = word_counts(product_text(products))bm25, semantic = LexicalSearch(products), SemanticSearch()probe_queries, probe_vectors = probes()      # recorded embeddings of the four typo queries, spelled correctlyspelling = probe_queries[probe_queries["kind"] == "spelling"]# the probes' embeddings, keyed by the correctly spelled text, so a corrected query can find its ownspelled = {row["query"]: probe_vectors[index] for index, row in spelling.iterrows()}typo_queries = spelling["of_query_id"].astype(int).tolist()print("typo queries:", len(typo_queries))print("of them, test queries:", (queries.loc[typo_queries, "split"] == "test").sum())for query_id in typo_queries + [459]:        # the typo queries, then the one variant spelling, tye dye    typed = queries.at[query_id, "query"]    corrected = correct_query(typed, counts)    label = f"{query_id} ({queries.at[query_id, 'split']})"    print(f"{label}: {typed} -> {corrected}")    for name, text in [("typed", typed), ("corrected", corrected)]:        ranking = list(bm25.search(text, k=10).index)        print(f"{label}, bm25 ndcg@10 {name}: {ndcg_at_k(ranking, judgments[query_id], 10):.3f}")    if corrected == typed.lower():        print(f"{label}: the corrector changes nothing")    elif corrected in spelled:        for name, vector in [("typed", semantic.query_vectors[query_id]), ("corrected", spelled[corrected])]:            ranking = list(semantic.search_vector(vector, k=10).index)            print(f"{label}, semantic ndcg@10 {name}: {ndcg_at_k(ranking, judgments[query_id], 10):.3f}")    else:        print(f"{label}: no recorded embedding of the corrected text")
Saídapython measure-spelling-corrections.py
typo queries: 4
of them, test queries: 1
305 (train): ligth bulb -> light bulb
305 (train), bm25 ndcg@10 typed: 0.945
305 (train), bm25 ndcg@10 corrected: 0.945
305 (train), semantic ndcg@10 typed: 1.000
305 (train), semantic ndcg@10 corrected: 1.000
20 (train): foutains with brick look -> fountains with brick look
20 (train), bm25 ndcg@10 typed: 0.356
20 (train), bm25 ndcg@10 corrected: 0.507
20 (train), semantic ndcg@10 typed: 0.353
20 (train), semantic ndcg@10 corrected: 0.645
224 (train): twin over full bunk beds cool desins -> twin over full bunk beds cool designs
224 (train), bm25 ndcg@10 typed: 0.488
224 (train), bm25 ndcg@10 corrected: 0.488
224 (train), semantic ndcg@10 typed: 0.565
224 (train), semantic ndcg@10 corrected: 0.616
406 (test): refrigerator with ice an water in door -> refrigerator with ice an water in door
406 (test), bm25 ndcg@10 typed: 0.501
406 (test), bm25 ndcg@10 corrected: 0.501
406 (test): the corrector changes nothing
459 (test): tye dye duvet cover -> the dye duvet cover
459 (test), bm25 ndcg@10 typed: 0.953
459 (test), bm25 ndcg@10 corrected: 0.953
459 (test): no recorded embedding of the corrected text

A correção importa mais para foutains with brick look (treino). A recuperação semântica passa de 0.353 para 0.645, e a BM25 de 0.356 para 0.507.

Dos outros dois erros de digitação de treino, twin over full bunk beds cool desins altera apenas a recuperação semântica, de 0.565 para 0.616, e ligth bulb não altera nenhum dos dois recuperadores. Para refrigerator with ice an water in door, o corretor não muda nada, e uma correção certa também não poderia ajudar a BM25. Do an digitado e do and correto, o bm25s descarta an, and como palavras de parada, e a cópia da consulta do capítulo 6 escrita com and obtém 0.501, a mesma pontuação da consulta como digitada.

Para tye dye duvet cover, a BM25 obtém 0.953 de qualquer forma, porque the é uma palavra de parada e tye não casa com nenhum produto, de modo que as duas versões buscam os mesmos termos. A recuperação semântica não pode ser pontuada no texto corrigido, porque as gravações não têm embedding dele. A loja tem 4 consultas com erro de digitação, das quais 1 são consultas de teste, e o menor valor-p de permutação bilateral que tão poucas podem dar é 0.125.

Regra prática: Construa o léxico a partir do seu catálogo e, quando tiver um, do seu registro de consultas, e corrija apenas as palavras que ele não contém, para que os nomes de marcas sobrevivam. Antes de corrigir uma palavra, verifique as palavras vizinhas: um corretor sem contexto transforma grafias variantes em palavras comuns e deixa passar erros de palavra real. Pontue cada correção com os julgamentos das próprias consultas com erro de digitação, e reúna muito mais consultas com erro de digitação do que a loja tem antes de testar um corretor.

Normalize as unidades do jeito que o catálogo as escreve

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

Um erro de digitação tem uma grafia correta; um tamanho, como em 7qt slow cooker, costuma ter várias. Normalização mapeia as diferentes formas de escrever uma mesma coisa para uma única forma, tanto nos produtos quanto na consulta. Os tamanhos neste catálogo precisam disso. Capítulo 5 constatou que 7qt e 7 qt nunca correspondem um ao outro, porque o tokenizador descarta o 7, que tem um único caractere. Um normalizador que une cada número à sua unidade, escrita de uma só forma, transforma os dois em um único termo, 7qt. Ele precisa ser aplicado ao texto dos produtos ao construir o índice, e a cada consulta. Ele também precisa produzir termos que o tokenizador mantenha inteiros. O tokenizador divide palavras no ponto decimal, então 3.7qt se tornaria 7qt. Para evitar isso, a função compartilhada lib.queries.normalize_units escreve o ponto como sublinhado, que o tokenizador mantém dentro de uma palavra. Ela também deixa in intacto quando um número ou one vem depois, como em 3 in 1.

Uma regra escrita a partir das consultas cobriria qt, in, inch e ". Antes de confiar nela, conte como o catálogo escreve as polegadas. Primeiro as contamos, imprimimos os termos que o tokenizador produz de alguns textos normalizados e construímos o BM25 três vezes: sobre o texto como foi escrito, normalizado pela primeira regra e normalizado por normalize_units, que também trata as duas aspas simples do catálogo, '', para polegadas. Avaliamos toda consulta, de treino ou de teste, que informe um número com uma unidade:

normalize-units-both-sides.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Counts how the catalog writes inches, prints the terms the tokenizer makes of normalized texts, and scores BM25 onevery query with a unit under three rules. The prose's point rests on the "bm25 ndcg@10" lines for queries 62 and 482."""from lib.lexical import LexicalSearchfrom lib.lexical_by_hand import tokenizefrom lib.metrics import ndcg_at_kfrom lib.queries import INCH_SPELLINGS, normalize_units, unit_rulesfrom lib.store import load_products, load_queries, product_text, qrelsproducts, queries, judgments = load_products(), load_queries(), qrels()text = product_text(products).str.lower()# the catalog's spellings of inches after a number; -? also takes a hyphen, as in 48-inchfor name, unit in [("''", r"''"), ('"', r"\""), ("inch", r"-?inch")]:    print(f"products that write a number then {name}:", text.str.contains(rf"\d\s*{unit}").sum())# the first rule, written from the queries' units: lib's inch spellings (inches, inch, in, ") without the two apostrophes; quarts are always includedfirst_try = unit_rules([spelling for spelling in INCH_SPELLINGS if spelling != "''"])   # written from queries# None leaves the text as written, with no normalizationrules = {"as written": None, "first try": first_try, "normalized": unit_rules()}checks = [("3.7-quart slow cooker", "normalized"), ("3 in 1 sofa bed", "normalized"), ("1 in twin", "normalized"),          ("48 '' range hood", "first try"), ("48 '' range hood", "normalized")]for example, name in checks:                                                   # what the tokenizer reads    print(f"terms of {example}, {name}:", " ".join(tokenize(normalize_units(example, rules[name]))))searches = {}for name, rule in rules.items():    rewritten = products.copy()    if rule is not None:        for column in ["name", "product_class", "category", "description"]:   # the columns product_text joins            rewritten[column] = rewritten[column].map(lambda value: normalize_units(value, rule))    searches[name] = LexicalSearch(rewritten)# queries with a number and a unit: qt, in, inch or a double quotewith_units = queries[queries["query"].str.contains(r"\d\s*(?:qt|in\b|inch|\")")]print("queries with a unit:", len(with_units))print("of them, test queries:", (with_units["split"] == "test").sum())for query_id, query in with_units["query"].items():    label = f"{query_id} ({queries.at[query_id, 'split']})"    print(f"{label}: {query} -> {normalize_units(query)}")    for name, rule in rules.items():        typed = query if rule is None else normalize_units(query, rule)        ranking = list(searches[name].search(typed, k=10).index)        print(f"{label}, bm25 ndcg@10 {name}: {ndcg_at_k(ranking, judgments[query_id], 10):.3f}")
Saídapython normalize-units-both-sides.py
products that write a number then '': 3014
products that write a number then ": 65
products that write a number then inch: 215
terms of 3.7-quart slow cooker, normalized: 3_7qt slow cooker
terms of 3 in 1 sofa bed, normalized: sofa bed
terms of 1 in twin, normalized: 1in twin
terms of 48 '' range hood, first try: 48 range hood
terms of 48 '' range hood, normalized: 48in range hood
queries with a unit: 4
of them, test queries: 2
62 (train): 7qt slow cooker -> 7qt slow cooker
62 (train), bm25 ndcg@10 as written: 0.554
62 (train), bm25 ndcg@10 first try: 0.930
62 (train), bm25 ndcg@10 normalized: 0.930
101 (train): 48 in entry table with side by side drawer -> 48in entry table with side by side drawer
101 (train), bm25 ndcg@10 as written: 0.569
101 (train), bm25 ndcg@10 first try: 0.569
101 (train), bm25 ndcg@10 normalized: 0.569
285 (test): 48" sliding single track , barn door for laundry -> 48in sliding single track , barn door for laundry
285 (test), bm25 ndcg@10 as written: 0.592
285 (test), bm25 ndcg@10 first try: 0.592
285 (test), bm25 ndcg@10 normalized: 0.592
482 (test): 48 inch kitchen hood -> 48in kitchen hood
482 (test), bm25 ndcg@10 as written: 1.000
482 (test), bm25 ndcg@10 first try: 0.824
482 (test), bm25 ndcg@10 normalized: 1.000

A forma mais usual de o catálogo escrever polegadas é aquela que a regra escrita a partir das consultas não cobre: duas aspas simples após um número, em produtos 3014, contra 65 para " e 215 para inch.

O tokenizador lê 3.7-quart slow cooker, normalizado, como 3_7qt slow cooker, e 3 in 1 sofa bed como sofa bed. normalize_units ainda interpreta mal 1 in twin como 1in twin, e é por isso que vale a pena imprimir os termos.

A normalização melhora a consulta de treino 7qt slow cooker: o nDCG@10 do BM25 vai de 0.554 para 0.930, e a primeira regra dá 0.930.

A consulta de teste 48 inch kitchen hood mostra o que a primeira regra perde por não tratar as duas aspas. Ela obtém 1.000 como escrita e 0.824 com a primeira regra. A consulta passa a ser 48in, enquanto a primeira regra deixa uma coifa escrita 48 '' como 48 range hood, e a regra completa a transforma em 48in range hood. Com a regra completa, a consulta sobre a coifa obtém 1.000.

A outra consulta de treino, 48 in entry table with side by side drawer, obtém 0.569 como escrita e 0.569 normalizada, e a consulta de teste sobre uma porta de correr de celeiro obtém 0.592 e 0.592. Isso dá 4 consultas com unidade, 2 delas consultas de teste: poucas demais para testar.

Regra prática: escreva as regras de normalização a partir do texto do catálogo, e não das consultas, contando todas as formas como ele escreve cada unidade. Imprima os termos que o tokenizador produz do texto normalizado, porque uma regra que parece correta pode produzir termos que correspondem aos produtos errados. Aplique as mesmas regras a produtos e consultas em uma mesma versão, e reconstrua o índice. Quando o catálogo guarda tamanhos em campos, como a largura em attributes, compare o tamanho com o campo, como o capítulo 6 sugere.

Expanda consultas com uma lista de sinônimos

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

Algumas lacunas não são erros de digitação nem unidades, mas palavras diferentes para uma mesma coisa, como quando os produtos exatos para midcentury tv unit dizem stand. A expansão de consulta acrescenta termos a uma consulta para que ela possa encontrar produtos que usam outras palavras para a mesma coisa. A expansão geralmente aumenta a revocação, a parcela dos produtos relevantes que a busca encontra (Manning et al., 2008). Ela também pode reduzir de forma significativa a precisão, a parcela dos produtos encontrados que são relevantes, sobretudo quando a consulta contém termos ambíguos (Manning et al., 2008). Uma palavra que a expansão acrescenta pode encontrar produtos que o comprador não pediu e afastar a consulta de seu significado; isso se chama deriva de consulta. Os termos de expansão podem vir de uma lista de sinônimos feita à mão ou dos resultados. A realimentação por pseudo-relevância supõe que os primeiros resultados são relevantes e acrescenta os termos deles à consulta, o que torna a deriva o seu risco conhecido (Manning et al., 2008).

Aqui lib.queries.SYNONYMS guarda 14 grupos de palavras intercambiáveis, como stand e unit, escritos a partir da leitura das consultas de treino cujos produtos exatos deixam de conter uma palavra da consulta. Quando uma consulta contém uma palavra ou expressão de um grupo, expand acrescenta os outros termos desse grupo, e o BM25 busca o resultado. Meça isso nas consultas de treino e, em seguida, faça a primeira das comparações planejadas do capítulo nas consultas de teste:

synonym-expansion-train-and-test.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Expands each query with the synonym list, scores BM25 on the train and test queries as typed and expanded, andruns the list's planned test comparison. The prose's point rests on the "synonyms, bm25" lines of that comparison."""from lib.lexical import LexicalSearchfrom lib.metrics import evaluatefrom lib.queries import PLANNED_TEST_COMPARISONS, SYNONYMS, THRESHOLD, expand, report_plannedfrom lib.store import load_products, load_queries, qrelsproducts, judgments = load_products(), qrels()bm25 = LexicalSearch(products)print("synonym groups:", len(SYNONYMS))scores = {}for split in ["train", "test"]:    queries = load_queries(split)    expanded = queries.assign(query=queries["query"].map(expand))    changed = queries.index[expanded["query"] != queries["query"]]    print(f"{split} queries the list changes:", len(changed))    for name, frame in [("typed", queries), ("expanded", expanded)]:        scores[split, name] = evaluate(bm25.run(frame), qrels(split))        print(f"{split} ndcg@10 {name}: {scores[split, name]['ndcg@10'].mean():.3f}")        print(f"{split} judged@10 {name}: {scores[split, name]['judged@10'].mean():.3f}")for query in queries.loc[changed, "query"]:                   # the test queries the list changes    print(f"test query changed: {query}")    # expand returns the query, a space, then the added words, so this slice keeps only the added words    print(f"words the list adds to it: {expand(query)[len(query) + 1:]}")change = (scores["train", "expanded"]["ndcg@10"] - scores["train", "typed"]["ndcg@10"]).round(3)print(f"train queries better, worse: {(change > 0).sum()}, {(change < 0).sum()}")       # for choosing, not evidenceprint(f"share of the net train gain from the largest gain: {change.max() / change.sum():.3f}")for kind, query_id in [("gain", change.idxmax()), ("loss", change.idxmin())]:    query = load_queries().at[query_id, "query"]    # the same slice: everything after the query and the space that expand puts between them    added = expand(query)[len(query) + 1:]    print(f"largest train {kind}: {query}")    print(f"largest train {kind}, words added: {added}")    print(f"largest train {kind}, change: {change[query_id]:+.3f}")named = [product_id for product_id in bm25.search(expand(query), k=10).index if added in products.at[product_id, "name"]]print(f"largest train loss, top 10 names with {added}:", len(named))      # query and added: the largest loss'sprint("largest train loss, of those, unjudged:", sum(product_id not in judgments[query_id] for product_id in named))print("\nplanned test comparisons:", len(PLANNED_TEST_COMPARISONS))print(f"p-value threshold: {THRESHOLD:.2f}")report_planned("synonyms, bm25", scores["test", "expanded"]["ndcg@10"], scores["test", "typed"]["ndcg@10"])
Saídapython synonym-expansion-train-and-test.py
synonym groups: 14
train queries the list changes: 14
train ndcg@10 typed: 0.695
train judged@10 typed: 0.930
train ndcg@10 expanded: 0.722
train judged@10 expanded: 0.944
test queries the list changes: 1
test ndcg@10 typed: 0.725
test judged@10 typed: 0.927
test ndcg@10 expanded: 0.725
test judged@10 expanded: 0.927
test query changed: indoor multi tiered plant stand
words the list adds to it: unit
train queries better, worse: 6, 5
share of the net train gain from the largest gain: 0.473
largest train gain: midcentury tv unit
largest train gain, words added: stand mid century
largest train gain, change: +0.632
largest train loss: wire basket with dividers
largest train loss, words added: hamper
largest train loss, change: -0.176
largest train loss, top 10 names with hamper: 4
largest train loss, of those, unjudged: 4

planned test comparisons: 5
p-value threshold: 0.01
synonyms, bm25, mean difference: 0.000
synonyms, bm25, wins, losses, ties: 0, 0, 30
synonyms, bm25, permutation p: 1.000
synonyms, bm25, established at 0.01: no
synonyms, bm25, t-test p: 1.000
synonyms, bm25, t-test agrees: yes
synonyms, bm25, 99% interval: 0.000 to 0.000
synonyms, bm25, interval agrees: yes

A lista altera 14 consultas de treino. A média de nDCG@10 passa de 0.695 para 0.722, e judged@10, a parcela dos dez primeiros resultados com julgamento, também sobe, de 0.930 para 0.944.

Das consultas de treino alteradas, 6, 5 melhoram e pioram, respectivamente, e uma consulta, midcentury tv unit, responde por 0.473 do ganho líquido, ganhando +0.632 com stand mid century acrescentadas. A lista foi escrita a partir dessas consultas, por isso mesmo esses números a favorecem.

A maior perda, -0.176, mostra a deriva: wire basket with dividers recebe hamper, e 4 produtos cujos nomes contêm hamper entram em seus dez primeiros resultados. Destes, 4 não têm julgamento, de modo que a métrica os conta como irrelevantes, o que, para cestas, é uma suposição razoável.

Nas consultas de teste, a lista altera 1 consulta, indoor multi tiered plant stand, ao acrescentar unit. O judged@10 permanece em 0.927, e a diferença não se comprova (comparações planejadas). Nas consultas a partir das quais foi escrita, a lista ajudou quase tantas consultas quanto prejudicou, e as consultas para as quais ela não foi feita raramente contêm as suas palavras.

Regra prática: Mantenha uma lista de sinônimos para as lacunas de vocabulário que você já observou, escreva cada entrada a partir de uma consulta que falha e leia os produtos que cada entrada acrescenta antes de mantê-la. Nunca relate o ganho de uma lista nas consultas a partir das quais você a escreveu, e mantenha uma entrada apenas se uma comparação planejada nas consultas de teste mostrar ganho. Teste primeiro qualquer expansão em recuperação semântica: as reescritas do LLM, que acrescentam sinônimos e também ampliam e removem palavras, a prejudicam. Quando as lacunas forem numerosas demais para listar, experimente a radicalização ou a recuperação esparsa aprendida.

Treinar um classificador de consultas com texto de produtos

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

Em vez de alterar as palavras de uma consulta, um sistema pode prever que tipo de produto a consulta pede. Classificação de consultas atribui uma consulta a uma classe da taxonomia da loja, como Range Hoods. Na busca de produtos, "mapear uma consulta para uma taxonomia de produtos predefinida é uma etapa importante no pipeline de compreensão de consultas de e-commerce" (Skinner and Kallumadi, 2019): uma classe prevista pode direcionar a recuperação para a parte certa do catálogo. Treinar um classificador costuma exigir consultas rotuladas. Skinner e Kallumadi relatam que um mapeamento de taxonomia de produtos já existente pode melhorar a classificação de consultas e reduzir a necessidade de dados rotulados. Eles fazem um pré-treinamento com títulos de produtos, cujas classes são conhecidas, e depois ajustam o modelo com menos consultas rotuladas.

A loja vai além e não usa consultas rotuladas, porque não tem nenhuma. O WANDS atribui a cada consulta um query_class, "categoria à qual a consulta pertence" (WANDS), mas o capítulo 2 mostra que se trata de uma previsão, e alguns valores estão errados. E a amostra do WANDS do livro tem no máximo uma consulta por classe (examples/data/wands/README.md), então nenhuma classe tem duas consultas para aprender. Por isso, treine com os produtos, que trazem product_class, e aplique o classificador às consultas.

Um classificador Bayes ingênuo pode aprender classes a partir do texto dos produtos em poucas linhas. Em palavras, o Bayes ingênuo considera provável uma classe para uma consulta quando a classe é comum entre os produtos e quando as palavras da consulta são comuns no texto de produtos dessa classe. Ele trata as palavras como independentes, e essa é a parte "ingênua". Cada contagem recebe 1 somado, para que uma palavra nunca vista em uma classe não elimine a classe:

predicted class = argmax over classes c of  log P(c) + sum over the query's words w of  log P(w | c)
P(w | c)        = (count of w in class c's text + 1) / (number of words in class c's text + vocabulary size)

Vamos construí-lo à mão a partir de contagens de palavras do texto dos produtos, verificá-lo contra o MultinomialNB do scikit-learn na versão 1.9.1, e então comparar suas previsões com query_class e com as classes dos produtos exatos de cada consulta:

query-classes-by-hand.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""A naive Bayes query classifier built by hand from product text, checked against scikit-learn's MultinomialNB andcompared with each query's exact products. The prose's point rests on the two "queries where most exact productshave" lines and on the agreement line with MultinomialNB."""import numpy as npfrom lib.queries import class_rows, train_classifierfrom lib.store import load_labels, load_products, load_queries, product_textproducts, queries, labels = load_products(), load_queries(), load_labels()rows = class_rows(products)                     # one row per (product, class) for products with a classvectorizer, model = train_classifier(products)  # the same, by scikit-learn's MultinomialNBwords = vectorizer.transform(product_text(rows))  # word counts: one row per (product, class), one column per wordclasses = np.array(sorted(rows["label"].unique()))print("product classes:", len(classes))print("products without a class:", (products["product_class"] == "").sum())print("products with several classes:", products["product_class"].str.contains("|", regex=False).sum())# query classes whose name matches no product classmissing = queries["query_class"].dropna()[lambda names: ~names.isin(classes)]print("query classes that no product has:", len(missing))print("query classes that no product has, names:", "; ".join(missing))# Naive Bayes: log P(class) + sum over the query's words of log P(word | class), each word count smoothed by 1word_counts = np.vstack([np.asarray(words[(rows["label"] == name).to_numpy()].sum(axis=0)) for name in classes])log_prior = np.log(rows["label"].value_counts()[classes].to_numpy() / len(rows))log_likelihood = np.log((word_counts + 1) / (word_counts.sum(axis=1, keepdims=True) + word_counts.shape[1]))query_words = vectorizer.transform(queries["query"])predicted = classes[np.asarray(query_words @ log_likelihood.T + log_prior).argmax(axis=1)]print("same predictions as MultinomialNB:", (predicted == model.predict(query_words)).sum(), "of", len(queries))queries = queries.assign(predicted=predicted)print("predicted class equals query_class:", (queries["predicted"] == queries["query_class"]).sum())# judgment grade 2 is exact; a product's classes are joined by |, so they're split before matchingexact = labels[labels["grade"] == 2].join(products["product_class"].str.split("|"), on="product_id")for column, name in [("predicted", "predicted class"), ("query_class", "query_class")]:    share = [exact.loc[exact["query_id"] == query_id, "product_class"].apply(lambda names: label in names).mean()             for query_id, label in queries[column].items()]    print(f"queries where most exact products have the {name}:", (np.array(share) > 0.5).sum())# outdoor light fixtures, desk and chair set, and pool floatsfor query_id in [133, 255, 410]:    query, split, label = queries.loc[query_id, ["query", "split", "predicted"]]    print(f"{query_id} ({split}): {query} -> {label}"          f" (query_class: {queries.at[query_id, 'query_class']})")print("predicted class for 7qt slow cooker:", queries.at[62, "predicted"])       # its query_class has no products
Saídapython query-classes-by-hand.py
product classes: 410
products without a class: 800
products with several classes: 620
query classes that no product has: 1
query classes that no product has, names: Crock Pots & Slow Cookers
same predictions as MultinomialNB: 80 of 80
predicted class equals query_class: 60
queries where most exact products have the predicted class: 63
queries where most exact products have the query_class: 63
133 (test): outdoor light fixtures -> Light Bulbs (query_class: Outdoor Wall Lights)
255 (test): desk and chair set -> Desks (query_class: Office Chairs)
410 (train): pool floats -> Deck Boxes (query_class: Lawn Games)
predicted class for 7qt slow cooker: Slow Cookers

Os produtos usam 410 classes. 800 produtos não têm nenhuma e ficam de fora, e 620 têm várias, então cada um deles gera uma linha de treino por classe.

O classificador construído à mão faz a mesma previsão que MultinomialNB para 80 of 80 consultas. Sua previsão é igual a query_class em 60 delas, mas query_class também é um palpite. Em relação aos julgamentos, os dois palpites empatam: para 63 consultas, a maioria dos produtos exatos tem a classe prevista, e para 63 elas têm query_class. Três de suas previsões mostram como ele interpreta uma consulta apenas pelas palavras: outdoor light fixtures vira Light Bulbs, desk and chair set vira Desks, e pool floats vira Deck Boxes.

O desenho da amostra limita o que essa verificação pode mostrar. Cada classe é testada por no máximo uma consulta, então nenhuma acurácia por classe pode ser medida, e 80 consultas cobrem apenas parte das 410 classes, então os números nada dizem sobre o restante. Um classificador de consultas não pode ser treinado com essas consultas de forma alguma, e dois classificadores só podem ser comparados quanto a acertarem ou não estas poucas consultas. E 1 classe de consulta, Crock Pots & Slow Cookers, não nomeia nenhuma classe de produto, então nenhum classificador treinado com produtos pode prevê-la.

Regra prática: Quando você não tem consultas rotuladas, treine um classificador de consultas com as classes dos seus produtos e verifique-o contra as classes dos produtos exatos julgados, não contra os palpites de outro classificador. Quando seus registros lhe derem consultas rotuladas, treine com elas. Trate a classe prevista como uma dica para o ranqueamento, nunca como um rótulo.

Reforçar a classe prevista em vez de filtrar

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

Aqui a classe prevista vem do classificador naive Bayes treinado sobre o texto dos produtos. Uma classe prevista pode atuar sobre a recuperação de duas maneiras. Um filtro mantém apenas os produtos da classe prevista. Um reforço soma uma quantidade fixa às pontuações dos produtos da classe prevista, de modo que eles subam sem que nada mais seja removido. Um filtro só é tão bom quanto o classificador: cada produto relevante fora da classe prevista desaparece.

Os julgamentos de treino da loja mostram quanto um filtro custaria: para as consultas de treino, 501 of 1937 produtos exatos estão fora da classe prevista de sua consulta. Acrescentamos um reforço às similaridades da recuperação semântica, o melhor ranqueador da loja e, portanto, o ranqueador a ser superado, e testamos cinco pesos de reforço e um filtro nas consultas de treino. Levamos o melhor reforço às consultas de teste para a segunda das comparações planejadas do capítulo:

class-boost-train-and-test.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Counts the exact train products outside each query's predicted class, scores a class filter and several boosts onthe train queries, and takes the best boost to the test queries as a planned comparison. The prose's point rests onthe "exact train products outside the predicted class" line and on the planned comparison's lines."""from lib.metrics import evaluatefrom lib.queries import THRESHOLD, class_boost_run, in_class, report_planned, train_classifierfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrelsproducts, queries = load_products(), load_queries()vectorizer, model = train_classifier(products)               # trained on product text, never on queriespredicted = dict(zip(queries.index, model.predict(vectorizer.transform(queries["query"]))))semantic = SemanticSearch()train, train_judgments = load_queries("train"), qrels("train")exact, outside = 0, 0for query_id, judged in train_judgments.items():    member = in_class(products, predicted[query_id])    exact += sum(grade == 2 for grade in judged.values())    outside += sum(grade == 2 and not member[product_id] for product_id, grade in judged.items())print(f"exact train products outside the predicted class: {outside} of {exact}")base = evaluate(semantic.run(train), train_judgments)print(f"train ndcg@10 semantic: {base['ndcg@10'].mean():.3f}")print(f"train judged@10 semantic: {base['judged@10'].mean():.3f}")train_scores = {}for weight in [None, 0.01, 0.02, 0.05, 0.1, 0.2]:                          # None: keep only the predicted class    train_scores[weight] = evaluate(class_boost_run(semantic, train.index, predicted, products, weight), train_judgments)    name = "filter" if weight is None else f"boost {weight}"    print(f"train ndcg@10 {name}: {train_scores[weight]['ndcg@10'].mean():.3f}")# every weight except None, the filterboosts = [weight for weight in train_scores if weight is not None]best = max(boosts, key=lambda weight: train_scores[weight]["ndcg@10"].mean())for name, weight in [("filter", None), ("best boost", best)]:    print(f"train judged@10 {name}: {train_scores[weight]['judged@10'].mean():.3f}")print("best boost on train:", best)print(f"\nthe planned test comparison, threshold {THRESHOLD:.2f}:")test, test_judgments = load_queries("test"), qrels("test")boosted = evaluate(class_boost_run(semantic, test.index, predicted, products, best), test_judgments)plain = evaluate(semantic.run(test), test_judgments)print(f"test judged@10 semantic: {plain['judged@10'].mean():.3f}")print(f"test judged@10 boosted: {boosted['judged@10'].mean():.3f}")report_planned("class boost, semantic", boosted["ndcg@10"], plain["ndcg@10"])
Saídapython class-boost-train-and-test.py
exact train products outside the predicted class: 501 of 1937
train ndcg@10 semantic: 0.772
train judged@10 semantic: 0.964
train ndcg@10 filter: 0.675
train ndcg@10 boost 0.01: 0.773
train ndcg@10 boost 0.02: 0.774
train ndcg@10 boost 0.05: 0.768
train ndcg@10 boost 0.1: 0.742
train ndcg@10 boost 0.2: 0.692
train judged@10 filter: 0.866
train judged@10 best boost: 0.966
best boost on train: 0.02

the planned test comparison, threshold 0.01:
test judged@10 semantic: 0.990
test judged@10 boosted: 0.993
class boost, semantic, mean difference: 0.005
class boost, semantic, wins, losses, ties: 7, 4, 19
class boost, semantic, permutation p: 0.174
class boost, semantic, established at 0.01: no
class boost, semantic, t-test p: 0.164
class boost, semantic, t-test agrees: yes
class boost, semantic, 99% interval: -0.002 to 0.017
class boost, semantic, interval agrees: yes

Nas consultas de treino, o filtro tem desempenho pior que o ranqueador simples: o nDCG@10 cai de 0.772 para 0.675, e o judged@10 de 0.964 para 0.866, de modo que seus primeiros 10 também se enchem de produtos que ninguém julgou.

Reforços pequenos quase não alteram a pontuação de treino, e os grandes a prejudicam: o nDCG@10 é 0.773 com 0.01 e 0.692 com 0.2. O melhor reforço no treino é 0.02, com 0.774, com judged@10 de 0.966.

Nas consultas de teste, o judged@10 é 0.990 sem o reforço e 0.993 com ele, e o ganho do reforço não está estabelecido (comparações planejadas).

Regra prática: Não filtre pela classe prevista. Reforce-a com um peso ajustado nas consultas de treino, e mantenha o reforço somente se sua comparação planejada estiver estabelecida. A da loja não está, então sua recuperação semântica permanece sem reforço. Recomendamos um filtro por classe apenas quando o cliente escolheu a classe, por exemplo ao clicar em uma categoria.

Reescrever consultas com um LLM

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

A reescrita de consultas substitui a consulta por um texto escrito para recuperar melhor. Enquanto o corretor, as regras de unidade e a lista de sinônimos corrigem cada um um tipo de lacuna, um LLM pode corrigir a ortografia, expandir abreviações e acrescentar sinônimos em um único passo, sem lista para manter. Em rewrite-retrieve-read, a consulta reescrita vai para o recuperador no lugar da original (Ma et al., 2023). Alguns estudos relatam ganhos. Com query2doc, que acrescenta à consulta um pseudodocumento escrito por um LLM, o BM25 melhorou de 3% a 15% em conjuntos de dados de RI ad hoc, com o text-davinci-003 escrevendo os pseudodocumentos para as consultas do MS MARCO e do TREC DL (Wang et al., 2023). Outros estudos relatam fracassos. Uma comparação de 11 métodos de expansão, 12 conjuntos de dados e 24 recuperadores constatou que a expansão ajuda modelos mais fracos e, em geral, prejudica os mais fortes (Weller et al., 2024). Outro estudo constatou que a expansão baseada em LLM pode degradar significativamente a recuperação quando o LLM não tem o conhecimento necessário ou quando a consulta é altamente ambígua (Abe et al., 2025).

As reescritas que os exemplos leem foram registradas com o LLM da loja, o modelo aberto nomeado em a abertura do capítulo, executado localmente sobre cada consulta isoladamente. A instrução do prompt é: "Rewrite this search query from an online furniture and home-goods store so that a search engine finds what the shopper wants. Fix spelling, expand abbreviations and add common synonyms for the product type, but keep every requirement the shopper stated and add none of your own. Return a single line." O restante do prompt traz a consulta e pede JSON, e o manifesto da gravação o registra por completo. O script de gravação incorporou cada reescrita como consulta, com o mesmo modelo de embeddings dos produtos. O BM25 pesquisa o texto da reescrita, e a recuperação semântica, o seu embedding. As consultas de treino vêm primeiro, para ver o que as reescritas mudam antes de qualquer teste:

llm-rewrites-on-train.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Prints the store's recorded LLM rewrites for a few train queries, then scores BM25 and semantic retrieval on thetrain queries, typed and rewritten. The prose's point rests on the nDCG@10 lines for both retrievers."""from lib.lexical import LexicalSearchfrom lib.metrics import evaluatefrom lib.recorded import llm_rewrites, manifestfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrelsrecording = manifest("llm-rewrites")print("model:", recording["model"])print("embedding model:", recording["embedding_model"])print("rewrite prompt, first line:", recording["prompts"]["rewrite"].split("\n")[0])table, rewrite_vectors, _ = llm_rewrites()rewrites = table.set_index("query_id")["rewrite"]# the embeddings come in the table's row order, not query order: row maps each query_id to its rowrow = {query_id: position for position, query_id in enumerate(table["query_id"])}# a spelling fix, a product code, and malachi sledfor query_id in [20, 205, 313]:    print(f"rewrite of {load_queries().at[query_id, 'query']}: {rewrites[query_id]}")queries, judgments = load_queries("train"), qrels("train")products = load_products()# judgment grade 2 is exactexact = [product_id for product_id, grade in judgments[313].items() if grade == 2]print("exact products for malachi sled:", "; ".join(products.loc[exact, "name"]))bm25, semantic = LexicalSearch(products), SemanticSearch()runs = {"bm25, typed": bm25.run(queries),        "bm25, rewrite": bm25.run(queries.assign(query=rewrites[queries.index].to_numpy())),        "semantic, typed": semantic.run(queries),        "semantic, rewrite": {query_id: list(semantic.search_vector(rewrite_vectors[row[query_id]]).index)                              for query_id in queries.index}}scores = {name: evaluate(run, judgments) for name, run in runs.items()}for name, frame in scores.items():    print(f"train ndcg@10 {name}: {frame['ndcg@10'].mean():.3f}")    print(f"train judged@10 {name}: {frame['judged@10'].mean():.3f}")for retriever in ["bm25", "semantic"]:                       # for choosing, not evidence    change = (scores[f"{retriever}, rewrite"]["ndcg@10"] - scores[f"{retriever}, typed"]["ndcg@10"]).round(3)    print(f"train queries better, worse, {retriever}: {(change > 0).sum()}, {(change < 0).sum()}")    print(f"largest train loss, {retriever}: {queries.at[change.idxmin(), 'query']}")    print(f"largest train loss, {retriever}, change: {change.min():+.3f}")
Saídapython llm-rewrites-on-train.py
model: gemma4:12b-it-q4_K_M
embedding model: Snowflake/snowflake-arctic-embed-m-v1.5
rewrite prompt, first line: Rewrite this search query from an online furniture and home-goods store so that a search engine finds what the shopper wants. Fix spelling, expand abbreviations and add common synonyms for the product type, but keep every requirement the shopper stated and add none of your own. Return a single line.
rewrite of foutains with brick look: fountains with brick look, brick style water features, masonry fountains, faux brick fountains
rewrite of ines shag rug w003096809: Ines shag rug w003096809 area rug carpet
rewrite of malachi sled: Malachi sled sofa couch settee loveseat
exact products for malachi sled: malachi sled end table; malachi 44 '' console table; malachi sled coffee table
train ndcg@10 bm25, typed: 0.695
train judged@10 bm25, typed: 0.930
train ndcg@10 bm25, rewrite: 0.646
train judged@10 bm25, rewrite: 0.868
train ndcg@10 semantic, typed: 0.772
train judged@10 semantic, typed: 0.964
train ndcg@10 semantic, rewrite: 0.759
train judged@10 semantic, rewrite: 0.924
train queries better, worse, bm25: 23, 24
largest train loss, bm25: malachi sled
largest train loss, bm25, change: -0.644
train queries better, worse, semantic: 18, 25
largest train loss, semantic: wall design shelf
largest train loss, semantic, change: -0.653

A ortografia fica correta (fountains with brick look, brick style water features, masonry fountains, faux brick fountains), e os códigos são preservados (Ines shag rug w003096809 area rug carpet). Para malachi sled, uma linha de produtos, o LLM adivinhou um sofá: escreveu Malachi sled sofa couch settee loveseat, enquanto os produtos exatos são malachi sled end table; malachi 44 '' console table; malachi sled coffee table.

Nas consultas de treino, a reescrita reduz o nDCG@10 para os dois recuperadores: o BM25 vai de 0.695 para 0.646, e a recuperação semântica, de 0.772 para 0.759. O Judged@10 cai para os dois, de 0.930 para 0.868 e de 0.964 para 0.924, o que significa que as reescritas trazem produtos que ninguém julgou, e parte da queda do nDCG@10 pode vir daí.

As perdas não são de uma única consulta ruim: o número de consultas que pontuam melhor e pior é 23, 24 para o BM25 e 18, 25 para a recuperação semântica. A maior perda do BM25 é malachi sled, a linha de produtos que o LLM transformou em sofá, com -0.644, e a da recuperação semântica é wall design shelf, com -0.653.

Esses números de treino moldam expectativas e não provam nada. A terceira e a quarta das 5 comparações planejadas do capítulo foram fixadas antecipadamente, então vão para as consultas de teste, qualquer que seja o resultado das consultas de treino, e cada uma conta como estabelecida se p estiver abaixo de 0.01. Antes que os números de teste cheguem, escolha uma opção: a reescrita ajuda o BM25, o recuperador mais fraco, prejudica a recuperação semântica, o mais forte, ou não faz nenhuma das duas coisas?

llm-rewrites-on-test.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Scores BM25 and semantic retrieval on the test queries, as typed and rewritten, as the chapter's planned comparisons,then repeats both on condensed runs as an exploratory check. The prose's point rests on the "established at 0.01" lines."""from lib.lexical import LexicalSearchfrom lib.metrics import evaluatefrom lib.queries import THRESHOLD, condensed, report_planned, rewrite_runsfrom lib.semantic import SemanticSearchfrom lib.significance import comparefrom lib.store import load_products, load_queries, qrelsqueries, judgments = load_queries("test"), qrels("test")             # scored on the human judgments# for each retriever, its run on the rewrite, then its run on the query as typedruns = rewrite_runs(queries, LexicalSearch(load_products()), SemanticSearch())print(f"the planned test comparisons, threshold {THRESHOLD:.2f}:")for retriever, (rewritten, typed) in runs.items():    name = f"llm rewrite, {retriever}"    after, before = evaluate(rewritten, judgments), evaluate(typed, judgments)    for form, frame in [("typed", before), ("rewrite", after)]:        print(f"{name}, test ndcg@10 {form}: {frame['ndcg@10'].mean():.3f}")        print(f"{name}, test judged@10 {form}: {frame['judged@10'].mean():.3f}")    report_planned(name, after["ndcg@10"], before["ndcg@10"])    # Exploratory, never established: the same comparison on condensed runs, which drop unjudged products    # rewritten comes first in each pair, as rewrite_runs returns them; the rewrite is "after"    after, before = (evaluate(condensed(run, judgments), judgments)["ndcg@10"] for run in (rewritten, typed))    # confidence = 1 - THRESHOLD: a 99% interval, at the level the planned comparisons use    result = compare(after, before, confidence=1 - THRESHOLD)    print(f"{name}, condensed ndcg@10 typed: {before.mean():.3f}")    print(f"{name}, condensed ndcg@10 rewrite: {after.mean():.3f}")    print(f"{name}, condensed, exploratory mean difference: {result['mean difference']:.3f}")    print(f"{name}, condensed, exploratory permutation p: {result['permutation p']:.3f}")    low, high = result["ci low"], result["ci high"]    print(f"{name}, condensed, exploratory {1 - THRESHOLD:.0%} interval: {low:.3f} to {high:.3f}")
Saídapython llm-rewrites-on-test.py
the planned test comparisons, threshold 0.01:
llm rewrite, bm25, test ndcg@10 typed: 0.725
llm rewrite, bm25, test judged@10 typed: 0.927
llm rewrite, bm25, test ndcg@10 rewrite: 0.669
llm rewrite, bm25, test judged@10 rewrite: 0.903
llm rewrite, bm25, mean difference: -0.056
llm rewrite, bm25, wins, losses, ties: 13, 15, 2
llm rewrite, bm25, permutation p: 0.060
llm rewrite, bm25, established at 0.01: no
llm rewrite, bm25, t-test p: 0.060
llm rewrite, bm25, t-test agrees: yes
llm rewrite, bm25, 99% interval: -0.143 to 0.005
llm rewrite, bm25, interval agrees: yes
llm rewrite, bm25, condensed ndcg@10 typed: 0.778
llm rewrite, bm25, condensed ndcg@10 rewrite: 0.725
llm rewrite, bm25, condensed, exploratory mean difference: -0.053
llm rewrite, bm25, condensed, exploratory permutation p: 0.044
llm rewrite, bm25, condensed, exploratory 99% interval: -0.150 to -0.002
llm rewrite, semantic, test ndcg@10 typed: 0.830
llm rewrite, semantic, test judged@10 typed: 0.990
llm rewrite, semantic, test ndcg@10 rewrite: 0.749
llm rewrite, semantic, test judged@10 rewrite: 0.947
llm rewrite, semantic, mean difference: -0.081
llm rewrite, semantic, wins, losses, ties: 7, 19, 4
llm rewrite, semantic, permutation p: 0.000
llm rewrite, semantic, established at 0.01: yes
llm rewrite, semantic, t-test p: 0.000
llm rewrite, semantic, t-test agrees: yes
llm rewrite, semantic, 99% interval: -0.132 to -0.035
llm rewrite, semantic, interval agrees: yes
llm rewrite, semantic, condensed ndcg@10 typed: 0.834
llm rewrite, semantic, condensed ndcg@10 rewrite: 0.791
llm rewrite, semantic, condensed, exploratory mean difference: -0.043
llm rewrite, semantic, condensed, exploratory permutation p: 0.002
llm rewrite, semantic, condensed, exploratory 99% interval: -0.079 to -0.014

Para o BM25, o nDCG@10 cai de 0.725 para 0.669, diferença que não é estabelecida (comparações planejadas). O Judged@10 também cai, de 0.927 para 0.903.

A recuperação semântica apresenta uma perda estabelecida: o nDCG@10 cai de 0.830 para 0.749, com um valor p de permutação que arredonda para 0.000. O Judged@10 também cai, de 0.990 para 0.947.

Como o judged@10 caiu, repetimos as duas comparações sobre listas condensadas, que descartam os produtos não julgados antes de calcular a pontuação. Essa verificação foi escolhida depois de ver a queda, então é exploratória e não pode estabelecer nada.

Para a recuperação semântica, o nDCG@10 condensado ainda cai, de 0.834 para 0.791, uma diferença de -0.043, com p de permutação de 0.002 e um intervalo de 99% de -0.079 to -0.014. Assim, a perda não se apoia apenas nos produtos não julgados.

Para o BM25, o nDCG@10 condensado vai de 0.778 para 0.725, com p de permutação de 0.044.

A reescrita não ajudou o BM25: ela se moveu no sentido oposto ao que Weller et al. e query2doc relatam, embora não por uma quantidade estabelecida. O dano que a reescrita causa à recuperação semântica é o que Weller et al. encontraram para recuperadores fortes. Os dois resultados valem para este modelo, este prompt e estas consultas.

As consultas que mais se movem mostram o que uma reescrita faz. Leia-as com o número de produtos não julgados em cada top 10 reescrito, que a métrica conta como irrelevantes:

rewrite-largest-changes.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""For each retriever, finds the test queries whose nDCG@10 moves most under the rewrite, and counts the unjudgedproducts in each rewritten top 10. The prose's point rests on the largest-loss and largest-gain lines, and on thespelling-only check for BM25's largest gain."""from bm25s.stopwords import STOPWORDS_ENfrom lib.lexical import LexicalSearchfrom lib.metrics import evaluate, ndcg_at_kfrom lib.queries import rewrite_runsfrom lib.recorded import llm_rewrites, probesfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrelsqueries, judgments = load_queries("test"), qrels("test")bm25 = LexicalSearch(load_products())rewrites = llm_rewrites()[0].set_index("query_id")["rewrite"]largest = {}for retriever, (rewritten, typed) in rewrite_runs(queries, bm25, SemanticSearch()).items():    change = evaluate(rewritten, judgments)["ndcg@10"] - evaluate(typed, judgments)["ndcg@10"]    for kind, query_id in [("loss", change.idxmin()), ("gain", change.idxmax())]:        label, largest[(retriever, kind)] = f"{retriever}, largest {kind}", query_id        print(f"{label}: {queries.at[query_id, 'query']}")        print(f"{label}, change: {change[query_id]:+.3f}")        print(f"{label}, rewrite: {rewrites[query_id]}")        unjudged = sum(product_id not in judgments[query_id] for product_id in rewritten[query_id][:10])        print(f"{label}, unjudged products in the rewrite's top 10: {unjudged}")# BM25's largest gain: score the query with only its spelling fixed (chapter 6's probe), apart from the added wordsquery_id = largest[("bm25", "gain")]# the spelling probes, keyed by the test query each one correctsspelled = probes()[0].dropna(subset=["of_query_id"]).set_index("of_query_id")["query"]if query_id in spelled.index:    for name, text in [("typed", queries.at[query_id, "query"]), ("spelling fixed only", spelled[query_id])]:        ranking = list(bm25.search(text, k=10).index)        print(f"bm25, largest gain, ndcg@10 {name}: {ndcg_at_k(ranking, judgments[query_id], 10):.3f}")    # bm25s's English stop words, which it drops before matching    print("bm25 stop words among an and and:", ", ".join(word for word in ["an", "and"] if word in STOPWORDS_EN))
Saídapython rewrite-largest-changes.py
bm25, largest loss: fold in half table
bm25, largest loss, change: -0.471
bm25, largest loss, rewrite: folding table, collapsible table, drop leaf table, gateleg table
bm25, largest loss, unjudged products in the rewrite's top 10: 3
bm25, largest gain: refrigerator with ice an water in door
bm25, largest gain, change: +0.159
bm25, largest gain, rewrite: refrigerator with ice and water in door, fridge with door dispenser, refrigerator with external water and ice dispenser
bm25, largest gain, unjudged products in the rewrite's top 10: 1
semantic, largest loss: pull out sleeper loveseat
semantic, largest loss, change: -0.304
semantic, largest loss, rewrite: pull out sleeper loveseat sofa couch convertible sofa sofa bed
semantic, largest loss, unjudged products in the rewrite's top 10: 4
semantic, largest gain: nautical platters
semantic, largest gain, change: +0.055
semantic, largest gain, rewrite: nautical platters serving trays seafood platters maritime serving boards
semantic, largest gain, unjudged products in the rewrite's top 10: 0
bm25, largest gain, ndcg@10 typed: 0.501
bm25, largest gain, ndcg@10 spelling fixed only: 0.501
bm25 stop words among an and and: an, and

As duas maiores perdas vêm de uma reescrita que descarta ou amplia o que o cliente pediu. A maior perda do BM25, -0.471 para fold in half table, vem de folding table, collapsible table, drop leaf table, gateleg table, que descarta in half e acrescenta outros tipos de mesa; 3 dos seus 10 primeiros são não julgados. A maior perda da recuperação semântica, -0.304 para pull out sleeper loveseat, vem de pull out sleeper loveseat sofa couch convertible sofa sofa bed, que amplia uma poltrona para qualquer sofá; 4 dos seus 10 primeiros são não julgados.

O maior ganho do BM25, +0.159 para refrigerator with ice an water in door, vem de refrigerator with ice and water in door, fridge with door dispenser, refrigerator with external water and ice dispenser. A reescrita corrige an, mas, só com essa correção, o BM25 pontua 0.501, o mesmo que a consulta como digitada, 0.501, porque as duas grafias são palavras de parada. O ganho vem das palavras que a reescrita acrescenta. O maior ganho da recuperação semântica é +0.055, para nautical platters, reescrita como nautical platters serving trays seafood platters maritime serving boards.

Regra prática: Não coloque uma reescrita por LLM na frente de um recuperador forte sem uma comparação planejada sobre as consultas de teste. Leia as perdas por consulta em busca de requisitos descartados e produtos ampliados, que a instrução do prompt "mantenha todos os requisitos" não impede. A recuperação semântica da loja, o ranqueador a ser superado, continua pesquisando a consulta como digitada.

Busca com um produto hipotético (HyDE)

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

Onde uma reescrita pede ao LLM uma consulta melhor, o HyDE, abreviação de hypothetical document embeddings (embeddings de documentos hipotéticos), pede a ele o documento que imagina responder à consulta. Um codificador gera o embedding do documento hipotético, escrito por um LLM para responder à consulta, e o vetor cai em uma vizinhança do espaço de embeddings do corpus onde estão os documentos reais (Gao et al., 2023). Os detalhes inventados não precisam ser verdadeiros: os autores argumentam que o gargalo denso do codificador filtra detalhes alucinados, e isso é um argumento deles, não uma medição. Seus resultados principais usam o InstructGPT (text-davinci-003), amostrado com temperatura 0.7. No TREC DL19, um benchmark de ranqueamento de passagens, o HyDE elevou o nDCG@10 do Contriever, um modelo de embeddings treinado sem rótulos de relevância, de 44.5 para 61.3 em uma escala de 0 a 100 (Gao et al., Tabela 1). Com um Contriever ajustado com rótulos, o resultado dependeu do LLM. Os menores reduziram levemente o nDCG@10, já que modelos de instrução mais fracos podem prejudicar o desempenho geral do recuperador ajustado, enquanto o InstructGPT o elevou, sobretudo no DL19, de 62.1 para 67.4 (Tabela 4).

Vários métodos de expansão mantêm a consulta original na mistura. O HyDE faz a média dos embeddings dos documentos hipotéticos junto com o embedding da própria consulta (Gao et al., seção 3.2). Realimentação de relevância melhora uma consulta a partir de julgamentos sobre seus primeiros resultados, e a versão de Rocchio move o vetor da consulta em direção aos resultados julgados relevantes, mantendo o vetor original na soma (Manning et al., 2008). Para o BM25, o query2doc repete a consulta cinco vezes antes da passagem gerada, para que os termos originais mantenham seu peso (Wang et al., 2023).

A gravação do HyDE contém um produto hipotético por consulta, que o LLM da loja escreveu a partir apenas da consulta: um nome, uma classe e uma descrição, incorporados como um produto. A função hyde aqui faz a média dele com o embedding da consulta e reescala o resultado para comprimento 1, como o capítulo 6 recomenda após qualquer média. Os dois embeddings diferem em um ponto: o da consulta carrega o prompt de consulta do modelo de embeddings, e o do produto não tem nenhum, como ocorre com todos os produtos.

hyde(query) = (embedding(hypothetical product) + embedding(query)) / 2,  then scaled to length 1

Nas consultas de treino, também testamos o embedding do produto hipotético sozinho e, para o BM25, o texto do produto hipotético sozinho e com a consulta repetida cinco vezes antes dele, como o query2doc o pondera. Em seguida, executamos a última das comparações planejadas do capítulo:

hyde-train-and-test.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Scores HyDE, its parts and their combinations with BM25 and semantic retrieval on the train queries, then runs HyDEagainst semantic retrieval as the chapter's last planned comparison on the test queries. The prose's point rests onthe train lines for the hypothetical product alone and on the planned comparison's lines."""import numpy as npfrom lib.lexical import LexicalSearchfrom lib.metrics import evaluatefrom lib.queries import THRESHOLD, report_plannedfrom lib.recorded import llm_rewritesfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrels# the hypothetical products' embeddings come in the table's row order; zip pairs each with its query_idtable, _, hypothetical_vectors = llm_rewrites()hypothetical, vectors = table.set_index("query_id")["hypothetical"], dict(zip(table["query_id"], hypothetical_vectors))bm25, semantic = LexicalSearch(load_products()), SemanticSearch()def hyde(query_id):    """Gao et al.'s average of the hypothetical product's embedding and the query's, scaled back to length 1."""    average = (vectors[query_id] + semantic.query_vectors[query_id]) / 2    return average / np.linalg.norm(average)def runs(queries):    ids, typed = queries.index, queries["query"]    return {"semantic": semantic.run(queries),            "hypothetical alone": {query_id: list(semantic.search_vector(vectors[query_id]).index) for query_id in ids},            "hyde": {query_id: list(semantic.search_vector(hyde(query_id)).index) for query_id in ids},            "bm25": bm25.run(queries),            "bm25, hypothetical alone": bm25.run(queries.assign(query=ids.map(hypothetical))),            "bm25, query five times plus hypothetical": bm25.run(queries.assign(           # query2doc's weighting                query=[" ".join([typed[query_id]] * 5 + [hypothetical[query_id]]) for query_id in ids]))}train = {name: evaluate(run, qrels("train")) for name, run in runs(load_queries("train")).items()}for name, frame in train.items():    print(f"train ndcg@10 {name}: {frame['ndcg@10'].mean():.3f}")    print(f"train judged@10 {name}: {frame['judged@10'].mean():.3f}")change = (train["hypothetical alone"]["ndcg@10"] - train["semantic"]["ndcg@10"]).round(3)    # for choosing, not evidenceprint(f"train queries better, worse, hypothetical alone: {(change > 0).sum()}, {(change < 0).sum()}")print(f"\nthe planned test comparison, threshold {THRESHOLD:.2f}:")test = {name: evaluate(run, qrels("test")) for name, run in runs(load_queries("test")).items()        if name in ["semantic", "hyde"]}for name, frame in test.items():    print(f"test judged@10 {name}: {frame['judged@10'].mean():.3f}")report_planned("hyde, semantic", test["hyde"]["ndcg@10"], test["semantic"]["ndcg@10"])
Saídapython hyde-train-and-test.py
train ndcg@10 semantic: 0.772
train judged@10 semantic: 0.964
train ndcg@10 hypothetical alone: 0.704
train judged@10 hypothetical alone: 0.890
train ndcg@10 hyde: 0.769
train judged@10 hyde: 0.946
train ndcg@10 bm25: 0.695
train judged@10 bm25: 0.930
train ndcg@10 bm25, hypothetical alone: 0.644
train judged@10 bm25, hypothetical alone: 0.854
train ndcg@10 bm25, query five times plus hypothetical: 0.694
train judged@10 bm25, query five times plus hypothetical: 0.912
train queries better, worse, hypothetical alone: 13, 29

the planned test comparison, threshold 0.01:
test judged@10 semantic: 0.990
test judged@10 hyde: 0.970
hyde, semantic, mean difference: -0.031
hyde, semantic, wins, losses, ties: 8, 14, 8
hyde, semantic, permutation p: 0.108
hyde, semantic, established at 0.01: no
hyde, semantic, t-test p: 0.121
hyde, semantic, t-test agrees: yes
hyde, semantic, 99% interval: -0.115 to 0.001
hyde, semantic, interval agrees: yes

Nas consultas de treino, o produto hipotético sozinho leva o nDCG@10 da recuperação semântica de 0.772 para 0.704, e os números de consultas que pontuam melhor e pior são 13, 29. Judged@10 cai junto, de 0.964 para 0.890.

Com a média da consulta, ele pontua 0.769, com judged@10 de 0.946. O BM25 se comporta da mesma forma: 0.695 com a consulta, 0.644 com o texto hipotético sozinho e 0.694 com a consulta repetida cinco vezes antes dele, com judged@10 de 0.930, 0.854 e 0.912.

Manter a consulta recupera o que o produto hipotético perde, e, nas consultas de treino, para qualquer um dos dois recuperadores, a combinação não acrescenta nada em relação à consulta sozinha. Os números de treino orientam o desenho; só a comparação de teste planejada é evidência.

Nas consultas de teste, judged@10 vai de 0.990 para 0.970, e o HyDE não mostra diferença estabelecida em relação à recuperação semântica (comparações planejadas). Este resultado vale para um produto hipotético por consulta, gerado pelo modelo de 12 bilhões de parâmetros da loja, gemma4:12b-it-q4_K_M, executado com temperatura 0. Gao et al. amostraram de um LLM muito maior, e somente esse elevou o seu recuperador ajustado.

Regra prática: Ao testar o HyDE, sempre faça a média com o embedding próprio da consulta. Espere os maiores ganhos com um codificador treinado sem rótulos; com um codificador ajustado, Gao et al. viram ganhos apenas com o maior LLM deles, e a loja, com seu modelo, prompt e codificador, não viu nenhum. Em um codificador como o da loja, que já supera o BM25 nessas consultas, teste o HyDE antes de pagar uma chamada de LLM por consulta. A loja não o usa.

Transforme uma pergunta de acompanhamento em consulta autônoma

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

A última lacuna da abertura do capítulo vem da conversa: a próxima mensagem de um comprador muitas vezes depende da anterior, como in white refina uma busca por uma mesa. A recuperação enxerga apenas um texto, então uma pergunta de acompanhamento precisa se tornar uma consulta autônoma, uma que se lê sem os turnos anteriores e mantém o que o comprador ainda quer. A reescrita de consultas conversacionais transforma uma pergunta dependente do contexto em uma pergunta autossuficiente, com a mesma resposta, e o conjunto de dados CANARD contém 40,527 dessas reescritas (Elgohary et al., 2019). No TREC CAsT 2019, uma avaliação de busca conversacional, as reescritas feitas por pessoas superaram o melhor sistema automático em 35% em termos relativos (Dalton et al., 2020). Trabalhos posteriores com LLMs guiados por prompts descobriram que "reescritas informativas de consulta podem produzir um desempenho de recuperação substancialmente melhor do que reescritas humanas, especialmente com recuperadores esparsos" (Ye et al., 2023), e no TREC iKAT 2025, sucessor do CAsT, a maioria das execuções usou LLMs em seus pipelines, para reescrita de consulta única ou múltipla (visão geral do TREC iKAT 2025).

WANDS não tem conversas, então escrevemos as conversas da loja para o livro: 12 perguntas de acompanhamento, cada uma refinando uma consulta de teste por um atributo: cor, forma, tamanho ou acabamento. O LLM da loja, que viu apenas os dois turnos, reescreveu cada uma para que fosse autônoma. Por exemplo, depois de coat rack for bedroom vem something in black, reescrita como black coat rack for bedroom. Os julgamentos avaliam produtos para a primeira consulta, não para a consulta refinada, então o nDCG não consegue pontuar a pergunta de acompanhamento. Em vez disso, contamos três tipos de produto em cada top 10: os que mantêm o refinamento, porque seus attributes ou texto contêm o valor, como black (o exemplo também imprime a contagem só com attributes); os do tipo certo, que os juízes classificaram como exato ou parcial para a primeira consulta; e os que são as duas coisas. Comparamos a pergunta de acompanhamento sozinha com os dois turnos unidos e com a consulta autônoma, cada uma embutida como consulta, tendo a primeira consulta como linha de base. Aplicamos um filtro sobre os 100 primeiros resultados da consulta autônoma que mantém apenas produtos que declaram o valor, tirando o valor da conversa registrada; um sistema em produção precisaria extraí-lo da pergunta de acompanhamento.

follow-up-refinements.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Counts, in each conversation's top 10, the products that keep the refinement and the products of the right kind, forthe follow-up alone, the joined turns, the standalone query, and the standalone query filtered by the value. The prose'spoint rests on the "refinement in text or attributes" and "right kind with the refinement" lines."""import numpy as npfrom lib.queries import mentionsfrom lib.recorded import llm_conversationsfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, product_text, qrelsproducts, judgments, semantic = load_products(), qrels("test"), SemanticSearch()attributes, text = products["attributes"], product_text(products)        # the embeddings read only the textconversations, vectors = llm_conversations()                 # follow-ups we wrote for the book, not shoppers'print("conversations:", len(conversations))# row 4, the fifth conversation, which the example printsexample = conversations.iloc[4]print(f"first query: {load_queries().at[example['query_id'], 'query']}")print(f"follow-up: {example['follow_up']}")print(f"standalone: {example['standalone']}")shares, filtered_lengths = {}, []                            # shares: (top 10, measure) -> one share per conversationfor row, (first, value) in enumerate(zip(conversations["query_id"], conversations["value"])):    # the standalone query's top 100, the pool the filter draws from    standalone = semantic.search_vector(vectors["standalone"][row], k=100).index    stated = mentions(standalone, value, attributes) | mentions(standalone, value, text)    tops = {"first query": semantic.search(first, k=10).index,            "follow-up alone": semantic.search_vector(vectors["follow_up"][row], k=10).index,            "turns joined": semantic.search_vector(vectors["joined"][row], k=10).index,            "standalone": standalone[:10],            "standalone, filtered": standalone[stated][:10]}         # given the value, which a live system extracts    filtered_lengths.append(len(tops["standalone, filtered"]))    for name, top in tops.items():        in_attributes = mentions(top, value, attributes)        in_either = in_attributes | mentions(top, value, text)        # the first query's grade 1 (partial) or 2 (exact); a product with no judgment counts as 0        right_kind = np.array([judgments[first].get(product_id, 0) >= 1 for product_id in top], dtype=bool)        for measure, hits in [("refinement in attributes", in_attributes), ("refinement in text or attributes", in_either),                              ("right kind", right_kind), ("right kind with the refinement", in_either & right_kind)]:            shares.setdefault((name, measure), []).append(hits.sum() / 10)     # empty places count as missesfor (name, measure), values in shares.items():    print(f"{name}, {measure}: {np.mean(values):.3f}")kept = np.subtract(shares["standalone", "refinement in text or attributes"], shares["turns joined", "refinement in text or attributes"])print(f"standalone against turns joined, more, fewer, same: {(kept > 0).sum()}, {(kept < 0).sum()}, {(kept == 0).sum()}")print("conversations the filter leaves with fewer than 10 products:", sum(length < 10 for length in filtered_lengths))
Saídapython follow-up-refinements.py
conversations: 12
first query: coat rack for bedroom
follow-up: something in black
standalone: black coat rack for bedroom
first query, refinement in attributes: 0.125
first query, refinement in text or attributes: 0.200
first query, right kind: 0.958
first query, right kind with the refinement: 0.175
follow-up alone, refinement in attributes: 0.433
follow-up alone, refinement in text or attributes: 0.950
follow-up alone, right kind: 0.058
follow-up alone, right kind with the refinement: 0.058
turns joined, refinement in attributes: 0.208
turns joined, refinement in text or attributes: 0.383
turns joined, right kind: 0.933
turns joined, right kind with the refinement: 0.325
standalone, refinement in attributes: 0.200
standalone, refinement in text or attributes: 0.392
standalone, right kind: 0.958
standalone, right kind with the refinement: 0.350
standalone, filtered, refinement in attributes: 0.583
standalone, filtered, refinement in text or attributes: 0.900
standalone, filtered, right kind: 0.675
standalone, filtered, right kind with the refinement: 0.675
standalone against turns joined, more, fewer, same: 5, 4, 3
conversations the filter leaves with fewer than 10 products: 3

A pergunta de acompanhamento sozinha mantém o refinamento em 0.950 do seu top 10, mas apenas 0.058 são do tipo certo de produto. Qualquer forma que carregue a primeira consulta encontra o tipo certo de produto: 0.933 para os turnos unidos e 0.958 para a consulta autônoma.

Nessas conversas, os turnos unidos e a consulta autônoma mantêm o refinamento com mais frequência do que a primeira consulta, que nunca o pediu: 0.383 e 0.392, contra 0.200.

Contando apenas com attributes, as proporções são menores: 0.208, 0.200 e 0.125, porque muitos produtos declaram o valor apenas no texto, que é tudo o que os embeddings leem. As conclusões abaixo baseiam-se na contagem de texto ou atributos, que pode superestimar, pois um produto que menciona round legs conta como redondo.

A reescrita do LLM não se sai melhor do que unir os turnos: em comparação com os turnos unidos, a consulta autônoma mantém mais, menos ou o mesmo número de produtos refinados em 5, 4, 3 conversas, e os produtos do tipo certo que também mantêm o refinamento representam 0.350 dos top 10 da consulta autônoma, contra 0.325 para os turnos unidos.

O filtro eleva essa proporção para 0.675, mas deixa 3 conversas com menos de 10 produtos.

Essas 12 conversas são nossas, não dos compradores, então as contagens são um diagnóstico, não um teste.

Regra prática: Nunca busque uma pergunta de acompanhamento isoladamente. Una-a pelo menos aos turnos anteriores, ou reescreva-a para que seja autônoma. Quando o refinamento nomear um valor que o catálogo declara, extraia-o e use-o para dar peso ou filtrar, e recorra à lista sem filtro quando restarem produtos em número insuficiente. Meça em conversas dos seus próprios registros antes de confiar em qualquer parte disso.

O que dá errado em produção

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

Toda reescrita por LLM é uma chamada ao modelo no caminho da consulta. Os exemplos leem reescritas gravadas uma vez, offline, mas uma caixa de busca ao vivo chama o modelo a cada consulta, enquanto o comprador espera. Os autores do query2doc observam que ele precisa de inferência de LLM, que pode ser consideravelmente mais lenta (Wang et al., 2023), e a consulta mais longa também deixa a busca BM25 mais lenta. Uma regra geral, não uma medição: reescreva offline as consultas frequentes e armazene os resultados em cache, e chame o modelo online apenas para consultas em que um teste mostre ganho.

Uma reescrita pertence a um modelo e a um prompt. Outra versão do modelo ou um prompt reformulado pode alterar qualquer reescrita. Os manifestos das gravações da loja guardam o digest do modelo e cada prompt literalmente, e qualquer mudança em um dos dois exige medir de novo.

O léxico deve acompanhar o catálogo. Um corretor construído a partir do catálogo do mês passado pode tratar nomes de marcas deste mês como erros de digitação. Reconstrua o léxico junto com o índice e registre cada consulta que o corretor altera, ao lado da original, para encontrar correções excessivas como tye → the. Em consultas traduzidas por máquina, erros de grafia mudam quais produtos a busca retorna (Hanneman et al., 2024), então espere que um erro que o corretor não captou se manifeste como resultados instáveis para uma consulta.

O classificador acompanha sua taxonomia. Quando classes de produto são renomeadas, divididas ou fundidas, treine o classificador novamente. Uma classe de consulta que não nomeia nenhuma classe de produto, como Crock Pots & Slow Cookers, nunca pode ser prevista; para 7qt slow cooker, o classificador prevê Slow Cookers no lugar.

Consultas reescritas trazem produtos não julgados. Toda mudança baseada em LLM neste capítulo que foi avaliada com nDCG@10 reduziu o judged@10. Antes de adotar uma reescrita, peça que os produtos não julgados nos top 10 de cada consulta sejam julgados, ou verifique as pontuações condensadas, como faz o capítulo 2.

Regra prática: Registre a consulta como digitada e como reescrita, armazene em cache as reescritas do LLM, versione o modelo e o prompt junto com as saídas, e reconstrua o léxico e o classificador sempre que o catálogo mudar.

Decisões tomadas neste capítulo

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

Cada configuração abaixo foi escolhida com as consultas de treino. A tabela traz as 5 comparações planejadas do capítulo sobre as consultas de teste, uma por coluna: um recuperador com uma mudança, contra o mesmo recuperador na consulta como foi digitada.

Medida BM25, sinônimos Semântico, reforço por classe BM25, reescrita por LLM Semântico, reescrita por LLM Semântico, HyDE
Diferença média 0.000 0.005 -0.056 -0.081 -0.031
Vitórias, derrotas, empates 0, 0, 30 7, 4, 19 13, 15, 2 7, 19, 4 8, 14, 8
p de permutação 1.000 0.174 0.060 0.000 0.108
Estabelecida no no no yes no
p do teste t 1.000 0.164 0.060 0.000 0.121
Intervalo de 99% 0.000 to 0.000 -0.002 to 0.017 -0.143 to 0.005 -0.132 to -0.035 -0.115 to 0.001
Teste t concorda yes yes yes yes yes
Intervalo concorda yes yes yes yes yes
  • Ortografia: corrigir somente palavras que o catálogo não usa. O corretor corrige os erros de digitação da loja nas consultas de treino, mas as consultas com erro de digitação são poucas para testá-lo, e ele precisa de contexto antes de tratar tye dye ou ice an water. A loja ainda não o executa.
  • Unidades: uma forma escrita para produtos e consultas, a partir da grafia do próprio catálogo, com decimais mantidos inteiros. As consultas de tamanho são poucas para testá-lo, por isso o BM25 de referência permanece como está.
  • Sinônimos: uma lista para lacunas observadas nas consultas de treino, apenas para o BM25. Ela alterou 1 das consultas de teste e não mostrou diferença estabelecida, por isso a referência não expande.
  • Classes de consulta: Bayes ingênuo treinado sobre o texto dos produtos, porque a amostra tem no máximo uma consulta por classe. A classe prevista é apenas uma dica. Um filtro perde no treino, e o melhor reforço não é estabelecido no teste, por isso a recuperação semântica permanece sem reforço.
  • Reescritas por LLM: não usadas. A perda para a recuperação semântica é estabelecida, e a mudança do BM25 não é.
  • HyDE: não usado. Calculado em média com a consulta, não mostra diferença estabelecida, e o produto hipotético sozinho perde no treino.
  • Perguntas de acompanhamento: nunca pesquisadas isoladamente. Unir os turnos tem desempenho semelhante à consulta independente do LLM. Um filtro sobre o valor refinado é o próximo passo, e ele exige um valor extraído e um plano alternativo.
  • Os recuperadores recebem a consulta como foi digitada: a recuperação semântica continua sendo o ranqueador a ser superado, e o BM25, sem radicalização, continua sendo a referência.
  • O que o capítulo mostrou: uma mudança que parece correta nas consultas de treino precisa vencer uma comparação planejada nas consultas de teste, e nenhuma das mudanças testadas aqui venceu como ganho. A reescrita do LLM foi a única diferença estabelecida, e foi uma perda para a recuperação semântica.

Este capítulo, nesta edição

Edição 2026.11.10Exemplos aprovados em 19 de nov de 202612 de 12 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 8 de 11: Compreendendo consultas

  1. Corrija a ortografia com base nas palavras do catálogo
  2. Normalize as unidades do jeito que o catálogo as escreve
  3. Expanda consultas com uma lista de sinônimos
  4. Treinar um classificador de consultas com texto de produtos
  5. Reforçar a classe prevista em vez de filtrar
  6. Reescrever consultas com um LLM
  7. Busca com um produto hipotético (HyDE)
  8. Transforme uma pergunta de acompanhamento em consulta autônoma
  9. O que dá errado em produção
  10. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos