oriolrius.me Production RAGGuía de referencia
Parte 04·Fundamentos

Embeddings, vector stores y cómo leer los scores de similitud

Convertir chunks en vectores, guardarlos en Chroma y aprender a leer bien los scores de similitud.

41 min de lectura 14 secciones Fundamentos
Resumen en audio · 6:39 · ES
Embeddings, vector stores y cómo leer los scores de similitud

La Parte 3 te dejó con chunks. Los chunks son texto, y el texto no se puede comparar aritméticamente. Esta parte es el puente: convierte esos chunks en números, pone los números en algún sitio donde puedas buscarlos y luego —lo que casi todo el mundo hace mal la primera vez— te enseña a leer los números que salen de vuelta.

En el modelo mental de la Parte 1, estás trabajando exactamente sobre cuatro cajas:

Figura 1Dónde se sitúan los embeddings y los vector stores en las dos fases del pipeline
ASCII original
PHASE A — INDEX      Load → Split → [Contextualize] → [EMBED] → [STORE + INDEX]
PHASE B — QUERY      Gate → Cache → [EMBED QUERY] → [RETRIEVE] → Fuse/Filter → …

Dos de esas cajas están en la fase offline y se pagan una vez. Dos están en la fase online y se pagan en cada request. El mismo embedding model tiene que estar en las dos: es el invariante 2, y es la regla que sostiene toda esta parte. Todo lo demás aquí es mecánica.

Fuente: capítulos 6, 7 y 8 del curso, 00:48:12 – 01:24:32: un capítulo de teoría cargado de diapositivas, el primer capítulo práctico de todo el curso y un capítulo muy corto que en realidad son dos lecciones pegadas.

Un embedding model no es un modelo de chat

El instructor abre el capítulo 6 señalando esto como «esta distinción tan crucial que confunde a mucha gente» 00:48:13, y tiene razón. Los dos viven detrás del mismo objeto cliente de OpenAI, los dos se facturan por token, los dos se llaman «modelos». No son intercambiables en ninguna de las dos direcciones.

Modelo de chatEmbedding model
Entradauna conversación (messages=[{role, content}])un único string plano (input="…")
Salidatexto que puedes leeruna lista de floats
Superficie del SDKclient.chat.completions.create(...)client.embeddings.create(...)
Modelo de ejemplogpt-4o-minitext-embedding-3-small
De dónde se lee el resultadoresponse.choices[0].message.contentresponse.data[0].embedding
¿Se puede cambiar más adelante?Sí, librementeNo: mira «la Regla» más abajo

00:49:14 — «Así que misma empresa, distinto modelo».

El recurso didáctico del capítulo es deliberadamente mínimo: escribe la demo de chat, la ejecuta, la comenta, descomenta la demo de embeddings que está justo debajo y la ejecuta. Cambian tres líneas. El tipo de salida cambia por completo.

Python
# Reconstructed from the ch.6 narration [00:49:14]–[00:51:16].
# NOT a checked-in repo file — the instructor types this into a scratch buffer.
from openai import OpenAI

client = OpenAI()

# --- demo 1: CHAT model ---
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)
print(response.choices[0].message.content)   # -> "The capital of France is Paris."

# --- demo 2: EMBEDDING model (the chat block above gets commented out) ---
response = client.embeddings.create(
    input="Your text string goes here",
    model="text-embedding-3-small",
)
print(response)                              # full object: vector + metadata
print(response.model)                        # "text-embedding-3-small"
print(response.object)                       # "list"
print(response.usage)                        # prompt_tokens / total_tokens
print(len(response.data[0].embedding))       # 1536

Hay tres cosas en ese segundo bloque que valen más de lo que parece.

len(response.data[0].embedding) → 1536. Esa es toda la definición de dimensión, entregada como una medición práctica en lugar de como un punto de una diapositiva 00:51:16. La dimensión de text-embedding-3-small es 1536 porque la lista que devuelve tiene 1536 floats. Nada místico.

response.usage lleva prompt_tokens y total_tokens. Las llamadas de embedding se facturan por tokens exactamente igual que las de chat 00:50:14. La gente interioriza que «el chat cuesta dinero» y, no se sabe cómo, da por hecho que los embeddings son gratis. No lo son y —ver más abajo— los pagas dos veces: una por chunk en el momento de indexar y una por pregunta para siempre.

¿Por qué números? Porque los números se pueden comparar matemáticamente y el texto no 00:51:16. Puedes calcular una distancia entre dos vectores. No puedes calcular una distancia entre dos frases en inglés. Todo lo que viene después —búsqueda por similitud, umbrales, reranking, fusión— existe solo porque la representación se volvió aritmética.

00:51:16 — «Porque los números se pueden comparar matemáticamente con facilidad».

Cómo elegir la dimensión

Más dimensiones significa más espacio para almacenar rasgos de lo que hayas convertido en embedding: más significados, más semántica, más matices distinguibles 00:52:18. Es lo único que mejora a medida que sube el número. Hay tres cosas que empeoran.

00:54:20 — «Más dimensiones equivale a captar más matices semánticos. Pero más almacenamiento y una búsqueda más lenta».

La tabla de referencia. Fíjate en que las dimensiones salen de las diapositivas 00:52:18–00:53:19 y los precios salen de un bloque de comentarios al principio de embeddings.py en el repo: el instructor nunca dice un precio en voz alta, así que considera que la columna del dinero procede del repo y contrástala con los precios actuales del proveedor antes de citársela a nadie.

ModeloDimensionesCoste / 1M de tokensIdeal para
text-embedding-3-small1536$0.02Uso general: el valor por defecto del curso
text-embedding-3-large3072$0.13Alta precisión (6.5× el precio)
text-embedding-ada-0021536$0.10Legacy: no hay motivo para elegirlo hoy
Embedding model de Gemini768nivel gratuito«un poco pequeño, pero la buena noticia es que es gratis»
BGE-small384local / gratisMuy pequeño; mandan la velocidad y la huella
all-MiniLM-L6-v2 (Sentence-Transformers)384local / gratisEl sustituto que usa el repo para la clase de 384 dimensiones

Dos salvedades honestas sobre esa tabla. Primera: el instructor nombra BGE-small en la diapositiva de 00:53:19, pero el repo incluye sentence-transformers/all-MiniLM-L6-v2 en su lugar; los dos tienen 384 dimensiones y los dos son modelos abiertos pequeños habituales, pero no son el mismo checkpoint; no dejes que la propia tabla de la guía dé a entender que lo son. Segunda: dice «Gemini embeddings, 768 dimensiones» sin nombrar nunca una versión concreta. Google ha publicado tanto text-embedding-004 con 768 como gemini-embedding-001 con dimensiones configurables, así que resiste la tentación de rellenar un id de modelo que la fuente nunca dio.

El procedimiento de decisión, en el orden en que deberías seguirlo de verdad:

  1. Por defecto, la franja de 768–1536. Para aquí salvo que se aplique algo de lo siguiente.
  2. ¿Máxima fidelidad semántica, y puedes pagar el almacenamiento y la latencia por query para siempre?

→ 3072 (text-embedding-3-large), a 6.5× el precio por token.

  1. ¿El coste es la restricción que manda, o quieres un nivel gratuito? → 768 (Gemini).
  2. ¿Mandan la huella y la velocidad y la semántica es sencilla? → 384 (BGE-small,

all-MiniLM-L6-v2 u otro modelo local).

  1. En todos los casos: decide a partir de tu carga de trabajo, no de un ranking público. El estribillo de

todo el capítulo es «depende de los casos de uso».

Este es el fichero real del repo. Es corto, es casi todo un comentario y el comentario es lo más citable que tiene, pero también contiene tres trampas distintas, así que lee las anotaciones antes de copiarlo.

Python
# /home/oriol/lab/rag/code/production-course-main-code/embeddings.py  (lines 1-17, verbatim)
# Model	              Dimensions	Cost per 1M tokens	Best For
# text-embedding-3-small	1536	    $0.02	            General use
# text-embedding-3-large	3072	    $0.13	                High accuracy
# text-embedding-ada-002	1536	    $0.10	                Legacy

from langchain_openai.embeddings import OpenAIEmbeddings
from langchain_community.embeddings import HuggingFaceEmbeddings
from dotenv import load_dotenv

load_dotenv()

embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2") # 384 dimensions


# Ollama 
from langchain_ollama import OllamaEmbeddings
embeddings = OllamaEmbeddings(model="llama2-7b-embedding-q4_0")

El resto del fichero —comentado en el repo— es la API de LangChain de dos métodos que usarás durante el resto de esta guía:

Python
# /home/oriol/lab/rag/code/production-course-main-code/embeddings.py, lines 33-51,
# with one leading "#" stripped from each line. Otherwise unchanged.
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")

# single text
text = "This is a sample text to be embedded."
embedding = embeddings.embed_query(text)
# print(f"Embedding for single text: {embedding}")

print(len(embedding))  # Should print 1536 for text-embedding-3-small


# multiple texts
embeds = embeddings.embed_documents(
    ["This is the first document.", "This is the second document."]
)
print(f"Embeddings for multiple texts: {embeds}")
print(f"Number of embeddings returned: {len(embeds)}")  # Should print 2
print(
    f"Length of each embedding: {len(embeds[0])}"
)  # Should print 1536 for text-embedding-3-small

embed_query es para la pregunta única del camino de lectura. embed_documents recibe una lista y devuelve un vector por elemento en un único viaje de ida y vuelta: es el método que quieres en el momento de indexar, y la distinción importa más adelante cuando metes cache, porque CacheBackedEmbeddings cachea embed_documents y deja embed_query sin cachear salvo que lo pidas (Parte 9). Fíjate también en que este bloque asigna el nombre embeddings una tercera vez: si simplemente lo descomentas donde está, queda por debajo de las dos asignaciones activas del principio del fichero y gana sin hacer ruido. Borra las que no uses.

Lo que te dan los números: ranking por similitud coseno

Antes de entregar los vectores a una base de datos, vale la pena hacer la búsqueda a mano una vez. Treinta líneas de numpy son toda la idea de la búsqueda semántica, sin store, sin índice y sin ninguna abstracción por medio.

Python
# /home/oriol/lab/rag/code/production-course-main-code/embeddings_deep.py  (lines 35-65)
def similarity_search():

    docs = [
        "Python is a programming language",
        "JavaScript is used for web development",
        "Machine learning enables AI applications",
        "Deep learning uses neural networks",
        "Cats are popular pets",
    ]

    query = "What programming languages exist?"

    # embed documents and query
    doc_vector = embeddings_model.embed_documents(docs)
    query_vector = embeddings_model.embed_query(query)

    # compute cosine similarities
    def cosine_similarity(vec1, vec2):
        return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))

    similarities = [cosine_similarity(query_vector, doc_vec) for doc_vec in doc_vector]

    # rank documents by similarity
    ranked_docs = sorted(zip(docs, similarities), key=lambda x: x[1], reverse=True)

    print(f"Query: {query}\n")
    print("Ranked by similarity:")
    for doc, score in ranked_docs:
        print(f"  {score:.4f}: {doc}")

Lee lo que hace realmente una base de datos vectorial, en cuatro líneas: generar el embedding del corpus, generar el embedding de la query, puntuar cada pareja, ordenar de mayor a menor. Un vector store de producción añade un índice para que no tengas que puntuar cada pareja, además de persistencia, filtrado y concurrencia, pero la semántica de arriba es la semántica que implementa.

Fíjate en la polaridad: esta función ordena con reverse=True, porque en la similitud coseno más alto es mejor. Quédate con esa idea; Chroma está a punto de darte la convención contraria.

Hay una cosa más en ese fichero que vale la pena copiar aunque no se ejecute. basic_embeddings() imprime tres datos de un vector recién generado: su longitud, sus cinco primeros valores y np.linalg.norm(...). Es la sonda mínima de «qué me ha devuelto realmente», y el tercer print es el interesante: si la norma sale ≈1.0000, tu proveedor te está dando vectores de longitud unitaria, y en ese caso la similitud coseno y un producto escalar simple son el mismo número y la división de cosine_similarity no hace nada. No lo des por hecho: imprímelo. Los proveedores son distintos, y uno que no normalice hará que tu atajo del producto escalar dé resultados erróneos sin avisar.

Las dos fases, contadas de forma concreta

Esta es la columna vertebral del capítulo 6 00:54:20–00:56:23, y es el mismo modelo de dos fases de la Parte 1 con las cajas rellenas.

Fase 1 — Indexación. Ocurre una vez por conjunto de documentos.

  1. Load: cargar los documentos.
  2. Split: cortarlos; «digamos que de 500 a 1,000 tokens cada uno» 00:54:20.
  3. Embed: pasar cada chunk por el embedding model que hayas elegido.
  4. Store: guardar el resultado.

Lo que acaba realmente en el store no son solo los vectores: «tenemos los vectores en sí, los embeddings, el texto original y todo eso» 00:55:23. El vector, el texto original del chunk y sus metadatos viajan juntos. Eso importa porque el paso 3 de la fase de query necesita el texto, no los números. Al final de la indexación, el store contiene miles de vectores, cada uno de los cuales representa un chunk.

(El instructor usa «vector store» y «base de datos vectorial» indistintamente, y lo dice explícitamente. Esta guía hace lo mismo).

Fase 2 — Consulta. Ocurre por pregunta, en cada pregunta.

  1. Generar el embedding de la query —«el mismo embedding model; esto es importante» 00:55:23— para obtener

un vector de query.

  1. Buscar vectores similares en el store.
  2. Recuperar: «el proceso de obtener los chunks de texto originales de esos vectores».
  3. Aumentar: combinar system prompt + chunks recuperados + query del usuario 00:55:23.
  4. Generar: enviar el prompt montado a un modelo de chat y devolver la respuesta.

El paso 4 es la «A» de RAG, y es más concreto de lo que se suele decir. La aumentación son exactamente tres ingredientes fusionados en un prompt 00:55:23. No hay reentrenamiento, ni fine-tuning, ni actualización de pesos: «estamos aumentando el conocimiento del gran modelo de lenguaje con nuestros documentos recuperados» 00:56:23, en el momento del prompt, para una request, y luego desaparece.

Y la asimetría que aparece al poner las dos fases una al lado de la otra:

El embedding en tiempo de indexación es un coste de batch puntual que amortizas. El embedding en tiempo de query se paga en cada pregunta, para siempre. Por eso la elección de la dimensión pesa más en tiempo de query: un modelo de 3072 dimensiones no es «el doble de almacenamiento», es el doble de almacenamiento y un vector más lento en el camino crítico de cada request.

La solución para la mitad recurrente es el caching, que el curso pone en embeddings_deep.py::embedding_caching() —CacheBackedEmbeddings.from_bytes_store sobre un LocalFileStore— y que esta guía trata a fondo en la Parte 9. Tres cosas que conviene saber ya para no coger un mal hábito:

  • En LangChain 1.x, esos dos símbolos viven bajo langchain_classic, no bajo langchain:

from langchain_classic.embeddings.cache import CacheBackedEmbeddings y from langchain_classic.storage import LocalFileStore. Todos los tutoriales antiguos que encuentres los importan desde el paquete de nivel superior langchain y te darán un ImportError.

  • CacheBackedEmbeddings rellena document_embedding_cache; es decir, cachea

embed_documents y deja embed_query sin cachear salvo que también pases query_embedding_cache=. El repo solo pasa lo primero, así que el camino de indexación está cacheado y el de query, el que de verdad pagas en cada request, no.

  • El argumento namespace= debería ser el id de tu embedding model. El repo pasa

namespace="exercise", que es una etiqueta, no una identidad: cambia de modelo detrás de un namespace compartido y la cache te servirá tan tranquila vectores del antiguo. Es exactamente el fallo del que trata la siguiente sección, con una cache añadida para esconderlo.

La regla que nunca puedes romper

Todo lo de esta parte llevaba hasta aquí.

Hay dos mecanismos distintos que la rompen, y fallan de forma muy diferente:

FalloCausaSíntoma
Dimensiones distintasVector de query de 1536 dimensiones frente a vectores almacenados de 768Ruidoso. Las matemáticas no cuadran; obtienes una excepción.
Misma dimensión, distinto modelop. ej., ada-002 (1536) al indexar, 3-small (1536) al consultarSilencioso. Nada da error. Los dos modelos no comparten sistema de coordenadas, así que las distancias no significan nada y obtienes tonterías verosímiles.

La segunda fila es la peligrosa, y es la que nadie prueba. Los dos modelos producen 1536 floats. Las dos llamadas funcionan. La búsqueda devuelve los k documentos pedidos. El LLM escribe una respuesta fluida. Lo único que falla es que la respuesta no tiene nada que ver con la pregunta, y no hay ninguna excepción en ningún punto del trace. Es el invariante 4 —los fallos son silenciosos— en estado puro.

00:57:25 — «Si cambias de modelo, tus vectores no serán comparables. Por tanto, esta búsqueda fallará».

Ese aviso se repite tres veces dentro de un mismo capítulo de trece minutos (00:55:23, 00:56:23, 01:00:26). Es la frase más repetida de la hora.

Y la asimetría que la hace contraintuitiva: el modelo de generación se puede cambiar por completo. «GPT-4, GPT-5, GPT-10, Claude, da igual» 00:56:23. Puedes cambiar de LLM un martes por la tarde con un import y un string de modelo. El embedding model no se puede cambiar sin volver a generar el embedding de cada chunk que tengas. Los ingenieros que han interiorizado que «los modelos son intercambiables» desde el lado del chat se llevan ese hábito al lado de los embeddings y destrozan un índice.

La forma mecánica de hacerla cumplir es una cuestión de estilo de una línea de código. Tanto vector_stores.py como rag_pipeline.py declaran el modelo exactamente una vez, a nivel de módulo, y nunca escriben un string de modelo en línea en el punto de llamada:

Python
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py:11
# (identical line at rag_pipeline.py:22)
embeddings_model = OpenAIEmbeddings(model="text-embedding-3-small")

Esa única asignación se pasa luego a Chroma.from_documents(...) al indexar y la reutilizan todos los caminos de query del módulo. Si te tienes que quedar con una sola lección de código del capítulo 6, es esta: declara el embedding model una vez, como constante a nivel de módulo, y nunca escribas el string del modelo en línea en un punto de llamada. En un sistema real, llévalo más lejos: una variable de entorno más una aserción al arrancar que compruebe que el id de modelo registrado en la colección coincide con el configurado.

Las tres reglas de producción que se derivan

Directamente de la diapositiva de 00:59:26:

  1. Usa el mismo embedding model en todas partes. Indexación y consulta, modelos idénticos,

versión incluida.

  1. Calidad de los embeddings > cantidad. «Mejores embeddings sobre menos documentos ganan a peores

embeddings sobre más documentos». Un argumento directo contra el instinto de arreglar un mal retrieval volcando más datos en el índice.

  1. Prueba tu retrieval por separado. Antes de culpar al LLM, imprime qué documentos han

vuelto.

Esa tercera regla viene con el número que la justifica:

00:59:26 — «El 90% de los fallos de RAG son fallos de retrieval, no de generación».

Igual que la cifra de «el 90% de los sistemas RAG fallan en producción» de la Parte 1, es una afirmación de campo sin fuente: no se da ningún estudio, ningún dataset, ninguna metodología. Trata el número como retórico y el orden como correcto: cuando una respuesta de RAG está mal, inspecciona los chunks recuperados antes de tocar el prompt o el modelo. Y hay un techo al progreso de los modelos que ninguna versión futura elimina:

00:59:26 — «Si recuperas los documentos equivocados, ni GPT 100 puede salvarte».

El camino bueno y el camino malo

El ejemplo resuelto es deliberadamente mundano. Query: «¿Cuál es la política de reembolsos?»

El camino bueno 00:58:25: el vector de query capta el significado de «política de reembolsos»; la búsqueda vectorial encuentra chunks sobre devoluciones, reembolsos, recuperar el dinero —incluidos algunos sin ninguna coincidencia léxica con la query— porque «todo va del significado real, no solo de la palabra clave»; se recupera el texto relevante; el LLM recibe contexto real; el usuario recibe una respuesta precisa. Esa coincidencia entre «recuperar el dinero» y «política de reembolsos» es toda la propuesta de valor de la búsqueda semántica frente a la búsqueda por palabras clave.

El camino malo 00:58:25–00:59:26: el vector de query no capta bien el significado; la búsqueda devuelve chunks aleatorios; el LLM recibe contexto irrelevante; el usuario recibe una respuesta incorrecta o una alucinación.

Fíjate también en lo que este replanteamiento le hace a la alucinación. En el capítulo 6 no es un defecto del modelo; es el síntoma aguas abajo de un mal retrieval. «El LLM solo puede trabajar con lo que le das» 00:59:26. Eso es lo que hace que la regla 3 sea accionable: la alucinación se convierte en un bug de retrieval que puedes reproducir y medir, no en una propiedad misteriosa del modelo.

Y la cadena causal que une esta parte con la Parte 3 (invariante 1: la calidad se hereda hacia delante y nunca se recupera aguas abajo):

00:57:25 — «Un mal chunking va a llevar a malos embeddings, que van a llevar a un RAG roto».

00:59:26 — «Embeddings basura equivalen a retrieval basura, que equivale a respuestas basura».

El embedding model no tiene criterio. Codifica fielmente lo que le des. Si le das media sección de OAuth, obtienes un vector perfecto, seguro de sí mismo y bien formado de media sección de OAuth.

El diagrama del workflow de Chroma: el modelo de referencia para cualquier base de datos vectorial

El capítulo 7 dedica sus primeros siete minutos 01:01:06–01:08:15 a un único diagrama, y el instructor deja claro que esta es la parte que hay que recordar:

01:07:13 — «esta es la lección … a la que siempre deberías volver … para entender cualquier base de datos»

Este capítulo no tiene capturas (el índice del curso lista 01:01:05 entre los «capítulos sin captura»), así que aquí tienes la estructura en texto.

Dos capas. La capa de aplicación, arriba, contiene exactamente tres cosas visibles: la query entrante, la context window del LLM y la respuesta que sale de vuelta 01:02:08. Aquí arriba no vive nada relacionado con vectores. La capa de Chroma DB, debajo, «almacena y gestiona los embeddings»: los documentos, ya divididos en chunks, junto con sus vectores.

El paso de traducción obligatorio en medio. Entre las dos está «gen embedding». No puedes interactuar en absoluto con una base de datos vectorial hasta que la query se ha transformado en un vector, porque el embedding es «el formato, el idioma que se necesita» para la base de datos 01:03:08. La query nunca se envía como texto.

El resto de afirmaciones del diagrama, que conviene tener en una sola lista:

  • El almacenamiento es un medio, nunca el objetivo. 01:02:08 — «No guardas datos solo por

el hecho de guardarlos». El material almacenado existe para pasar por la context window de un LLM junto con la query del usuario.

  • «Documentos» representa cualquier tipo de dato 01:02:08, incluidos los datos no estructurados.

Se usa texto plano porque queda limpio en una demo.

  • Las queries suelen ser texto, pero la modalidad no es fija: «simplemente un texto o voz o

lo que sea» 01:03:08. Al final todo se reduce a un vector.

  • Un documento ↔ un embedding 01:03:08–01:04:09, cada uno de los cuales representa el

contenido de ese documento en forma de vector.

  • El retrieval se hace por distancia vectorial, no por coincidencia de palabras clave 01:04:09.
  • Un registro almacenado lleva más que el vector. Los documentos viven en el store «en forma de

embeddings, que son vectores que pueden contener algo más de información que los vectores en sí» 01:01:06. En concreto: {id, embedding, document text, metadata}. La demo práctica lo confirma: el resultado de la query vuelve con ids, documentos y distancias.

  • El LLM hace tres cosas con el material recuperado 01:04:09: obtiene información

relacionada, interpreta la intención de la query y genera texto nuevo a partir de patrones aprendidos. No es un simple formateador: puede ampliar el contexto recuperado, y por eso precisamente el patrón de prompt antialucinaciones de la Parte 1 no es opcional.

  • La respuesta es contexto *más* conocimiento paramétrico, no solo contexto. 01:07:13 —

el modelo, «porque tiene su conocimiento», es el que sabe cómo procesar el material recuperado. Ese es el mecanismo que hay detrás del punto anterior, y es la razón por la que un chunk equivocado no produce una respuesta obviamente equivocada: el modelo tiene suficientes conocimientos previos propios para tapar el hueco y darte algo fluido.

  • La respuesta tiene que estar fundamentada. 01:04:09–01:05:12 — la salida final «tiene que tener

algo de contexto aportado por la base de datos Chroma». Se plantea como algo innegociable.

  • Dos caminos posibles después de generar el embedding de la query 01:05:12: comparar con los embeddings

almacenados para encontrar documentos relevantes (RAG normal) o ir directamente al LLM (el camino degenerado sin retrieval; vale la pena nombrarlo, porque la puerta de la Parte 12 hace que ese camino sea deliberado y no accidental).

  • Por qué esto gana a la búsqueda por palabras clave 01:06:12: el sistema puede «entender y procesar

queries complejas con más precisión que los sistemas tradicionales de búsqueda por palabras clave», y produce respuestas contextualmente relevantes y semánticamente ricas. No te tomes esta afirmación al pie de la letra: la Parte 6 muestra exactamente dónde la búsqueda vectorial pura pierde frente a la búsqueda por palabras clave (códigos de producto, IDs, strings exactos), y por eso existe el retrieval híbrido.

Lo importante es la generalización: «aquí solo estamos usando Chroma en este caso, pero cualquier base de datos vectorial, al final, necesita interactuar con el mundo real» 01:07:13. Cambia Chroma por pgvector, Pinecone, Qdrant o FAISS y el diagrama no cambia. Solo se mueve la API del cliente.

Constrúyelo una vez a mano: el cliente chromadb en bruto

Ahora la mecánica, sin ningún framework por medio. El capítulo 7 es el primer capítulo práctico del curso: carpeta vacía, un fichero, app.py.

Las versiones, para que consten, ya que ninguna se dice en voz alta: el repo del curso fija requires-python = ">=3.12", incluye chromadb 1.4.1 en su lockfile y declara langchain-chroma>=1.1.0, que es el wrapper del que dependen el capítulo 8 y siguientes, y que la Parte 2 ya te advirtió que instalaras en lugar de langchain-community para el vector store.

El entorno, en las dos plataformas, exactamente como se narra 01:09:16–01:10:18:

bash
# macOS / Linux
python3 -m venv venv
source venv/bin/activate          # confirm the venv is ACTIVE before continuing
pip install chromadb
text
# Windows
python -m venv myenv      # or:  py -m venv myenv
myenv\Scripts\activate
pip install chromadb

Se frena a mitad de comando cuando está a punto de instalar en el entorno global —«antes incluso de hacer eso… necesito crear un entorno virtual» 01:09:16— por la razón obvia:

01:09:16 — «para que no instales todas estas dependencias y paquetes distintos por todas partes»

Después, el fichero en sí. Esta es la reconstrucción a partir de la narración (app.py, ~15 líneas):

Python
# app.py — reconstructed from the ch.7 narration [01:11:18]–[01:16:27].
# NOT a checked-in repo file. Raw chromadb client — no LangChain, no API key.
import chromadb

chroma_client = chromadb.Client()

collection_name = "test_collection"
collection = chroma_client.get_or_create_collection(name=collection_name)

documents = [
    {"id": "doc1", "text": "hello world"},
    {"id": "doc2", "text": "how are you today"},
    {"id": "doc3", "text": "..."},          # third doc's text is never read aloud
]

query_text = "hello world"

for doc in documents:
    collection.upsert(ids=[doc["id"]], documents=[doc["text"]])

results = collection.query(query_texts=[query_text], n_results=3)
print(results)

Fichero pequeño, cinco lecciones reales.

1. Una colección es una tabla. 01:13:22 — la analogía más clara del capítulo. test_collection es el contenedor con nombre que guarda documentos, ids y embeddings. Si conoces SQL, la correspondencia mental es: cliente → conexión, colección → tabla, documento → fila, id → clave primaria.

2. get_or_create_collection, no create_collection. La documentación del proveedor enseña create_collection; él lo cambia a propósito 01:11:18–01:12:18 porque durante el desarrollo los scripts se vuelven a ejecutar constantemente y create_collection entra en conflicto cuando el nombre ya existe. *(Una corrección a la narración: dice que get-or-create «va a reescribirlo todo», lo cual induce a error. No borra ni sobrescribe nada: devuelve la colección existente. La seguridad frente a sobrescrituras viene de upsert, no de esta llamada).*

3. upsert, nunca add. Es el aviso principal del capítulo 01:13:22. collection.add() no tiene protección frente a colisiones de id, así que cada vez que vuelves a ejecutar tu script añade en silencio otra copia de todo tu corpus. upsert inserta o actualiza por id.

4. La API de Chroma usa listas en todas partes. documents=[...], ids=[...], query_texts=[...]: las operaciones que suenan a singular siguen queriendo listas. Lo aprende en directo: la ejecución falla con «got an unexpected keyword argument text» porque escribió text=…; el parámetro es documents y recibe una lista 01:16:27.

La lección generalizable, que vale más que el arreglo concreto: cuando un SDK de Python rechaza un kwarg, no adivines el nombre; abre la referencia de la API de ese método exacto y copia de ahí los nombres de los parámetros.

Y una vez que te has dado cuenta de que los parámetros son listas, fíjate en lo que hace el bucle: llama a upsert una vez por documento, cada vez con una lista de un solo elemento. Tres documentos, tres viajes de ida y vuelta, tres batches de embedding. La misma llamada acepta todo el corpus —collection.upsert(ids=[d["id"] for d in documents], documents=[d["text"] for d in documents])— de una sola vez. Con tres documentos es inofensivo; con diez mil es la diferencia entre una ingesta que tarda un minuto y otra que tarda una tarde. Agrupa tus escrituras en batches.

5. El resultado es un único dict de listas paralelas. collection.query(query_texts=[q], n_results=3) devuelve ids, documentos y distancias como tres arrays alineados 01:16:27, no como una lista de objetos registro. n_results es el número de resultados que quieres («queremos traer tres. Podemos decir 2, 1, 3, etcétera»). También hay un parámetro query_embeddings para pasar vectores ya calculados en lugar de texto; se menciona una vez y no se usa en ningún sitio del curso.

Y después, la observación hacia la que se encamina toda esta parte. La query es "hello world" y el texto de doc1 es "hello world", así que doc1 vuelve con una distancia de 0:

01:17:29 — «Así que cuanto más cerca de cero está, más parecidos son esos dos».

Las otras distancias que lee de la salida rondan 0.01 y más. Lo señalo con honestidad: ese 0.01 es ambiguo en la transcripción automática; puede ser 0.0 leído dígito a dígito seguido de otro número. No lo cites como exacto. El 0 de la coincidencia exacta no tiene ambigüedad.

Detalles del capítulo práctico que todavía le cuestan una hora a la gente
  • **Un import chromadb subrayado en rojo después de una instalación correcta = intérprete equivocado, no un paquete

roto.** 01:11:18 Apunta VS Code al Python de tu venv. No reinstales.

  • Lee primero la documentación del proveedor, y conoce su forma. 01:08:15 Abre a propósito

la página «Getting Started» de Chroma y copia fragmentos de ella; después edita dos (create_collection → get_or_create_collection, add → upsert) porque la documentación está optimizada para la primera ejecución y tú estás optimizando para la número cien.

  • Disciplina de alcance. 01:08:15 — «Obviamente, esto no es un curso de Chroma DB». Lo que

se traslada entre bases de datos vectoriales es el diagrama del workflow; los nombres de los métodos, no.

  • Windows cambia en *los dos* pasos 01:09:16–01:10:18: la creación (python / py

en lugar de python3) y la activación (Scripts\activate en lugar de bin/activate).

  • Un hueco en el material grabado. El capítulo 8 dice que el store se construye con un directorio temporal

«como hicimos antes», pero persist_directory no aparece nunca en pantalla en el capítulo 7, que usaba el Client() en memoria a secas. Si lo sigues y te parece que te has saltado un paso, no es así: ese paso nunca se grabó.

Constrúyelo otra vez con LangChain

El capítulo 8 empieza con la misma base de datos, una capa de abstracción más arriba:

01:17:50 — «ya veis que es muy fácil cuando usamos el wrapper de Chroma y LangChain».

No dejes que la continuidad te haga creer que las API son iguales. No lo son:

Conceptochromadb en bruto (cap. 7)langchain_chroma (cap. 8 en adelante)
Crear + poblarcollection.upsert(ids=[…], documents=[…])Chroma.from_documents(documents=…, embedding=…, persist_directory=…)
La unidad de datosdict {"id": …, "text": …}Document(page_content=…, metadata={…})
Búsquedacollection.query(query_texts=[q], n_results=N)vectorstore.similarity_search(q, k=N)
Búsqueda con scoredistancias en el dict de resultadosimilarity_search_with_score(q, k=N) → tuplas
Quién genera los embeddingsEl modelo por defecto que trae Chromael objeto embedding= que le pasas

Esa última fila es la importante. Con LangChain proporcionas el embedding model de forma explícita, y eso es lo que te devuelve al cumplimiento de la Regla.

El corpus de todas las demos que quedan en esta parte es un fixture de 8 documentos. Vale la pena copiarlo literalmente en tus propias pruebas, porque los valores de topic están pensados para que la demo de filtrado dé un resultado interesante.

SAMPLE_DOCS: el fixture de 8 documentos (vector_stores.py:14-47)
Python
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py, lines 1-47, verbatim
from langchain_openai.embeddings import OpenAIEmbeddings
from langchain_chroma import Chroma
from langchain_core.documents import Document
from langchain_text_splitters import RecursiveCharacterTextSplitter
import tempfile
import shutil
from dotenv import load_dotenv

load_dotenv()

embeddings_model = OpenAIEmbeddings(model="text-embedding-3-small")

# Sample documents
SAMPLE_DOCS = [
    Document(
        page_content="LangChain is a framework for developing applications powered by language models.",
        metadata={"source": "langchain_docs", "topic": "overview"},
    ),
    Document(
        page_content="LangGraph is a library for building stateful, multi-actor applications with LLMs.",
        metadata={"source": "langgraph_docs", "topic": "overview"},
    ),
    Document(
        page_content="Vector stores are databases optimized for storing and searching embeddings.",
        metadata={"source": "vector_guide", "topic": "database"},
    ),
    Document(
        page_content="RAG combines retrieval with generation for more accurate LLM responses.",
        metadata={"source": "rag_guide", "topic": "architecture"},
    ),
    Document(
        page_content="Embeddings convert text into numerical vectors for semantic similarity.",
        metadata={"source": "embeddings_guide", "topic": "fundamentals"},
    ),
    Document(
        page_content="Chroma is an open-source embedding database for AI applications.",
        metadata={"source": "chroma_docs", "topic": "database"},
    ),
    Document(
        page_content="FAISS is a library for efficient similarity search developed by Facebook.",
        metadata={"source": "faiss_docs", "topic": "database"},
    ),
    Document(
        page_content="Pinecone is a managed vector database service for production workloads.",
        metadata={"source": "pinecone_docs", "topic": "database"},
    ),
]

Distribución de topics (memorízala, todos los números posteriores dependen de ella): 4 × database (vector_guide, chroma_docs, faiss_docs, pinecone_docs) · 2 × overview · 1 × architecture · 1 × fundamentals.

Tres notas sobre esas nueve primeras líneas. El import es langchain_chroma, no langchain_community: la Parte 2 lo señaló como una trampa en el momento de instalar y este es el fichero que rompe. load_dotenv() se ejecuta en la línea 9, antes de que la línea 11 construya el cliente de embeddings, que es el único orden que funciona porque el SDK lee OPENAI_API_KEY del entorno del proceso al construirse. Y shutil, en la línea 6, se importa y nunca se usa; es peso muerto, no una pista de que algo limpie después.

Construir y consultar lo básico son tres líneas de trabajo real:

Python
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py:50-68
def chroma_basics():
    with tempfile.TemporaryDirectory() as tmpdir:
        # create vector store from documents
        vectorstore = Chroma.from_documents(
            documents=SAMPLE_DOCS, embedding=embeddings_model, persist_directory=tmpdir
        )
        print(
            f"Vector store created {vectorstore._collection.count()} documents and persisted."
        )

        # perform similarity search
        query = "What is LangChain?"
        results = vectorstore.similarity_search(query, k=2)

        print(f"Top 2 results for query '{query}':")
        for i, doc in enumerate(results):
            print(
                f"Result {i+1}: {doc.page_content} (Source: {doc.metadata['source']})"
            )

Fíjate en el hábito de impresión, que se repite en todas y cada una de las funciones de demo del fichero: se añade el metadato source a cada resultado. Él nunca lo comenta. Adóptalo igualmente.

Tres avisos sobre el andamiaje que el capítulo despacha como código repetitivo —«así que aquí nada nuevo, la verdad» 01:17:50—:

  • tempfile.TemporaryDirectory() significa que cada ejecución vuelve a generar los embeddings de todo el corpus. Son ocho

documentos de juguete, así que aquí no se nota. Con el tamaño de un corpus real es una factura de API y un muro de latencia en cada ejecución. Usa un persist_directory estable en cuanto tu corpus deje de ser de juguete.

  • vectorstore._collection.count() mete la mano en un atributo privado. Funciona con

langchain-chroma 1.1.0, pero no es API pública. En el código que pienses conservar, mejor len(vectorstore.get()["ids"]).

  • El bloque __main__ viene con todas las llamadas comentadas. Ese es todo el modelo de ejecución

del curso para estos ficheros de pruebas: descomentar una función, ejecutar, volver a comentar 01:18:52. Si clonas el repo y no pasa nada, es por eso.

La persistencia, cuando estés listo para ella, es el mismo objeto con una ruta real, y con una incoherencia de nombres realmente desagradable:

Python
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py, lines 153-179.
# Two print statements (lines 164 and 179) elided; everything else is verbatim.
def persist_chroma():
    persist_dir = "./chroma_db/"

    vectorstore = Chroma.from_documents(
        documents=SAMPLE_DOCS,
        embedding=embeddings_model,
        persist_directory=persist_dir,
    )

    original_count = vectorstore._collection.count()
    print(f"Persisted vector store with {original_count} documents.")

    # simulate restart - load from disk
    del vectorstore

    reloaded = Chroma(
        embedding_function=embeddings_model,
        persist_directory=persist_dir,
    )

    reloaded_count = reloaded._collection.count()
    print(f"Reloaded vector store with {reloaded_count} documents.")

    # verify search still works
    results = reloaded.similarity_search("LangChain", k=2)

Las tres últimas líneas son todo el sentido de la función: la recarga no pasa ningún documento, solo el mismo directorio y el mismo embedding model, y similarity_search sigue funcionando. Eso es lo que te da la «persistencia»: los vectores estaban en disco, no en el proceso.

Cómo leer los scores: la trampa de distancia frente a similitud

El capítulo 8 dura seis minutos y existe casi por completo para esta única corrección.

La variante de la búsqueda con score recibe los mismos argumentos y devuelve un tipo distinto:

Python
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py:71-87
def similarity_search_with_scores():
    with tempfile.TemporaryDirectory() as tmpdir:
        # create vector store from documents
        vectorstore = Chroma.from_documents(
            documents=SAMPLE_DOCS, embedding=embeddings_model, persist_directory=tmpdir
        )

        # perform similarity search with scores
        query = "Explain vector stores."
        results_with_scores = vectorstore.similarity_search_with_score(query, k=3)

        print(f"Top 3 results with scores for query '{query}':")
        for i, (doc, score) in enumerate(results_with_scores):
            final_score = 1 / (1 + score)  # Convert distance to similarity
            print(
                f"Result {i+1}: {doc.page_content} (Score: {final_score:.4f}, Source: {doc.metadata['source']})"
            )

similarity_search devuelve List[Document]. similarity_search_with_score devuelve List[Tuple[Document, float]]. Por eso la cabecera del bucle cambia de for i, doc in enumerate(results) a for i, (doc, score) in enumerate(results_with_scores). Reutilizar el cuerpo del bucle sin score sobre los resultados con score lanza un AttributeError sobre una tupla: es la forma más habitual en que esta API se le rompe a la gente. (Fíjate en que el nombre del método está en singular, ..._with_score, mientras que la función de demo que lo envuelve está en plural, ..._with_scores. Errata fácil). El método también acepta un kwarg where_document= junto a filter=: la misma idea aplicada al contenido del chunk en lugar de a los metadatos, p. ej., {"$contains": "OAuth"}. El curso no lo usa nunca; a veces es la forma más barata de imponer una restricción de string exacto que la búsqueda vectorial por sí sola no respetará.

Ahora, los números. Query "Explain vector stores.", k=3, y la ejecución produce:

PosiciónDocumentoDistancia en brutoDespués de 1/(1+d)
1 (la mejor)el documento de vector stores (vector_guide)0.6612≈ 0.6019
2Pinecone (pinecone_docs)no se dice—
3 (la peor)el documento de embeddings (embeddings_guide)1.34≈ 0.4274

Y la objeción que el instructor plantea en nombre del alumno 01:18:52: ¿por qué 0.66 es un score mejor que algo por encima de 1?

Distancia y similitud son dos polaridades opuestas sobre la misma geometría:

DistanciaSimilitud
Coincidencia perfecta01
Dirección de «mejor»hacia abajohacia arriba
Rango0 → sin límiteaproximadamente (0, 1]
Forma del umbralif score < Tif score > T
Ordenascendentereverse=True

01:19:53 — «Si fueran scores de similitud, los unos serían muy similares, ¿verdad?»

La conversión. Si quieres un número normalizado en el que más alto sea mejor, basta con una línea 01:20:55:

Python
final_score = 1 / (1 + score)   # distance -> similarity, vector_stores.py:84

Transforma la distancia 0 en 1.0, es monótona decreciente, empuja las distancias grandes hacia 0 y conserva exactamente el orden. Distancia 0.6612 → ≈0.6019; distancia 1.34 → ≈0.4274.

La polaridad depende de cada store, y los umbrales no se trasladan. «Algunos vector stores sí calculan la distancia de similitud» 01:19:53; es decir, algunos backends te dan directamente una similitud. Pasar de Chroma a pgvector, Pinecone o FAISS puede invertir el operador de comparación que necesitas. Así que el procedimiento práctico para cualquier score que no hayas visto nunca es:

  1. Mira el número asociado al resultado mejor clasificado.
  2. ¿El número más pequeño está arriba? → tienes distancias; más bajo es mejor.
  3. ¿El número más grande está arriba, tendiendo a 1? → tienes similitudes; más alto es mejor.
  4. Confírmalo con el docstring del propio método, que suele ser explícito. El de

Chroma.similarity_search_with_score de LangChain lo dice con todas las letras: «distance in float for each. Lower score represents more similarity».

  1. ¿Necesitas una relevancia normalizada de 0 a 1? Aplica 1/(1+distance), o fija el espacio de la colección y

usa similarity_search_with_relevance_scores.

  1. Repite los pasos 1–4 cada vez que cambies de vector store. La respuesta no es trasladable.

Es el mismo problema con el que se topa la búsqueda híbrida de la Parte 6 a escala industrial: los scores de BM25 y los scores vectoriales viven en escalas que no se pueden comparar, y justo por eso la fusión por rango recíproco (RRF) tira los scores y fusiona los rankings.

La variante con score también es un instrumento de medición, no solo una llamada de retrieval. Es su uso de más valor y el capítulo nunca lo menciona. Como el score es un número, puedes dejar fija la query, construir dos stores que solo se diferencien en una cosa —chunker, dimensión, estrategia de contextualización— y comparar los scores con k=1 entre ellos. Así es exactamente como se evalúa a sí mismo el código de retrieval avanzado que aparece más adelante en el curso: fcc-production-rag-part-6/02_contextual_retrieval.py llama a similarity_search_with_score(query, k=1) contra un store original y un store contextualizado e imprime los dos scores uno al lado del otro. La regla 3 («prueba tu retrieval por separado») deja de ser un eslogan en cuanto tienes ese arnés.

Filtrado por metadatos: precisión gratis

En 01:20:55 el capítulo da un giro: «vamos a ver el filtrado por metadatos, porque es otro concepto importante que tener en nuestro arsenal». Trátalo como la segunda mitad del capítulo, al mismo nivel que la primera, no como un apéndice. Es la palanca de precisión más barata de toda la guía: ninguna llamada extra a un modelo, ninguna latencia extra relevante, un kwarg más.

La demo está planteada como un A/B controlado: misma query, mismo k, una sola variable cambiada:

Python
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py:90-116
def metadata_filtering():
    with tempfile.TemporaryDirectory() as tmpdir:
        # create vector store from documents
        vectorstore = Chroma.from_documents(
            documents=SAMPLE_DOCS, embedding=embeddings_model, persist_directory=tmpdir
        )

        query = "What databases are available?"

        # without metadata filtering
        results = vectorstore.similarity_search(query, k=5)
        print(f"Results without metadata filtering for query '{query}':")
        for i, doc in enumerate(results):
            print(
                f"Result {i+1}: {doc.page_content} (Source: {doc.metadata['source']})"
            )

        # with metadata filtering
        filter_criteria = {"topic": "database"}
        filtered_results = vectorstore.similarity_search(
            query, k=5, filter=filter_criteria
        )
        print(f"\nResults with metadata filtering for query '{query}':")
        for i, doc in enumerate(filtered_results):
            print(
                f"Result {i+1}: {doc.page_content} (Source: {doc.metadata['source']})"
            )

Mismo método, un kwarg más. No llamas a una función distinta 01:21:56: sigue siendo similarity_search, más filter=. Los criterios de filtrado son «un objeto o un diccionario»: las claves son nombres de campos de metadatos adjuntados en la ingesta y los valores son la coincidencia exigida.

El resultado, y el hallazgo principal:

Ejecuciónk pedidoResultados devueltosQué volvió
Sin filtro554 documentos database + el documento de RAG (topic: architecture)
filter={"topic": "database"}54vector_guide, chroma_docs, faiss_docs, pinecone_docs

Cuatro, porque exactamente cuatro de los ocho SAMPLE_DOCS llevan topic: "database" 01:22:58. El filtro es un predicado por documento que se evalúa como una puerta sobre el conjunto de candidatos; recorre la lista en voz alta en 01:23:59: este es database, se añade; este es database, se añade; este es fundamentals, se descarta; este es architecture, se descarta.

Lo que quitó el filtro es toda la lección. Sin filtro, el hueco n.º 5 fue para el documento de RAG —«RAG combines retrieval with generation for more accurate LLM responses», etiquetado topic: architecture—. Está semánticamente cerca de «What databases are available?» —trata del mismo stack tecnológico, comparte vocabulario— y la similitud vectorial pura lo sacó a la superficie sin problema. No responde a la pregunta.

La proximidad semántica no es corrección temática. El embedding dice «cerca». Tu usuario preguntó «cuáles». Son preguntas distintas, y el vector store no sabe distinguirlas.

Ese hueco es la semilla de todo lo de la Parte 6: el reranking, el retrieval híbrido y la reescritura de queries existen porque el vecino más cercano en el espacio de embeddings, con frecuencia, no es la respuesta correcta. El filtrado por metadatos es la más barata de esas soluciones y la primera a la que recurrir, pero solo si hiciste el trabajo antes.

Una capa más arriba: el retriever

vector_stores.py contiene una función más que el capítulo 8 no narra, pero que es el puente hacia la Parte 5, así que tómala como una referencia adelantada y no como una lección:

Python
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py — the two retriever
# constructions from as_retriever(), lines 129-133 and 141-145. Print loops elided.
# plain similarity retriever
retriever = vectorstore.as_retriever(
    search_type="similarity", search_kwargs={"k": 3}
)
docs = retriever.invoke("How do I build AI applications?")

# MMR retriever — diversity instead of pure proximity
mmr_retriever = vectorstore.as_retriever(
    search_type="mmr",
    search_kwargs={"k": 3, "fetch_k": 5},  # fetch 5 docs and return 3 diverse
)
mmr_docs = mmr_retriever.invoke("vector databases and embeddings")

as_retriever() envuelve el store en la fina fachada que nombró la Parte 1: el objeto con el que se compone una chain de LCEL. k y filter reaparecen dentro de search_kwargs. search_type="mmr" (maximal marginal relevance) obtiene fetch_k candidatos y devuelve k diversos, que es la respuesta estándar a «mis 5 primeros resultados son cinco casi-copias del mismo párrafo». Un ajuste realista es fetch_k ≈ 4–10× k; fetch_k=5 sobre un corpus de 8 documentos no deja casi margen para la diversidad, así que la demo publicada no puede mostrar bien el efecto.

Checklist y decisiones que tomar

Decisiones que tienes que tomar antes de generar ningún embedding

DecisiónPor defectoCámbiala cuando
Embedding modeltext-embedding-3-smallla calidad del retrieval medida diga lo contrario
Dimensiones1536 (franja: 768–1536)3072 para precisión a 6.5× el precio; 384 por huella
Dónde vive el string del modelouna única constante a nivel de módulonunca: esto no se negocia
StoreChroma con un persist_directory realla Parte 10 trata pgvector/Supabase a escala
Esquema de metadatoscomo mínimo source + topicañade tenant/acceso/fecha/versión antes de la ingesta
Espacio de distanciael l2 por defecto de Chromaelige cosine al crear la colección o nunca
Polaridad del scoreverifícala empíricamente en cada storecada vez que cambies de backend
Idempotenciaids= explícitos / upsertnunca confíes en add/from_documents para deduplicar

Dos de esas filas son irreversibles sin reindexar: el embedding model y el espacio de distancia. Otra más es irreversible sin repetir la ingesta: el esquema de metadatos. Dedica ahí tu tiempo de reflexión y trata el resto como ajustable.

Checklist previa

  1. El embedding model se declara una vez, a nivel de módulo, y lo leen tanto el camino de indexación

como el de query. Ningún string de modelo en línea en ninguna parte.

  1. El id y la versión del modelo se registran dentro de la colección, y al arrancar se comprueba que

el modelo configurado coincide con aquel con el que se construyó la colección. langchain-chroma te da el hueco gratis —collection_metadata= se escribe en la colección al crearla—, así que no hay excusa para un índice cuya procedencia no se puede saber:

Python
   EMBEDDING_MODEL = "text-embedding-3-small"

   vectorstore = Chroma.from_documents(
       documents=chunks,
       embedding=OpenAIEmbeddings(model=EMBEDDING_MODEL),
       persist_directory=PERSIST_DIR,
       collection_metadata={"embedding_model": EMBEDDING_MODEL},
   )

Cada vez que la vuelvas a abrir, lee esa clave —vectorstore._collection.metadata["embedding_model"], privada, pero es el único asidero disponible— y falla con estrépito si no coincide con EMBEDDING_MODEL. Un fallo al arrancar es la versión más barata posible de este bug; la alternativa es descubrirlo seis meses después por un ticket de soporte sobre «respuestas raras».

  1. La dimensión está en la franja de 768–1536, salvo que tengas una medición que justifique otra cosa.
  2. Sabes si tu store devuelve distancia o similitud porque ejecutaste una

query y miraste el número del resultado mejor clasificado, no porque lo dieras por hecho. Hazlo una vez, en un test, y deja que el test falle si una actualización de dependencias le da la vuelta.

  1. Ningún umbral de tu código compara un score sin un comentario que indique la polaridad y

el store contra el que se calibró.

  1. Cada print de resultados incluye doc.metadata['source'].
  2. Cada documento lleva todos los campos de metadatos por los que alguien podría querer filtrar alguna vez, incluidos los

de seguridad. No puedes añadirlos más tarde sin reindexar.

  1. El código aguas abajo soporta 0 ≤ len(results) ≤ k, nunca == k.
  2. La ingesta es idempotente: ids explícitos, semántica de upsert y una reejecución que no

duplica tu corpus.

  1. El store es persistente. Ningún TemporaryDirectory en ningún camino que ejecutes más de una vez.
  2. Las escrituras van en batches. Una llamada a upsert/add_documents por porción del corpus, no una por

documento.

  1. Tienes claro que el coste de embedding en tiempo de query es por request y recurrente, y hay un

plan (Parte 9) para cachearlo, con el id del modelo como namespace de la cache.

  1. Antes de tocar el prompt o cambiar de LLM, has impreso los chunks recuperados. Regla

3, siempre.

01:00:26 — «Calidad de los embeddings equivale a calidad del RAG. Acierta con esto o nada más importa».

La Parte 5 coge el store que acabas de construir, lo envuelve en un retriever, le cuelga una chain de LCEL y saca una respuesta real; y después te enseña a averiguar por qué esa respuesta está mal.