Recuperação semântica
Cerca de 42 minutos min de leitura, com 16 exemplos em 13 seções.
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
Nesta página
- Transforme textos em embeddings
- Compare embeddings com a similaridade de cosseno
- Encontre os vizinhos mais próximos exatos com NumPy
- Troque recall por velocidade com HNSW
- Verifique o índice nas consultas de teste
- Verifique consultas que contêm dígitos
- Espere que um código tenha pouco peso
- Teste embeddings com negação
- Escolha um modelo de embeddings
- Leia os benchmarks como uma lista de candidatos
- Trunque as dimensões e depois teste a perda
- O que dá errado em produção
- Decisões tomadas neste capítulo
Ao final deste capítulo, você será capaz de construir a recuperação semântica para um catálogo a partir de embeddings armazenados: comparar vetores por similaridade de cosseno, encontrar exatamente os produtos mais próximos de uma consulta com NumPy, trocar para um índice aproximado quando um catálogo ultrapassar a busca exata e medir o que o índice deixa de encontrar, e identificar as consultas em que os embeddings falham. Você também poderá escolher um tamanho de vetor testando-o com seus próprios julgamentos, e comparar modelos da mesma forma.
Para 48 inch kitchen hood, a recuperação semântica retorna coifas de outras larguras, e para rug that is not round, tapetes redondos. No entanto, nas consultas de teste, obteve um nDCG@10 médio de 0.830. Sua vantagem sobre o BM25, que obteve 0.725, é uma que o capítulo 3 estabelece. O livro a tem usado como uma classe, lib.semantic.SemanticSearch. O capítulo 1 a construiu para a loja, cujo catálogo vai de sofás a cortinas de chuveiro, sobre vetores que um único modelo calculou uma vez, antecipadamente. Antes que a loja dependa dela, você precisa saber o que esses vetores contêm, quanto custaria pesquisá-los em um catálogo muito maior e quais consultas eles erram. Este capítulo constrói a busca exata manualmente, mede um índice aproximado em relação a ela e testa ambos com as consultas e os julgamentos da loja.
Nas consultas de teste, o capítulo planeja 2 comparações, ambas na seção sobre teste do índice. Cada uma opõe a busca exata, que compara uma consulta com todos os produtos, ao HNSW, um índice aproximado que a compara com apenas uma fração deles: uma vez com a configuração padrão do faiss e outra vez com a configuração escolhida nas consultas de treino. Cada uma está sujeita à regra do livro, aqui um p-valor abaixo de 0.025. Qualquer outra análise de uma consulta de teste neste capítulo é exploratória.
Transforme textos em embeddings
Um embedding posiciona textos de significados parecidos próximos uns dos outros; esta seção mostra como. O modelo que calcula um embedding é um encoder, treinado para que textos de significados parecidos recebam vetores que apontem em direções parecidas, tenham ou não palavras em comum. Todo texto recebe a mesma quantidade de números, a dimensão do embedding, seja ele uma consulta de três palavras ou a descrição completa de um produto. Um número isolado não significa nada; só as comparações entre vetores inteiros têm sentido.
A busca usa o encoder como bi-encoder: ele codifica cada produto isoladamente, uma única vez, antecipadamente, e cada consulta isoladamente, no momento em que o cliente a digita. Comparar uma consulta com um produto é então uma operação aritmética sobre dois vetores, e não uma nova execução do modelo, o que a torna barata o bastante para comparar uma consulta com um catálogo inteiro. Capítulo 1 mostra o tamanho dessa diferença a partir do artigo do Sentence-BERT: cerca de 65 horas para o BERT ler todos os pares de 10,000 sentenças, contra cerca de 5 segundos para embutir cada sentença uma vez e compará-las. Um modelo que lê uma consulta e um produto juntos é um cross-encoder, e o capítulo 1 usa um desses modelos para reordenar uma lista de candidatos.
O encoder da loja é Snowflake/snowflake-arctic-embed-m-v1.5, um modelo aberto com 109 milhões de parâmetros, sob a licença Apache-2.0 (model card). Merrick et al. (2024) relatam que o treinamento da sua família manteve apenas documentos identificados como predominantemente em inglês. Escolhemos esse modelo porque qualquer pessoa pode usá-lo comercialmente, ele é pequeno e foi treinado de modo que seus vetores possam ser encurtados, o que a seção sobre dimensões testa. Em vez disso, os exemplos leem uma gravação: vetores que o script recordings/embeddings.py calculou uma única vez, em uma revisão fixada, e salvou com comprimento unitário, de modo que todo exemplo vê os mesmos números. O model card pede um prefixo apenas nas consultas, então o script o acrescenta a cada consulta e embute os produtos como estão. Os exemplos leem os vetores por meio de lib.recorded.embeddings():
1"""Loads the recorded vectors and shows the lengths lib.recorded stores and rescales, and how close two shopper queries are. The prose's point about rounding rests on the stored- and rescaled-length lines, and its point about nearby queries on the median and nearest-query lines."""2import re34import numpy as np56from lib.recorded import RECORDED, embeddings, manifest7from lib.store import load_queries89# unit-length rows, one per ID; the queries carry the model's query prefix10product_ids, product_vectors, query_ids, query_vectors = embeddings()11recording = manifest("embeddings")12print("embedding model:", recording["model"])13print("query prompt:", recording["prompts"]["query"])14print(f"products embedded: {len(product_ids):,}")15print("dimensions:", product_vectors.shape[1])16print("stored as:", recording["dtype"])17print("longest product text, tokens:", recording["longest_product_tokens"])18print("model's input limit, tokens:", recording["max_seq_length"])19# row 0 is product 1; [0, :4] takes its first four numbers20print(f"product {product_ids[0]}, first four numbers:", ", ".join(f"{x:.3f}" for x in product_vectors[0, :4]))21stored = np.load(RECORDED / "embeddings" / "products.npy").astype(np.float32) # as saved, before lib.recorded22stored_lengths, lengths = np.linalg.norm(stored, axis=1), np.linalg.norm(product_vectors, axis=1)23print(f"stored vector lengths: {stored_lengths.min():.5f} to {stored_lengths.max():.5f}")24print(f"lengths after lib.recorded rescales: {lengths.min():.5f} to {lengths.max():.5f}")2526# How close are two shopper queries? Compare every query with every other one.27queries = load_queries().loc[query_ids, "query"].tolist()28similarity = query_vectors @ query_vectors.T # unit length, so the dot product is the cosine29np.fill_diagonal(similarity, np.nan) # leave out each query's similarity to itself30print(f"median similarity of two queries: {np.nanmedian(similarity):.3f}")31for query in ["whimsical solar lights", "wall design shelf"]:32 row = queries.index(query)33 nearest = int(np.nanargmax(similarity[row]))34 # whole words as typed, with no stemming, so `lights` and `light` differ35 shared = set(re.findall(r"\w+", query)) & set(re.findall(r"\w+", queries[nearest]))36 print()37 print(f"{query}, nearest other query:", queries[nearest])38 print(f"{query}, similarity: {similarity[row, nearest]:.3f}")39 print(f"{query}, words in common:", len(shared))
python inspect-recorded-embeddings.pyembedding model: Snowflake/snowflake-arctic-embed-m-v1.5
query prompt: Represent this sentence for searching relevant passages:
products embedded: 12,000
dimensions: 768
stored as: float16
longest product text, tokens: 201
model's input limit, tokens: 512
product 1, first four numbers: -0.033, 0.051, 0.111, -0.012
stored vector lengths: 0.99994 to 1.00006
lengths after lib.recorded rescales: 1.00000 to 1.00000
median similarity of two queries: 0.291
whimsical solar lights, nearest other query: outdoor light fixtures
whimsical solar lights, similarity: 0.637
whimsical solar lights, words in common: 0
wall design shelf, nearest other query: kitchen storage shelves
wall design shelf, similarity: 0.679
wall design shelf, words in common: 0
Cada um dos 12,000 produtos é um vetor de 768 números; o vetor do produto 1 começa com -0.033, 0.051, 0.111, -0.012, e nenhum desses números significa algo sozinho. A gravação armazena cada número como um float16, em 2 bytes, e lib.recorded os converte para floats de 32 bits ao carregá-los. Esse arredondamento desloca levemente os comprimentos armazenados em relação a 1: eles variam de 0.99994 to 1.00006. Por isso, lib.recorded também reescala cada vetor de volta ao comprimento 1, e os comprimentos que ele devolve variam de 1.00000 to 1.00000. O encoder da loja lê o texto como tokens, pedaços de palavras do vocabulário próprio dele, e não como os termos do tokenizador do capítulo 5. O texto de produto mais longo tem 201 tokens, dentro do limite de 512 tokens do modelo, então o modelo leu todos os produtos por inteiro.
A mediana da similaridade entre duas consultas da loja é 0.291, em uma escala em que 1 significa que dois vetores apontam para o mesmo lado (similaridade de cosseno). Ainda assim, whimsical solar lights encontra outdoor light fixtures com 0.637, e wall design shelf encontra kitchen storage shelves com 0.679, com 0 e 0 palavras em comum: lights e light são cadeias de caracteres diferentes, assim como shelves e shelf. O BM25 de referência não faz stemming, então não vê nada em comum em nenhum dos dois pares. O stemming do capítulo 5 faria coincidir lights com light, mas não shelves com shelf.
Regra prática: Calcule os embeddings dos produtos antecipadamente e os das consultas no momento da busca, com o mesmo modelo na mesma revisão, e siga o model card quanto aos prompts: aqui, um prefixo apenas nas consultas. Registre o modelo, a revisão e os prompts junto aos vetores, como cada manifest.json em examples/data/recorded/ faz. Verifique se o seu produto mais longo cabe no limite de entrada do modelo antes de confiar no embedding dele.
Compare embeddings com a similaridade de cosseno
Para classificar produtos para uma consulta, você precisa de um número por par que indique o quanto dois vetores se parecem. Similaridade de cosseno é o cosseno do ângulo entre dois vetores: 1 quando apontam para o mesmo lado, 0 em ângulo reto e −1 quando apontam em sentidos opostos. Ela ignora o comprimento dos vetores. O produto escalar multiplica dois vetores número a número e soma os resultados, então é igual ao cosseno multiplicado pelos dois comprimentos. Escalar cada vetor para comprimento 1, chamado normalização, faz com que os dois sejam o mesmo número, como afirma a documentação do Sentence Transformers. O produto escalar é então a escolha mais barata, porque dispensa o cálculo dos comprimentos.
dot(q, d) = q1 × d1 + q2 × d2 + ... + qn × dn
length(q) = √(q1² + q2² + ... + qn²)
cosine(q, d) = dot(q, d) / (length(q) × length(d))
Para ver a fórmula em funcionamento, tome a consulta de teste clear shower curtain e o produto mais parecido com ela: calcule o produto escalar e o cosseno à mão, e confira o cosseno com o scikit-learn 1.9.1. Depois, quebre a única suposição que faz os dois coincidirem. Mantenha os primeiros 256 dos 768 números de cada vetor, um atalho que a seção sobre dimensões testa, mas dispense a reescala, e classifique os produtos de cada consulta pelos dois métodos:
1"""Computes the cosine of one test query and its best product by hand and with scikit-learn, then ranks every query's products by dot product and by cosine after the vectors are shortened. The prose's point rests on the line that counts queries whose top 10 changes."""2import numpy as np3from sklearn.metrics.pairwise import cosine_similarity45from lib.recorded import embeddings6from lib.store import load_products78products = load_products()9product_ids, product_vectors, query_ids, query_vectors = embeddings()10query = query_vectors[list(query_ids).index(246)] # clear shower curtain11best = int(np.argmax(product_vectors @ query))12product = product_vectors[best]13print("product:", products.at[product_ids[best], "name"])1415# cosine = dot product / (length of q * length of d)16dot = query @ product17cosine = dot / (np.linalg.norm(query) * np.linalg.norm(product))18print(f"dot product: {dot:.3f}")19print(f"cosine by hand: {cosine:.3f}")20print(f"cosine from scikit-learn: {cosine_similarity([query], [product])[0, 0]:.3f}")2122# Keep the first 256 numbers of each vector and don't rescale: the lengths are no longer 1.23short_products, short_queries = product_vectors[:, :256], query_vectors[:, :256]24lengths = np.linalg.norm(short_products, axis=1)25print(f"shortened product lengths: {lengths.min():.3f} to {lengths.max():.3f}")26# stable sort: tied scores keep their stored order27by_dot = np.argsort(-(short_queries @ short_products.T), axis=1, kind="stable")[:, :10]28# only the products are rescaled: a query's length scales all its scores alike, so it can't change their order29by_cosine = np.argsort(-(short_queries @ (short_products / lengths[:, None]).T), axis=1, kind="stable")[:, :10]30# compares the sets: a new order within the same 10 doesn't count31changed = sum(set(dot_top) != set(cosine_top) for dot_top, cosine_top in zip(by_dot, by_cosine))32print("queries:", len(query_ids))33print("queries whose top 10 changes:", changed)
python cosine-by-hand.pyproduct: woolley vinyl solid color single shower curtain
dot product: 0.577
cosine by hand: 0.577
cosine from scikit-learn: 0.577
shortened product lengths: 0.706 to 0.778
queries: 80
queries whose top 10 changes: 61
Nos vetores de comprimento 1 da loja, o produto escalar é 0.577, o cosseno à mão é 0.577, e o cosine_similarity do scikit-learn dá 0.577, então os três concordam.
Encurtar quebra isso. Os vetores encurtados têm comprimentos de 0.706 to 0.778, e, para 61 das 80 consultas, classificar pelo produto escalar dá um top 10 diferente de classificar pelo cosseno. O comprimento da própria consulta multiplica todos os seus escores pelo mesmo fator, então não pode mudar a ordem deles. O comprimento de um produto pode: ele multiplica o escore desse produto para cada consulta, um impulso que o comprador nunca pediu.
Algumas bibliotecas informam uma distância em vez de uma similaridade. Os índices L2 do faiss retornam a distância euclidiana ao quadrado, e o produto interno deles é igual à similaridade de cosseno somente quando os vetores estão normalizados, segundo a wiki do faiss. Para vetores unitários, a distância ao quadrado é 2 − 2 × cosseno, então ela ordena os produtos na mesma ordem que o cosseno, da menor distância para a maior.
Regra prática: Normalize cada vetor uma vez, ao armazená-lo, e classifique pelo produto escalar. Normalize de novo após qualquer coisa que altere um vetor, como encurtá-lo ou calcular a média de vários. Se a documentação de um modelo diz que ele foi treinado para o produto escalar de vetores não normalizados, siga a documentação, e nunca misture os dois em um mesmo índice.
Encontre os vizinhos mais próximos exatos com NumPy
A recuperação por embeddings é uma busca pelo vizinho mais próximo: encontrar os k produtos cujos vetores são mais semelhantes ao da consulta. A busca exata compara a consulta com todos os produtos e mantém os k melhores, então nunca deixa de encontrar um deles. Com vetores de comprimento unitário, comparar uma consulta com todos os produtos é um único produto matriz–vetor, e comparar muitas consultas é um único produto de matrizes, com uma linha por consulta e uma coluna por produto. Resta encontrar os k maiores scores em cada linha. Ordenar cada linha faz mais trabalho do que o necessário. A função argpartition do NumPy move os k maiores scores para um dos lados sem ordenar nenhum dos dois lados, e a documentação do NumPy deixa essa ordem indefinida, por isso você ordena apenas esses k.
A busca semântica do capítulo 1 obteve seus rankings de lib.semantic.SemanticSearch. Construa o núcleo dela à mão para as 30 consultas de teste com NumPy 2.5.5, depois verifique-o duas vezes: contra lib.semantic e contra o IndexFlatIP do faiss, que calcula o produto interno com todos os vetores. As diretrizes do faiss citam dois índices que garantem resultados exatos, IndexFlatIP e IndexFlatL2:
1"""Builds exact search from one matrix product, then checks its top 10 against lib.semantic and faiss's IndexFlatIP. The prose's point rests on the two 'same top 10' lines, which show the hand-built search matches both."""2import faiss3import numpy as np45from lib.metrics import evaluate6from lib.recorded import embeddings7from lib.semantic import SemanticSearch8from lib.store import load_queries, qrels910product_ids, product_vectors, query_ids, query_vectors = embeddings()11test = load_queries("test").index12rows = np.isin(query_ids, test)131415def top_k(scores, k):16 """Column indices of the k highest scores in each row, best first."""17 # argpartition's kth is 0-based: with k - 1, the first k positions hold the k highest scores, in no order18 candidates = np.argpartition(-scores, k - 1, axis=1)[:, :k] # the top k, in no order19 # stable sort: tied scores keep their candidate order20 order = np.argsort(-np.take_along_axis(scores, candidates, axis=1), axis=1, kind="stable")21 return np.take_along_axis(candidates, order, axis=1)222324scores = query_vectors[rows] @ product_vectors.T # one row per test query, one column per product25top = top_k(scores, 10)26print("similarities computed:", f"{scores.size:,}")27print("similarities per query:", f"{scores.shape[1]:,}")2829semantic = SemanticSearch()30# two lists match only if the same products come in the same order31same = sum(list(product_ids[found]) == list(semantic.search(query_id, 10).index)32 for query_id, found in zip(query_ids[rows], top))33print("same top 10 as lib.semantic:", same, "of", rows.sum())3435flat = faiss.IndexFlatIP(product_vectors.shape[1]) # faiss's exact index: inner product with every product36flat.add(product_vectors)37_, found = flat.search(query_vectors[rows], 10)38# the same products in the same order, row by row39print("same top 10 as faiss IndexFlatIP:", (found == top).all(axis=1).sum(), "of", rows.sum())40run = {query_id: list(product_ids[row]) for query_id, row in zip(query_ids[rows], top)}41print(f"ndcg@10 of the exact run: {evaluate(run, qrels('test'))['ndcg@10'].mean():.3f}")
python exact-search-numpy.pysimilarities computed: 360,000
similarities per query: 12,000
same top 10 as lib.semantic: 30 of 30
same top 10 as faiss IndexFlatIP: 30 of 30
ndcg@10 of the exact run: 0.830
A busca construída à mão concorda com as duas verificações: ela retorna os mesmos 10 primeiros de lib.semantic para 30 of 30 consultas de teste, e os do faiss para 30 of 30, portanto sua execução obtém o mesmo nDCG@10 médio, 0.830. Um único produto de matrizes calculou todas as similaridades: 360,000 delas, 12,000 por consulta. O módulo compartilhado do livro, lib.vectors, mantém esse top_k para os exemplos seguintes e o encapsula em exact_search.
Se a busca exata basta depende do custo. Seu trabalho cresce junto com o catálogo: uma similaridade por produto, para cada consulta. Sua memória são os próprios vetores:
1"""Prints the bytes one product's float32 vector takes, and the memory the catalog's vectors use, for the store and for a million products. The prose's point rests on the MB line for the store's catalog and the GB line for a million products."""2from lib.recorded import embeddings34# Exact search keeps every product vector in memory, as 32-bit floats.5product_ids, product_vectors, _, _ = embeddings()6print(f"products: {len(product_ids):,}")7print(f"float32 bytes per product: {product_vectors[0].nbytes:,}")8# decimal MB and GB: a megabyte is a million bytes, a gigabyte a billion9print(f"product vectors in memory, MB: {product_vectors.nbytes / 1e6:.1f}")10print(f"the same for 1,000,000 products, GB: {1_000_000 * product_vectors[0].nbytes / 1e9:.1f}")
python exact-search-memory.pyproducts: 12,000
float32 bytes per product: 3,072
product vectors in memory, MB: 36.9
the same for 1,000,000 products, GB: 3.1
Cada produto ocupa 3,072 bytes como floats de 32 bits, então o catálogo da loja ocupa 36.9 MB, e um milhão de produtos ocuparia 3.1 GB. Douze et al. (2024) recomendam decidir primeiro se um índice é necessário, pois em alguns casos a busca por força bruta é a melhor opção. Consideramos que o catálogo da loja é um desses casos.
Regra prática: Recomendamos a busca exata até que ela deixe de caber na memória ou deixe de atender ao seu orçamento de latência, medido com o seu próprio catálogo no seu próprio hardware. Ela não tem configurações a ajustar e nunca deixa de encontrar um vizinho, por isso também serve como referência de verdade para qualquer índice aproximado. Armazene os vetores normalizados como uma única matriz de 32 bits, obtenha os k primeiros com argpartition e ordene apenas esses.
Troque recall por velocidade com HNSW
Quando a busca exata custa caro demais, um índice de vizinho mais próximo aproximado (ANN, do inglês approximate nearest-neighbour) pula a maior parte das comparações e, em troca, pode deixar de encontrar alguns dos verdadeiros vizinhos mais próximos. A qualidade de um índice ANN é o seu recall@k em relação à busca exata: a fração do top k da busca exata que ele também retorna. Isso não é o recall@k do capítulo 3, que compara um ranking com julgamentos. Um índice com recall perfeito em relação à busca exata retorna o que a busca exata retorna, seja bom ou ruim.
HNSW, abreviação de hierarchical navigable small world, é um índice de grafo. Cada produto é um nó ligado a alguns de seus vizinhos mais próximos, em uma pilha de camadas: a camada inferior contém todos os produtos, e cada camada acima contém menos. Uma busca começa no topo, passa para o nó ligado mais próximo da consulta, desce uma camada quando não consegue se aproximar mais e, na camada inferior, explora uma lista de candidatos antes de retornar os k melhores (Malkov and Yashunin, 2018). No faiss, M define o número de ligações por nó. Mais ligações encontram mais verdadeiros vizinhos, mas usam mais memória (faiss wiki). efConstruction, o fator de expansão no momento da construção, define quantos candidatos a construção considera, e efSearch, o fator de expansão no momento da busca, quantos candidatos a busca considera. Com o faiss 1.16.0, seus valores padrão são 40 e 16, e a construção do grafo é determinística, porque a única construção que add() usa é determinística (HNSW.h; changelog). Por isso, os resultados aqui se repetem exatamente. Os tempos variam de máquina para máquina, então os exemplos contam o trabalho: o faiss conta as distâncias que calcula em cada busca (HNSW.h), que, para este índice, são similaridades. A contagem deixa de fora o seguimento de ligações e a leitura de memória, então ela é um guia para a velocidade, não uma medida dela.
A loja não precisa de índice, mas uma loja com milhões de produtos precisaria, e um catálogo pequeno o bastante para verificar cada resposta é o lugar para aprender o compromisso. Construa um HNSW sobre os 12,000 produtos da loja com hnsw_index(product_vectors, links=32), nome que lib.vectors recebe para M = 32. Depois, varra efSearch de 16 a 256 nas consultas de treino:
1"""Builds HNSW with M = 32 and sweeps efSearch on the train queries against exact search, printing recall, the worst query and the work per query. The prose's point rests on the efSearch 16 lines and the two smallest-efSearch lines printed after the table."""2import faiss3import numpy as np45from lib.recorded import embeddings6from lib.store import load_products, load_queries7# EF_SEARCH_GRID runs 16 to 256 in steps of 16; WORST_RECALL is 0.9: at least 9 of the true top 108from lib.vectors import EF_SEARCH_GRID, WORST_RECALL, exact_search, hnsw_index, hnsw_search, recall_against_exact910product_ids, product_vectors, query_ids, query_vectors = embeddings()11names = load_products().loc[product_ids, "name"].str[:36].to_numpy() # by row number, cut to 36 characters12rows = np.isin(query_ids, load_queries("train").index) # tune on train queries only13queries = load_queries().loc[query_ids[rows], "query"].to_numpy()1415index = hnsw_index(product_vectors, links=32) # M = 32, and faiss's default efConstruction of 4016levels = faiss.vector_to_array(index.hnsw.levels) # how many layers each product reaches17for layer in range(1, levels.max() + 1):18 print(f"products in layer {layer}: {(levels >= layer).sum():,}")1920exact = exact_search(query_vectors[rows], product_vectors, 10)21print("\nefSearch mean recall@10 worst queries at 0 similarities per query")22sweep = {}23for ef_search in EF_SEARCH_GRID:24 # similarities is faiss's count of the distances each search computed, per query, not a score25 found, similarities = hnsw_search(index, query_vectors[rows], 10, ef_search)26 # share of exact search's top 10 that the approximate search also found, order ignored27 recall = recall_against_exact(found, exact)28 sweep[ef_search] = (recall, similarities)29 print(f"{ef_search:>8} {recall.mean():>14.3f} {recall.min():>5.1f} {(recall == 0).sum():>12} {similarities:>22.0f}")3031recall, similarities = sweep[16] # faiss's default32print(f"\nefSearch 16, recall@10 against exact: {recall.mean():.3f}")33print(f"efSearch 16, similarities computed per query: {similarities:.0f}")34print(f"efSearch 16, train queries with recall@10 of 0: {(recall == 0).sum()}")35print("efSearch 16, those queries:", ", ".join(queries[recall == 0]))36print("smallest efSearch with no query at 0:", min(ef for ef, (r, _) in sweep.items() if r.min() > 0))37chosen = min(ef for ef, (r, _) in sweep.items() if r.min() >= WORST_RECALL)38print(f"smallest efSearch with every query at {WORST_RECALL} or more:", chosen)39print(f"chosen efSearch, recall@10 against exact: {sweep[chosen][0].mean():.3f}")40print(f"chosen efSearch, similarities computed per query: {sweep[chosen][1]:.0f}\n")4142# the top 3 at the default efSearch, for the query that fails43found, _ = hnsw_search(index, query_vectors[rows], 3, 16)44row = list(queries).index("foutains with brick look")45for rank, (approximate, nearest) in enumerate(zip(found[row], exact[row]), start=1):46 print(f"{rank} hnsw: {names[approximate]:<36} exact: {names[nearest]}")
python hnsw-efsearch-sweep.pyproducts in layer 1: 12,000
products in layer 2: 369
products in layer 3: 10
efSearch mean recall@10 worst queries at 0 similarities per query
16 0.934 0.0 2 282
32 0.936 0.0 2 346
48 0.940 0.0 2 404
64 0.940 0.0 2 463
80 0.956 0.0 1 530
96 0.978 0.3 0 611
112 0.980 0.3 0 682
128 0.994 0.8 0 767
144 0.998 0.9 0 835
160 0.998 0.9 0 924
176 0.998 0.9 0 1020
192 0.998 0.9 0 1115
208 0.998 0.9 0 1191
224 1.000 1.0 0 1271
240 1.000 1.0 0 1349
256 1.000 1.0 0 1441
efSearch 16, recall@10 against exact: 0.934
efSearch 16, similarities computed per query: 282
efSearch 16, train queries with recall@10 of 0: 2
efSearch 16, those queries: foutains with brick look, sheffield home bath set
smallest efSearch with no query at 0: 96
smallest efSearch with every query at 0.9 or more: 144
chosen efSearch, recall@10 against exact: 0.998
chosen efSearch, similarities computed per query: 835
1 hnsw: dayse outdoor square cushion with fi exact: tribeca 2 '' x 10 '' porcelain brick
2 hnsw: 3 piece wall decor set exact: barbados 5 '' x 10 '' ceramic brick
3 hnsw: rustic autumn ivy branch exact: kimary 0.75 '' x 1.5 '' glass brick
O grafo fica rarefeito rapidamente: a camada inferior contém todos os 12,000 produtos, a seguinte 369 e a do topo 10.
A média esconde uma falha. Com o efSearch padrão de 16, uma consulta calcula 282 similaridades em vez de 12,000, e o recall@10 médio em relação à busca exata é 0.934. Ainda assim, 2 consultas de treino não obtêm nenhum dos seus 10 verdadeiros melhores resultados.
Essas consultas são foutains with brick look, sheffield home bath set. Veja foutains with brick look, uma delas: o HNSW retorna uma almofada, um conjunto de decoração de parede e um ramo de hera, enquanto os 3 melhores resultados da busca exata são azulejos com aparência de tijolo.
O menor efSearch da varredura em que nenhuma consulta de treino está em 0 é 96, mas a tabela da varredura mostra que sua pior consulta ainda deixa de encontrar a maior parte dos seus 10 verdadeiros melhores resultados. Por isso, escolha por uma regra mais rigorosa: o menor efSearch em que toda consulta de treino encontra pelo menos 9 dos seus 10 verdadeiros melhores resultados. Esse é 144, com recall médio de 0.998 e 835 similaridades por consulta.
Regra prática: Use um índice ANN somente quando a busca exata for lenta ou grande demais. Ajuste-o com as consultas de treino pelo seu recall em relação à busca exata, no k que seu pipeline usa, e escolha pela pior consulta, não pela média. Recomenda-se o menor efSearch em que toda consulta mantenha pelo menos 9 dos seus 10 verdadeiros melhores resultados, com M = 32. Este capítulo ajusta apenas efSearch; M e efConstruction mudam o próprio grafo e merecem a mesma varredura em um catálogo grande. Aumüller et al. (2018) constataram que métodos ANN muito diferentes alcançam compromissos entre qualidade e desempenho comparáveis, então meça com os seus próprios dados, e não pela reputação.
Verifique o índice nas consultas de teste
Um índice ajustado com consultas de treino ainda precisa ser verificado em consultas que ele não viu, pelo seu recall em relação à busca exata e pelo seu efeito nas pontuações avaliadas. Estas são as 2 comparações de teste planejadas do capítulo, cada uma um teste de permutação pareado com um teste t ao lado: o índice HNSW com efSearch padrão do faiss, de 16, e com a configuração escolhida nas consultas de treino, ambos em comparação com a busca exata. A busca também pede k = 100, porque a recuperação híbrida funde os 100 primeiros resultados de cada recuperador:
1"""Compares HNSW at faiss's default efSearch, and at the setting chosen on train queries, with exact search on the test queries, using paired tests at the planned threshold. The prose's point rests on the default setting's permutation and interval lines, and on the chosen setting's recall line."""2import numpy as np34from lib.metrics import evaluate5from lib.recorded import embeddings6from lib.significance import compare, verdict7from lib.store import load_queries, qrels8from lib.vectors import as_run, choose_ef_search, exact_search, hnsw_index, hnsw_search, recall_against_exact910# Planned before scoring: HNSW at faiss's default efSearch, and at the setting chosen on train, each against exact.11PLANNED = 212threshold = 0.05 / PLANNED # the book's rule splits 0.05 across the planned comparisons13product_ids, product_vectors, query_ids, query_vectors = embeddings()14rows = np.isin(query_ids, load_queries("test").index)15index = hnsw_index(product_vectors, links=32)16# the smallest efSearch at which every train query keeps WORST_RECALL of its true top 1017chosen = choose_ef_search(index, query_vectors[np.isin(query_ids, load_queries("train").index)], product_vectors)18# k = 100 because hybrid retrieval fuses each retriever's top 10019exact = exact_search(query_vectors[rows], product_vectors, 100)20exact_ndcg = evaluate(as_run(exact, query_ids[rows], product_ids), qrels("test"))["ndcg@10"]21print("planned test comparisons:", PLANNED)22print(f"p-value threshold: {threshold:.3f}")23print("efSearch chosen on train queries:", chosen)24print(f"exact ndcg@10: {exact_ndcg.mean():.3f}")2526for name, ef_search in [("default", 16), ("chosen", chosen)]:27 found, _ = hnsw_search(index, query_vectors[rows], 100, ef_search)28 # the first 10 of the 10029 recall = recall_against_exact(found[:, :10], exact[:, :10])30 ndcg = evaluate(as_run(found, query_ids[rows], product_ids), qrels("test"))["ndcg@10"]31 result = compare(ndcg, exact_ndcg, confidence=1 - threshold) # a 97.5% interval, at the test's level32 print(f"\n{name}, recall@10 against exact: {recall.mean():.3f}")33 print(f"{name}, queries with recall@10 of 0: {(recall == 0).sum()}")34 print(f"{name}, those queries:", ", ".join(load_queries().loc[query_ids[rows][recall == 0], "query"]) or "none")35 print(f"{name}, recall@100 against exact: {recall_against_exact(found, exact).mean():.3f}")36 print(f"{name}, hnsw ndcg@10: {ndcg.mean():.3f}")37 # compare rounds each difference to 3 decimals: wins and losses are the nonzero ones38 print(f"{name}, queries whose ndcg@10 changes: {result['wins'] + result['losses']}")39 print(f"{name}, permutation p: {result['permutation p']:.3f}")40 print(f"{name}, t-test p: {result['t-test p']:.3f}")41 print(f"{name}, {1 - threshold:.1%} interval: {result['ci low']:.4f} to {result['ci high']:.4f}")42 for check, passed in verdict(result, threshold).items(): # established, t-test agrees, interval agrees43 print(f"{name}, {check}: {'yes' if passed else 'no'}")
python hnsw-test-recall.pyplanned test comparisons: 2
p-value threshold: 0.025
efSearch chosen on train queries: 144
exact ndcg@10: 0.830
default, recall@10 against exact: 0.930
default, queries with recall@10 of 0: 2
default, those queries: liberty hardware francisco, 48" sliding single track , barn door for laundry
default, recall@100 against exact: 0.849
default, hnsw ndcg@10: 0.791
default, queries whose ndcg@10 changes: 3
default, permutation p: 0.256
default, t-test p: 0.154
default, 97.5% interval: -0.1544 to -0.0006
default, established: no
default, t-test agrees: yes
default, interval agrees: no
chosen, recall@10 against exact: 1.000
chosen, queries with recall@10 of 0: 0
chosen, those queries: none
chosen, recall@100 against exact: 0.994
chosen, hnsw ndcg@10: 0.830
chosen, queries whose ndcg@10 changes: 0
chosen, permutation p: 1.000
chosen, t-test p: 1.000
chosen, 97.5% interval: 0.0000 to 0.0000
chosen, established: no
chosen, t-test agrees: yes
chosen, interval agrees: yes
A configuração escolhida nas consultas de treino se sustenta. Seu recall@10 em relação à busca exata é 1.000, sua média de nDCG@10 é 0.830, igual à da busca exata, 0.830, e 0 consultas mudam de pontuação.
Com a configuração padrão do faiss, 2 consultas de teste não recebem nenhum dos seus 10 primeiros verdadeiros (liberty hardware francisco, 48" sliding single track , barn door for laundry), e a média de nDCG@10 cai para 0.791, mas apenas 3 consultas mudam de pontuação, e a queda não está comprovada: o teste de permutação dá p = 0.256, e o teste t concorda com p = 0.154. O intervalo de 97.5%, de -0.1544 to -0.0006, não inclui 0, então discorda dos testes. Com tão poucas consultas carregando a diferença, o achado é a perda de recall em relação à busca exata, e não uma perda de qualidade medida.
Pedir mais resultados não compensa um valor pequeno de efSearch: com a configuração padrão, o recall@100 é 0.849, contra 0.994 na configuração escolhida.
O grafo também custa memória, além dos vetores:
1"""Counts the links per product in the HNSW graph, and the bytes per product of the exact and the HNSW index. The prose's point rests on the two bytes-per-product lines, set against faiss's estimate."""2import faiss34from lib.recorded import embeddings5from lib.vectors import hnsw_index67product_ids, product_vectors, _, _ = embeddings()8dimensions = product_vectors.shape[1]9flat = faiss.IndexFlatIP(dimensions) # exact search: the vectors only10flat.add(product_vectors)11index = hnsw_index(product_vectors, links=32) # the vectors, plus the graph's links1213# layer 0 is the bottom layer: 2 × M links there, and M on each upper layer14print("links per product, upper layers:", index.hnsw.nb_neighbors(1))15print("links per product, bottom layer:", index.hnsw.nb_neighbors(0))16# 8M with M = 32: 4 bytes for each of the 2M bottom-layer links17print(f"faiss's estimate, 4d + 8M bytes per product: {4 * dimensions + 8 * 32:,}")18# the saved index's size, spread over the products19for name, built in [("exact index", flat), ("hnsw index", index)]:20 print(f"bytes per product, {name}: {faiss.serialize_index(built).nbytes / len(product_ids):,.0f}")
python hnsw-index-memory.pylinks per product, upper layers: 32
links per product, bottom layer: 64
faiss's estimate, 4d + 8M bytes per product: 3,328
bytes per product, exact index: 3,072
bytes per product, hnsw index: 3,344
Cada produto tem 32 conexões nas camadas superiores e 64 na camada inferior, o dobro de M. O faiss estima 4d + 8M bytes por vetor (wiki do faiss): 4 bytes para cada um dos d números e 4 bytes para cada uma das 2M conexões da camada inferior, 3,328 aqui. O índice salvo chega perto, com 3,344 bytes por produto, contra 3,072 do índice exato.
Regra prática: Verifique um índice ajustado em consultas reservadas pelo seu recall em relação à busca exata, e leia as consultas que perdem todo o seu top k antes da média das pontuações. Trate uma queda no nDCG@10 que se apoia em um punhado de consultas como não comprovada até que um teste pareado a estabeleça. Planeje a memória para as conexões, além dos vetores.
Verifique consultas que contêm dígitos
Um índice só pode retornar o que os embeddings colocam perto de uma consulta, então a próxima pergunta é quais consultas os embeddings erram. Um codificador comprime a consulta inteira em um único vetor, de modo que um token curto que muda o sentido, como um tamanho, um número de modelo ou uma negação, pode deslocar esse vetor muito pouco. Deng et al. (2026) mediram isso para números, em um estudo com 13 modelos de embeddings sobre texto financeiro sintético. A acurácia deles em distinguir textos pelo número foi de 0.54, apenas um pouco acima dos 0.5 de um chute aleatório, e os números de quatro dígitos ficaram no nível do chute. Produtos não são relatórios financeiros, então verifique as consultas da loja.
Poucas consultas da loja contêm dígitos, então compare a recuperação BM25 e a semântica em cada uma que os contém, nas duas divisões. Nada é ajustado para essas consultas, e um punhado delas não consegue estabelecer nada:
1"""Scores BM25 and semantic retrieval on each query with a digit, in both splits, and counts the products whose text writes 7qt or 7 qt. The prose's point rests on the three lines that count which ranker wins and the two product counts."""2import pandas as pd34from lib.lexical import LexicalSearch5from lib.metrics import evaluate6from lib.semantic import SemanticSearch7from lib.store import load_products, load_queries, product_text, qrels89products, queries = load_products(), load_queries()10with_digit = queries[queries["query"].str.contains(r"\d")] # both splits: a diagnosis, nothing is tuned11judgments = {query_id: grades for query_id, grades in qrels().items() if query_id in with_digit.index}12# each ranker returns its top 100; nDCG@10 scores the first 10 of them13scores = pd.DataFrame({14 "split": with_digit["split"],15 "bm25": evaluate(LexicalSearch(products).run(with_digit, k=100), judgments)["ndcg@10"],16 "semantic": evaluate(SemanticSearch().run(with_digit, k=100), judgments)["ndcg@10"],17 "query": with_digit["query"],18}).round(3)1920print("queries with a digit:", len(scores))21print(scores.to_string())22print("semantic better:", (scores["semantic"] > scores["bm25"]).sum())23print("bm25 better:", (scores["bm25"] > scores["semantic"]).sum())24# a gap under 0.03 counts as a near tie: the book's choice, not a measured limit25print("gaps under 0.03:", ((scores["semantic"] - scores["bm25"]).abs() < 0.03).sum())2627text = product_text(products).str.lower()28print("products whose text has the word 7qt:", text.str.contains(r"\b7qt\b").sum())29# '7 qt', but not '17 qt' or '3.7 qt'30print("products whose text has 7 qt:", text.str.contains(r"(?<![\d.])7 qt\b").sum())
python digits-in-queries.pyqueries with a digit: 7
split bm25 semantic query
query_id
45 train 0.288 0.316 70s inspired furniture
62 train 0.554 0.930 7qt slow cooker
101 train 0.569 0.770 48 in entry table with side by side drawer
203 train 0.606 0.740 ge top loading washer 4.5
205 train 0.935 0.930 ines shag rug w003096809
285 test 0.592 0.555 48" sliding single track , barn door for laundry
482 test 1.000 0.921 48 inch kitchen hood
semantic better: 4
bm25 better: 3
gaps under 0.03: 2
products whose text has the word 7qt: 0
products whose text has 7 qt: 8
Nenhum dos dois métodos de ranqueamento domina as 7 consultas com dígito. A recuperação semântica pontua mais alto em 4 delas e o BM25 em 3, e 2 das diferenças são menores que 0.03. A derrota mais clara do BM25 é 7qt slow cooker: a palavra 7qt aparece em 0 produtos, e 8 escrevem 7 qt.
Na consulta de teste 48 inch kitchen hood, o BM25 pontua mais alto, então aqui está o top 10 da recuperação semântica:
1"""Lists semantic retrieval's top 10 for 48 inch kitchen hood with each hood's width, read from the attributes column the embeddings never saw. The prose's point rests on the two width-48 lines, one for each ranker."""2from lib.lexical import LexicalSearch3from lib.semantic import SemanticSearch4from lib.store import load_products, load_queries, qrels56LABELS = {2: "exact", 1: "partial", 0: "irrelevant"}7products = load_products()8query_id = 482 # 48 inch kitchen hood, a test query9query = load_queries().at[query_id, "query"]10judgments = qrels()[query_id]11# The width sits in the attributes column, which the embeddings never saw: product_text leaves it out.12width = products["attributes"].str.extract(r"\bwidth: ([\d.]+)", expand=False).astype(float)1314semantic = SemanticSearch().search(query_id, k=10).index15bm25 = LexicalSearch(products).search(query, k=10).index16print("query:", query)17print(" judgment width name")18for rank, product_id in enumerate(semantic, start=1):19 label = LABELS.get(judgments.get(product_id), "unjudged")20 print(f"{rank:>2} {label:<10} {width[product_id]:>5g} {products.at[product_id, 'name'][:50]}")2122print()23# exact: a 48-inch hood is 48 wide, where probe-pair-overlap allows half an inch for hoods listed at 35.7524for name, top in [("semantic", semantic), ("bm25", bm25)]:25 print(f"{name}, width 48 in the top 10:", (width[top] == 48).sum())26 print(f"{name}, exact in the top 10:", sum(judgments.get(product_id) == 2 for product_id in top))
python hood-query-digits.pyquery: 48 inch kitchen hood
judgment width name
1 exact 48 48 '' 1200 cfm ducted wall mount range hood in bru
2 exact 48 48 '' 400 cfm ducted wall mount range hood in brus
3 exact 48 48 '' 400 cfm convertible wall mount range hood
4 partial 35.75 36 '' ws-48 series 500 cfm ducted under cabinet ra
5 exact 48 48 '' hand crafted designer wood island hood serie
6 exact 48 48 '' island range hood
7 exact 48 48 inch wall mount chimney range hood with 600 cfm
8 exact 48 48 '' ducted island range hood
9 exact 48 48 '' professional 900cfm ducted island range hood
10 partial 29.8 30 '' 480 cfm convertible under cabinet range hood
semantic, width 48 in the top 10: 8
semantic, exact in the top 10: 8
bm25, width 48 in the top 10: 10
bm25, exact in the top 10: 10
Para esta consulta, o embedding casou os dígitos como texto, não a largura que eles representam. Dos 10 primeiros da recuperação semântica, 8 coifas têm largura de 48. As demais são uma coifa de 36 polegadas de uma série chamada ws-48 e uma coifa de 30 polegadas com 480 cfm, pés cúbicos por minuto, a vazão de ar do seu ventilador. Ambas contêm os dígitos 48, nenhuma tem 48 de largura, e os juízes marcaram as duas como parcial. O top 10 do BM25 traz 10 coifas de largura 48.
A largura de cada coifa vem da coluna attributes, que contém campos selecionados das características de produto do WANDS, como largura, formato e material. product_text, o texto que o modelo incorporou, deixa essa coluna de fora, de modo que os embeddings nunca a viram, e um tamanho digitado pelo cliente pode ser conferido exatamente contra ela.
Uma única consulta não mostra um padrão. Para ver como o modelo lida com tamanhos em geral, use consultas de sondagem: pares de consultas escritas para o livro que diferem apenas por um tamanho, um código ou uma negação, e que recordings/probes.py incorpora com o mesmo modelo. Uma delas repete a consulta de teste 48 inch kitchen hood palavra por palavra. As sondagens não têm julgamentos, então o exemplo conta os seus top 10 e nunca os pontua. O tamanho certo vem da largura em attributes para as coifas, e do nome para o restante:
1"""Counts, for each probe pair, the products the two top 10s share and the top-10 products of the right size, without scoring anything. The prose's point rests on the right-size lines for the hood, slow-cooker and bed probes, and on the seat-count and loveseat lines for the sofa probe."""2from lib.recorded import probes3from lib.semantic import SemanticSearch4from lib.store import load_products56# Probe queries written for the book, embedded by the same model. They have no judgments,7# so this example counts what each top 10 holds; it doesn't score anything.8probe_queries, probe_vectors = probes()9products = load_products()10names = products["name"]11width = products["attributes"].str.extract(r"\bwidth: ([\d.]+)", expand=False).astype(float)12semantic = SemanticSearch()131415def states(size, unit):16 """Names that state this size, such as "7 qt" or "7-quart", but not "3.7 qt"."""17 return names.str.contains(rf"(?<![\d.]){size}[ -]?(?:{unit})")181920RIGHT_SIZE = { # the size each probe asks for: the width attribute, or the name21 # within half an inch of 36 or 48, so a 35.75-inch hood counts as 3622 "36 inch kitchen hood": (width - 36).abs() <= 0.5, "48 inch kitchen hood": (width - 48).abs() <= 0.5,23 "4 qt slow cooker": states(4, "qt|quart"), "7 qt slow cooker": states(7, "qt|quart"),24 # the whole word, which also matches 'twin over full' bunk beds25 "twin bed": names.str.contains(r"\btwin\b"), "king bed": names.str.contains(r"\bking\b"),26 "2 seat sofa": names.str.contains(r"\bloveseat\b"), # a two-seat sofa is a loveseat27}28DIGIT_ONLY = {"2 seat sofa": states(2, " in 1| piece"), "4 seat sofa": states(4, " in 1| piece")}2930for pair in ["hood", "cooker", "bed", "seats"]:31 first, second = probe_queries.index[probe_queries["pair"] == pair] # each pair is two probes, in file order32 tops = {row: semantic.search_vector(probe_vectors[row], k=10).index for row in (first, second)}33 print(f"{pair}, similarity of the two queries: {probe_vectors[first] @ probe_vectors[second]:.3f}")34 print(f"{pair}, products in both top 10s:", len(set(tops[first]) & set(tops[second])))35 for row, top in tops.items():36 query = probe_queries.at[row, "query"]37 if query in RIGHT_SIZE:38 print(f"{query}, right size in the top 10:", RIGHT_SIZE[query][top].sum())39 if query in DIGIT_ONLY:40 print(f"{query}, same digit but a piece count or 2 in 1:", DIGIT_ONLY[query][top].sum())41 print()42# the two counts the sofa probes ask for43print("catalog names that give a seat count:", (states(2, "seat") | states(4, "seat")).sum())44print("catalog products named loveseat:", names.str.contains(r"\bloveseat\b").sum())
python probe-pair-overlap.pyhood, similarity of the two queries: 0.795
hood, products in both top 10s: 0
36 inch kitchen hood, right size in the top 10: 8
48 inch kitchen hood, right size in the top 10: 8
cooker, similarity of the two queries: 0.841
cooker, products in both top 10s: 1
4 qt slow cooker, right size in the top 10: 6
7 qt slow cooker, right size in the top 10: 7
bed, similarity of the two queries: 0.697
bed, products in both top 10s: 0
twin bed, right size in the top 10: 10
king bed, right size in the top 10: 10
seats, similarity of the two queries: 0.759
seats, products in both top 10s: 1
2 seat sofa, right size in the top 10: 0
2 seat sofa, same digit but a piece count or 2 in 1: 4
4 seat sofa, same digit but a piece count or 2 in 1: 4
catalog names that give a seat count: 0
catalog products named loveseat: 14
Nessas sondagens, o modelo em geral encontra o tamanho certo. As duas sondagens de coifas compartilham 0 produtos, mas cada top 10 traz coifas da largura certa, 8 para 36 polegadas e 8 para 48. As sondagens de panelas de cozimento lento encontram 6 e 7 da capacidade certa, e as de camas encontram 10 e 10 do tamanho certo. Quando o catálogo não tem um número para casar, o dígito assume o controle. O número de nomes de produto que informam uma quantidade de lugares é 0, então o top 10 de 2 seat sofa traz 4 produtos que compartilham apenas o dígito, como conjuntos de duas peças e sofás infantis "2 em 1", e 0 dos 14 loveseats do catálogo.
Espere que um código tenha pouco peso
Um código de produto deve corresponder exatamente a um produto. Para um codificador, ele é uma sequência rara de letras e dígitos. Dois pares das consultas de sondagem testam códigos: um construído sobre um código que nenhum produto possui, tirado da consulta de treino ines shag rug w003096809, e outro construído sobre uma resolução de tela que o texto de exatamente um produto contém:
1"""Compares the top 10s of two probe queries that differ only in a code no product holds, and shows where one product ranks for two resolutions, semantically and with BM25. The prose's point rests on the shared-top-10 line for the code and on the rank lines for the resolutions."""2from lib.lexical import LexicalSearch3from lib.recorded import probes4from lib.semantic import SemanticSearch5from lib.store import load_products, product_text67# Probe queries written for the book, embedded by the same model; no judgments, so nothing is scored.8probe_queries, probe_vectors = probes()9products = load_products()10text = product_text(products).str.lower()11semantic, bm25 = SemanticSearch(), LexicalSearch(products)1213# A code no product holds: does changing it change the results?14first, second = probe_queries.index[probe_queries["pair"] == "code"]15tops = [set(semantic.search_vector(probe_vectors[row], k=10).index) for row in (first, second)]16print("products whose text contains w003096809:", text.str.contains("w003096809").sum())17print(f"code, similarity of the two queries: {probe_vectors[first] @ probe_vectors[second]:.3f}")18print("code, products in both top 10s:", len(tops[0] & tops[1]))1920# A code one product holds: where does that product rank, with its code and with another?21holder = text.index[text.str.contains("1920x1080p")]22print()23print("products whose text contains 1920x1080p:", len(holder))24print("that product:", products.at[holder[0], "name"])25print("products in the Projectors class:", (products["product_class"] == "Projectors").sum())26for row in probe_queries.index[probe_queries["pair"] == "resolution"]:27 query = probe_queries.at[row, "query"]28 ranked = semantic.search_vector(probe_vectors[row], k=len(products)) # ranks every product, so the rank is exact29 lexical = list(bm25.search(query, k=100).index) # BM25 ranks are read from its top 100 only30 print(f"{query}, its semantic rank: {list(ranked.index).index(holder[0]) + 1}") # ranks count from 131 print(f"{query}, its similarity: {ranked[holder[0]]:.3f}")32 # the best product other than this one33 print(f"{query}, similarity of the next product: {ranked.drop(holder[0]).iloc[0]:.3f}")34 print(f"{query}, its bm25 rank:", lexical.index(holder[0]) + 1 if holder[0] in lexical else "not in the top 100")
python code-probes.pyproducts whose text contains w003096809: 0
code, similarity of the two queries: 0.967
code, products in both top 10s: 10
products whose text contains 1920x1080p: 1
that product: 5000 portable transmissive projector
products in the Projectors class: 4
1920x1080p projector, its semantic rank: 1
1920x1080p projector, its similarity: 0.562
1920x1080p projector, similarity of the next product: 0.496
1920x1080p projector, its bm25 rank: 1
2560x1440p projector, its semantic rank: 1
2560x1440p projector, its similarity: 0.509
2560x1440p projector, similarity of the next product: 0.508
2560x1440p projector, its bm25 rank: not in the top 100
Alterar os últimos dígitos do código desconhecido deixa as duas consultas com uma similaridade de 0.967, e seus 10 primeiros resultados compartilham 10 produtos. Um código que não corresponde a nada não muda nada, e o BM25 também não tem o que corresponder.
Um código que um único produto possui decide o ranqueamento do BM25 e apenas empurra levemente o do embedding. A resolução 1920x1080p aparece somente no texto do 5000 portable transmissive projector. O BM25 a ranqueia em 1 para 1920x1080p projector; para 2560x1440p projector, ela fica em not in the top 100. Sciavolino et al. (2021) constataram que recuperadores densos (baseados em embeddings) se saem drasticamente pior que métodos esparsos em perguntas sobre entidades raras, enquanto Karpukhin et al. (2020) descrevem o BM25 como sensível a palavras-chave e frases altamente seletivas.
O embedding ranqueia-o em 1 com o próprio código e em 1 com o outro, porque a loja tem apenas 4 projetores. O código aparece somente na margem sobre o produto seguinte: 0.562 contra 0.496 com ele, e 0.509 contra 0.508 sem ele.
Regra prática: Liste as consultas do seu registro que contêm tamanhos, quantidades ou códigos, e compare os dois rankers nelas antes de confiar em qualquer um. Quando um código importa, faça a correspondência lexical. Quando um tamanho exato importa, compare-o com um campo do produto, como a largura em attributes, ou faça a correspondência lexical depois que o tokenizador mantiver os dígitos e as unidades escritos de um único jeito (capítulo 5, capítulo 8). Deixe o restante da consulta para a recuperação semântica. Capítulo 7 testa a combinação das duas.
Teste embeddings com negação
A negação inverte o que o cliente quer com uma palavra curta: um tapete que não é redondo. O embedding da consulta inteira pode permanecer próximo da mesma consulta sem essa palavra. A NevIR, um benchmark de pares de documentos que diferem por uma negação, constatou que nenhuma arquitetura bi-encoder ultrapassa 12% de acurácia pareada, enquanto o ranqueamento aleatório obtém 25% (Weller et al., 2024). Em uma reprodução de 2025, van den Elsen et al. constataram que um bi-encoder de 7 bilhões de parâmetros, o GritLM-7B, alcançou 39.0%, que os outros bi-encoders melhoraram pouco e que somente os cross-encoders e os rerankers LLM de tipo listwise lidaram razoavelmente bem com as duas tarefas de negação.
0 das consultas da loja contêm "no", "not", "without" ou "non", então os julgamentos não conseguem testar negação. Em seu lugar, entram 3 pares de consultas de sondagem, cada um formado por uma consulta e sua negação, e contamos o que cada top 10 contém.
O catálogo poderia atender a todas as sondagens com negação: ele tem 42 produtos chamados armless, 62 mesas de centro que nunca mencionam vidro e 90 tapetes de área que não são chamados round.
Antes da execução, estime quantos dos top 10 da recuperação semântica para rug that is not round são chamados round.
1"""Counts what each negation probe's top 10 holds for semantic retrieval and for BM25, without scoring it. The prose's point rests on the semantic top 10 lines for the rug, coffee-table and sofa probes."""2import bm25s34from lib.lexical import LexicalSearch5from lib.recorded import probes6from lib.semantic import SemanticSearch7from lib.store import load_products, load_queries, product_text89# Probe queries written for the book, with no judgments: count what the top 10 holds, never score it.10probe_queries, probe_vectors = probes()11products = load_products()12names, text = products["name"].str.lower(), product_text(products).str.lower()13semantic, bm25 = SemanticSearch(), LexicalSearch(products)14# armless and round are matched in product names, glass in the full text15FEATURES = {"arms": ("armless", names), "glass": ("glass", text), "round": ("round", names)}1617negated = load_queries()["query"].str.contains(r"\b(?:no|not|without|non)\b")18print("store queries with no, not, without or non:", negated.sum())19# the tokenizer settings LexicalSearch uses, so these are the terms BM25 searches20tokens = bm25s.tokenize(["rug that is not round"], stopwords="en", return_ids=False, show_progress=False)21print("bm25 terms of rug that is not round:", " ".join(tokens[0]))22print("products named armless:", names.str.contains(r"\barmless\b").sum())23coffee_tables = products["product_class"] == "Coffee & Cocktail Tables"24area_rugs = products["product_class"] == "Area Rugs"25print("coffee tables that never mention glass:", (coffee_tables & ~text.str.contains(r"\bglass\b")).sum())26print("area rugs not named round:", (area_rugs & ~names.str.contains(r"\bround\b")).sum())2728negation = probe_queries[probe_queries["kind"] == "negation"]29print("negation probe pairs:", negation["pair"].nunique())30for row, probe in negation.iterrows():31 word, field = FEATURES[probe["pair"]]32 has_feature = field.str.contains(rf"\b{word}\b")33 semantic_top = semantic.search_vector(probe_vectors[row], k=10).index34 bm25_top = bm25.search(probe["query"], k=10).index35 print()36 print(f"{probe['query']}, semantic top 10 with {word}:", has_feature[semantic_top].sum())37 print(f"{probe['query']}, bm25 top 10 with {word}:", has_feature[bm25_top].sum())
python negation-probes.pystore queries with no, not, without or non: 0
bm25 terms of rug that is not round: rug round
products named armless: 42
coffee tables that never mention glass: 62
area rugs not named round: 90
negation probe pairs: 3
sofa with arms, semantic top 10 with armless: 1
sofa with arms, bm25 top 10 with armless: 0
sofa without arms, semantic top 10 with armless: 8
sofa without arms, bm25 top 10 with armless: 0
coffee table with glass top, semantic top 10 with glass: 10
coffee table with glass top, bm25 top 10 with glass: 9
coffee table not glass, semantic top 10 with glass: 10
coffee table not glass, bm25 top 10 with glass: 10
round rug, semantic top 10 with round: 10
round rug, bm25 top 10 with round: 10
rug that is not round, semantic top 10 with round: 10
rug that is not round, bm25 top 10 with round: 10
Se você estimou poucos, leu o "not" como um cliente lê, e o embedding não. Nas sondagens de tapete e de mesa de centro, ele manteve o atributo e perdeu o "not". O top 10 da recuperação semântica para rug that is not round contém 10 produtos chamados round, e o seu top 10 para round rug contém 10. Para coffee table not glass, 10 dos top 10 mencionam vidro, contra 10 para coffee table with glass top.
sofa without arms vai no sentido oposto, e 8 dos seus top 10 são chamados armless, contra 1 para sofa with arms. O catálogo tem uma palavra para essa negação, armless, e o modelo posiciona "without arms" perto dela.
O BM25 não se sai melhor nessas sondagens. Seu tokenizador descarta "not", "that" e "is" como palavras de parada, então pesquisa rug that is not round como rug round. Seus top 10 contêm 10 tapetes chamados round e 0 sofás chamados armless.
Essas sondagens são poucos pares, não uma medição, e o par dos sofás vai no sentido oposto. Mas os pares de tapete e de mesa de centro concordam com a NevIR: o vetor da consulta permanece próximo do atributo que a consulta nomeia.
Regra prática: Não confie em um recuperador de primeira etapa, lexical ou semântico, para tratar negação. Quando os clientes excluem um atributo que o catálogo armazena, como forma, material ou braços, detecte a exclusão e filtre pelo atributo. Caso contrário, reordene, já que na reprodução de van den Elsen et al. os cross-encoders e os rerankers LLM trataram a negação muito melhor. O capítulo 9 reordena a recuperação semântica da loja com um cross-encoder e LLMs, e nenhum de seus rerankers supera a recuperação semântica nas consultas julgadas da loja, que não conseguem testar negação. Mantenha sondagens como estas como uma verificação a ser executada novamente sempre que você trocar de modelo ou adicionar um reranker.
Escolha um modelo de embeddings
O modelo define o que os vetores podem saber, e trocá-lo depois significa gerar os embeddings de todo o catálogo novamente. Os benchmarks públicos reduzem o leque de opções. Quem decide são os julgamentos da própria loja.
Leia os benchmarks como uma lista de candidatos
O MTEB, o Massive Text Embedding Benchmark, avalia modelos em muitas tarefas. Seus autores constataram que nenhum método domina em todas elas (Muennighoff et al., 2023). Eles também constataram que as médias do benchmark tendem a favorecer tarefas com muitos conjuntos de dados, notadamente recuperação, classificação e agrupamento. Por isso, leia as pontuações referentes à tarefa que você tem em mãos.
Pontuações públicas também podem superestimar o desempenho em dados que o modelo não viu. Os criadores do RTEB, um benchmark de recuperação, descrevem uma diferença entre as pontuações que os modelos reportam em benchmarks públicos e o desempenho real deles em dados novos, não vistos (Liu et al., 2025). O RTEB mantém privados 28 dos seus 48 conjuntos de dados. Verma et al. (2026) verificam que as classificações de modelos no RTEB se correlacionam apenas em ρ = 0.38 com as classificações no MTEB e no BEIR (Thakur et al., 2021), um benchmark anterior de recuperação em muitos domínios. Aqui, ρ é uma correlação de postos, em que 1 significa a mesma ordem. Tamanho também não é sinônimo de qualidade. Enevoldsen et al. (2025) relatam que, no MMTEB, sucessor multilíngue do MTEB, o modelo de melhor desempenho disponível publicamente é o multilingual-e5-large-instruct, que tem apenas 560 milhões de parâmetros.
A loja considerou quatro modelos abertos, e nenhuma das fichas deles relata resultados no WANDS. São eles o codificador da loja e Qwen/Qwen3-Embedding-0.6B (ficha). Os outros dois são BAAI/bge-base-en-v1.5 (ficha) e ibm-granite/granite-embedding-english-r2 (ficha). Benchmarks de busca de produtos, como o ESCI, que rotula pares consulta–produto como exato, substituto, complementar ou irrelevante e reúne cerca de 130,000 consultas e 2.6 milhões de julgamentos (Reddy et al., 2022), estão mais próximos da tarefa da loja, mas ainda não são o catálogo dela. Assim, a lista de candidatos da loja se apoia em verificações que uma tabela de classificação não consegue fazer: uma licença que permita uso comercial, suporte ao inglês, um tamanho que rode sem hardware especial e suporte documentado a vetores menores. A ficha do modelo escolhido pela loja relata 55.14 nDCG@10 nas tarefas de recuperação do MTEB, uma medição do fornecedor sobre texto geral, não sobre produtos (ficha do modelo). Para escolher entre os candidatos, registre cada um sobre o mesmo texto de produtos e as mesmas consultas, pontue cada um nas consultas de treino e compare-os com os testes pareados do livro, como a próxima subseção faz para um modelo em vários tamanhos.
Trunque as dimensões e depois teste a perda
Cada dimensão custa 4 bytes por produto como um float de 32 bits, e cada similaridade multiplica todas elas, de modo que um vetor mais curto é mais barato de armazenar e de pesquisar. O treinamento Matryoshka ensina um modelo a colocar a informação mais útil nas suas primeiras dimensões, de modo que o início de um vetor funcione sozinho como um embedding menor. Kusupati et al. (2022) relatam embeddings até 14 vezes menores para a classificação no ImageNet-1K no mesmo nível de acurácia. Encurtar economiza armazenamento e busca, não codificação: um modelo Matryoshka não é mais rápido de executar, como observa a documentação do Sentence Transformers. Somente modelos treinados dessa forma são construídos para tolerar o encurtamento, e um vetor encurtado não tem comprimento unitário, então normalize-o novamente, como faz o próprio exemplo do model card.
O codificador da loja tem um model card que documenta o encurtamento para 256 dimensões. lib.recorded.embeddings(dims=...) mantém os primeiros dims números de cada vetor e normaliza novamente. Calcule a pontuação de cada tamanho nas consultas de treino:
1"""Scores semantic retrieval on the train queries at 768, 256 and 128 dimensions, with each product's float32 size. The prose's point rests on the nDCG@10 line for each length, set against 768 dimensions."""2from lib.metrics import evaluate3from lib.semantic import SemanticSearch4from lib.store import load_queries, qrels56train, judgments = load_queries("train"), qrels("train") # choose on train queries78# dims keeps the first dims numbers of every vector and rescales each to length 1 (lib.recorded).9for dims in [768, 256, 128]:10 semantic = SemanticSearch(dims=dims)11 scores = evaluate(semantic.run(train, k=100), judgments)12 # semantic.products holds the product vectors, not the product table13 print(f"{dims} dimensions, float32 bytes per product: {semantic.products[0].nbytes:,}")14 print(f"{dims} dimensions, ndcg@10: {scores['ndcg@10'].mean():.3f}")15 print(f"{dims} dimensions, judged@10: {scores['judged@10'].mean():.3f}")16 print()
python truncate-embeddings.py768 dimensions, float32 bytes per product: 3,072
768 dimensions, ndcg@10: 0.772
768 dimensions, judged@10: 0.964
256 dimensions, float32 bytes per product: 1,024
256 dimensions, ndcg@10: 0.762
256 dimensions, judged@10: 0.952
128 dimensions, float32 bytes per product: 512
128 dimensions, ndcg@10: 0.680
128 dimensions, judged@10: 0.874
Encurtar para 256 dimensões reduz um produto de 3,072 bytes para 1,024, e move o nDCG@10 médio de 0.772 para 0.762.
Com 128 dimensões, a média é 0.680, com judged@10 em 0.874 contra 0.964, de modo que parte dessa queda poderia vir de produtos que ninguém avaliou.
A mudança é real, ou é ruído entre 50 consultas? Teste com lib.significance.compare, que executa o teste de permutação do capítulo 3 e o seu teste t pareado. Ele também informa um intervalo bootstrap. Essas comparações usam consultas de treino, portanto ajustam o tamanho do vetor; elas não são evidência sobre as consultas de teste:
1"""Tests the change in nDCG@10 from shortening to 256 and 128 dimensions against the full vectors, on the train queries, with a permutation test, a paired t-test and a bootstrap interval. The prose's point rests on the permutation, interval and effect-size lines for each length."""2from lib.metrics import evaluate3from lib.semantic import SemanticSearch4from lib.significance import compare5from lib.store import load_queries, qrels67# Train queries: these comparisons tune the vector size. They are not evidence about the test queries.8train, judgments = load_queries("train"), qrels("train")91011def ndcg(dims):12 return evaluate(SemanticSearch(dims=dims).run(train, k=100), judgments)["ndcg@10"]131415def p_value(p):16 return "below 0.001" if p < 0.001 else f"{p:.3f}"171819full = ndcg(768)20for dims in [256, 128]:21 # compare's default interval is 95%22 result = compare(ndcg(dims), full) # paired by train query: shortened minus full23 print(f"{dims} vs 768, mean difference in ndcg@10: {result['mean difference']:.3f}")24 print(f"{dims} vs 768, queries worse: {result['losses']}")25 print(f"{dims} vs 768, permutation test p: {p_value(result['permutation p'])}")26 print(f"{dims} vs 768, paired t-test p: {p_value(result['t-test p'])}")27 print(f"{dims} vs 768, 95% bootstrap interval: {result['ci low']:.4f} to {result['ci high']:.4f}")28 print(f"{dims} vs 768, interval excludes 0: {'yes' if result['ci high'] < 0 or result['ci low'] > 0 else 'no'}")29 print(f"{dims} vs 768, effect size: {result['effect size']:.3f}")30 print()
python truncation-paired-test.py256 vs 768, mean difference in ndcg@10: -0.010
256 vs 768, queries worse: 24
256 vs 768, permutation test p: 0.076
256 vs 768, paired t-test p: 0.080
256 vs 768, 95% bootstrap interval: -0.0211 to -0.0002
256 vs 768, interval excludes 0: yes
256 vs 768, effect size: -0.253
128 vs 768, mean difference in ndcg@10: -0.092
128 vs 768, queries worse: 33
128 vs 768, permutation test p: below 0.001
128 vs 768, paired t-test p: below 0.001
128 vs 768, 95% bootstrap interval: -0.1569 to -0.0565
128 vs 768, interval excludes 0: yes
128 vs 768, effect size: -0.547
Com 128 dimensões, a perda é clara. A diferença média é -0.092, e 33 consultas de treino pioram. O teste de permutação dá p below 0.001, e o intervalo de 95%, de -0.1569 to -0.0565, não inclui 0.
Com 256 dimensões, a evidência é limítrofe, porque os testes e o intervalo não concordam. A diferença média é -0.010; o teste de permutação dá p = 0.076 e o teste t dá p = 0.080, mas o intervalo, de -0.0211 to -0.0002, não inclui 0 por uma margem mínima. O tamanho do efeito, -0.253 com 256 dimensões contra -0.547 com 128, indica que qualquer perda com 256 dimensões é a menor das duas.
Para a loja, a decisão depende do seu tamanho, não do teste. Seus vetores completos ocupam 36.9 MB, então há pouco a economizar; ela mantém todas as 768 dimensões, e sua pontuação no teste não muda. Um catálogo de centenas de milhões de produtos pesaria uma redução de 3,072 para 1,024 bytes por produto contra uma perda que este número de consultas de treino não consegue precisar, e avaliaria mais consultas antes de decidir.
Regra prática: Faça uma pré-seleção de modelos por licença, idioma, tamanho e domínio, e trate as posições nos benchmarks apenas como uma indicação. Decida entre modelos, ou entre tamanhos de vetor, com as suas consultas de treino e um teste pareado, e leia o intervalo além do valor-p. Encurte vetores apenas para um modelo treinado para isso, normalize após o encurtamento, e somente quando a memória ou o tempo de busca exigir.
O que dá errado em produção
Uma similaridade não é uma confiança. É tentador não mostrar nada quando a melhor similaridade é baixa. Mas as similaridades não estão em uma mesma escala entre consultas:
1"""Finds the test query with the lowest best similarity and the one with the highest 10th similarity, and counts the products above a 0.5 cutoff. The prose's point rests on the two similarity lines and the cutoff counts."""2import numpy as np34from lib.recorded import embeddings5from lib.semantic import SemanticSearch6from lib.store import load_queries, qrels78product_ids, product_vectors, query_ids, query_vectors = embeddings()9test = load_queries("test")10rows = np.isin(query_ids, test.index)11similarity = np.sort(query_vectors[rows] @ product_vectors.T, axis=1)[:, ::-1] # best first, per query12queries = test.loc[query_ids[rows], "query"].to_numpy()1314weakest = similarity[:, 0].argmin() # the query whose best match is least similar15strongest = similarity[:, 9].argmax() # the query whose 10th match is most similar16print("first query, lowest best similarity:", queries[weakest])17print(f"its best similarity: {similarity[weakest, 0]:.3f}")18judgments = qrels()[query_ids[rows][weakest]]19top = SemanticSearch().search(query_ids[rows][weakest], k=10).index20print("exact products in its top 10:", sum(judgments.get(product_id) == 2 for product_id in top))21print("second query, highest 10th similarity:", queries[strongest])22print(f"its 10th similarity: {similarity[strongest, 9]:.3f}")2324cutoff = 0.5 # an illustrative cutoff; nothing about the model sets it25print()26print(f"products above {cutoff} for the first query:", (similarity[weakest] > cutoff).sum())27print(f"products above {cutoff} for the second query:", (similarity[strongest] > cutoff).sum())28print(f"test queries with no product above {cutoff}:", (similarity[:, 0] <= cutoff).sum())
python similarity-scale.pyfirst query, lowest best similarity: liberty hardware francisco
its best similarity: 0.436
exact products in its top 10: 5
second query, highest 10th similarity: kohler whitehaven farmhouse kitchen sink
its 10th similarity: 0.647
products above 0.5 for the first query: 0
products above 0.5 for the second query: 103
test queries with no product above 0.5: 2
Os dois extremos entre as consultas de teste mostram isso. liberty hardware francisco tem a melhor correspondência mais fraca, com 0.436, mas seu top 10 contém 5 produtos exatos, enquanto kohler whitehaven farmhouse kitchen sink tem a décima correspondência mais similar de todas, com 0.647.
Um corte em 0.5 manteria 0 produtos para a primeira consulta e 103 para a segunda, e nenhum para 2 consultas de teste. Além disso, a recuperação semântica nunca devolve resultado vazio: um código que nenhum produto tem ainda recebe um top 10 completo. Decida que uma consulta não tem correspondência de outra forma, por exemplo quando a recuperação lexical não encontra nenhum de seus termos raros.
Vetores incompatíveis falham silenciosamente. Os vetores da consulta e dos produtos devem vir do mesmo modelo, da mesma revisão e dos mesmos prompts. Vetores de dois modelos são números em espaços diferentes, e, quando os dois têm a mesma dimensão, compará-los não gera erro. O encode_query do Sentence Transformers acrescenta o prompt de consulta predefinido do modelo, quando ele existe (referência da API). Verifique se o código que gera os vetores das consultas em tempo real faz o mesmo que o código de indexação.
Um índice não acompanha o catálogo sozinho. Segundo a wiki do faiss, o HNSW do faiss não oferece suporte à remoção de vetores; por isso, um produto descontinuado permanece no grafo até que você o filtre dos resultados ou reconstrua o índice. Douze et al. (2024) afirmam que o faiss não é um banco de dados: ele não tem escritas concorrentes, fragmentação (sharding) nem transações. O recall em relação à busca exata pertence a um catálogo e a um conjunto de configurações; por isso, meça-o novamente após cada reconstrução.
Textos longos são cortados. O modelo lê no máximo 512 tokens, e a referência da API do Sentence Transformers informa que entradas mais longas são truncadas. O produto mais longo da loja tem 201 tokens, mas, em um catálogo com descrições longas, o modelo nunca lê o que passa do limite. Conte os tokens antes de gerar os vetores, como faz recordings/embeddings.py.
Erros de digitação deslocam os vetores. Zhuang e Zuccon (2021) constataram que, em recuperadores baseados em BERT que não foram treinados com erros de ortografia, erros de digitação podem causar uma queda significativa na eficácia da recuperação e do ranqueamento. 4 das consultas da loja contêm erro de digitação, e cada uma tem uma sonda com a grafia correta. Uma sonda corrigida pede o mesmo que sua consulta, de modo que os julgamentos dessa consulta podem avaliá-la:
1"""Scores each correctly spelled probe with the judgments of the query it corrects, for semantic retrieval and BM25, as typed and as corrected. The prose's point rests on the semantic nDCG@10 lines for each spelling and on the smallest-p line."""2from lib.lexical import LexicalSearch3from lib.metrics import ndcg_at_k4from lib.recorded import probes5from lib.semantic import SemanticSearch6from lib.store import load_products, load_queries, qrels78# Each spelling probe is the correctly spelled text of one store query (of_query_id), embedded by the same9# model. It asks for the same thing, so it is scored with that query's judgments. A diagnosis, not a test.10probe_queries, probe_vectors = probes()11products, queries, judgments = load_products(), load_queries(), qrels()12semantic, bm25 = SemanticSearch(), LexicalSearch(products)1314spelling = probe_queries[probe_queries["kind"] == "spelling"]15for row, probe in spelling.iterrows():16 query_id, pair = int(probe["of_query_id"]), probe["pair"]17 typed, corrected = semantic.search(query_id, k=10).index, semantic.search_vector(probe_vectors[row], k=10).index18 print(f"{pair}: {queries.at[query_id, 'query']} | {probe['query']} ({queries.at[query_id, 'split']} query)")19 print(f"{pair}, similarity of the two spellings: {semantic.query_vectors[query_id] @ probe_vectors[row]:.3f}")20 print(f"{pair}, products in both semantic top 10s:", len(set(typed) & set(corrected)))21 print(f"{pair}, semantic ndcg@10 as typed: {ndcg_at_k(list(typed), judgments[query_id], 10):.3f}")22 print(f"{pair}, semantic ndcg@10 corrected: {ndcg_at_k(list(corrected), judgments[query_id], 10):.3f}")23 for name, text in [("as typed", queries.at[query_id, "query"]), ("corrected", probe["query"])]:24 print(f"{pair}, bm25 ndcg@10 {name}: {ndcg_at_k(list(bm25.search(text, k=10).index), judgments[query_id], 10):.3f}")25 print()26print("spelling probes:", len(spelling))27# a sign-flip test on n queries has 2 ** n outcomes, and its two most extreme give the smallest two-sided p28print(f"smallest two-sided permutation p-value possible with {len(spelling)} queries: {2 / 2 ** len(spelling):.3f}")
python spelling-probes.pyligth: ligth bulb | light bulb (train query)
ligth, similarity of the two spellings: 0.710
ligth, products in both semantic top 10s: 5
ligth, semantic ndcg@10 as typed: 1.000
ligth, semantic ndcg@10 corrected: 1.000
ligth, bm25 ndcg@10 as typed: 0.945
ligth, bm25 ndcg@10 corrected: 0.945
foutains: foutains with brick look | fountains with brick look (train query)
foutains, similarity of the two spellings: 0.668
foutains, products in both semantic top 10s: 0
foutains, semantic ndcg@10 as typed: 0.353
foutains, semantic ndcg@10 corrected: 0.645
foutains, bm25 ndcg@10 as typed: 0.356
foutains, bm25 ndcg@10 corrected: 0.507
desins: twin over full bunk beds cool desins | twin over full bunk beds cool designs (train query)
desins, similarity of the two spellings: 0.829
desins, products in both semantic top 10s: 6
desins, semantic ndcg@10 as typed: 0.565
desins, semantic ndcg@10 corrected: 0.616
desins, bm25 ndcg@10 as typed: 0.488
desins, bm25 ndcg@10 corrected: 0.488
ice-an: refrigerator with ice an water in door | refrigerator with ice and water in door (test query)
ice-an, similarity of the two spellings: 0.975
ice-an, products in both semantic top 10s: 9
ice-an, semantic ndcg@10 as typed: 0.807
ice-an, semantic ndcg@10 corrected: 0.829
ice-an, bm25 ndcg@10 as typed: 0.501
ice-an, bm25 ndcg@10 corrected: 0.501
spelling probes: 4
smallest two-sided permutation p-value possible with 4 queries: 0.125
Um único erro de digitação pode mudar todo o top 10 semântico de uma consulta. Para a consulta de treino foutains with brick look, as grafias digitada e corrigida compartilham 0 produtos, e o nDCG@10 vai de 0.353 para 0.645; o BM25 também se desloca, de 0.356 para 0.507.
Nas demais sondas, as pontuações variam menos: a única consulta de teste entre elas, refrigerator with ice an water in door, passa de 0.807 para 0.829. Nada disso estabelece um padrão: com 4 sondas, o menor valor-p bilateral de permutação possível é 0.125.
Regra prática: Não filtre por uma similaridade fixa. Registre o modelo, a revisão e os prompts junto de cada vetor, e verifique-os onde as consultas são convertidas em vetores. Reconstrua e meça novamente o índice à medida que o catálogo muda, conte os tokens antes de gerar os vetores e corrija a ortografia antes de gerar o vetor de uma consulta quando seu registro mostrar erros de digitação, usando um corretor que verifica os vizinhos de cada palavra (capítulo 8).
Decisões tomadas neste capítulo
Sempre que as consultas de treino permitiam medir uma escolha, a escolha foi medida.
- Modelo:
Snowflake/snowflake-arctic-embed-m-v1.5, querecordings/embeddings.pyregistra uma vez em uma revisão fixada. É aberto, sob Apache-2.0, pequeno e treinado para vetores mais curtos. As consultas recebem o prefixo que o card do modelo pede; os produtos não. - Similaridade: o produto escalar de vetores de comprimento unitário, que é a similaridade de cosseno. Os vetores são normalizados uma vez, e de novo após qualquer alteração.
- Busca: exata, com NumPy, por meio de
lib.vectors.exact_search, porque os vetores do armazenamento ocupam 36.9 MB. Ela também é a referência de verdade para qualquer índice. - Se o catálogo ultrapassar a busca exata: faiss HNSW com
M = 32e umefSearchde 144, a menor configuração da varredura de treino em que cada consulta mantém pelo menos 9 de seus 10 primeiros verdadeiros. Nas consultas de teste, o recall@10 em relação à busca exata é 1.000. - O recall de um índice é medido em relação à busca exata, nas consultas de treino, no k que o pipeline usa, observando também as piores consultas, além da média.
- Dimensões: todas as 768 dimensões. Reduzir para 256 cortaria cada produto de 3,072 para 1,024 bytes, a um custo que as consultas de treino não conseguem precisar, e o armazenamento tem pouco a economizar.
- Consultas de sondagem testam o que os julgamentos não cobrem, como negação, códigos e grafia. Elas são comparadas por seus 10 primeiros resultados, à parte das consultas julgadas; somente uma grafia corrigida, que pede a mesma coisa, é avaliada com os julgamentos de sua consulta.
- Pontos fracos conhecidos vão para outras etapas: os códigos vão para a recuperação lexical, e os tamanhos exatos vão para campos de atributo, ou para a recuperação lexical quando o tokenizador mantiver os dígitos (capítulo 5, capítulo 8). Para ambos, um filtro a testar em vez de uma mistura (capítulo 7). A negação vai para filtros de atributo e reranqueamento.
- O que o capítulo mostrou: um índice vale somente o recall medido em relação à busca exata, no catálogo e nas configurações que você publica. As sondagens constataram que os embeddings lidam com a maioria dos tamanhos, mas não dos códigos nem das negações nos pares de tapete e mesa de centro, e alguns pares não provam nada.
Este capítulo, nesta edição
Edição 2026.11.10Exemplos aprovados em 19 de nov de 202616 de 16 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.10.