Busca, de ponta a ponta

Cerca de 36 minutos min de leitura, com 11 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 montar um pipeline de busca aproximado, mas completo, para um catálogo de produtos, que vai da consulta de um cliente até uma lista ordenada de produtos, e de medir com um único número se uma mudança nesse pipeline ajuda. Cada capítulo seguinte pega uma parte desse pipeline e a torna sólida.

Clientes de uma loja online de móveis e itens para casa digitam consultas como clear shower curtain ou 48 inch kitchen hood na caixa de busca. O livro acompanha essa loja do começo ao fim e a chama de loja. A loja precisa de duas respostas: quão boa é a sua busca e se uma mudança a torna melhor. Você vai enfrentar essas mesmas duas perguntas com qualquer sistema de busca, então o livro testa todos os métodos na loja, onde você pode ver o que cada um faz com consultas reais.

A loja tem o que é necessário para responder a elas: um catálogo, um conjunto de consultas reais e julgamentos de pessoas sobre quais produtos correspondem a cada consulta. Assim, neste capítulo você vai buscar no catálogo de três maneiras (por correspondência de palavras, por correspondência de significado e pela combinação das duas), reordenar os melhores resultados com um modelo mais lento e avaliar cada versão em relação a esses julgamentos. Nem toda etapa melhora a pontuação. Essa é a principal lição do capítulo: meça cada mudança.

Carregue os dados da loja

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

Antes de melhorar um sistema de busca, você precisa de três coisas: os itens que ele pesquisa, as consultas que as pessoas digitam e julgamentos que dizem quais itens correspondem a cada consulta. Mecanismos de busca chamam os itens de documentos. Neste livro, eles são produtos. Um julgamento é o rótulo que uma pessoa atribui a um par formado por uma consulta e um produto, e um grau é o número que representa o rótulo de um julgamento. Sem julgamentos, você pode observar resultados e formar opiniões, mas não consegue distinguir uma correção de uma regressão.

Os dados da loja, que os exemplos do livro pesquisam e avaliam, são reais. Trata-se de uma amostra do WANDS, um conjunto de dados público de busca de produtos que a Wayfair publicou com um artigo na ECIR 2022 (Chen et al., 2022), sob a licença MIT (licença). O conjunto completo tem 42,994 produtos, 480 consultas e 233,448 julgamentos (repositório). As consultas são uma amostra estratificada de consultas reais de compradores, extraída de um trimestre de registros de busca de 2021, e cada rótulo é o voto majoritário de até três anotadores treinados (Chen et al., seções 4.1 e 5). O script prep/wands_sample.py gera a amostra do livro, e o cartão de dados da amostra, examples/data/wands/README.md, explica como. O código de configuração de que muitos exemplos precisam está nos módulos compartilhados do livro, arquivos curtos em examples/lib/ que você pode abrir e ler. lib.store, um desses módulos, carrega a amostra, e o exemplo seguinte imprime o que é retornado:

load-the-store.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 Aprovado
"""Loads the store's sample and prints its size, how its queries split, and how its judgments are labelled. The prose quotes the split from the `train queries` and `test queries` lines."""import pandas as pdfrom lib.store import DATA, load_labels, load_products, load_queriesproducts = load_products()queries = load_queries()labels = load_labels()                                   # one row per judged (query, product) pairconflicts = pd.read_csv(DATA / "label_conflicts.csv")    # pairs WANDS labelled two waysprint(f"products: {len(products):,}")print("queries:", len(queries))print("train queries:", (queries["split"] == "train").sum())print("test queries:", (queries["split"] == "test").sum())print(f"judged pairs: {len(labels):,}")print("pairs with conflicting labels:", len(conflicts))for label in ["exact", "partial", "irrelevant"]:    print(f"{label} pairs: {(labels['label'] == label).sum():,}")print(f"products judged for at least one query: {labels['product_id'].nunique():,}")print()print(queries.head(4).to_string())
Saídapython load-the-store.py
products: 12,000
queries: 80
train queries: 50
test queries: 30
judged pairs: 13,077
pairs with conflicting labels: 7
exact pairs: 3,252
partial pairs: 7,972
irrelevant pairs: 1,853
products judged for at least one query: 11,917

                               query        query_class  split
query_id
6                acrylic clear chair      Dining Chairs  train
10                   king poster bed               Beds  train
20          foutains with brick look          Wallpaper  train
36        laundry basket with wheels  Hampers & Baskets  train

A amostra tem 12,000 produtos e 80 consultas. Ela divide as consultas uma única vez, antes que qualquer ranqueador seja executado: 50 consultas de treino para ajuste e 30 consultas de teste para relatório. Toda pontuação deste livro é relatada nas consultas de teste, e nada é ajustado com base nelas. Uma pontuação em consultas com as quais você ajustou mede o quanto o sistema se ajustou a essas consultas, não o quão bem a busca funciona.

O WANDS julgou alguns pares mais de uma vez. A amostra mantém uma linha por par, 13,077 no total. Quando os rótulos de um par diferem, ela mantém o grau mais baixo e lista o par em label_conflicts.csv, que contém 7 pares. O código que pontua um ranqueamento lê os julgamentos por meio de lib.store.qrels, que os devolve como {query_id: {product_id: grade}}. O Capítulo 2 analisa os julgamentos com atenção.

Cada julgamento é um de três rótulos, definidos pelos autores do conjunto de dados (Chen et al., seção 3.2). Exato significa que o produto corresponde totalmente à consulta de busca. Parcial significa que ele "só corresponde à entidade-alvo da consulta, mas não atende aos modificadores da consulta". Irrelevante significa que o produto não é relevante para a consulta. Os graus do livro são 2, 1 e 0. Entre os pares julgados, 3,252 são exatos, 7,972 parciais e 1,853 irrelevantes. Neste livro, um produto relevante é aquele julgado como exato para a consulta, salvo se uma frase disser o contrário.

Três advertências acompanham os dados da loja. Primeiro, a query_class de cada consulta é a classe prevista pelo WANDS para ela, não um julgamento (Chen et al., Tabela 1): foutains with brick look é classificada como Wallpaper. Trate-a como uma dica. Segundo, ninguém julgou todos os produtos para todas as consultas. Isso teria exigido cerca de 60 milhões de julgamentos, então o WANDS julgou candidatos reunidos a partir de produtos que compradores clicaram ou adicionaram ao carrinho e de vários sistemas de busca, e parou quando surgiram poucas novas correspondências exatas (Chen et al., seções 4.2 e 4.3). Um produto sem julgamento para uma consulta é não julgado: desconhecido, não irrelevante. Terceiro, quase todos os produtos da amostra, 11,917 de 12,000, são julgados para pelo menos uma de suas consultas, por isso a amostra contém menos distratores do que um catálogo completo teria: produtos que disputam as primeiras posições de uma consulta sem corresponder a ela.

Regra prática: Divida suas consultas em treino e teste antes de alterar qualquer coisa. Leia os resultados de teste para entender um ranqueador, mas escolha e ajuste toda mudança com consultas de treino, e relate com as de teste. Trate produtos não julgados como desconhecidos. Se ainda não tiver julgamentos, reúna alguns antes de mudar o ranqueamento.

Ordene produtos com BM25

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

Pesquisar o catálogo da loja envolve duas tarefas. Recuperação encontra os produtos que podem corresponder a uma consulta, dentre todo o catálogo. Ranqueamento coloca os produtos recuperados em ordem, do melhor para o pior. A abordagem lexical faz as duas coisas comparando as palavras da consulta com as palavras do texto de cada produto e atribuindo uma pontuação à sobreposição entre elas.

BM25 é uma função de pontuação lexical com três partes. Um produto recebe pontuação maior quando contém as palavras da consulta, e recebe ainda mais quando essas palavras são raras, porque uma palavra que aparece em poucos produtos diz mais sobre eles. Repetir uma palavra acrescenta cada vez menos, até um limite, fenômeno que a literatura sobre BM25 chama de saturação. E um texto longo sofre desconto em relação a um texto curto, de modo que não pode vencer apenas por conter mais palavras; o parâmetro b define o tamanho desse desconto, de 0 (sem desconto) a 1 (desconto total) (Robertson and Zaragoza, 2009). O Capítulo 5 constrói a fórmula manualmente.

O BM25 do livro roda na bm25s 0.3.16, uma biblioteca Python para BM25. Por padrão, ela calcula a pontuação com a variante do BM25 usada pela biblioteca de busca Lucene, com k1=1.5 (a configuração de saturação) e b=0.75 (código-fonte da bm25s). Suas pontuações diferem um pouco da fórmula clássica dos livros-texto, mas um estudo de reprodutibilidade com três coleções de notícias não encontrou diferenças significativas de eficácia entre as variantes do BM25 (Kamphuis et al., 2020). Antes de calcular as pontuações, a bm25s divide o texto em tokens. Ela os converte para minúsculas, mantém palavras com dois ou mais caracteres, remove as stopwords do inglês, como and, e não reduz as palavras a um radical comum (tokenizador da bm25s). O ranqueador usado neste livro, lib.lexical.LexicalSearch, indexa o nome, a classe, a categoria e a descrição de cada produto, unidos em um único texto.

A consulta de teste da loja, clear shower curtain, mostra o BM25 em funcionamento. Um cliente que a digita quer uma cortina transparente, e o catálogo tem muitas cortinas que não são transparentes, além de acessórios que compartilham as mesmas palavras. Estes são os 10 primeiros resultados do BM25:

A maioria dos dez são cortinas de box ou forros, mas os últimos são ganchos para cortina de box. O BM25 encontrou as palavras "shower curtain" nos nomes dos ganchos e lhes atribuiu uma pontuação quase tão alta quanto a das cortinas, porque ele combina palavras, não coisas: não tem como saber que um gancho não é uma cortina. Nada impresso aqui indica se as cortinas são claras. Para isso, você precisa dos julgamentos da loja.

Regra prática: comece com o BM25 nos padrões da biblioteca como sua linha de base. Ele não exige dados de treinamento nem modelo, e, quando falha, você consegue ver quais palavras causaram o problema. Não altere seus parâmetros até conseguir medir uma mudança em consultas de treinamento. Quando clientes e produtos usarem palavras diferentes para a mesma coisa, adicione a recuperação semântica.

Verifique os resultados contra os julgamentos

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

Um ranking significa pouco enquanto você não sabe o que o comprador queria. Os julgamentos fornecem essa informação, um par de cada vez. Para esse propósito, eles são evidências melhores do que os cliques. Os autores do WANDS observam que "User behavior log data suffer from positional biases and would favor the rankings similar to the production system" (Chen et al., seção 3.1). Um comprador clica no que é mostrado primeiro, então os cliques, em geral, apenas confirmam o ranking que você já tem.

Em seguida, coloque cada um dos 10 primeiros produtos do BM25 para clear shower curtain ao lado do seu julgamento. Um produto que ninguém julgou para essa consulta aparece como unjudged:

judge-first-results.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Puts BM25's top 10 for `clear shower curtain` beside each product's judgment, and counts the labels. The prose's reading of the top 10 rests on the labelled rows and the `in the top 10` lines after them."""from lib.lexical import LexicalSearchfrom lib.store import load_products, load_queries, qrelsLABELS = {2: "exact", 1: "partial", 0: "irrelevant"}products = load_products()query_id = 246query = load_queries().at[query_id, "query"]judgments = qrels()[query_id]                        # {product_id: grade} for this querytop = LexicalSearch(products).search(query, k=10).index# a product with no judgment for this query is unjudged, not irrelevantresults = [LABELS.get(judgments.get(product_id), "unjudged") for product_id in top]print("query:", query)print()for rank, (product_id, label) in enumerate(zip(top, results), start=1):    print(f"{rank:>2}  {label:<10}  {products.at[product_id, 'name'][:55]}")print()for label in ["exact", "partial", "irrelevant", "unjudged"]:    print(f"{label} in the top 10: {results.count(label)}")print("products judged for this query:", len(judgments))print("exact products judged for this query:", sum(grade == 2 for grade in judgments.values()))
Saídapython judge-first-results.py
query: clear shower curtain

 1  partial     rodas vinyl shower curtain
 2  exact       woolley vinyl single shower curtain
 3  exact       woolley vinyl solid color single shower curtain
 4  exact       siniard single shower curtain
 5  exact       simmon vinyl single shower curtain liner
 6  partial     71 '' x71 '' 4pcs shower curtain sets beach theme showe
 7  partial     newburg check 3d vinyl single shower curtain + hooks
 8  irrelevant  gilded pineapple shower curtain hooks
 9  irrelevant  double shower curtain hooks
10  irrelevant  stainless steel shower curtain hooks

exact in the top 10: 4
partial in the top 10: 3
irrelevant in the top 10: 3
unjudged in the top 10: 0
products judged for this query: 253
exact products judged for this query: 12

Os 10 primeiros resultados do BM25 contêm 4 produtos exatos, 3 produtos parciais, 3 produtos irrelevantes (os ganchos) e 0 produtos não julgados. O primeiro resultado é parcial: pela definição do conjunto de dados, ele corresponde ao que o comprador pediu, uma cortina de chuveiro, mas não ao modificador clear.

Os julgamentos também mostram o que um top 10 ideal conteria. Os avaliadores classificaram 253 produtos para esta consulta, 12 deles exatos. Assim, um ranking ideal poderia preencher as dez posições com produtos exatos, e o BM25 preencheu 4. Essa diferença é o que uma métrica precisa medir.

Ler os resultados dessa forma mostra o tipo de erro que um ranqueador comete. Aqui, o BM25 casou as palavras de um acessório e deixou de considerar um modificador. Uma média sobre muitas consultas esconde isso, e os erros que você vê são os que você pode corrigir.

Regra prática: Antes de calcular qualquer métrica, leia os primeiros resultados de cinco ou dez consultas ao lado de seus julgamentos. Procure padrões: acessórios, modificadores ignorados, tamanhos errados. Quando vários dos primeiros resultados não forem julgados, peça que sejam julgados antes de confiar em uma pontuação para essa consulta.

Pontue um ranking com nDCG@10

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

Para comparar rankings, você precisa de um número por ranking. Ele deve recompensar produtos correspondentes, e os exatos mais do que os parciais, e contar um produto próximo ao topo mais do que um próximo ao fim, porque os compradores leem de cima para baixo. Ganho cumulativo descontado normalizado em 10, nDCG@10, faz as três coisas.

Em palavras: cada um dos 10 primeiros resultados recebe um ganho igual ao seu grau: 2 para exato, 1 para parcial, 0 para irrelevante. O ganho é dividido por um desconto que cresce com a posição: log2 da posição mais um, de modo que o primeiro resultado conta por inteiro e o terceiro conta pela metade. Somando os ganhos descontados obtém-se o ganho cumulativo descontado, DCG. Dividindo pelo DCG do melhor top 10 possível para aquela consulta, o DCG ideal, a pontuação fica entre 0 e 1, em que 1 significa que não existe top 10 melhor. Um produto não julgado ganha 0.

DCG@10  = sum over positions i from 1 to 10 of  grade(i) / log2(i + 1)
nDCG@10 = DCG@10 / ideal DCG@10

O artigo do WANDS também pontua a busca com nDCG@10, com ganhos de 1.0, 0.5 e 0 para exato, parcial e irrelevante (Chen et al., seção 6). Os graus do livro são o dobro desses ganhos, o que dobra tanto o DCG quanto o DCG ideal, e por isso o nDCG não muda.

Considere o ranking do BM25 para clear shower curtain: primeiro um produto parcial, depois cortinas exatas e parciais, e então três ganchos irrelevantes. Calcule à mão o DCG, o DCG ideal e a razão entre eles, e depois compare com lib.metrics, o módulo compartilhado de métricas do livro:

ndcg-for-one-query.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Computes nDCG@10 for one test query step by step, then checks it against `lib.metrics`. The prose's point rests on the `ndcg@10` line and on the library line that prints the same value."""import mathfrom lib.lexical import LexicalSearchfrom lib.metrics import ndcg_at_kfrom lib.store import load_products, load_queries, qrelsproducts = load_products()query = load_queries().at[246, "query"]                      # "clear shower curtain"judgments = qrels("test")[246]                                # {product_id: grade}ranking = list(LexicalSearch(products).search(query, k=10).index)grades = [judgments.get(product_id, 0) for product_id in ranking]     # unjudged counts as 0# positions count from 1, so the first result is discounted by log2(2) = 1dcg = sum(grade / math.log2(position + 1) for position, grade in enumerate(grades, start=1))best = sorted(judgments.values(), reverse=True)[:10]                  # the best possible top 10ideal = sum(grade / math.log2(position + 1) for position, grade in enumerate(best, start=1))print("grades:", grades)print("best grades:", best)print(f"dcg@10: {dcg:.3f}")print(f"ideal dcg@10: {ideal:.3f}")print(f"ndcg@10: {dcg / ideal:.3f}")print(f"ndcg@10 from lib.metrics: {ndcg_at_k(ranking, judgments, 10):.3f}")
Saídapython ndcg-for-one-query.py
grades: [1, 2, 2, 2, 2, 1, 1, 0, 0, 0]
best grades: [2, 2, 2, 2, 2, 2, 2, 2, 2, 2]
dcg@10: 5.586
ideal dcg@10: 9.087
ndcg@10: 0.615
ndcg@10 from lib.metrics: 0.615

O ranking ganha um DCG de 5.586. O melhor top 10 possível contém apenas produtos exatos e ganha 9.087. A razão entre eles, 0.615, coincide com o que ndcg_at_k em lib.metrics retorna: 0.615. O produto parcial na posição 1 custa mais do que qualquer resultado isolado, porque ocupa o lugar sem desconto. Cada gancho custa menos, porque está mais abaixo, mas juntos custam mais.

Esse único número resume o que os julgamentos mostraram: um ranking que encontrou o tipo certo de produto e cometeu dois tipos de erro. Você pode calcular para qualquer ranking de qualquer consulta julgada e comparar.

Regra prática: Use o nDCG@10 como métrica principal quando seus julgamentos forem graduados e a primeira página de resultados importar mais, como acontece na busca de uma loja. Quando você tiver apenas rótulos de sim ou não, ou quando os compradores olharem apenas um resultado, outra métrica se encaixa melhor. O capítulo 3 constrói as alternativas e diz quando escolher cada uma.

Pontue todas as consultas de teste

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

Uma consulta é uma anedota. Para julgar um ranqueador, pontue-o em um conjunto fixo de consultas e calcule a média: neste livro, as consultas de teste. Os rankings de todas as consultas de um conjunto formam uma execução, escrita como {query_id: [product_id, ...]}, da melhor para a pior posição. lib.metrics.evaluate pontua uma execução contra os julgamentos e retorna uma linha por consulta.

Ao lado do nDCG@10, evaluate informa o judged@10: a fração dos 10 primeiros produtos que tem algum julgamento para a consulta. Como produtos não julgados contam como nota 0, um judged@10 baixo significa que a pontuação é, em parte, um palpite. Ela não consegue distinguir um produto irrelevante de um produto relevante que ninguém julgou.

Agora execute o BM25 em todas as consultas de teste, mantenha os 100 primeiros produtos de cada uma e pontue a execução:

bm25-test-scores.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Scores BM25 on every test query, keeping each query's top 100, and prints the averages and the spread. The prose's point rests on the mean and judged@10 lines and on the three lowest queries printed after them."""from lib.lexical import LexicalSearchfrom lib.metrics import evaluatefrom lib.store import load_products, load_queries, qrelsLABELS = {2: "exact", 1: "partial", 0: "irrelevant"}products, queries, judgments = load_products(), load_queries("test"), qrels("test")run = LexicalSearch(products).run(queries, k=100)       # {query_id: [product_id, ...]}scores = evaluate(run, judgments)                        # one row per test queryscores["query"] = queries["query"]print("test queries:", len(scores))print(f"mean ndcg@10: {scores['ndcg@10'].mean():.3f}")print(f"mean judged@10: {scores['judged@10'].mean():.3f}")print(f"lowest ndcg@10: {scores['ndcg@10'].min():.3f}")print(f"median ndcg@10: {scores['ndcg@10'].median():.3f}")print(f"highest ndcg@10: {scores['ndcg@10'].max():.3f}")print("queries with ndcg@10 of 1:", (scores["ndcg@10"].round(3) == 1).sum())print()lowest = scores.nsmallest(3, "ndcg@10")print(lowest[["query", "ndcg@10", "judged@10"]].round(3).to_string())print("lowest query:", lowest["query"].iloc[0])print(f"judged@10 of the lowest query: {lowest['judged@10'].iloc[0]:.3f}")print()# query 133, outdoor light fixtures, is the second-lowest scorer in the table aboveprint(f"judged@10 for {queries.at[133, 'query']}: {scores.at[133, 'judged@10']:.3f}")print("bm25 top 5 for", queries.at[133, "query"])for product_id in run[133][:5]:    label = LABELS.get(judgments[133].get(product_id), "unjudged")    print(f"  {label:<10}  {products.at[product_id, 'name'][:60]}")
Saídapython bm25-test-scores.py
test queries: 30
mean ndcg@10: 0.725
mean judged@10: 0.927
lowest ndcg@10: 0.212
median ndcg@10: 0.687
highest ndcg@10: 1.000
queries with ndcg@10 of 1: 4

                            query  ndcg@10  judged@10
query_id
46           beach blue headboard    0.212        0.5
133        outdoor light fixtures    0.286        0.2
292       decorative white pillow    0.467        1.0
lowest query: beach blue headboard
judged@10 of the lowest query: 0.500

judged@10 for outdoor light fixtures: 0.200
bm25 top 5 for outdoor light fixtures
  exact       malikah 1 -bulb outdoor bulkhead light
  unjudged    60 watt equivalent e12 led candle light bulb
  unjudged    5w ( 40 watt equivalent ) , b11 led , dimmable light bulb e1
  unjudged    60 watt equivalent , a19 led , non-dimmable light bulb , war
  unjudged    40 watt equivalent e12 dimmable led edison candle light bulb

Em 30 consultas de teste, o BM25 obtém em média um nDCG@10 de 0.725, com um judged@10 médio de 0.927. Essa média é o primeiro resultado medido da loja, e todos os ranqueadores posteriores são comparados com ele.

A média esconde uma grande dispersão. As pontuações vão de 0.212 a 1.000, com mediana de 0.687, e 4 consultas obtêm a nota máxima, 1.

A consulta de menor pontuação, beach blue headboard, tem judged@10 de 0.500. Outra consulta com baixa pontuação, outdoor light fixtures, tem judged@10 de 0.200: o top 5 do BM25 traz uma luminária externa exata, seguida de lâmpadas que compartilham as palavras da consulta e que ninguém julgou para essa consulta. Uma lâmpada não é uma luminária, então, aqui, a nota 0 provavelmente é justa. Mas a métrica não tem como saber disso, e, para outro ranqueador ou outra consulta, produtos não julgados podem ser bons.

Regra prática: informe a média do nDCG@10 sobre as consultas de teste ao lado do judged@10 médio, e leia as consultas de menor pontuação sempre que pontuar uma execução. Quando o judged@10 de um ranqueador for menor que o de outro, descubra o motivo antes de comparar os nDCG deles: a diferença pode vir de julgamentos ausentes, e não de resultados piores.

Busca por significado com embeddings

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

A recuperação léxica falha quando as palavras do comprador e as do produto são diferentes, ou quando palavras iguais têm significados diferentes, como os ganchos que o BM25 ranqueia para clear shower curtain. A recuperação semântica compara os significados da consulta e do produto, em vez de suas palavras. Ela se apoia em embeddings. Um embedding é uma lista de números, um vetor, que uma rede neural calcula para um trecho de texto. A rede é treinada para que textos com significados parecidos recebam vetores que apontam para direções parecidas. Você calcula o embedding de cada produto uma única vez, com antecedência. Na hora da busca, calcula-se o embedding da consulta e retornam-se os produtos cujos vetores estão mais próximos dele. Com todos os vetores normalizados para comprimento 1, a proximidade é o produto escalar entre dois vetores, que é igual ao cosseno do ângulo entre eles.

Calcular os embeddings dos produtos com antecedência é o que torna isso rápido. No artigo que apresentou o Sentence-BERT, encontrar o par mais parecido entre 10,000 sentenças levou cerca de 65 horas em uma GPU V100 quando o BERT lia cada par. Calcular o embedding de cada sentença uma vez e comparar os embeddings levou cerca de 5 segundos, quase todos gastos no cálculo dos embeddings; a comparação em si levou cerca de 0.01 segundo (Reimers and Gurevych, 2019).

Os embeddings da loja vêm do modelo aberto Snowflake/snowflake-arctic-embed-m-v1.5. Os exemplos nunca chamam um modelo, para que todos rodem offline e deem a mesma saída a cada vez. Em vez disso, uma gravação, aqui o script recordings/embeddings.py, executa o modelo uma vez e salva seus vetores, e os exemplos leem esses vetores offline por meio de lib.recorded. Escolhemos este modelo porque ele é aberto e está sob a licença Apache 2.0, de modo que qualquer pessoa pode baixar a versão fixada e executar a gravação novamente. A gravação acrescenta a cada consulta a instrução que o cartão do modelo pede ("Represent this sentence for searching relevant passages:") e calcula os embeddings dos produtos como eles estão (model card). A recuperação semântica do livro, construída como lib.semantic.SemanticSearch, multiplica cada vetor de produto pelo vetor da consulta e ordena os resultados. O capítulo 6 a constrói passo a passo.

Cada produto é um vetor de 768 números, e a recuperação semântica compara o vetor da consulta com cada um deles; a seguir estão os dez mais próximos, com seus julgamentos:

Nessa consulta, a recuperação semântica vai melhor que o BM25. Suas 10 primeiras posições trazem 5 produtos exatos, contra 4 do BM25, e 0 irrelevantes. Seu nDCG@10 é 0.793, contra 0.615 do BM25. Observe como as similaridades são próximas: a primeira e a décima diferem por 0.035. A recuperação semântica sempre retorna algo, ordenado por pequenas diferenças.

Uma única consulta pode enganar, então compare os dois ranqueadores em cada consulta de teste:

compare-lexical-semantic.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Scores BM25 and semantic retrieval on every test query and counts the queries each one is better on. The prose's point that the test set is too small to show a pattern rests on the `better` and `size in inches` lines."""from lib.lexical import LexicalSearchfrom lib.metrics import evaluatefrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrelsproducts, queries, judgments = load_products(), load_queries("test"), qrels("test")bm25 = evaluate(LexicalSearch(products).run(queries, k=100), judgments)semantic = evaluate(SemanticSearch().run(queries, k=100), judgments)for name, scores in [("bm25", bm25), ("semantic", semantic)]:    print(f"{name} ndcg@10: {scores['ndcg@10'].mean():.3f}")    print(f"{name} judged@10: {scores['judged@10'].mean():.3f}")# per test query, rounded to three decimals: queries that differ only beyond the third place count as tieddifference = (semantic["ndcg@10"] - bm25["ndcg@10"]).round(3)print("semantic better:", (difference > 0).sum())print("bm25 better:", (difference < 0).sum())print("tied:", (difference == 0).sum())sized = queries["query"].str.contains(r"\d+\s*(?:inch|in\b|\"|'')")             # a size in inchesprint("test queries with a size in inches:", sized.sum())print("of those, bm25 better:", (difference[sized] < 0).sum())print()print("queries where bm25 is better:")print(queries.loc[difference[difference < 0].index, "query"].to_string())
Saídapython compare-lexical-semantic.py
bm25 ndcg@10: 0.725
bm25 judged@10: 0.927
semantic ndcg@10: 0.830
semantic judged@10: 0.990
semantic better: 21
bm25 better: 7
tied: 2
test queries with a size in inches: 2
of those, bm25 better: 2

queries where bm25 is better:
query_id
63                                     monthly calendar
72                                   fold in half table
94             kohler whitehaven farmhouse kitchen sink
285    48" sliding single track , barn door for laundry
292                             decorative white pillow
293                            wood floor protector mat
482                                48 inch kitchen hood

Na média das consultas de teste, a recuperação semântica está à frente: nDCG@10 de 0.830 contra 0.725 do BM25. Seu judged@10, 0.990, também é maior que o 0.927 do BM25, então parte da desvantagem do BM25 pode vir de produtos que ninguém julgou. Para outdoor light fixtures, pelo menos, esses produtos são lâmpadas, e uma pontuação de 0 é justa.

A recuperação semântica é melhor em 21 consultas, o BM25 em 7, e 2 estão empatadas. A loja tem apenas 30 consultas de teste, então o capítulo 3 testa se uma diferença como esta é maior do que o acaso.

O BM25 é melhor em 2 das 2 consultas de teste que informam um tamanho em polegadas. Termos exatos, como tamanhos e números de modelo, podem favorecer a correspondência de palavras, mas uma contagem tão pequena não consegue mostrar um padrão. Nas consultas de treino que contêm um dígito, o BM25 é melhor em 1 de 5 (Encontre as consultas que cada recuperador vence), e o modelo de embeddings também reconhece dígitos, como texto (Verifique consultas que contêm dígitos).

Um resultado teórico mostra onde vetores únicos ficam aquém. Weller et al. demonstram que a dimensão de um embedding limita quais combinações de melhores resultados um único vetor consegue retornar. No LIMIT, um conjunto de dados que eles construíram para testar esse limite, o BM25 encontra 93.6% dos itens relevantes em seu top 100, e o melhor modelo de vetor único, 18.9%. Em uma variante do LIMIT em que as palavras foram substituídas por sinônimos, a pontuação do BM25 cai mais de 89% (Weller et al., 2025). A recuperação léxica e a semântica falham em lugares diferentes.

Regra prática: Adicione a recuperação semântica quando os compradores descreverem o que querem com as próprias palavras. Não presuma que a recuperação léxica vence em termos exatos, como tamanhos, marcas e números de modelo: antes de confiar nela nesses casos, conte qual recuperador vence nas consultas de treino que contêm esses termos. Nestes dados, a recuperação semântica isoladamente tem a maior pontuação até agora, então é o ranqueador a ser superado.

Funda dois rankings com reciprocal rank fusion

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

Como a recuperação lexical e a semântica falham em lugares diferentes, a recuperação híbrida combina um ranking de cada uma, aqui o do BM25 e o da recuperação semântica, na esperança de manter os pontos fortes de ambas. Suas pontuações não podem ser somadas diretamente, porque estão em escalas diferentes (o capítulo 7 mostra por quê). O reciprocal rank fusion (RRF) evita o problema usando apenas as posições. Cada produto recebe, para cada ranking que o contém, 1 dividido pela soma de uma constante e da sua posição, e as pontuações são somadas:

RRF(product) = sum over rankings r of  1 / (k + rank of product in r),   with k = 60

A constante k achata o topo: com k = 60, a posição 1 vale 1/61 e a posição 10 vale 1/70. Assim, um produto próximo do topo dos dois rankings supera um que está no topo de apenas um. Os autores fixaram k = 60 em um estudo piloto e constataram que "a escolha não era crítica" (Cormack et al., 2009). Eles fundiram dois tipos de execuções: submissões ao TREC, as avaliações compartilhadas da Text REtrieval Conference, e 30 configurações de um único sistema de busca. Nesses experimentos, o RRF superou, em média, a melhor execução individual em 4% a 5% na mean average precision (MAP), que faz a média, sobre as consultas, da precisão na posição de cada resultado relevante. Esse é um cenário diferente de fundir um ranking lexical e um semântico, e um estudo posterior sobre busca híbrida constatou que uma soma ponderada e ajustada de pontuações normalizadas supera o RRF (Bruch et al., 2023). O capítulo 7 ajusta ambos com consultas de treino. Aqui, o RRF roda sem ajuste.

O RRF é curto o bastante para ser escrito à mão, em duas funções: rrf_scores calcula as pontuações dos produtos de uma consulta, e reciprocal_rank_fusion ordena os produtos de todas as consultas, colocando os produtos com pontuações iguais em ordem de product_id, de modo que nenhum dos rankings vença os empates por ter sido passado primeiro. O exemplo hybrid-rrf funde os 100 primeiros resultados do BM25 e da recuperação semântica para cada consulta de teste, confere as pontuações dos dois produtos que clear shower curtain coloca em primeiro lugar e avalia a execução híbrida.

O BM25 pontua 0.725 e a recuperação semântica 0.830, então o ranqueador mais fraco recebe um voto igual. O voto dele vai puxar para baixo a execução fundida, ou as duas vão cobrir as falhas uma da outra bem o bastante para superar a recuperação semântica? Escolha uma de três respostas antes de ler a saída: acima da recuperação semântica, entre as duas, ou abaixo do BM25.

hybrid-rrf.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Fuses BM25 and semantic retrieval with reciprocal rank fusion, by hand for one query and then for every test query. The prose's point rests on the hybrid's `ndcg@10` line and on the two scores printed for the first product, which agree."""from lib.lexical import LexicalSearchfrom lib.metrics import evaluatefrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrelsdef rrf_scores(rankings, k=60):    """Each product scores the sum of 1 / (k + rank) over the rankings that contain it."""    scores = {}    for ranking in rankings:        for rank, product_id in enumerate(ranking, start=1):            scores[product_id] = scores.get(product_id, 0) + 1 / (k + rank)    return scoresdef reciprocal_rank_fusion(runs, k=60, depth=100):    """For each query, products in order of their RRF scores, best first; equal scores by product_id."""    fused = {}    for query_id in runs[0]:        scores = rrf_scores([run[query_id] for run in runs], k)        # equal scores fall back to product_id, so neither ranking wins ties by being passed first        fused[query_id] = sorted(scores, key=lambda product_id: (-scores[product_id], product_id))[:depth]    return fusedproducts, queries, judgments = load_products(), load_queries("test"), qrels("test")bm25, semantic = LexicalSearch(products).run(queries, k=100), SemanticSearch().run(queries, k=100)hybrid = reciprocal_rank_fusion([bm25, semantic])for place, product_id in zip(["first", "second"], hybrid[246]):       # query 246, "clear shower curtain"    # list.index counts from 0, and a rank counts from 1    bm25_rank, semantic_rank = bm25[246].index(product_id) + 1, semantic[246].index(product_id) + 1    print(f"{place} product: {products.at[product_id, 'name']}")    print(f"{place} product's bm25 rank: {bm25_rank}")    print(f"{place} product's semantic rank: {semantic_rank}")    # the formula with the two ranks in it, where k = 60    print(f"{place} product's score by hand: {1 / (60 + bm25_rank) + 1 / (60 + semantic_rank):.5f}")    print(f"{place} product's score from rrf_scores: {rrf_scores([bm25[246], semantic[246]])[product_id]:.5f}")hybrid_scores, semantic_scores = evaluate(hybrid, judgments), evaluate(semantic, judgments)print(f"hybrid ndcg@10: {hybrid_scores['ndcg@10'].mean():.3f}")print(f"hybrid judged@10: {hybrid_scores['judged@10'].mean():.3f}")difference = (hybrid_scores["ndcg@10"] - semantic_scores["ndcg@10"]).round(3)print("better than semantic:", (difference > 0).sum())print("worse than semantic:", (difference < 0).sum())print("tied with semantic:", (difference == 0).sum())
Saídapython hybrid-rrf.py
first product: woolley vinyl solid color single shower curtain
first product's bm25 rank: 3
first product's semantic rank: 1
first product's score by hand: 0.03227
first product's score from rrf_scores: 0.03227
second product: woolley vinyl single shower curtain
second product's bm25 rank: 2
second product's semantic rank: 2
second product's score by hand: 0.03226
second product's score from rrf_scores: 0.03226
hybrid ndcg@10: 0.812
hybrid judged@10: 0.980
better than semantic: 9
worse than semantic: 14
tied with semantic: 7

O primeiro produto fundido, woolley vinyl solid color single shower curtain, está na posição 3 no ranking do BM25 e na posição 1 no da recuperação semântica. Sua pontuação soma um termo de cada ranking, 1/(60 + 3) + 1/(60 + 1), que, feito à mão, dá 0.03227, o mesmo valor que rrf_scores fornece.

O segundo, woolley vinyl single shower curtain, está na posição 2 no ranking do BM25 e na posição 2 no da recuperação semântica, e tem pontuação 0.03226, por isso fica em segundo.

A execução híbrida pontua 0.812: acima do BM25 e abaixo da recuperação semântica isolada. Consulta por consulta, ela supera a recuperação semântica em 9 consultas, perde em 14 e empata em 7. Seu judged@10 é 0.980.

Portanto, a fusão não superou a recuperação semântica neste caso, o que não é o mesmo que piorar a busca. Por que ela não ajudou é uma questão para o capítulo 7, que verifica cada recuperador antes da fusão e ajusta a combinação com consultas de treino.

Se você escolheu acima da recuperação semântica, a lição é que combinar dois rankings não garante ganho. A fusão é uma mudança como qualquer outra, e precisa ser medida.

Regra prática: Meça cada recuperador isoladamente antes de fundi-los. Use RRF com k = 60 como padrão sem ajuste, e mantenha o ranking fundido somente se ele superar o melhor recuperador isolado em consultas reservadas (não usadas no ajuste). Quando um dos recuperadores é muito mais fraco, experimente ponderar os rankings ou ajustar k com consultas de treino, em vez de aceitar votos iguais. O capítulo 7 testa as duas abordagens nos dados da loja, e nenhuma das combinações ajustadas que ele relata nas consultas de teste supera a recuperação semântica (Relatar as combinações ajustadas nas consultas de teste).

Reordene os 50 primeiros com um cross-encoder

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

Todas as etapas até aqui foram de recuperação, que precisa pontuar cada produto do catálogo para cada consulta e, por isso, deve ser barata. Reordenação (reranking) reordena uma lista curta vinda da recuperação com um modelo mais lento, que pode se dar ao luxo de examinar a consulta e cada produto juntos porque vê apenas algumas dezenas de produtos.

Um tipo de modelo de reordenação é o cross-encoder, que lê a consulta e o texto do produto juntos, como uma única entrada, e produz uma pontuação de relevância para o par, pontuando cada par de forma independente (Nogueira e Cho, 2019). Um modelo de embeddings lê o produto sozinho, de modo que seus vetores podem ser calculados antecipadamente. Um cross-encoder precisa da consulta, por isso não consegue calcular nada antecipadamente, e executá-lo sobre cada par custa tempo: o lado lento da comparação com Sentence-BERT era o BERT lendo cada par de frases como um cross-encoder. Assim, um cross-encoder reordena uma lista curta que um primeiro estágio mais barato recupera (Nogueira e Cho, seção 2; Retrieve & Re-Rank). Em troca desse custo, ele consegue relacionar cada palavra da consulta com cada palavra do produto por meio de atenção, a parte do modelo que permite a cada palavra se apoiar nas demais de sua entrada. Reimers e Gurevych (2019, seção 4.3) observam que o BERT pode usar atenção para comparar diretamente as duas frases. Em 2019, no benchmark de passagens MS MARCO, reordenar as 1,000 primeiras passagens do BM25 dessa forma melhorou o MRR@10, medida de quão alto aparece a primeira passagem relevante, em 27% em relação ao melhor resultado anterior (Nogueira e Cho).

Um cross-encoder é um modelo de linguagem, mas não um modelo de linguagem de grande porte (LLM). Um LLM é um modelo treinado com grandes volumes de texto para gerar texto em resposta a um prompt. Capítulos posteriores usam LLMs para julgar, reescrever e reordenar. Um cross-encoder não gera nada: produz um único número.

O cross-encoder da loja é o modelo aberto Alibaba-NLP/gte-reranker-modernbert-base, escolhido pelo mesmo motivo que o modelo de embeddings: é aberto e sob a licença Apache 2.0, de modo que qualquer pessoa pode executar a gravação novamente. Sua gravação, recordings/cross_encoder.py, salva as pontuações do modelo uma única vez, para cada produto na união dos 100 primeiros de cada consulta da recuperação BM25 e da recuperação semântica, de modo que todo produto dos 50 primeiros da execução híbrida tem uma pontuação. A etapa de reordenação reorganiza os 50 primeiros de a execução híbrida, BM25 e recuperação semântica combinados com RRF, segundo essas pontuações, mantém o restante nas posições originais e avalia o resultado, que o livro chama de híbrido reordenado:

cross-encoder-rerank.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Reorders the top 50 of the hybrid run by cross-encoder score, keeps the rest in place, and scores the result. The prose's point rests on the reranked nDCG@10 line, set beside the hybrid's score, and on the better and worse counts."""from lib.fusion import reciprocal_rank_fusionfrom lib.lexical import LexicalSearchfrom lib.metrics import evaluatefrom lib.recorded import cross_encoder_scores, manifestfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrelsproducts, queries, judgments = load_products(), load_queries("test"), qrels("test")bm25 = LexicalSearch(products).run(queries, k=100)semantic = SemanticSearch().run(queries, k=100)hybrid = reciprocal_rank_fusion([bm25, semantic])        # the same function as in the hybrid sectionrecorded = cross_encoder_scores()                        # one score per (query, product) pairscore = {(query_id, product_id): value for query_id, product_id, value in recorded.itertuples(index=False)}print("cross-encoder model:", manifest("cross-encoder")["model"])depth = 50                                               # rerank the top 50reranked = {}for query_id, ranking in hybrid.items():    # the top 50 are reordered by score; equal scores keep the hybrid's order    top = sorted(ranking[:depth], key=lambda product_id: score[(query_id, product_id)], reverse=True)    # products below the top 50 keep their hybrid order    reranked[query_id] = top + ranking[depth:]before, after = evaluate(hybrid, judgments), evaluate(reranked, judgments)print(f"reranked ndcg@10: {after['ndcg@10'].mean():.3f}")print(f"reranked judged@10: {after['judged@10'].mean():.3f}")difference = (after["ndcg@10"] - before["ndcg@10"]).round(3)print("better than hybrid:", (difference > 0).sum())print("worse than hybrid:", (difference < 0).sum())
Saídapython cross-encoder-rerank.py
cross-encoder model: Alibaba-NLP/gte-reranker-modernbert-base
reranked ndcg@10: 0.798
reranked judged@10: 0.980
better than hybrid: 11
worse than hybrid: 12

Aqui, o reordenador não ajuda. Ele obtém 0.798 contra 0.812 da execução híbrida de onde partiu. Ele melhora 11 consultas e piora 12. Ao longo do capítulo, nas consultas de teste:

Ranqueador nDCG@10 judged@10
BM25 0.725 0.927
Semântico 0.830 0.990
Híbrido (RRF, k = 60) 0.812 0.980
Híbrido reordenado (top 50) 0.798 0.980

Uma consulta que ele piorou, refrigerator with ice an water in door, mostra como um reordenador perde terreno:

rerank-one-query.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Shows the hybrid and reranked top 5 for one query whose nDCG@10 the reranker lowered, with each product's cross-encoder score and judgment. The prose's point rests on the two rank lines and the two nDCG@10 lines."""import refrom lib.fusion import reciprocal_rank_fusionfrom lib.lexical import LexicalSearchfrom lib.metrics import ndcg_at_kfrom lib.recorded import cross_encoder_scoresfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, product_text, qrelsLABELS = {2: "exact", 1: "partial", 0: "irrelevant"}products = load_products()query_id = 406query = load_queries().at[query_id, "query"]judgments = qrels()[query_id]recorded = cross_encoder_scores()score = recorded[recorded["query_id"] == query_id].set_index("product_id")["score"]bm25 = {query_id: list(LexicalSearch(products).search(query, k=100).index)}semantic = {query_id: list(SemanticSearch().search(query_id, k=100).index)}hybrid = reciprocal_rank_fusion([bm25, semantic])[query_id]# the top 50 are reordered by score; the rest stay in the hybrid's orderreranked = sorted(hybrid[:50], key=score.get, reverse=True) + hybrid[50:]print("query:", query)for name, ranking in [("hybrid", hybrid), ("reranked", reranked)]:    first_exact = next(rank for rank, product_id in enumerate(ranking, start=1) if judgments.get(product_id) == 2)    print()    print(f"{name} ndcg@10: {ndcg_at_k(ranking, judgments, 10):.3f}")    print(f"{name} rank of the first exact product: {first_exact}")    for product_id in ranking[:5]:        label = LABELS.get(judgments.get(product_id), "unjudged")        print(f"  {score[product_id]:.2f}  {label:<10}  {products.at[product_id, 'name']}")exact = next(product_id for product_id in hybrid if judgments.get(product_id) == 2)words = set(re.findall(r"\w+", product_text(products).at[exact].lower()))   # name, class, category, descriptionprint()print("hybrid's first exact product:", products.at[exact, "name"])print("its text says ice or water:", "yes" if {"ice", "water"} & words else "no")
Saídapython rerank-one-query.py
query: refrigerator with ice an water in door

hybrid ndcg@10: 0.660
hybrid rank of the first exact product: 3
  1.95  partial     apec water icemaker-kit-38-14-ro refrigerator/icemaker installation accessory
  2.06  partial     36 '' french door 26.1 cu . ft. smart energy star refrigerator with interior ice maker
  1.44  exact       36 '' french door refrigerator 27 cu . ft. energy star refrigerator
  2.19  partial     36 '' energy star counter-depth french door 22.6 cu . ft. refrigerator with ice maker
  2.19  partial     800 series 21 cu . ft. smart energy star counter depth french door refrigerator with internal water dispenser

reranked ndcg@10: 0.533
reranked rank of the first exact product: 9
  2.20  partial     smeg classic 36 '' french door 22 cu . ft. refrigerator with ice maker
  2.19  partial     36 '' energy star counter-depth french door 22.6 cu . ft. refrigerator with ice maker
  2.19  partial     800 series 21 cu . ft. smart energy star counter depth french door refrigerator with internal water dispenser
  2.10  partial     28 '' energy star counter depth top freezer 12.56 cu . ft. refrigerator with auto ice maker
  2.06  partial     36 '' french door 26.1 cu . ft. smart energy star refrigerator with interior ice maker

hybrid's first exact product: 36 '' french door refrigerator 27 cu . ft. energy star refrigerator
its text says ice or water: no

O cross-encoder enterra o primeiro produto exato, movendo-o da posição 3 para a posição 9, e reduz o nDCG@10 desta consulta de 0.660 para 0.533. Os 5 primeiros reordenados são geladeiras cujos nomes contêm ice maker ou water dispenser, e os avaliadores as marcaram como parciais: correspondem ao que foi pedido, uma geladeira, mas não ao modificador, gelo e água na porta. O primeiro produto exato na execução híbrida, uma geladeira French door, recebe a menor pontuação do cross-encoder entre os 5 primeiros do híbrido.

Os avaliadores marcaram essa geladeira como exata, portanto, pela definição do conjunto de dados, ela corresponde totalmente à consulta. No entanto, seu texto não diz nada sobre gelo ou água, de modo que nenhum modelo que leia apenas o texto poderia ranqueá-la por esse modificador. Os avaliadores do WANDS viram a imagem e a página web de cada produto, além do nome (diretrizes de anotação), o que provavelmente lhes permitiu ver o que o texto não diz. Um reordenador de uso geral nunca viu os julgamentos desta loja. O capítulo 9 treina ranqueadores com os julgamentos das consultas de treino.

Regra prática: Reordene uma lista curta, aqui 50 produtos, porque o custo cresce com cada par. Adote um reordenador somente quando ele superar a melhor recuperação isolada em consultas reservadas. Este não superou a execução híbrida nem a recuperação semântica, de modo que o melhor pipeline da loja até agora é a recuperação semântica isolada. Antes de desistir da reordenação, teste outra profundidade ou um ranqueador treinado com os seus próprios julgamentos. Nem outra profundidade nem LambdaMART superam a recuperação semântica nas consultas de teste do capítulo 9 (Defina a profundidade de reordenação a partir de um orçamento, Relate o LambdaMART nas consultas de teste).

O que dá errado em produção

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

O tokenizador descarta palavras sem avisar você. O tokenizador padrão do bm25s mantém apenas tokens com dois ou mais caracteres e não faz stemming (tokenizador do bm25s). Execute-o em uma consulta de treino e em uma consulta de teste e conte os produtos que ele não consegue corresponder:

tokenizer-drops-terms.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Aprovado
"""Tokenizes one train query, one test query and the products' text with bm25s, and counts the products that have `chairs` or only `chair`. The prose's points rest on the printed token lists and on the two product counts."""import bm25sfrom lib.store import load_products, product_textdef tokenize(texts):    """The tokenizer lib.lexical uses for products and queries, with bm25s's default settings."""    # stopwords="en" removes English words such as "and"; no stemmer is set, so "chairs" and "chair" stay different tokens    return bm25s.tokenize(texts, stopwords="en", return_ids=False, show_progress=False)for query in ["ge top loading washer 4.5", "bistro table and chairs"]:    print(f"{query!r} -> {tokenize([query])[0]}")products = tokenize(product_text(load_products()).tolist())print()print("products with the token chairs:", sum("chairs" in tokens for tokens in products))print("products with chair but not chairs:", sum("chair" in tokens and "chairs" not in tokens for tokens in products))
Saídapython tokenizer-drops-terms.py
'ge top loading washer 4.5' -> ['ge', 'top', 'loading', 'washer']
'bistro table and chairs' -> ['bistro', 'table', 'chairs']

products with the token chairs: 895
products with chair but not chairs: 359

O 4.5 em ge top loading washer 4.5 desaparece, porque 4 e 5 têm um caractere cada, e por isso esse número não participa do ranqueamento. E chairs corresponde apenas a produtos que dizem chairs: 895 produtos dizem, enquanto 359 dizem chair e nunca chairs, e nenhum deles consegue corresponder a essa palavra de bistro table and chairs. Nenhum dos dois casos gera erro. O Capítulo 5 mostra os dois problemas e acrescenta stemming.

Resultados não avaliados parecem falhas. Um ranqueador que exibe produtos que ninguém avaliou recebe notas menores do que talvez mereça, e um ranqueador que exibe os produtos avaliados ganha uma vantagem. Informe o judged@10 junto de cada nota, e faça com que novos produtos sejam avaliados quando ele cair.

Notas obtidas em uma amostra provavelmente são otimistas. A amostra mantém 12,000 produtos, quase todos avaliados para alguma consulta. O catálogo completo do WANDS tem 42,994 (repositório), e o catálogo de uma loja pode ser muito maior, com mais quase-acertos disputando as 10 primeiras posições. Nada neste capítulo mede isso, mas espere notas menores em um catálogo completo. Também não compare as notas daqui com as do artigo do WANDS: ele executou o BM25 do Solr, um servidor de busca, sobre títulos e descrições de produtos (Chen et al.).

Saídas de modelo pertencem a uma única versão do modelo. Os embeddings de produtos e de consultas devem vir do mesmo modelo, na mesma versão, ou suas similaridades não são comparáveis. Ao trocar o modelo, você deve recalcular os embeddings de todo o catálogo. Cada pasta em examples/data/recorded/ tem um manifest.json que fixa o modelo e a sua versão.

O reranqueamento custa tempo em cada consulta. Os embeddings dos produtos são calculados uma única vez. Um cross-encoder roda sobre cada par, em cada consulta, enquanto o cliente espera. Neste capítulo, um script de gravação calcula as notas com antecedência em uma GPU, o que oculta esse custo. O Capítulo 9 calcula o que custa cada profundidade de reranqueamento (Defina a profundidade de reranqueamento a partir de um orçamento).

Regra prática: Verifique os tokens em que suas consultas se transformam, acompanhe o judged@10 e registre a versão do modelo ao lado de cada vetor que você armazenar.

Decisões tomadas neste capítulo

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

Estes padrões valem até que um capítulo posterior teste um deles nas consultas de treino.

  • Reportar no teste, ajustar no treino. Todas as pontuações deste capítulo são calculadas sobre as 30 consultas de teste. Este capítulo não ajusta nenhum parâmetro; os capítulos posteriores ajustam apenas com base nas 50 consultas de treino.
  • Métrica principal: nDCG@10, com judged@10 ao lado. As notas servem como ganhos, produtos não julgados contam como nota 0, e judged@10 mostra quando essa suposição tem peso relevante.
  • Linha de base: BM25 com os padrões do bm25s, k1=1.5 e b=0.75, sobre o nome, a classe, a categoria e a descrição de cada produto. O ajuste fica para depois, quando puder ser medido nas consultas de treino.
  • Recuperação semântica a partir de embeddings registrados de um modelo aberto, comparados por produto escalar de vetores de comprimento unitário, de modo que todos os exemplos sejam executados offline e produzam a mesma saída a cada vez. A escolha entre modelos é uma questão para depois.
  • Recuperação híbrida: RRF com k = 60 e pesos iguais, sem ajuste, como seus autores a usaram.
  • Profundidade de reranqueamento: os 50 primeiros da híbrida, pontuados por um cross-encoder registrado, de modo que todo produto reranqueado tenha uma pontuação registrada. Em uma loja em produção, a profundidade é tanto uma decisão de custo quanto de qualidade.
  • O ranqueador a superar é a recuperação semântica isolada, porque, com estes dados, nem a fusão nem este reranqueador melhoraram sobre ela. O Capítulo 3 testa se diferenças como estas são maiores do que o acaso, em um arcabouço de avaliação.
  • O que o capítulo mostrou: uma etapa que deveria ajudar, fusão ou reranqueamento, não superou a recuperação semântica com estes dados; por isso, cada mudança é medida antes de ser mantida.

Este capítulo, nesta edição

Edição 2026.11.10Exemplos aprovados em 19 de nov de 202611 de 11 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 1 de 11: Busca, de ponta a ponta

  1. Carregue os dados da loja
  2. Ordene produtos com BM25
  3. Verifique os resultados contra os julgamentos
  4. Pontue um ranking com nDCG@10
  5. Pontue todas as consultas de teste
  6. Busca por significado com embeddings
  7. Funda dois rankings com reciprocal rank fusion
  8. Reordene os 50 primeiros com um cross-encoder
  9. O que dá errado em produção
  10. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos