Recuperación semántica

Unos 36 minutos de lectura, con 16 ejemplos en 13 secciones.

Edición 2026.11.10 Ejemplos verificados el 19 de nov de 2026 132 de 132 ejemplos pasan Qué ha cambiado

Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros

Traducido del libro en inglés, edición 2026.11.10. Lee el original

Al final de este capítulo podrás construir una recuperación semántica para un catálogo a partir de embeddings almacenados: comparar vectores por similitud coseno, encontrar exactamente los productos más cercanos a una consulta con NumPy, cambiar a un índice aproximado cuando un catálogo crece demasiado para la búsqueda exacta y medir lo que el índice se pierde, y encontrar las consultas en las que los embeddings fallan. También podrás elegir un tamaño de vector probándolo con tus propios juicios, y comparar modelos de la misma manera.

Para 48 inch kitchen hood, la recuperación semántica devuelve campanas de otros anchos, y para rug that is not round, alfombras redondas. Sin embargo, en las consultas de prueba obtuvo un nDCG@10 medio de 0.830. Su ventaja sobre BM25, que obtuvo 0.725, es una que el capítulo 3 establece. El libro la ha usado como una sola clase, lib.semantic.SemanticSearch. El capítulo 1 la construyó para la tienda, cuyo catálogo va de sofás a cortinas de ducha, sobre vectores que un modelo calculó una vez, de antemano. Antes de que la tienda dependa de ella, necesitas saber qué contienen esos vectores, cuánto costaría buscar en ellos para un catálogo mucho mayor y en qué consultas se equivocan. Este capítulo construye a mano la búsqueda exacta, mide un índice aproximado frente a ella y prueba ambos con las consultas y los juicios de la tienda.

Sobre las consultas de prueba, el capítulo planea 2 comparaciones, ambas en la sección sobre la prueba del índice. Cada una enfrenta la búsqueda exacta, que compara una consulta con cada producto, con HNSW, un índice aproximado que la compara solo con una fracción de ellos: una vez con la configuración predeterminada de faiss y otra vez con la configuración elegida con las consultas de entrenamiento. Cada una se somete a la regla del libro, aquí un valor p por debajo de 0.025. Toda otra mirada a una consulta de prueba en este capítulo es exploratoria.

Convertir texto en embeddings

Último cambio en la edición 2026.11.10

Un embedding coloca los textos con significados parecidos cerca unos de otros; esta sección abre ese tema explicando cómo. El modelo que calcula un embedding es un codificador, entrenado para que los textos con significados parecidos reciban vectores que apunten en direcciones parecidas, tengan o no palabras en común. Cada texto recibe la misma cantidad de números, la dimensión del embedding, ya sea una consulta de tres palabras o la descripción completa de un producto. Un número por sí solo no significa nada; solo las comparaciones entre vectores completos tienen sentido.

La búsqueda usa el codificador como bi-codificador: codifica cada producto por separado, una sola vez y de antemano, y cada consulta por separado en el momento en que el cliente la escribe. Comparar una consulta con un producto es entonces una operación aritmética entre dos vectores, en lugar de una nueva ejecución del modelo, lo que la hace lo bastante barata como para comparar una consulta con un catálogo entero. El capítulo 1 muestra la magnitud de la diferencia a partir del artículo de Sentence-BERT: unas 65 horas para que BERT lea todos los pares de 10,000 oraciones, frente a unos 5 segundos para calcular el embedding de cada oración una vez y compararlas. Un modelo que lee una consulta y un producto juntos es un codificador cruzado, y el capítulo 1 lo usa para reordenar una lista corta de candidatos.

El codificador de la tienda es Snowflake/snowflake-arctic-embed-m-v1.5, un modelo abierto con 109 millones de parámetros bajo la licencia Apache-2.0 (ficha del modelo). Merrick et al. (2024) señalan que el entrenamiento de su familia solo conservó documentos identificados como mayoritariamente en inglés. Lo elegimos porque cualquiera puede usarlo comercialmente, es pequeño y fue entrenado de forma que sus vectores pueden acortarse, algo que la sección sobre dimensiones pone a prueba. Los ejemplos leen en su lugar una grabación: vectores que el script recordings/embeddings.py calculó una vez, en una revisión fijada, y guardó con longitud unitaria, de modo que todos los ejemplos ven los mismos números. La ficha del modelo pide un prefijo solo en las consultas, así que el script lo añade a cada consulta y calcula los embeddings de los productos tal como están. Los ejemplos leen los vectores mediante lib.recorded.embeddings():

inspect-recorded-embeddings.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 Superado
"""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."""import reimport numpy as npfrom lib.recorded import RECORDED, embeddings, manifestfrom lib.store import load_queries# unit-length rows, one per ID; the queries carry the model's query prefixproduct_ids, product_vectors, query_ids, query_vectors = embeddings()recording = manifest("embeddings")print("embedding model:", recording["model"])print("query prompt:", recording["prompts"]["query"])print(f"products embedded: {len(product_ids):,}")print("dimensions:", product_vectors.shape[1])print("stored as:", recording["dtype"])print("longest product text, tokens:", recording["longest_product_tokens"])print("model's input limit, tokens:", recording["max_seq_length"])# row 0 is product 1; [0, :4] takes its first four numbersprint(f"product {product_ids[0]}, first four numbers:", ", ".join(f"{x:.3f}" for x in product_vectors[0, :4]))stored = np.load(RECORDED / "embeddings" / "products.npy").astype(np.float32)   # as saved, before lib.recordedstored_lengths, lengths = np.linalg.norm(stored, axis=1), np.linalg.norm(product_vectors, axis=1)print(f"stored vector lengths: {stored_lengths.min():.5f} to {stored_lengths.max():.5f}")print(f"lengths after lib.recorded rescales: {lengths.min():.5f} to {lengths.max():.5f}")# How close are two shopper queries? Compare every query with every other one.queries = load_queries().loc[query_ids, "query"].tolist()similarity = query_vectors @ query_vectors.T  # unit length, so the dot product is the cosinenp.fill_diagonal(similarity, np.nan)               # leave out each query's similarity to itselfprint(f"median similarity of two queries: {np.nanmedian(similarity):.3f}")for query in ["whimsical solar lights", "wall design shelf"]:    row = queries.index(query)    nearest = int(np.nanargmax(similarity[row]))    # whole words as typed, with no stemming, so `lights` and `light` differ    shared = set(re.findall(r"\w+", query)) & set(re.findall(r"\w+", queries[nearest]))    print()    print(f"{query}, nearest other query:", queries[nearest])    print(f"{query}, similarity: {similarity[row, nearest]:.3f}")    print(f"{query}, words in common:", len(shared))
Salidapython inspect-recorded-embeddings.py
embedding 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 uno de los 12,000 productos es un vector de 768 números; el del producto 1 empieza por -0.033, 0.051, 0.111, -0.012, y ninguno de esos números significa nada por sí solo. La grabación guarda cada número como un float16, en 2 bytes, y lib.recorded los amplía a números en coma flotante de 32 bits al cargarlos. Ese redondeo desplaza ligeramente las longitudes guardadas respecto de 1: van desde 0.99994 to 1.00006. Por eso lib.recorded también reescala cada vector a longitud 1, y las longitudes que devuelve van desde 1.00000 to 1.00000. El codificador de la tienda lee el texto como tokens, fragmentos de palabras de su propio vocabulario, no como los términos del tokenizador del capítulo 5. El texto de producto más largo tiene 201 tokens, dentro del límite del modelo de 512 tokens, así que el modelo leyó cada producto completo.

La similitud mediana entre dos consultas de la tienda es 0.291, en una escala donde 1 significa que dos vectores apuntan en la misma dirección (similitud coseno). Sin embargo, whimsical solar lights encuentra outdoor light fixtures con 0.637, y wall design shelf encuentra kitchen storage shelves con 0.679, con 0 y 0 palabras en común: lights y light son cadenas distintas, y también lo son shelves y shelf. La referencia BM25 no reduce las palabras a su raíz, así que no ve nada compartido en ninguno de los dos pares. La reducción a raíces del capítulo 5 emparejaría lights con light, pero no shelves con shelf.

Regla práctica: Calcula de antemano los embeddings de los productos y, en el momento de la búsqueda, los de las consultas, con el mismo modelo en la misma revisión, y sigue la ficha del modelo en cuanto a los prompts: aquí, un prefijo solo en las consultas. Registra el modelo, la revisión y los prompts junto a los vectores, como hace cada manifest.json en examples/data/recorded/. Comprueba que tu producto más largo cabe dentro del límite de entrada del modelo antes de confiar en su embedding.

Compara embeddings con similitud del coseno

Último cambio en la edición 2026.11.10

Para ordenar productos según una consulta, necesitas un número por cada par que indique cuán parecidos son dos vectores. La similitud del coseno es el coseno del ángulo entre dos vectores: 1 cuando apuntan en la misma dirección, 0 en ángulo recto y −1 cuando apuntan en direcciones opuestas. Ignora qué tan largos son los vectores. El producto punto multiplica dos vectores número por número y suma los resultados, de modo que equivale al coseno multiplicado por ambas longitudes. Escalar cada vector a longitud 1, lo que se llama normalizar, hace que los dos valores sean el mismo número, como indica Sentence Transformers. Entonces el producto punto es la opción más económica, porque se ahorra calcular las longitudes.

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 la fórmula en acción, toma la consulta de prueba clear shower curtain y su producto más parecido: calcula el producto punto y el coseno a mano, y verifica el coseno con scikit-learn 1.9.1. Luego rompe el único supuesto que hace que coincidan. Conserva los primeros 256 de los 768 números de cada vector, un atajo que la sección sobre dimensiones pone a prueba, pero omite el reescalado, y ordena los productos de cada consulta de ambas formas:

cosine-by-hand.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 · scikit-learn 1.9.1 · scipy 1.18.1 Superado
"""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."""import numpy as npfrom sklearn.metrics.pairwise import cosine_similarityfrom lib.recorded import embeddingsfrom lib.store import load_productsproducts = load_products()product_ids, product_vectors, query_ids, query_vectors = embeddings()query = query_vectors[list(query_ids).index(246)]           # clear shower curtainbest = int(np.argmax(product_vectors @ query))product = product_vectors[best]print("product:", products.at[product_ids[best], "name"])# cosine = dot product / (length of q * length of d)dot = query @ productcosine = dot / (np.linalg.norm(query) * np.linalg.norm(product))print(f"dot product: {dot:.3f}")print(f"cosine by hand: {cosine:.3f}")print(f"cosine from scikit-learn: {cosine_similarity([query], [product])[0, 0]:.3f}")# Keep the first 256 numbers of each vector and don't rescale: the lengths are no longer 1.short_products, short_queries = product_vectors[:, :256], query_vectors[:, :256]lengths = np.linalg.norm(short_products, axis=1)print(f"shortened product lengths: {lengths.min():.3f} to {lengths.max():.3f}")# stable sort: tied scores keep their stored orderby_dot = np.argsort(-(short_queries @ short_products.T), axis=1, kind="stable")[:, :10]# only the products are rescaled: a query's length scales all its scores alike, so it can't change their orderby_cosine = np.argsort(-(short_queries @ (short_products / lengths[:, None]).T), axis=1, kind="stable")[:, :10]# compares the sets: a new order within the same 10 doesn't countchanged = sum(set(dot_top) != set(cosine_top) for dot_top, cosine_top in zip(by_dot, by_cosine))print("queries:", len(query_ids))print("queries whose top 10 changes:", changed)
Salidapython cosine-by-hand.py
product: 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

Con los vectores de longitud unitaria de la tienda, el producto punto es 0.577, el coseno a mano es 0.577, y el cosine_similarity de scikit-learn da 0.577, así que los tres coinciden.

Acortar los vectores rompe esa coincidencia. Los vectores acortados tienen longitudes de 0.706 to 0.778, y para 61 de las 80 consultas, ordenar por producto punto da un top 10 distinto que ordenar por coseno. La longitud propia de una consulta escala todas sus puntuaciones por el mismo factor, así que no puede cambiar su orden. La longitud de un producto sí puede: multiplica la puntuación de ese producto para cada consulta, un impulso que el comprador nunca pidió.

Algunas bibliotecas informan una distancia en lugar de una similitud. Los índices L2 de faiss devuelven la distancia euclidiana al cuadrado, y su producto interno equivale a la similitud del coseno solo cuando los vectores están normalizados, según la wiki de faiss. Para vectores unitarios, la distancia al cuadrado es 2 − 2 × coseno, así que ordena los productos en el mismo orden que el coseno, de menor a mayor distancia.

Regla práctica: Normaliza cada vector una vez, al guardarlo, y ordena por producto punto. Vuelve a normalizar después de cualquier cambio en un vector, como acortarlo o promediar varios. Si la documentación de un modelo indica que fue entrenado para el producto punto de vectores sin normalizar, sigue la documentación en su lugar, y nunca mezcles ambos enfoques en un mismo índice.

Encuentra los vecinos más cercanos exactos con NumPy

Último cambio en la edición 2026.11.9

La recuperación por embeddings es una búsqueda de vecinos más cercanos: encontrar los k productos cuyos vectores son más parecidos al de la consulta. La búsqueda exacta compara la consulta con cada producto y conserva los k mejores, así que nunca se le escapa ninguno. Con vectores de longitud unitaria, comparar una consulta con cada producto es un único producto matriz–vector, y comparar muchas consultas es un único producto matricial, con una fila por consulta y una columna por producto. Lo que queda es encontrar las k puntuaciones más altas en cada fila. Ordenar cada fila hace más trabajo del necesario. argpartition de NumPy mueve las k puntuaciones más altas a un lado sin ordenar ninguno de los dos lados, y la documentación de NumPy deja ese orden indefinido, así que tú solo ordenas esas k.

La búsqueda semántica del capítulo 1 tomó sus rankings de lib.semantic.SemanticSearch. Construye su núcleo a mano para las 30 consultas de prueba con NumPy 2.5.5, y luego compruébalo dos veces: contra lib.semantic, y contra IndexFlatIP de faiss, que calcula el producto interno con cada vector. Las pautas de faiss mencionan dos índices que garantizan resultados exactos, IndexFlatIP y IndexFlatL2:

exact-search-numpy.py Python 3.12.15 · faiss-cpu 1.16.0 · numpy 2.5.5 · pandas 3.1.1 Superado
"""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."""import faissimport numpy as npfrom lib.metrics import evaluatefrom lib.recorded import embeddingsfrom lib.semantic import SemanticSearchfrom lib.store import load_queries, qrelsproduct_ids, product_vectors, query_ids, query_vectors = embeddings()test = load_queries("test").indexrows = np.isin(query_ids, test)def top_k(scores, k):    """Column indices of the k highest scores in each row, best first."""    # argpartition's kth is 0-based: with k - 1, the first k positions hold the k highest scores, in no order    candidates = np.argpartition(-scores, k - 1, axis=1)[:, :k]          # the top k, in no order    # stable sort: tied scores keep their candidate order    order = np.argsort(-np.take_along_axis(scores, candidates, axis=1), axis=1, kind="stable")    return np.take_along_axis(candidates, order, axis=1)scores = query_vectors[rows] @ product_vectors.T      # one row per test query, one column per producttop = top_k(scores, 10)print("similarities computed:", f"{scores.size:,}")print("similarities per query:", f"{scores.shape[1]:,}")semantic = SemanticSearch()# two lists match only if the same products come in the same ordersame = sum(list(product_ids[found]) == list(semantic.search(query_id, 10).index)           for query_id, found in zip(query_ids[rows], top))print("same top 10 as lib.semantic:", same, "of", rows.sum())flat = faiss.IndexFlatIP(product_vectors.shape[1])     # faiss's exact index: inner product with every productflat.add(product_vectors)_, found = flat.search(query_vectors[rows], 10)# the same products in the same order, row by rowprint("same top 10 as faiss IndexFlatIP:", (found == top).all(axis=1).sum(), "of", rows.sum())run = {query_id: list(product_ids[row]) for query_id, row in zip(query_ids[rows], top)}print(f"ndcg@10 of the exact run: {evaluate(run, qrels('test'))['ndcg@10'].mean():.3f}")
Salidapython exact-search-numpy.py
similarities 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

La búsqueda construida a mano concuerda con ambas comprobaciones: devuelve los mismos 10 primeros que lib.semantic para 30 of 30 consultas de prueba, y los de faiss para 30 of 30, así que su ejecución obtiene la misma nDCG@10 media, 0.830. Un solo producto matricial calculó todas las similitudes: 360,000 de ellas, 12,000 por consulta. El módulo compartido del libro, lib.vectors, mantiene este top_k para los ejemplos posteriores y lo envuelve en exact_search.

Si la búsqueda exacta basta depende de su coste. Su trabajo crece en proporción al catálogo: una similitud por producto, para cada consulta. Su memoria son los propios vectores:

exact-search-memory.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 Superado
"""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."""from lib.recorded import embeddings# Exact search keeps every product vector in memory, as 32-bit floats.product_ids, product_vectors, _, _ = embeddings()print(f"products: {len(product_ids):,}")print(f"float32 bytes per product: {product_vectors[0].nbytes:,}")# decimal MB and GB: a megabyte is a million bytes, a gigabyte a billionprint(f"product vectors in memory, MB: {product_vectors.nbytes / 1e6:.1f}")print(f"the same for 1,000,000 products, GB: {1_000_000 * product_vectors[0].nbytes / 1e9:.1f}")
Salidapython exact-search-memory.py
products: 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 producto ocupa 3,072 bytes como números de coma flotante de 32 bits, así que el catálogo de la tienda ocupa 36.9 MB, y un millón de productos ocuparía 3.1 GB. Douze et al. (2024) aconsejan decidir primero si hace falta un índice, porque en algunos casos la búsqueda por fuerza bruta es la mejor opción. Consideramos que el catálogo de la tienda es uno de esos casos.

Regla práctica: Recomendamos la búsqueda exacta hasta que deje de caber en memoria o de cumplir tu presupuesto de latencia, medido con tu propio catálogo y tu propio hardware. No tiene parámetros que ajustar y nunca pierde un vecino, por lo que también es la referencia de verdad para cualquier índice aproximado. Guarda los vectores normalizados como una única matriz de 32 bits, toma los k primeros con argpartition y ordena solo esos.

Intercambia recall por velocidad con HNSW

Último cambio en la edición 2026.11.10

Cuando la búsqueda exacta cuesta demasiado, un índice de vecino más cercano aproximado (ANN) omite la mayoría de sus comparaciones, y a cambio puede pasar por alto algunos de los vecinos más cercanos reales. La calidad de un índice ANN es su recall@k frente a la búsqueda exacta: la proporción de los k primeros de la búsqueda exacta que también devuelve. Eso no es el recall@k del capítulo 3, que compara un ranking con juicios. Un índice con recall perfecto frente a la búsqueda exacta devuelve lo que devuelve la búsqueda exacta, sea bueno o malo.

HNSW, abreviatura de hierarchical navigable small world, es un índice de grafo. Cada producto es un nodo enlazado con algunos de sus vecinos más cercanos, en una pila de capas: la capa inferior contiene todos los productos, y cada capa superior contiene menos. Una búsqueda empieza arriba, se desplaza al nodo enlazado más cercano a la consulta, baja una capa cuando ya no se acerca, y en la capa inferior explora una lista de candidatos antes de devolver los k mejores (Malkov and Yashunin, 2018). En faiss, M fija los enlaces por nodo. Más enlaces encuentran más vecinos reales, pero usan más memoria (faiss wiki). efConstruction, el factor de expansión en el momento de la construcción, fija cuántos candidatos considera la construcción, y efSearch, el factor de expansión en el momento de la búsqueda, cuántos considera una búsqueda. Con faiss 1.16.0, sus valores por defecto son 40 y 16, y su construcción del grafo es determinista, porque la única construcción que add() usa es una determinista (HNSW.h; changelog). Por eso los resultados aquí se repiten exactamente. Los tiempos difieren de una máquina a otra, así que los ejemplos cuentan el trabajo: faiss cuenta las distancias que calcula en cada búsqueda (HNSW.h), que para este índice son similitudes. El conteo deja fuera seguir enlaces y leer memoria, así que es una guía de velocidad, no una medida.

La tienda no necesita un índice, pero una tienda con millones de productos sí lo necesitaría, y un catálogo lo bastante pequeño como para comprobar cada respuesta es el lugar para aprender la compensación. Construye HNSW sobre los 12,000 productos de la tienda con hnsw_index(product_vectors, links=32), que es el nombre que lib.vectors da a M = 32. Después recorre efSearch de 16 a 256 sobre las consultas de entrenamiento:

hnsw-efsearch-sweep.py Python 3.12.15 · faiss-cpu 1.16.0 · numpy 2.5.5 · pandas 3.1.1 Superado
"""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."""import faissimport numpy as npfrom lib.recorded import embeddingsfrom lib.store import load_products, load_queries# EF_SEARCH_GRID runs 16 to 256 in steps of 16; WORST_RECALL is 0.9: at least 9 of the true top 10from lib.vectors import EF_SEARCH_GRID, WORST_RECALL, exact_search, hnsw_index, hnsw_search, recall_against_exactproduct_ids, product_vectors, query_ids, query_vectors = embeddings()names = load_products().loc[product_ids, "name"].str[:36].to_numpy()   # by row number, cut to 36 charactersrows = np.isin(query_ids, load_queries("train").index)                 # tune on train queries onlyqueries = load_queries().loc[query_ids[rows], "query"].to_numpy()index = hnsw_index(product_vectors, links=32)          # M = 32, and faiss's default efConstruction of 40levels = faiss.vector_to_array(index.hnsw.levels)      # how many layers each product reachesfor layer in range(1, levels.max() + 1):    print(f"products in layer {layer}: {(levels >= layer).sum():,}")exact = exact_search(query_vectors[rows], product_vectors, 10)print("\nefSearch  mean recall@10  worst  queries at 0  similarities per query")sweep = {}for ef_search in EF_SEARCH_GRID:    # similarities is faiss's count of the distances each search computed, per query, not a score    found, similarities = hnsw_search(index, query_vectors[rows], 10, ef_search)    # share of exact search's top 10 that the approximate search also found, order ignored    recall = recall_against_exact(found, exact)    sweep[ef_search] = (recall, similarities)    print(f"{ef_search:>8}  {recall.mean():>14.3f}  {recall.min():>5.1f}  {(recall == 0).sum():>12}  {similarities:>22.0f}")recall, similarities = sweep[16]                       # faiss's defaultprint(f"\nefSearch 16, recall@10 against exact: {recall.mean():.3f}")print(f"efSearch 16, similarities computed per query: {similarities:.0f}")print(f"efSearch 16, train queries with recall@10 of 0: {(recall == 0).sum()}")print("efSearch 16, those queries:", ", ".join(queries[recall == 0]))print("smallest efSearch with no query at 0:", min(ef for ef, (r, _) in sweep.items() if r.min() > 0))chosen = min(ef for ef, (r, _) in sweep.items() if r.min() >= WORST_RECALL)print(f"smallest efSearch with every query at {WORST_RECALL} or more:", chosen)print(f"chosen efSearch, recall@10 against exact: {sweep[chosen][0].mean():.3f}")print(f"chosen efSearch, similarities computed per query: {sweep[chosen][1]:.0f}\n")# the top 3 at the default efSearch, for the query that failsfound, _ = hnsw_search(index, query_vectors[rows], 3, 16)row = list(queries).index("foutains with brick look")for rank, (approximate, nearest) in enumerate(zip(found[row], exact[row]), start=1):    print(f"{rank}  hnsw: {names[approximate]:<36}  exact: {names[nearest]}")
Salidapython hnsw-efsearch-sweep.py
products 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

El grafo se adelgaza rápido: la capa inferior contiene los 12,000 productos, la siguiente 369 y la superior 10.

La media oculta un fallo. Con el efSearch por defecto de 16, una consulta calcula 282 similitudes en lugar de 12,000, y el recall@10 medio frente a la búsqueda exacta es 0.934. Sin embargo, 2 consultas de entrenamiento no obtienen ninguno de sus 10 primeros verdaderos.

Esas consultas son foutains with brick look, sheffield home bath set. Mira foutains with brick look, una de ellas: HNSW devuelve un cojín, un juego de decoración de pared y una rama de hiedra, mientras que los 3 primeros de la búsqueda exacta son azulejos con aspecto de ladrillo.

El efSearch más pequeño del barrido en el que ninguna consulta de entrenamiento está en 0 es 96, pero la tabla del barrido muestra que su peor consulta todavía falla la mayor parte de sus 10 primeros verdaderos. Así que elige con una regla más estricta: el efSearch más pequeño en el que cada consulta de entrenamiento encuentra al menos 9 de sus 10 primeros verdaderos. Ese es 144, con un recall medio de 0.998 y 835 similitudes por consulta.

Regla práctica: Usa un índice ANN solo cuando la búsqueda exacta sea demasiado lenta o demasiado grande. Ajústalo con consultas de entrenamiento según su recall frente a la búsqueda exacta, con el k que use tu proceso, y elige según la peor consulta, no la media. Recomendamos el efSearch más pequeño en el que cada consulta conserve al menos 9 de sus 10 primeros verdaderos, con M = 32. Este capítulo ajusta solo efSearch; M y efConstruction cambian el propio grafo, y merecen el mismo barrido en un catálogo grande. Aumüller et al. (2018) encuentran que métodos ANN muy distintos alcanzan compensaciones entre calidad y rendimiento comparables, así que mide con tus propios datos, no por reputación.

Comprueba el índice con las consultas de prueba

Último cambio en la edición 2026.11.8

Un índice ajustado con las consultas de entrenamiento todavía debe comprobarse con consultas que no ha visto, por su recall frente a la búsqueda exacta y por su efecto en las puntuaciones juzgadas. Estas son las 2 comparaciones planificadas del capítulo, cada una con una prueba de permutación pareada y una prueba t junto a ella: el índice HNSW con el valor por defecto de faiss para efSearch, que es 16, y con el valor elegido con las consultas de entrenamiento, frente a la búsqueda exacta. La búsqueda también pide k = 100, porque la recuperación híbrida fusiona los 100 primeros resultados de cada recuperador:

hnsw-test-recall.py Python 3.12.15 · faiss-cpu 1.16.0 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Superado
"""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."""import numpy as npfrom lib.metrics import evaluatefrom lib.recorded import embeddingsfrom lib.significance import compare, verdictfrom lib.store import load_queries, qrelsfrom lib.vectors import as_run, choose_ef_search, exact_search, hnsw_index, hnsw_search, recall_against_exact# Planned before scoring: HNSW at faiss's default efSearch, and at the setting chosen on train, each against exact.PLANNED = 2threshold = 0.05 / PLANNED  # the book's rule splits 0.05 across the planned comparisonsproduct_ids, product_vectors, query_ids, query_vectors = embeddings()rows = np.isin(query_ids, load_queries("test").index)index = hnsw_index(product_vectors, links=32)# the smallest efSearch at which every train query keeps WORST_RECALL of its true top 10chosen = choose_ef_search(index, query_vectors[np.isin(query_ids, load_queries("train").index)], product_vectors)# k = 100 because hybrid retrieval fuses each retriever's top 100exact = exact_search(query_vectors[rows], product_vectors, 100)exact_ndcg = evaluate(as_run(exact, query_ids[rows], product_ids), qrels("test"))["ndcg@10"]print("planned test comparisons:", PLANNED)print(f"p-value threshold: {threshold:.3f}")print("efSearch chosen on train queries:", chosen)print(f"exact ndcg@10: {exact_ndcg.mean():.3f}")for name, ef_search in [("default", 16), ("chosen", chosen)]:    found, _ = hnsw_search(index, query_vectors[rows], 100, ef_search)    # the first 10 of the 100    recall = recall_against_exact(found[:, :10], exact[:, :10])    ndcg = evaluate(as_run(found, query_ids[rows], product_ids), qrels("test"))["ndcg@10"]    result = compare(ndcg, exact_ndcg, confidence=1 - threshold)  # a 97.5% interval, at the test's level    print(f"\n{name}, recall@10 against exact: {recall.mean():.3f}")    print(f"{name}, queries with recall@10 of 0: {(recall == 0).sum()}")    print(f"{name}, those queries:", ", ".join(load_queries().loc[query_ids[rows][recall == 0], "query"]) or "none")    print(f"{name}, recall@100 against exact: {recall_against_exact(found, exact).mean():.3f}")    print(f"{name}, hnsw ndcg@10: {ndcg.mean():.3f}")    # compare rounds each difference to 3 decimals: wins and losses are the nonzero ones    print(f"{name}, queries whose ndcg@10 changes: {result['wins'] + result['losses']}")    print(f"{name}, permutation p: {result['permutation p']:.3f}")    print(f"{name}, t-test p: {result['t-test p']:.3f}")    print(f"{name}, {1 - threshold:.1%} interval: {result['ci low']:.4f} to {result['ci high']:.4f}")    for check, passed in verdict(result, threshold).items():      # established, t-test agrees, interval agrees        print(f"{name}, {check}: {'yes' if passed else 'no'}")
Salidapython hnsw-test-recall.py
planned 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

El valor elegido con las consultas de entrenamiento se sostiene. Su recall@10 frente a la búsqueda exacta es 1.000, su nDCG@10 medio es 0.830, igual que el 0.830 de la búsqueda exacta, y 0 consultas cambian de puntuación.

Con el valor por defecto de faiss, 2 consultas de prueba no obtienen ninguno de sus 10 mejores verdaderos (liberty hardware francisco, 48" sliding single track , barn door for laundry), y el nDCG@10 medio baja a 0.791, pero solo 3 consultas cambian de puntuación, y la caída no queda establecida: la prueba de permutación da p = 0.256, y la prueba t coincide con p = 0.154. El intervalo del 97.5%, que va de -0.1544 to -0.0006, excluye el 0, así que discrepa de las pruebas. Con tan pocas consultas que explican la diferencia, el hallazgo es el recall perdido frente a la búsqueda exacta, no una pérdida de calidad medida.

Pedir más resultados no compensa un efSearch pequeño: con el valor por defecto, el recall@100 es 0.849, frente a 0.994 con el valor elegido.

El grafo también cuesta memoria, además de los vectores:

hnsw-index-memory.py Python 3.12.15 · faiss-cpu 1.16.0 · numpy 2.5.5 · pandas 3.1.1 Superado
"""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."""import faissfrom lib.recorded import embeddingsfrom lib.vectors import hnsw_indexproduct_ids, product_vectors, _, _ = embeddings()dimensions = product_vectors.shape[1]flat = faiss.IndexFlatIP(dimensions)                    # exact search: the vectors onlyflat.add(product_vectors)index = hnsw_index(product_vectors, links=32)           # the vectors, plus the graph's links# layer 0 is the bottom layer: 2 × M links there, and M on each upper layerprint("links per product, upper layers:", index.hnsw.nb_neighbors(1))print("links per product, bottom layer:", index.hnsw.nb_neighbors(0))# 8M with M = 32: 4 bytes for each of the 2M bottom-layer linksprint(f"faiss's estimate, 4d + 8M bytes per product: {4 * dimensions + 8 * 32:,}")# the saved index's size, spread over the productsfor name, built in [("exact index", flat), ("hnsw index", index)]:    print(f"bytes per product, {name}: {faiss.serialize_index(built).nbytes / len(product_ids):,.0f}")
Salidapython hnsw-index-memory.py
links 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 producto tiene 32 enlaces en las capas superiores y 64 en la capa inferior, que es el doble de M. faiss estima 4d + 8M bytes por vector (wiki de faiss): 4 bytes por cada uno de los d números, y 4 bytes por cada uno de los 2M enlaces de la capa inferior, 3,328 aquí. El índice guardado se acerca, con 3,344 bytes por producto, frente a 3,072 del índice exacto.

Regla práctica: Comprueba un índice ajustado con consultas reservadas (no usadas en el ajuste), midiendo su recall frente a la búsqueda exacta, y lee las consultas que pierden todo su top k antes que la puntuación media. Considera no demostrada una caída del nDCG@10 que descansa en un puñado de consultas hasta que una prueba pareada la establezca. Presupuesta la memoria de los enlaces además de la de los vectores.

Revisa las consultas que contienen dígitos

Último cambio en la edición 2026.11.10

Un índice solo puede devolver lo que los embeddings colocan cerca de una consulta, así que la siguiente pregunta es qué consultas los embeddings no interpretan bien. Un codificador comprime una consulta completa en un solo vector, de modo que un token breve que cambia el significado, como una medida, un número de modelo o una negación, puede mover ese vector muy poco. Deng et al. (2026) midieron esto para los números, en un estudio de 13 modelos de embeddings sobre texto financiero sintético. Su precisión para distinguir textos por un número fue de 0.54, apenas por encima del 0.5 de una adivinanza al azar, y los números de cuatro dígitos quedaron al nivel de la adivinanza. Los productos no son informes financieros, así que revisa las consultas de la tienda.

Pocas consultas de la tienda contienen un dígito, así que compara la recuperación BM25 y la semántica en cada una que lo tenga, de ambas particiones. Nada está ajustado con estas consultas, y unas pocas no pueden establecer nada:

digits-in-queries.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Superado
"""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."""import pandas as pdfrom lib.lexical import LexicalSearchfrom lib.metrics import evaluatefrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, product_text, qrelsproducts, queries = load_products(), load_queries()with_digit = queries[queries["query"].str.contains(r"\d")]       # both splits: a diagnosis, nothing is tunedjudgments = {query_id: grades for query_id, grades in qrels().items() if query_id in with_digit.index}# each ranker returns its top 100; nDCG@10 scores the first 10 of themscores = pd.DataFrame({    "split": with_digit["split"],    "bm25": evaluate(LexicalSearch(products).run(with_digit, k=100), judgments)["ndcg@10"],    "semantic": evaluate(SemanticSearch().run(with_digit, k=100), judgments)["ndcg@10"],    "query": with_digit["query"],}).round(3)print("queries with a digit:", len(scores))print(scores.to_string())print("semantic better:", (scores["semantic"] > scores["bm25"]).sum())print("bm25 better:", (scores["bm25"] > scores["semantic"]).sum())# a gap under 0.03 counts as a near tie: the book's choice, not a measured limitprint("gaps under 0.03:", ((scores["semantic"] - scores["bm25"]).abs() < 0.03).sum())text = product_text(products).str.lower()print("products whose text has the word 7qt:", text.str.contains(r"\b7qt\b").sum())# '7 qt', but not '17 qt' or '3.7 qt'print("products whose text has 7 qt:", text.str.contains(r"(?<![\d.])7 qt\b").sum())
Salidapython digits-in-queries.py
queries 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

Ningún ranqueador domina las 7 consultas con un dígito. La recuperación semántica puntúa más alto en 4 de ellas y BM25 en 3, y 2 de las diferencias están por debajo de 0.03. La derrota más clara de BM25 es 7qt slow cooker: la palabra 7qt aparece en 0 productos, y 8 escriben 7 qt.

En la consulta de prueba 48 inch kitchen hood, BM25 puntúa más alto, así que aquí están los 10 primeros de la recuperación semántica:

hood-query-digits.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Superado
"""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."""from lib.lexical import LexicalSearchfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrelsLABELS = {2: "exact", 1: "partial", 0: "irrelevant"}products = load_products()query_id = 482  # 48 inch kitchen hood, a test queryquery = load_queries().at[query_id, "query"]judgments = qrels()[query_id]# The width sits in the attributes column, which the embeddings never saw: product_text leaves it out.width = products["attributes"].str.extract(r"\bwidth: ([\d.]+)", expand=False).astype(float)semantic = SemanticSearch().search(query_id, k=10).indexbm25 = LexicalSearch(products).search(query, k=10).indexprint("query:", query)print("     judgment   width  name")for rank, product_id in enumerate(semantic, start=1):    label = LABELS.get(judgments.get(product_id), "unjudged")    print(f"{rank:>2}   {label:<10} {width[product_id]:>5g}  {products.at[product_id, 'name'][:50]}")print()# exact: a 48-inch hood is 48 wide, where probe-pair-overlap allows half an inch for hoods listed at 35.75for name, top in [("semantic", semantic), ("bm25", bm25)]:    print(f"{name}, width 48 in the top 10:", (width[top] == 48).sum())    print(f"{name}, exact in the top 10:", sum(judgments.get(product_id) == 2 for product_id in top))
Salidapython hood-query-digits.py
query: 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, el embedding coincidió con los dígitos como texto, no con el ancho que representan. De los 10 primeros de la recuperación semántica, 8 campanas tienen un ancho de 48. Las otras son una campana de 36 pulgadas de una serie llamada ws-48 y una campana de 30 pulgadas con una potencia de 480 cfm, pies cúbicos por minuto, el caudal de aire de su ventilador. Ambas contienen los dígitos 48, ninguna mide 48 de ancho, y los jueces marcaron ambas como parcial. Los 10 primeros de BM25 incluyen 10 campanas de ancho 48.

El ancho de cada campana proviene de la columna attributes, que contiene campos seleccionados de las características de productos de WANDS, como ancho, forma y material. product_text, el texto que el modelo incrustó, omite esa columna, así que los embeddings nunca la vieron, y una medida que escribe el comprador puede verificarse exactamente contra ella.

Una sola consulta no puede mostrar un patrón. Para ver cómo el modelo maneja las medidas en general, usa consultas de sondeo: pares de consultas escritas para el libro que solo difieren en una medida, un código o una negación, que recordings/probes.py incrusta con el mismo modelo. Una de ellas repite la consulta de prueba 48 inch kitchen hood palabra por palabra. Los sondeos no tienen juicios, así que el ejemplo cuenta sus 10 primeros resultados y nunca los puntúa. La medida correcta proviene del ancho en attributes para las campanas, y del nombre para el resto:

probe-pair-overlap.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 Superado
"""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."""from lib.recorded import probesfrom lib.semantic import SemanticSearchfrom lib.store import load_products# Probe queries written for the book, embedded by the same model. They have no judgments,# so this example counts what each top 10 holds; it doesn't score anything.probe_queries, probe_vectors = probes()products = load_products()names = products["name"]width = products["attributes"].str.extract(r"\bwidth: ([\d.]+)", expand=False).astype(float)semantic = SemanticSearch()def states(size, unit):    """Names that state this size, such as "7 qt" or "7-quart", but not "3.7 qt"."""    return names.str.contains(rf"(?<![\d.]){size}[ -]?(?:{unit})")RIGHT_SIZE = {                       # the size each probe asks for: the width attribute, or the name    # within half an inch of 36 or 48, so a 35.75-inch hood counts as 36    "36 inch kitchen hood": (width - 36).abs() <= 0.5, "48 inch kitchen hood": (width - 48).abs() <= 0.5,    "4 qt slow cooker": states(4, "qt|quart"), "7 qt slow cooker": states(7, "qt|quart"),    # the whole word, which also matches 'twin over full' bunk beds    "twin bed": names.str.contains(r"\btwin\b"), "king bed": names.str.contains(r"\bking\b"),    "2 seat sofa": names.str.contains(r"\bloveseat\b"),        # a two-seat sofa is a loveseat}DIGIT_ONLY = {"2 seat sofa": states(2, " in 1| piece"), "4 seat sofa": states(4, " in 1| piece")}for pair in ["hood", "cooker", "bed", "seats"]:    first, second = probe_queries.index[probe_queries["pair"] == pair]  # each pair is two probes, in file order    tops = {row: semantic.search_vector(probe_vectors[row], k=10).index for row in (first, second)}    print(f"{pair}, similarity of the two queries: {probe_vectors[first] @ probe_vectors[second]:.3f}")    print(f"{pair}, products in both top 10s:", len(set(tops[first]) & set(tops[second])))    for row, top in tops.items():        query = probe_queries.at[row, "query"]        if query in RIGHT_SIZE:            print(f"{query}, right size in the top 10:", RIGHT_SIZE[query][top].sum())        if query in DIGIT_ONLY:            print(f"{query}, same digit but a piece count or 2 in 1:", DIGIT_ONLY[query][top].sum())    print()# the two counts the sofa probes ask forprint("catalog names that give a seat count:", (states(2, "seat") | states(4, "seat")).sum())print("catalog products named loveseat:", names.str.contains(r"\bloveseat\b").sum())
Salidapython probe-pair-overlap.py
hood, 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

Para estos sondeos, el modelo en su mayoría encuentra la medida correcta. Los dos sondeos de campanas comparten 0 productos, pero cada uno de sus 10 primeros incluye campanas del ancho correcto, 8 para 36 pulgadas y 8 para 48; los sondeos de ollas de cocción lenta encuentran 6 y 7 de la capacidad correcta, y los sondeos de camas 10 y 10 de la medida correcta. Cuando el catálogo no tiene un número que coincida, el dígito toma el control. La cantidad de nombres de productos que indican un número de asientos es 0, así que los 10 primeros de 2 seat sofa incluyen 4 productos que comparten solo el dígito, juegos de dos piezas y sofás infantiles "2 en 1", y 0 de los 14 loveseats del catálogo.

Espera que un código pese poco

Último cambio en la edición 2026.11.8

Un código de producto debería coincidir exactamente con un solo producto. Para un codificador, es una cadena rara de letras y dígitos. Dos pares de las consultas de prueba ponen a prueba códigos: uno construido sobre un código que ningún producto tiene, tomado de la consulta de entrenamiento ines shag rug w003096809, y otro construido sobre una resolución de pantalla que contiene el texto de exactamente un producto:

code-probes.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Superado
"""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."""from lib.lexical import LexicalSearchfrom lib.recorded import probesfrom lib.semantic import SemanticSearchfrom lib.store import load_products, product_text# Probe queries written for the book, embedded by the same model; no judgments, so nothing is scored.probe_queries, probe_vectors = probes()products = load_products()text = product_text(products).str.lower()semantic, bm25 = SemanticSearch(), LexicalSearch(products)# A code no product holds: does changing it change the results?first, second = probe_queries.index[probe_queries["pair"] == "code"]tops = [set(semantic.search_vector(probe_vectors[row], k=10).index) for row in (first, second)]print("products whose text contains w003096809:", text.str.contains("w003096809").sum())print(f"code, similarity of the two queries: {probe_vectors[first] @ probe_vectors[second]:.3f}")print("code, products in both top 10s:", len(tops[0] & tops[1]))# A code one product holds: where does that product rank, with its code and with another?holder = text.index[text.str.contains("1920x1080p")]print()print("products whose text contains 1920x1080p:", len(holder))print("that product:", products.at[holder[0], "name"])print("products in the Projectors class:", (products["product_class"] == "Projectors").sum())for row in probe_queries.index[probe_queries["pair"] == "resolution"]:    query = probe_queries.at[row, "query"]    ranked = semantic.search_vector(probe_vectors[row], k=len(products))  # ranks every product, so the rank is exact    lexical = list(bm25.search(query, k=100).index)  # BM25 ranks are read from its top 100 only    print(f"{query}, its semantic rank: {list(ranked.index).index(holder[0]) + 1}")  # ranks count from 1    print(f"{query}, its similarity: {ranked[holder[0]]:.3f}")    # the best product other than this one    print(f"{query}, similarity of the next product: {ranked.drop(holder[0]).iloc[0]:.3f}")    print(f"{query}, its bm25 rank:", lexical.index(holder[0]) + 1 if holder[0] in lexical else "not in the top 100")
Salidapython code-probes.py
products 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

Cambiar los últimos dígitos del código desconocido deja las dos consultas con una similitud de 0.967, y sus 10 primeros resultados comparten 10 productos. Un código que no coincide con nada no cambia nada, y BM25 tampoco tiene nada que hacer coincidir.

Un código que solo tiene un producto decide el ranking de BM25 y apenas mueve el del embedding. La resolución 1920x1080p aparece solo en el texto del 5000 portable transmissive projector. BM25 lo ubica en la posición 1 para 1920x1080p projector; para 2560x1440p projector queda en la posición not in the top 100. Sciavolino et al. (2021) encontraron que los recuperadores densos (basados en embeddings) se desempeñan drásticamente peor que los métodos dispersos en preguntas sobre entidades raras, mientras que Karpukhin et al. (2020) describen BM25 como sensible a palabras clave y frases muy selectivas.

El embedding ubica el producto en la posición 1 con su propio código y en la posición 1 con el otro, porque la tienda tiene solo 4 proyectores. El código se nota solo en el margen sobre el producto siguiente: 0.562 frente a 0.496 con él, y 0.509 frente a 0.508 sin él.

Regla práctica: Haz una lista de las consultas de tu registro que contengan tamaños, cantidades o códigos, y compara ambos recuperadores con ellas antes de confiar en cualquiera de los dos. Cuando un código importa, haz coincidir de forma léxica. Cuando importa un tamaño exacto, compáralo con un campo del producto, como el ancho en attributes, o de forma léxica una vez que el tokenizador conserve los dígitos y las unidades se escriban de una sola manera (capítulo 5, capítulo 8). Deja el resto de la consulta a la recuperación semántica. El capítulo 7 pone a prueba la combinación de ambas.

Prueba los embeddings con la negación

Último cambio en la edición 2026.11.8

La negación invierte lo que busca un comprador con una sola palabra corta: una alfombra que no es redonda. Un embedding de la consulta completa puede quedar cerca de la misma consulta sin esa palabra. NevIR, un benchmark de pares de documentos que difieren en una negación, encontró que ninguna arquitectura bi-encoder supera el 12 % de precisión por pares, mientras que ordenar al azar obtiene el 25 % (Weller et al., 2024). En una reproducción de 2025, van den Elsen et al. encontraron que un bi-encoder de 7.000 millones de parámetros, GritLM-7B, alcanzó el 39.0 %, que otros bi-encoders mejoraron poco, y que solo los cross-encoders y los rerankers de LLM por listas manejaron razonablemente bien las dos tareas de negación.

0 de las consultas de la tienda contienen "no", "not", "without" o "non", así que los juicios no pueden probar la negación. En su lugar usamos 3 pares de consultas de prueba, cada una una consulta y su negación, y contamos qué contiene el top 10 de cada una.

El catálogo podría satisfacer todas las pruebas negadas: tiene 42 productos llamados armless, 62 mesas de centro que nunca mencionan el vidrio, y 90 alfombras de área que no se llaman round.

Antes de la ejecución, adivina cuántos de los 10 primeros resultados de la recuperación semántica para rug that is not round se llaman round.

negation-probes.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Superado
"""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."""import bm25sfrom lib.lexical import LexicalSearchfrom lib.recorded import probesfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, product_text# Probe queries written for the book, with no judgments: count what the top 10 holds, never score it.probe_queries, probe_vectors = probes()products = load_products()names, text = products["name"].str.lower(), product_text(products).str.lower()semantic, bm25 = SemanticSearch(), LexicalSearch(products)# armless and round are matched in product names, glass in the full textFEATURES = {"arms": ("armless", names), "glass": ("glass", text), "round": ("round", names)}negated = load_queries()["query"].str.contains(r"\b(?:no|not|without|non)\b")print("store queries with no, not, without or non:", negated.sum())# the tokenizer settings LexicalSearch uses, so these are the terms BM25 searchestokens = bm25s.tokenize(["rug that is not round"], stopwords="en", return_ids=False, show_progress=False)print("bm25 terms of rug that is not round:", " ".join(tokens[0]))print("products named armless:", names.str.contains(r"\barmless\b").sum())coffee_tables = products["product_class"] == "Coffee & Cocktail Tables"area_rugs = products["product_class"] == "Area Rugs"print("coffee tables that never mention glass:", (coffee_tables & ~text.str.contains(r"\bglass\b")).sum())print("area rugs not named round:", (area_rugs & ~names.str.contains(r"\bround\b")).sum())negation = probe_queries[probe_queries["kind"] == "negation"]print("negation probe pairs:", negation["pair"].nunique())for row, probe in negation.iterrows():    word, field = FEATURES[probe["pair"]]    has_feature = field.str.contains(rf"\b{word}\b")    semantic_top = semantic.search_vector(probe_vectors[row], k=10).index    bm25_top = bm25.search(probe["query"], k=10).index    print()    print(f"{probe['query']}, semantic top 10 with {word}:", has_feature[semantic_top].sum())    print(f"{probe['query']}, bm25 top 10 with {word}:", has_feature[bm25_top].sum())
Salidapython negation-probes.py
store 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

Si adivinaste pocos, leíste "not" como lo lee un comprador, y el embedding no. En las pruebas de alfombras y mesas de centro conservó el atributo y perdió el "not". El top 10 de la recuperación semántica para rug that is not round contiene 10 productos llamados round, y su top 10 para round rug contiene 10. Para coffee table not glass, 10 de los 10 primeros mencionan el vidrio, frente a 10 para coffee table with glass top.

sofa without arms ocurre al revés, y 8 de sus 10 primeros se llaman armless, frente a 1 para sofa with arms. El catálogo tiene una palabra para esa negación, armless, y el modelo coloca "without arms" cerca de ella.

BM25 no lo hace mejor en estas pruebas. Su tokenizador descarta "not", "that" e "is" como palabras vacías, así que busca rug that is not round como rug round. Sus top 10 contienen 10 alfombras round y 0 sofás armless.

Estas pruebas son unos pocos pares, no una medición, y el par de sofás va en sentido contrario. Pero los pares de alfombras y mesas de centro coinciden con NevIR: el vector de la consulta se mantiene cerca del atributo que la consulta nombra.

Regla práctica: No confíes en un recuperador de primera etapa, léxico o semántico, para manejar la negación. Cuando los compradores excluyen un atributo que tu catálogo almacena, como la forma, el material o los brazos, detecta la exclusión y filtra por ese atributo. Si no, reordena con un reranker, ya que en la reproducción de van den Elsen et al. los cross-encoders y los rerankers de LLM manejaron la negación bastante mejor. El capítulo 9 reordena la recuperación semántica de la tienda con un cross-encoder y LLMs, y ninguno de sus rerankers supera a la recuperación semántica en las consultas juzgadas de la tienda, que no pueden probar la negación. Conserva pruebas como estas como control que volver a ejecutar cada vez que cambies de modelo o añadas un reranker.

Elige un modelo de embeddings

El modelo decide lo que los vectores pueden saber, y cambiarlo más adelante significa volver a generar los embeddings de todo el catálogo. Los benchmarks públicos reducen el campo de opciones. Los juicios propios de la tienda son los que deciden.

Lee los benchmarks como una lista corta de candidatos

Último cambio en la edición 2026.11.8

MTEB, el Massive Text Embedding Benchmark, puntúa modelos en muchas tareas. Sus autores encontraron que ningún método domina en todas ellas (Muennighoff et al., 2023). Sus autores también encontraron que sus promedios favorecen las tareas con muchos conjuntos de datos, en especial la recuperación, la clasificación y el agrupamiento, así que lee las puntuaciones correspondientes a la tarea que tienes.

Las puntuaciones públicas también pueden exagerar el rendimiento sobre datos que un modelo no ha visto. Los creadores de RTEB, un benchmark de recuperación, describen una brecha entre las puntuaciones que los modelos reportan en benchmarks públicos y su rendimiento real con datos nuevos, no vistos (Liu et al., 2025). RTEB mantiene privados 28 de sus 48 conjuntos de datos. Verma et al. (2026) encuentran que las clasificaciones de modelos de RTEB se correlacionan solo con ρ = 0.38 con las de MTEB y con las de BEIR (Thakur et al., 2021), un benchmark anterior de recuperación en muchos dominios. Aquí ρ es una correlación de rangos, donde 1 significa el mismo orden. El tamaño tampoco equivale a calidad. Enevoldsen et al. (2025) informan que en MMTEB, el sucesor multilingüe de MTEB, el modelo disponible públicamente con mejor rendimiento es multilingual-e5-large-instruct, que tiene solo 560 millones de parámetros.

La tienda consideró cuatro modelos abiertos, y ninguna de sus fichas reporta resultados en WANDS. Son el codificador de la tienda y Qwen/Qwen3-Embedding-0.6B (ficha). Los otros dos son BAAI/bge-base-en-v1.5 (ficha) y ibm-granite/granite-embedding-english-r2 (ficha). Los benchmarks de búsqueda de productos, como ESCI, que etiqueta pares consulta–producto como exacto, sustituto, complementario o irrelevante, y contiene unas 130,000 consultas y 2.6 millones de juicios (Reddy et al., 2022), se acercan más a la tarea de la tienda, pero aun así no son su catálogo. Por eso la lista corta de la tienda se apoya en comprobaciones que una tabla de clasificación no puede hacer: una licencia que permita el uso comercial, el inglés, un tamaño que funcione sin hardware especial y soporte documentado para vectores más cortos. La ficha del modelo elegido por la tienda reporta 55.14 nDCG@10 en las tareas de recuperación de MTEB, una medición del proveedor sobre texto general, no sobre productos (ficha del modelo). Para elegir entre candidatos, registra cada uno sobre el mismo texto de productos y las mismas consultas, puntúa cada uno con las consultas de entrenamiento y compáralos con las pruebas pareadas del libro, como lo hace la siguiente subsección con un modelo en varios tamaños.

Trunca las dimensiones y luego prueba la pérdida

Último cambio en la edición 2026.11.8

Cada dimensión cuesta 4 bytes por producto como número de punto flotante de 32 bits, y cada similitud multiplica todas ellas, así que un vector más corto es más barato de almacenar y de buscar. El entrenamiento Matryoshka enseña a un modelo a colocar la información más útil en sus primeras dimensiones, de modo que el inicio de un vector funcione por sí solo como un embedding más pequeño. Kusupati et al. (2022) informan de embeddings hasta 14 veces más pequeños para la clasificación de ImageNet-1K con el mismo nivel de precisión. Acortar ahorra almacenamiento y búsqueda, no codificación: un modelo Matryoshka no es más rápido de ejecutar, como señala la documentación de Sentence Transformers. Solo los modelos entrenados de esta manera están preparados para soportarlo, y un vector acortado no tiene longitud unitaria, así que normalízalo de nuevo, como hace el propio ejemplo de la tarjeta del modelo.

El codificador de la tienda tiene una tarjeta del modelo que documenta el acortamiento a 256 dimensiones. lib.recorded.embeddings(dims=...) conserva los primeros dims números de cada vector y vuelve a normalizar. Puntúa cada longitud con las consultas de entrenamiento:

truncate-embeddings.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 Superado
"""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."""from lib.metrics import evaluatefrom lib.semantic import SemanticSearchfrom lib.store import load_queries, qrelstrain, judgments = load_queries("train"), qrels("train")       # choose on train queries# dims keeps the first dims numbers of every vector and rescales each to length 1 (lib.recorded).for dims in [768, 256, 128]:    semantic = SemanticSearch(dims=dims)    scores = evaluate(semantic.run(train, k=100), judgments)    # semantic.products holds the product vectors, not the product table    print(f"{dims} dimensions, float32 bytes per product: {semantic.products[0].nbytes:,}")    print(f"{dims} dimensions, ndcg@10: {scores['ndcg@10'].mean():.3f}")    print(f"{dims} dimensions, judged@10: {scores['judged@10'].mean():.3f}")    print()
Salidapython truncate-embeddings.py
768 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

Acortar a 256 dimensiones reduce un producto de 3,072 bytes a 1,024, y lleva la media de nDCG@10 de 0.772 a 0.762.

Con 128 dimensiones la media es 0.680, con judged@10 en 0.874 frente a 0.964, así que parte de esa caída podría deberse a productos que nadie evaluó.

¿Es real el cambio, o es ruido entre 50 consultas? Pruébalo con lib.significance.compare, que ejecuta la prueba de permutación del capítulo 3 y su prueba t pareada. También informa de un intervalo de bootstrap. Estas comparaciones usan consultas de entrenamiento, así que ajustan el tamaño del vector; no son evidencia sobre las consultas de prueba:

truncation-paired-test.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Superado
"""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."""from lib.metrics import evaluatefrom lib.semantic import SemanticSearchfrom lib.significance import comparefrom lib.store import load_queries, qrels# Train queries: these comparisons tune the vector size. They are not evidence about the test queries.train, judgments = load_queries("train"), qrels("train")def ndcg(dims):    return evaluate(SemanticSearch(dims=dims).run(train, k=100), judgments)["ndcg@10"]def p_value(p):    return "below 0.001" if p < 0.001 else f"{p:.3f}"full = ndcg(768)for dims in [256, 128]:    # compare's default interval is 95%    result = compare(ndcg(dims), full)                    # paired by train query: shortened minus full    print(f"{dims} vs 768, mean difference in ndcg@10: {result['mean difference']:.3f}")    print(f"{dims} vs 768, queries worse: {result['losses']}")    print(f"{dims} vs 768, permutation test p: {p_value(result['permutation p'])}")    print(f"{dims} vs 768, paired t-test p: {p_value(result['t-test p'])}")    print(f"{dims} vs 768, 95% bootstrap interval: {result['ci low']:.4f} to {result['ci high']:.4f}")    print(f"{dims} vs 768, interval excludes 0: {'yes' if result['ci high'] < 0 or result['ci low'] > 0 else 'no'}")    print(f"{dims} vs 768, effect size: {result['effect size']:.3f}")    print()
Salidapython truncation-paired-test.py
256 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

Con 128 dimensiones la pérdida es clara. La diferencia media es -0.092, y 33 consultas de entrenamiento empeoran. La prueba de permutación da p below 0.001, y el intervalo del 95%, desde -0.1569 to -0.0565, no incluye 0.

Con 256 dimensiones la evidencia es limítrofe, porque las pruebas y el intervalo no coinciden. La diferencia media es -0.010; la prueba de permutación da p = 0.076 y la prueba t da p = 0.080, pero el intervalo, desde -0.0211 to -0.0002, deja fuera el 0 por muy poco. El tamaño del efecto, -0.253 con 256 dimensiones frente a -0.547 con 128, indica que cualquier pérdida con 256 es la menor de las dos.

Para la tienda, la decisión depende de su tamaño, no de la prueba. Sus vectores completos ocupan 36.9 MB, así que hay poco que ahorrar; conserva las 768 dimensiones, y su puntuación en la prueba no cambia. Un catálogo de cientos de millones de productos sopesaría un recorte de 3,072 a 1,024 bytes por producto frente a una pérdida que tantas consultas de entrenamiento no pueden precisar, y evaluaría más consultas antes de decidir.

Regla práctica: Preselecciona modelos según licencia, idioma, tamaño y dominio, y trata los rankings de benchmark como una pista. Decide entre modelos, o entre tamaños de vector, con tus propias consultas de entrenamiento y una prueba pareada, y lee el intervalo además del valor p. Acorta vectores solo en un modelo entrenado para ello, normaliza después de acortar, y hazlo solo cuando la memoria o el tiempo de búsqueda lo requieran.

Qué sale mal en producción

Último cambio en la edición 2026.11.8

Una similitud no es una confianza. Resulta tentador no mostrar nada cuando la mejor similitud es baja. Pero las similitudes no están en una misma escala entre consultas:

similarity-scale.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 Superado
"""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."""import numpy as npfrom lib.recorded import embeddingsfrom lib.semantic import SemanticSearchfrom lib.store import load_queries, qrelsproduct_ids, product_vectors, query_ids, query_vectors = embeddings()test = load_queries("test")rows = np.isin(query_ids, test.index)similarity = np.sort(query_vectors[rows] @ product_vectors.T, axis=1)[:, ::-1]   # best first, per queryqueries = test.loc[query_ids[rows], "query"].to_numpy()weakest = similarity[:, 0].argmin()                    # the query whose best match is least similarstrongest = similarity[:, 9].argmax()                  # the query whose 10th match is most similarprint("first query, lowest best similarity:", queries[weakest])print(f"its best similarity: {similarity[weakest, 0]:.3f}")judgments = qrels()[query_ids[rows][weakest]]top = SemanticSearch().search(query_ids[rows][weakest], k=10).indexprint("exact products in its top 10:", sum(judgments.get(product_id) == 2 for product_id in top))print("second query, highest 10th similarity:", queries[strongest])print(f"its 10th similarity: {similarity[strongest, 9]:.3f}")cutoff = 0.5  # an illustrative cutoff; nothing about the model sets itprint()print(f"products above {cutoff} for the first query:", (similarity[weakest] > cutoff).sum())print(f"products above {cutoff} for the second query:", (similarity[strongest] > cutoff).sum())print(f"test queries with no product above {cutoff}:", (similarity[:, 0] <= cutoff).sum())
Salidapython similarity-scale.py
first 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

Los dos extremos entre las consultas de prueba lo muestran. liberty hardware francisco tiene la mejor coincidencia más débil, con 0.436, y sin embargo sus 10 primeros resultados contienen 5 productos exactos, mientras que kohler whitehaven farmhouse kitchen sink tiene la décima coincidencia más similar de todas, con 0.647.

Un umbral de 0.5 conservaría 0 productos para la primera consulta y 103 para la segunda, y ninguno para 2 consultas de prueba. Tampoco la recuperación semántica llega a quedar vacía: un código que ningún producto tiene sigue obteniendo un top 10 completo. Decide que una consulta no tiene coincidencia de otra forma, por ejemplo cuando la recuperación léxica no encuentra ninguno de sus términos poco frecuentes.

Los vectores que no coinciden fallan en silencio. Los vectores de la consulta y de los productos deben venir del mismo modelo, de la misma revisión y de los mismos prompts. Los vectores de dos modelos son números en espacios distintos, y cuando ambos tienen la misma dimensión, compararlos no produce ningún error. encode_query de Sentence Transformers añade el prompt de consulta predefinido del modelo, cuando existe (referencia de la API). Asegúrate de que el código que incrusta las consultas en vivo haga lo mismo que el código de indexación.

Un índice no sigue al catálogo por sí solo. El HNSW de faiss no admite eliminar vectores, según la wiki de faiss, así que un producto descontinuado permanece en el grafo hasta que lo filtres de los resultados o reconstruyas el índice. Douze et al. (2024) señalan que faiss no es una base de datos: no tiene escrituras concurrentes, fragmentación ni transacciones. El recall frente a la búsqueda exacta pertenece a un catálogo y a un conjunto de ajustes concretos, así que vuelve a medirla después de cada reconstrucción.

Los textos largos se truncan. El modelo lee como máximo 512 tokens, y la referencia de la API de Sentence Transformers indica que las entradas más largas se truncan. El producto más largo del almacén tiene 201 tokens, pero en un catálogo con descripciones largas el modelo nunca lee lo que queda más allá del límite. Cuenta los tokens antes de incrustar, como hace recordings/embeddings.py.

Las erratas desplazan los vectores. Zhuang y Zuccon (2021) encontraron que, en recuperadores basados en BERT no entrenados con faltas de ortografía, las erratas pueden provocar una caída significativa de la eficacia de recuperación y de ordenación. 4 de las consultas del almacén contienen una errata, y cada una tiene una sonda corregida. Una variante corregida pide lo mismo que su consulta, así que los juicios de esa consulta pueden puntuarla:

spelling-probes.py Python 3.12.15 · bm25s 0.3.16 · numpy 2.5.5 · pandas 3.1.1 · scipy 1.18.1 Superado
"""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."""from lib.lexical import LexicalSearchfrom lib.metrics import ndcg_at_kfrom lib.recorded import probesfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrels# Each spelling probe is the correctly spelled text of one store query (of_query_id), embedded by the same# model. It asks for the same thing, so it is scored with that query's judgments. A diagnosis, not a test.probe_queries, probe_vectors = probes()products, queries, judgments = load_products(), load_queries(), qrels()semantic, bm25 = SemanticSearch(), LexicalSearch(products)spelling = probe_queries[probe_queries["kind"] == "spelling"]for row, probe in spelling.iterrows():    query_id, pair = int(probe["of_query_id"]), probe["pair"]    typed, corrected = semantic.search(query_id, k=10).index, semantic.search_vector(probe_vectors[row], k=10).index    print(f"{pair}: {queries.at[query_id, 'query']} | {probe['query']} ({queries.at[query_id, 'split']} query)")    print(f"{pair}, similarity of the two spellings: {semantic.query_vectors[query_id] @ probe_vectors[row]:.3f}")    print(f"{pair}, products in both semantic top 10s:", len(set(typed) & set(corrected)))    print(f"{pair}, semantic ndcg@10 as typed: {ndcg_at_k(list(typed), judgments[query_id], 10):.3f}")    print(f"{pair}, semantic ndcg@10 corrected: {ndcg_at_k(list(corrected), judgments[query_id], 10):.3f}")    for name, text in [("as typed", queries.at[query_id, "query"]), ("corrected", probe["query"])]:        print(f"{pair}, bm25 ndcg@10 {name}: {ndcg_at_k(list(bm25.search(text, k=10).index), judgments[query_id], 10):.3f}")    print()print("spelling probes:", len(spelling))# a sign-flip test on n queries has 2 ** n outcomes, and its two most extreme give the smallest two-sided pprint(f"smallest two-sided permutation p-value possible with {len(spelling)} queries: {2 / 2 ** len(spelling):.3f}")
Salidapython spelling-probes.py
ligth: 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

Una sola errata puede cambiar por completo el top 10 semántico de una consulta. Para la consulta de entrenamiento foutains with brick look, las grafías con y sin corregir comparten 0 productos, y el nDCG@10 pasa de 0.353 a 0.645; BM25 también se mueve, de 0.356 a 0.507.

En las demás variantes las puntuaciones cambian menos: la única consulta de prueba entre ellas, refrigerator with ice an water in door, pasa de 0.807 a 0.829. Nada de esto establece un patrón: con 4 variantes, el menor valor p bilateral de permutación posible es 0.125.

Regla práctica: No filtres por una similitud fija. Registra el modelo, la revisión y los prompts con cada vector, y verifícalos donde se incrustan las consultas. Reconstruye y vuelve a medir el índice a medida que cambia el catálogo, cuenta los tokens antes de incrustar y corrige la ortografía antes de incrustar una consulta cuando tu registro muestre erratas, con un corrector que revise los vecinos de cada palabra (capítulo 8).

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.8

Cuando las consultas de entrenamiento podían medir una elección, lo hicieron.

  • Modelo: Snowflake/snowflake-arctic-embed-m-v1.5, que recordings/embeddings.py registra una sola vez en una revisión fijada. Es abierto, bajo Apache-2.0, pequeño y entrenado para vectores más cortos. Las consultas reciben el prefijo que indica su ficha; los productos no.
  • Similitud: el producto punto de vectores de longitud unitaria, que es la similitud coseno. Los vectores se normalizan una vez, y de nuevo después de cualquier cambio.
  • Búsqueda: exacta, con NumPy, mediante lib.vectors.exact_search, porque los vectores del almacén ocupan 36.9 MB. También es la verdad de referencia para cualquier índice.
  • Si el catálogo supera la búsqueda exacta: faiss HNSW con M = 32 y un efSearch de 144, la configuración más pequeña del barrido de entrenamiento en la que cada consulta conserva al menos 9 de sus 10 primeros verdaderos. En las consultas de prueba, su recall@10 frente a la búsqueda exacta es 1.000.
  • El recall de un índice se mide frente a la búsqueda exacta, sobre las consultas de entrenamiento, con la k que usa la canalización, y se revisan tanto las peores consultas como la media.
  • Dimensiones: todas las 768. Acortar a 256 dimensiones reduciría cada producto de 3,072 a 1,024 bytes, con un coste que las consultas de entrenamiento no logran precisar, y el almacén tiene poco que ahorrar.
  • Las consultas de sondeo prueban lo que los juicios no pueden, como la negación, los códigos y la ortografía. Se comparan por sus 10 primeros resultados, aparte de las consultas juzgadas; solo una ortografía corregida, que pregunta lo mismo, se evalúa con los juicios de su consulta.
  • Los puntos débiles conocidos pasan a otras etapas: los códigos pasan a la recuperación léxica, y las tallas exactas a los campos de atributos, o a la recuperación léxica una vez que el tokenizador conserve los dígitos (capítulo 5, capítulo 8). En ambos casos, un filtro que se prueba en lugar de una mezcla (capítulo 7). La negación pasa a los filtros de atributos y a la reordenación.
  • Lo que mostró el capítulo: un índice solo es tan bueno como su recall medido frente a la búsqueda exacta, sobre el catálogo y las configuraciones que despliegas. Las consultas de sondeo comprobaron que las incrustaciones manejan la mayoría de las tallas, pero no los códigos ni las negaciones de los pares de alfombra y mesa de centro, y unos pocos pares no demuestran nada.

Este capítulo, en esta edición

Edición 2026.11.10Ejemplos verificados el 19 de nov de 2026Superan la prueba 16 de 16 ejemplos ejemplos de este capítulo

Traducido del libro en inglés, edición 2026.11.10.

Cita esta sección

Formato

Cada formato cita el libro en inglés, que esta traducción sigue.

Cada formato nombra esta edición. Su enlace abre la edición actual, donde el encabezado de cada sección indica cuándo cambió su texto por última vez. Las fechas de acceso y de recuperación son el día en que lo abres.

En esta página

Capítulo 6 de 11: Recuperación semántica

  1. Convertir texto en embeddings
  2. Compara embeddings con similitud del coseno
  3. Encuentra los vecinos más cercanos exactos con NumPy
  4. Intercambia recall por velocidad con HNSW
  5. Comprueba el índice con las consultas de prueba
  6. Revisa las consultas que contienen dígitos
  7. Espera que un código pese poco
  8. Prueba los embeddings con la negación
  9. Elige un modelo de embeddings
  10. Lee los benchmarks como una lista corta de candidatos
  11. Trunca las dimensiones y luego prueba la pérdida
  12. Qué sale mal en producción
  13. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos