Por qué RAG se rompe en producción y cómo encajan las piezas
Ponerles nombre a los modos de fallo e instalar el mapa de punta a punta, la chain canónica y los seis invariantes.
Ya has construido RAG antes. Funcionaba. Hiciste la demo, las respuestas eran buenas, y luego lo apuntaste al corpus real y dejó de ser bueno — sin lanzar nunca una excepción, sin una sola línea roja en los logs, sin que se moviera ninguna métrica. Esa experiencia concreta es la premisa entera de esta guía, y es también como arranca el curso original 00:00:12. Su objetivo declarado es la transición del prototipo a producción, no una introducción a RAG — y esa distinción marca todo lo que sigue. No se te enseña qué es un embedding; se te enseña por qué el tuyo no se está recuperando.
Esta parte hace dos trabajos. Primero, nombra los fallos con la precisión suficiente para que cada parte posterior pueda señalar uno y decir esta es la caja que estoy arreglando. Segundo, instala el mapa — la imagen de extremo a extremo, la chain canónica de la que las quince partes restantes solo cambian un componente cada vez, y las seis invariantes que todo lo demás obedece. Lee esta parte una vez de forma lineal. Después, úsala como el índice al que vuelves cuando algo se rompe.
El precipicio: de diez documentos a diez mil
«Funcionaba con 10 documentos, pero entonces decides añadir 10,000 documentos y todo se rompió.» 00:00:12
El detalle que importa en esa frase es el que falta: el código no cambió. El mismo loader, el mismo splitter, el mismo embedding model, el mismo vector store, el mismo prompt. La única variable que se movió fue el tamaño del corpus, en un factor de mil, y el sistema pasó de útil a inútil.
El comentario que el instructor deja caer a continuación — «¿te suena?» 00:00:19 — también cumple una función real. Chocar con este muro es el resultado normal de seguir un tutorial, no la prueba de que hiciste algo estúpido. El muro es una propiedad de la arquitectura, no de tu disciplina.
Y no es un bug en el sentido al que estás acostumbrado. Es una propiedad de cómo se degrada RAG. Un corpus de diez documentos oculta todos los defectos de tu pipeline porque nada compite por los puestos del top-k. La base de conocimiento de la demo que verás más adelante en esta parte es un string Markdown de 1,010 caracteres dividido con chunk_size=500; después la demo recupera con k=2. Hiciera lo que hiciera el splitter, una fracción enorme del corpus entero acaba en el prompt en cada pregunta. La respuesta correcta está ahí por casualidad. La calidad del retrieval no se está poniendo a prueba; se está esquivando.
Con diez mil documentos — fácilmente cientos de miles de chunks — cada uno de esos defectos se vuelve decisivo. Ahora hay miles de chunks que tratan plausiblemente de tu query, y la función de ranking tiene que acertar de verdad. Un chunk cortado a mitad de frase ahora pierde frente a un competidor que no lo estaba. Una query formulada con el vocabulario del usuario ahora pierde frente a documentos redactados con el vocabulario de la empresa. Nada da error. El sistema simplemente empieza, en silencio, a responder a partir de los dos chunks equivocados.
La afirmación del 90% y la mitad que merece la pena conservar
«El 90% de los sistemas [RAG] que hay por ahí fracasan en producción.» 00:00:22 «Y todos fracasan por las mismas razones.» 00:00:24
Sé honesto con lo que esto es. Es la estimación de campo del instructor a partir de su experiencia docente, enunciada sin más y sin ninguna cita, y el README de la Parte 6 la reformula como *«por qué el 90% de los proyectos RAG fracasan en producción»* — proyectos en la fuente escrita, sistemas en el audio. La misma afirmación, dos sustantivos, ningún estudio detrás de ninguno de los dos. No la lleves a un documento de diseño como si fuera un hecho.
La segunda cláusula es la que se gana su sitio. Si los fallos de RAG fueran idiosincrásicos — si cada sistema roto se rompiera a su manera inédita — no podría existir ningún temario, checklist ni proceso de hardening. La razón por la que se puede escribir una guía como esta es que el conjunto de fallos es pequeño, finito y enumerable. El propio planteamiento del curso (el README de la Parte 6 atribuye la taxonomía a haber enseñado a más de 300K estudiantes y ver los mismos problemas una y otra vez) los cifra en cinco. Que el número real sea cinco o siete no es la cuestión; la cuestión es que está acotado, y un conjunto acotado de fallos se puede convertir en un procedimiento de diagnóstico.
Para quién es esto y qué se da por supuesto
El instructor deja caer en un inciso en 00:00:29 que el alumno al que se dirige ya ha construido sistemas RAG que no funcionan. Eso fija el nivel con precisión, y esta guía lo hereda:
| Requisito | Nivel |
|---|---|
| Python | Soltura con funciones, clases y gestión de paquetes |
| APIs | Conocimientos básicos de REST |
| LLMs | Útil, no imprescindible |
| Formación en ML / IA | No necesaria |
| GPU | No necesaria — todo el código se ejecuta en CPU; la única excepción (ColPali, Parte 16) es opcional |
No eres principiante construyendo. Eres principiante en hacer que lo que construyes sobreviva al contacto con un corpus real, usuarios reales, una factura real y un adversario real. Por eso esta guía no empieza con «qué es un embedding».
Hay algo más que vale la pena advertir en el planteamiento de la fuente antes de empezar a ponerle nombre a las cosas: la introducción hablada nunca menciona un vendor, un modelo ni una librería. Ni OpenAI, ni LangChain, ni Chroma — esos solo aparecen en el título del vídeo. Los modos de fallo se enuncian como propiedades de RAG, no de un stack. Por eso los diagnósticos de esta parte siguen valiendo aunque cambies todos los componentes: los arreglos son arquitectónicos, y solo los ejemplos de código tienen sabor a LangChain.
Procedencia y reglas de confianza para todo lo que sigue
Todo en esta guía deriva de una única fuente con defectos conocidos, y deberías conocer su forma antes de fiarte de cualquier cifra que aparezca en ella.
| Propiedad | Valor |
|---|---|
| Fuente | freeCodeCamp, Production RAG with LangChain & Vector Databases – Full Course, publicado el 2026-05-26 |
| Instructor | Paulo Dichone (más de 350,000 estudiantes, más de 70 cursos, construyendo IA en producción desde 2015 — según el README de la Parte 6, no se dice en el audio) |
| Duración | 07:38:38 repartidas en 32 capítulos |
| Transcripción | 10,598 líneas de subtítulos · 73,539 palabras, generada automáticamente |
| Vídeo | p.webm de 1.26 GB, AV1, 1920×1080, audio Opus |
| Repo complementario A | production-course-main-code — requires-python = ">=3.12", proyecto langc-course; su README.md está vacío (0 bytes) |
| Repo complementario B | fcc-production-rag-part-6 — requires-python = ">=3.13", proyecto fcc-production-rag, cabecera de requirements fechada en «April 2026»; el único README escrito en cualquiera de los dos repos |
Los dos capítulos de los que se nutre esta parte son los dos capítulos docentes más cortos del curso — el capítulo 1 dura 1 min 44 s / 276 palabras de puro encuadre, sin código y sin demo, y el capítulo 2 dura 6 min 43 s / 1,133 palabras de repaso de diapositivas, también sin programación en directo. Todo lo ejecutable que aparece abajo es el equivalente en el repositorio de lo que mostraban las diapositivas, abierto y leído en lugar de reconstruido a partir de la narración. Nada de esta parte lo tecleó el instructor en pantalla, y nada se reconstruyó a partir del audio.
Los pins exactos de dependencias, en ambos repos
production-course-main-code/pyproject.toml (requires-python = ">=3.12", nombre del proyecto langc-course):
dependencies = [
"langchain-community>=0.4.1",
"langchain>=1.2.7",
"langchain-anthropic>=1.3.1",
"langchain-core>=1.2.7",
"langchain-openai>=1.1.7",
"langgraph>=1.0.7",
"python-dotenv>=1.2.1",
"bs4>=0.0.2",
"pypdf>=6.6.2",
"langchain-ollama>=1.0.1",
"langchain-chroma>=1.1.0",
"rank-bm25>=0.2.2",
"langgraph-checkpoint-sqlite>=3.0.3",
"pytest>=9.0.2",
"fastapi>=0.129.0",
"uvicorn>=0.40.0",
]
fcc-production-rag-part-6/pyproject.toml (requires-python = ">=3.13", nombre del proyecto fcc-production-rag):
dependencies = [
"langchain>=1.2.0,<2.0.0",
"langchain-chroma>=1.1.0,<2.0.0",
"langchain-openai>=1.1.0,<2.0.0",
"langchain-text-splitters>=1.1.2",
"networkx>=3.6.1",
"openai>=2.32.0",
"python-dotenv>=1.0.0",
"tiktoken>=0.12.0",
]
El requirements.txt de la Parte 6 fija además langgraph>=1.1.0, chromadb>=1.5.0, langchain-classic>=1.0.0, pypdf>=6.0.0, pyvis>=0.3.2, pillow>=11.0.0, sentence-transformers>=5.0.0 y langchain-anthropic>=0.4.0 — las dependencias de grafos, visión y embeddings locales que solo necesita la Parte 16. Dos repos significan dos entornos virtuales; el material de la Parte 16 requiere de verdad el segundo.
Cuatro contradicciones concretas con las que te toparás si clonas los repos:
- El README dice Python 3.10+. Los ficheros
pyproject.tomlreales fijan ≥3.12 y ≥3.13. Fíate del código. - El README incluye Streamlit en el stack tecnológico. No aparece en ninguno de los dos ficheros de dependencias; el repo principal trae FastAPI + uvicorn en su lugar.
- El
git clone https://github.com/pdichone/production-rag-course.gitdel README y su estructuracode/part1-foundation/no coinciden con lo que se distribuye — el checkout de la Parte 6 es plano en la raíz del repo y supyproject.tomldeclaraname = "fcc-production-rag". - El paso 3 del README es
cp .env.example .env. Ninguno de los dos checkouts contiene un.env.example. El.envlo escribes desde cero; la Parte 2 te dice qué va dentro. (Los dos repos sí incluyen unuv.lock, así queuv— y no elpython -m venv+pipdel README — es como se construyó realmente este código. Esta guía usauven todo momento.)
El orden de construcción es una regla, no un temario
Cuatro verbos, en este orden 00:00:35:
- Construir — conseguir un pipeline que funcione de extremo a extremo.
- Depurar — averiguar por qué devuelve la respuesta equivocada.
- Optimizar — arreglar la calidad del retrieval.
- Escalar — solo ahora, hacerlo rápido y barato a gran volumen.
«Vamos a optimizar la calidad y después escalar para producción.» 00:01:00
El ecosistema de tutoriales se queda en el primer verbo. El orden de los otros tres es prescriptivo, no una cuestión de estilo. No puedes optimizar lo que no puedes observar, y por eso esta guía coloca la observabilidad antes de lo que lo hace el curso. Y no debes escalar lo que no has optimizado, por una razón que merece decirse sin rodeos:
Escalar un retriever de baja calidad produce respuestas equivocadas más rápido, en mayor volumen y a mayor coste. Escalar multiplica lo que ya tienes — incluido lo que está mal.
Combina los tres «retos que los tutoriales estándar ignoran» de la descripción del curso — escalado, depuración, seguridad — con el «optimizar la calidad» de la hoja de ruta, y obtienes los cuatro ejes en torno a los que se organiza la checklist de producción de esta guía:
| Eje | La pregunta que responde | Dónde se trata |
|---|---|---|
| Calidad | ¿Recupera y responde correctamente? | Partes 3–6 |
| Escala | ¿Sigue siendo correcto, rápido y asequible a gran volumen? | Partes 8–10 |
| Observabilidad / depurabilidad | Cuando se equivoca, ¿puedes averiguar por qué? | Partes 7, 13 |
| Seguridad | ¿Sobrevive a un usuario hostil? | Partes 12, 13 |
El curso original vota con su duración sobre cuál de ellos considera más difícil: el bloque de seguridad dura aproximadamente 67 minutos, el bloque individual más grande de un curso de 7 horas y media, y el capítulo de optimización, con 35 minutos, es el capítulo técnico individual más largo. Los fundamentos — todo aquello en lo que consisten la mayoría de los tutoriales — se llevan unos noventa minutos de las siete horas y media.
Los criterios de aceptación del propio curso para estar «listo para el deploy» son robusto, seguro, listo — fíjate en que rápido y barato no encabezan la lista, y es deliberado. La corrección bajo carga y la seguridad, sí.
Las seis partes de la fuente y las dieciséis de esta guía
El curso anuncia un arco de seis partes entre 00:00:44 y 00:01:44. Esta guía lo reorganiza en dieciséis partes, en orden de construcción, pero el arco es el mismo y merece la pena ver la correspondencia para que puedas encontrar el material original cuando lo necesites.
| Parte del curso | Tema | Su entregable | Esta guía |
|---|---|---|---|
| 1 | Construir los cimientos | Un pipeline RAG completo desde cero | Partes 2–5 |
| 2 | Depurar los fallos de RAG | Arreglar los 5 modos de fallo | Partes 3, 5, 7 |
| 3 | Optimizar la calidad | Chunking semántico, reranking, retrieval multi-query | Partes 3, 6, 9 |
| 4 | Escalar para producción | Caching, monitorización, bases de datos vectoriales de producción | Partes 7–10 |
| 5 | Proyecto de producción | Una aplicación RAG completa y lista para producción | Partes 11–13 |
| 6 | RAG avanzado 2026 | Agentic RAG, GraphRAG, contextual retrieval, multimodal | Partes 14–16 |
La Parte 1 del curso nombra cuatro primitivas fundamentales en el orden del pipeline — documentos, chunks, embeddings, vector stores 00:00:44 — y ese orden es en sí mismo el modelo mental de la fase de indexación: se carga un documento, se divide en chunks, se genera el embedding de cada chunk y los vectores acaban en un store. Las Partes 2–4 de esta guía ejecutan exactamente esa secuencia.
La Parte 6 del curso nombra cuatro técnicas punteras — agentic RAG 00:01:22, GraphRAG, contextual retrieval y multimodal RAG 00:01:44 — pero el repositorio trae seis ficheros de lección: long-context frente a RAG y late chunking se enseñan sin anunciarse. Las seis se cubren en las Partes 14–16.
Los cinco modos de fallo
Esta es la taxonomía a la que remite el resto de la guía. El instructor alude a ella entre 00:00:52 y 00:01:00 — «los cinco principales modos de fallo» — pero nunca los enumera en voz alta; la enumeración está en el README de la Parte 6, y se reproduce aquí junto con la parte de la guía que se encarga de cada arreglo.
| # | Modo de fallo | Qué ocurre | El arreglo | Dónde se trata |
|---|---|---|---|---|
| 1 | Chunking deficiente | Se recupera el contexto equivocado; chunks cortados a mitad de frase | Chunking semántico, overlap inteligente | Parte 3 |
| 2 | Desajuste de embeddings | El usuario dice «cancelar», los documentos dicen «política de rescisión» | Reescritura de la query, búsqueda híbrida | Partes 4–6 |
| 3 | Ruido en el retrieval | Se recuperan 10 documentos y solo 2 son relevantes | Reranking, filtrado | Parte 6 |
| 4 | Desbordamiento de contexto | Se mete demasiado en el prompt y el LLM ignora la mitad | Truncado inteligente, map-reduce | Parte 9 |
| 5 | Alucinación | La respuesta está en el contexto y aun así el LLM se inventa cosas | Prompts restringidos, citas | Esta parte; se detecta en la Parte 7, se prueba en la Parte 13 y se autoevalúa en la Parte 15 |
Léelos una vez con atención, porque la formulación está haciendo su trabajo.
1. Chunking deficiente. El splitter corta una frase, un bloque de código, una fila de una tabla o — lo peor — la mitad de un procedimiento. Después, el embedding model codifica fielmente el fragmento. No hay nada roto en ningún componente; el vector es una representación perfectamente precisa de una idea incompleta. La Parte 3 lo muestra con un documento de API de 50 páginas en el que la respuesta sobre OAuth2 queda a caballo entre los chunks 47 y 48, y ninguna de las dos mitades se puede recuperar como respuesta.
2. Desajuste de embeddings. El vocabulario del usuario y el del corpus son dialectos distintos. «Cancelar» y «política de rescisión» significan lo mismo para una persona y caen en vecindarios distintos del espacio vectorial. El retrieval puramente denso no tiene ningún ancla léxica que lo rescate. Los arreglos consisten en reescribir la query al dialecto del corpus y añadir un canal de palabras clave (BM25) que se fusiona de forma híbrida con el canal denso.
3. Ruido en el retrieval. Pediste diez chunks y dos son relevantes. Los otros ocho no son simplemente inútiles — son distractores activos que consumen presupuesto de contexto y le dan al modelo material equivocado pero de apariencia plausible a partir del que sintetizar. El arreglo es un reranker de segunda etapa y el filtrado por metadatos.
4. Desbordamiento de contexto. Resolviste el ruido recuperando más, y ahora el prompt es enorme y el modelo se salta la parte central. A partir de cierto punto, más contexto no significa más grounding. Los arreglos son un truncado consciente de lo que está descartando y estrategias map-reduce que resumen antes de sintetizar.
5. Alucinación. Esta es la que sorprende a la gente, por la formulación exacta: la respuesta está en el contexto y aun así el modelo inventa. No es un fallo de retrieval. El retrieval hizo su trabajo. Simplemente, nunca se le dijo al modelo que tenía prohibido ir más allá de lo que se le dio. El arreglo es un prompt restringido y citas — y es el arreglo más barato de toda la taxonomía, por eso se enseña en esta parte en lugar de aplazarlo.
La imagen de extremo a extremo
Este es el sistema completo, en el orden en que fluyen los datos por él en tiempo de query 00:01:44:
ASCII original
user query ──► retriever ──► vector store ──► context
│ │
└──────── question ────────────────────────┤
▼
prompt template
│
▼
LLM
│
▼
grounded response (+ citations)Cinco observaciones sobre esa imagen sostienen mucho de lo que viene después.
La query cumple dos papeles a la vez. Es a la vez lo que el usuario quiere que se le responda y la clave de retrieval — por eso aparece dos veces en el diagrama y solo una en la entrada. Un string, dos consumidores. Este doble papel es exactamente la razón por la que la pregunta tiene que atravesar el pipeline sin modificaciones; volveremos a ello cuando lleguemos a RunnablePassthrough.
Tres cosas convergen en el prompt template, y solo una sale de él. La pregunta, el contexto recuperado y las propias instrucciones del template se funden en un único string relleno. Ese string es el único artefacto que el modelo llega a ver. Todo lo demás del diagrama — el retriever, el store, los metadatos, tu cuidadoso scoring — existe únicamente para decidir qué entra en él. Si un dato no está en ese string, el modelo no lo tiene; si un marcador de cita no está en ese string, el modelo no puede citarlo.
El retriever es una fachada fina; el vector store es el motor.
«todo eso, por supuesto, lo mueve el vector store» 00:01:44
Un retriever es un objeto pequeño con un contrato invoke(question) -> list[Document]. Prácticamente no tiene inteligencia. Todas las propiedades que te importan — recall, latencia, soporte de filtros, capacidad híbrida — son propiedades del store y del índice que hay debajo. Cuando el retrieval es malo, no vayas a buscar en el retriever.
Generar embeddings no es indexar. 00:02:46 El instructor describe el store como algo que contiene documentos embebidos e indexados para la búsqueda, y esa «y» son dos propiedades distintas, no una reformulación:
- El embedding convierte texto en vectores. Es una elección de modelo: qué modelo, cuántas dimensiones, cuánto cuesta por millón de tokens.
- La indexación construye la estructura de búsqueda sobre esos vectores — HNSW, IVF. Es una elección de infraestructura con sus propios parámetros (
M,ef_construction,ef_search) y su propio compromiso entre precisión, velocidad y memoria.
Puedes tener embeddings excelentes dentro de un índice mal ajustado y obtener una búsqueda lenta y con poco recall. Puedes tener un grafo HNSW perfectamente ajustado sobre el embedding model equivocado y obtener disparates rápidos y seguros de sí mismos. Confundir ambas cosas es la razón por la que la gente «actualiza el embedding model» para arreglar un problema de latencia. Esta única frase es la semilla de todo el arco de ajuste de índices de la Parte 8.
La salida está *anclada en las fuentes* (grounded), y el grounding es una mitigación, no una cura.
«RAG ancla las respuestas de los grandes modelos de lenguaje en documentos reales, lo que reduce las alucinaciones» 00:02:46
El verbo es reduce. No elimina, no previene, no resuelve. Cualquier página de vendor, entrada de blog o revisión de arquitectura que afirme que RAG elimina la alucinación está equivocada, y el resto de esta guía — depuración, evaluación, validación de la salida, seguridad — existe precisamente porque lo que queda es lo bastante grande como para requerir ingeniería.
La chain canónica
Todo lo anterior se convierte en unas diez líneas de LCEL. Esta es la forma que verás en todas las partes de esta guía, y — esta es la afirmación importante — lo único que cambia en algún momento es lo que ocupa el hueco context.
# production-course-main-code/rag_pipeline.py — demo_basic_rag()
rag_chain = (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| prompt
| llm
| StrOutputParser()
)
Cuatro etapas: {context, question} → prompt template → LLM → output parser 00:02:46. Veámoslas de una en una.
Antes, fíjate de dónde vienen esos nombres. Merece la pena ver el bloque de imports una vez, porque todo lo de las Partes 2–6 sale del mismo conjunto y los principiantes pierden horas importando la clase correcta desde el paquete equivocado. Esta es la cabecera de rag_pipeline.py, sin editar:
# production-course-main-code/rag_pipeline.py
from langchain_openai.embeddings import OpenAIEmbeddings
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough, RunnableParallel
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain.chat_models import init_chat_model
from langchain_chroma import Chroma
from langchain_core.documents import Document
from langchain_text_splitters import RecursiveCharacterTextSplitter
from pydantic import BaseModel, Field
from typing import List
from dotenv import load_dotenv
import tempfile
Lee ese bloque como un mapa del ecosistema: langchain_core contiene las primitivas componibles (prompts, runnables, parsers, Document), langchain contiene la factoría independiente del proveedor init_chat_model, langchain_openai contiene los bindings de OpenAI, langchain_chroma contiene el store, y langchain_text_splitters es un paquete propio porque el splitting no depende de nada del resto. Chroma viene de langchain_chroma, no de langchain_community — la trampa señalada más arriba.
También contiene tres artefactos que vale la pena nombrar, porque tú producirás los mismos: OpenAIEmbeddings se importa dos veces desde dos rutas, ChatOpenAI se importa y nunca se usa (el fichero pasa por init_chat_model en su lugar), y RunnableParallel se importa y nunca se usa (el literal de diccionario lo cubre). Nada de eso rompe nada; todo ello es el aspecto que tiene un repo docente real. Fíate del código antes que del README, pero lee también el código con espíritu crítico.
Etapa 1: el literal de diccionario es un RunnableParallel implícito
«Esto llegará como entradas en paralelo, por supuesto.» 00:02:46
Ese {"context": ..., "question": ...} no es un diccionario de Python que se pasa como argumento. Dentro de un pipe LCEL, un literal de diccionario se convierte en un RunnableParallel: cada valor es un runnable, todos reciben la misma entrada y se ejecutan en paralelo. La salida es un diccionario con las mismas claves y los resultados de cada rama como valores.
Esto importa en lo mecánico y en lo conceptual. En lo mecánico, el retrieval no ocurre «antes» de que se procese la pregunta — ambas ramas consumen el mismo string de entrada de forma concurrente y se funden en un único diccionario, que es lo que consume el prompt template. En lo conceptual, pone el acrónimo entero en pantalla. La rama context es Retrieval (recuperación). El momento en que las dos ramas se funden en un diccionario es Augmentation (aumentación) — el instructor señala exactamente este paso y lo llama «parte del aumentado» 00:03:47. La etapa | llm es Generation (generación). Tres letras, tres posiciones en una sola expresión; si puedes señalar cada una de ellas en el código, entiendes lo que hace RAG, y si no puedes, ningún ajuste te va a ayudar.
«El contexto y la pregunta van a ir de la mano.» 00:02:46
Si prefieres la forma explícita — y deberías preferirla mientras aprendes, o cuando necesites dar nombre a las ramas para el tracing — chains_v1.py escribe lo mismo en versión larga con un retriever de pega, lo que aísla el concepto de passthrough de cualquier vector store. (El instructor presenta RunnablePassthrough con un «Si os acordáis» 00:03:47 — es un curso de producción, no LangChain 101, y se da por supuesta cierta familiaridad previa con LCEL. Esta guía parte del mismo supuesto, así que aquí va el repaso que él se salta.) Fíjate en que ahí el modelo se construye con init_chat_model(model="gpt-4o-mini", temperature=0) — cero, no el 0.2 de las demos de RAG, porque las demos de mecánica de chains buscan determinismo.
# production-course-main-code/chains_v1.py — demo_passthrough_chain()
prompt = ChatPromptTemplate.from_template(
"Original question: {question}\n"
"Context: {context}\n\n"
"Answer the question based on the context."
)
# simulate a retrieve operation
def fake_retriever(input_dict):
return " LangChain was created by Harrison Chase in 2022."
chain = (
RunnableParallel(
context=RunnableLambda(fake_retriever), question=RunnablePassthrough()
)
| RunnableLambda(
lambda x: {"context": x["context"], "question": x["question"]["question"]}
)
| prompt
| model
| StrOutputParser()
)
result = chain.invoke({"question": "Who created LangChain?"})
Fíjate en el RunnableLambda extra del medio. Como esta chain se invoca con un diccionario y no con un string a secas, RunnablePassthrough() reenvía el diccionario entero, de modo que la clave question contiene {"question": "..."} y hay que desenvolverla antes de que el prompt la vea. En rag_pipeline.py la chain se invoca con un string a secas (rag_chain.invoke(q)), así que el passthrough entrega directamente el string y no hace falta ningún paso de desenvoltura. El mismo operador, otro tipo de entrada, otra fontanería — este es el tropiezo más común de LCEL.
Etapa 1b: RunnablePassthrough significa «no toques esto»
«no modificar nada en lo que respecta a la pregunta» 00:03:47
En lo mecánico, reenvía su entrada sin cambios. En lo semántico, es un contrato, y la lectura semántica es la que merece la pena interiorizar: la formulación exacta del usuario tiene que llegar al prompt. Si en esta rama limpias, amplías, traduces o resumes la pregunta «para ayudar», has cambiado en silencio la pregunta que responde el modelo, y tu arnés de evaluación estará puntuando respuestas a una pregunta que el usuario nunca hizo.
Etapa 2: el prompt template transporta información e instrucciones
Dos placeholders, dos procedencias 00:04:49: {context} viene de la rama del retriever, {question} de la rama de passthrough. Pero el template no es solo un formateador de strings — es donde anclas el modelo a las fuentes, lo que significa que transporta tanto la información (los chunks recuperados) como las instrucciones (cómo comportarse con ellos). La siguiente sección trata por completo de esas instrucciones.
Etapas 3 y 4: el modelo, y el parser que no deberías saltarte
En rag_pipeline.py el modelo es gpt-4o-mini con temperature=0.2, construido mediante la factoría independiente del proveedor:
# production-course-main-code/rag_pipeline.py
llm = init_chat_model(model="gpt-4o-mini", temperature=0.2)
embeddings_model = OpenAIEmbeddings(model="text-embedding-3-small")
init_chat_model es la factoría independiente del proveedor: el identificador del modelo es un argumento de tipo string, así que cambiar OpenAI por Anthropic es una edición de un solo token y la chain que lo rodea no se mueve. Esa es la asimetría del invariante 2 hecha concreta — el modelo de generación es intercambiable, el modelo de embedding de la línea de abajo no lo es. Fíjate también en que este repo ejecuta sus demos de RAG con temperature=0.2 y sus demos de mecánica de chains con temperature=0; elige uno deliberadamente y déjalo por escrito, porque una temperatura distinta de cero hace que tus ejecuciones de evaluación no sean reproducibles.
.invoke() sobre un chat model devuelve un objeto mensaje, no un string — el texto está en .content, junto al uso de tokens y el motivo de parada. StrOutputParser() es el adaptador de una línea que lo desenvuelve, y lo que dice el instructor sobre los output parsers es «en la mayoría de los casos lo necesitamos» 00:02:46. La razón de más peso para mantener ese hueco es que es tu punto de control: cambia StrOutputParser por un parser estructurado y obtienes un objeto tipado en lugar de prosa. rag_pipeline.py demuestra exactamente eso, y merece la pena verlo ahora porque es la semilla de la capa de validación de la salida de la Parte 11:
Structured output — la misma chain con un contrato tipado en lugar de un string
# production-course-main-code/rag_pipeline.py — demo_structured_rag()
# (in the repo every name below is defined inside the demo function; the body is verbatim)
vectorstore = create_kb()
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})
class RAGResponse(BaseModel):
"""Structured RAG response."""
answer: str = Field(description="The answer to the question")
confidence: str = Field(description="high, medium, or low")
sources_used: List[str] = Field(description="List of sources referenced")
follow_up: str = Field(description="Suggested follow-up question")
structured_llm = llm.with_structured_output(RAGResponse)
prompt = ChatPromptTemplate.from_template(
"""
Based on the context below, answer the question.
Context:
{context}
Question: {question}
Provide a structured response."""
)
def format_docs(docs):
return "\n\n".join(
f"[{doc.metadata.get('source', 'unknown')}]: {doc.page_content}"
for doc in docs
)
rag_chain = (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| prompt
| structured_llm
)
result = rag_chain.invoke("What is LangGraph?")
print(f"Answer: {result.answer}")
print(f"Confidence: {result.confidence}")
print(f"Sources: {result.sources_used}")
Tres cosas que sacar de aquí. Primera: cuando la etapa final es with_structured_output(...), no hay StrOutputParser — el modelo estructurado ya devuelve una instancia de RAGResponse, y añadir aquí un parser de string lo rompería. Segunda: la única instrucción de ese prompt es «proporciona una respuesta estructurada»: el schema hace el trabajo que, si no, tendría que hacer la prosa, y precisamente por eso el structured output es más fácil de validar que el texto libre. Tercera: sources_used: List[str] hace que las citas vuelvan como datos y no como prosa que tendrías que extraer de un párrafo.
Una advertencia sobre ese campo confidence: es la autoevaluación del modelo, provocada por la descripción de un campo, no una probabilidad calibrada. Trátalo como una pista de enrutado (manda los low a una persona, o lanza un nuevo retrieval) y nunca como una medición. La confianza real sale de los scores de retrieval (Parte 4) y de la evaluación (Parte 7).
El fichero ejecutable completo, como referencia
Esta es la demo de principio a fin, para que veas dónde están la base de conocimiento, el splitter y la configuración del retriever respecto a la chain:
demo_basic_rag() y su base de conocimiento — el camino completo y ejecutable
# production-course-main-code/rag_pipeline.py
# (imports as listed earlier in this part)
load_dotenv()
embeddings_model = OpenAIEmbeddings(model="text-embedding-3-small")
KNOWLEDGE_BASE = """# LangChain Framework
... 1,010 characters of Markdown: Core Components, LangGraph, Pricing, Getting Started ...
"""
llm = init_chat_model(model="gpt-4o-mini", temperature=0.2)
def create_kb():
"""Create a vector store from knowledge base."""
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
doc = Document(
page_content=KNOWLEDGE_BASE, metadata={"source": "langchain_knowledge_base.md"}
)
chunks = splitter.split_documents([doc])
vector_store = Chroma.from_documents(
documents=chunks,
embedding=embeddings_model,
persist_directory=tempfile.mkdtemp(),
)
return vector_store
def demo_basic_rag():
vector_store = create_kb()
retriever = vector_store.as_retriever(
search_type="similarity", search_kwargs={"k": 2}
)
prompt = ChatPromptTemplate.from_template(
"""
Answer the question based only on the following context:
{context}
Question: {question}
Answer:
Make sure to answer in a concise manner,
and if you don't know the answer, just say "I don't know."""
)
def format_docs(docs):
return "\n\n".join([doc.page_content for doc in docs])
rag_chain = (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| prompt
| llm
| StrOutputParser()
)
questions = [
"What is LangChain?",
"Who created LangChain?",
"What is LangGraph used for?",
]
for q in questions:
answer = rag_chain.invoke(q)
print(f"Q: {q}")
print(f"A: {answer}\n")
Tres cosas en las que fijarse, y todas se convierten más adelante en capítulos:
metadata={"source": ...}se fija en el momento de la ingesta, antes del splitting. Es la única línea que hace posibles las citas en tiempo de query;split_documents()la propaga a cada chunk. Piérdela aquí y ningún código posterior podrá inventársela.persist_directory=tempfile.mkdtemp()significa que esta demo hace re-embed de todo el corpus en cada ejecución. Aceptable para una base de conocimiento de 1,010 caracteres; una factura real y un muro de latencia real a escala. Usa un directorio estable en cualquier cosa que vayas a ejecutar dos veces — este mismo antipatrón se repite en casi todos los ficheros de demo del repo.k=2en la demo básica,k=3en las demos de fuentes y de salida estructurada, y otra vezk=2en la demo de fallback. Son valores de demo elegidos para un corpus diminuto, no valores por defecto que debas heredar.
La base de conocimiento de la demo es un pequeño string Markdown sobre LangChain, y dos datos que contiene son clave para las demos: LangChain fue creado por Harrison Chase en octubre de 2022, y LangSmith tiene un plan gratuito, con planes de pago a partir de $39/month. Esos son el ground truth con el que se comprueban las demos de preguntas y respuestas — el dato de $39/month es en concreto la sonda dentro del corpus que usa la demo de fallback de más abajo.
Merece la pena leer la última función del fichero aunque esté etiquetada como ejercicio, porque es la primera vez que las ideas del capítulo se empaquetan como algo reutilizable en lugar de un script — un objeto que es dueño de su store, su retriever y su chain, y que expone un único método:
DocumentQA — la misma chain envuelta en una clase que de verdad podrías importar
# production-course-main-code/rag_pipeline.py — exercise_document_qa()
class DocumentQA:
def __init__(self, document: str, source_name: str = "document"):
# Split document
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
doc = Document(page_content=document, metadata={"source": source_name})
chunks = splitter.split_documents([doc])
# Create vector store
self.vectorstore = Chroma.from_documents(
documents=chunks,
embedding=OpenAIEmbeddings(model="text-embedding-3-small"),
)
self.retriever = self.vectorstore.as_retriever(search_kwargs={"k": 3})
# Create chain
self.llm = init_chat_model(model="gpt-4o-mini", temperature=0.2)
self.prompt = ChatPromptTemplate.from_template(
"""
Answer based on the context. Rate your confidence (high/medium/low).
Context: {context}
Question: {question}
Format: [Confidence: X] Answer"""
)
def format_docs(docs):
return "\n".join(d.page_content for d in docs)
self.chain = (
{
"context": self.retriever | format_docs,
"question": RunnablePassthrough(),
}
| self.prompt
| self.llm
| StrOutputParser()
)
def ask(self, question: str) -> str:
return self.chain.invoke(question)
Las mismas cuatro etapas, el mismo k=3, el mismo splitter 500/50. source_name es un argumento del constructor porque los metadatos los tiene que decidir quien llama en el momento de la ingesta — invariante: no puedes citar lo que no etiquetaste.
Dos advertencias antes de copiarla. Primera: en el repo esta clase se declara dentro de la función exercise_document_qa(), así que, pese a su forma, no se puede importar tal como está escrita; subirla al ámbito del módulo es tu primera edición.
Segunda: esta llamada a Chroma.from_documents(...) no pasa ningún persist_directory, así que el store vive en memoria y muere con el proceso. Cada construcción de DocumentQA(...) hace re-embed del documento entero y te lo cobra. Dale un directorio estable cuya clave sea un hash del contenido del documento, y la segunda construcción sale gratis.
El patrón de prompt contra las alucinaciones
El instructor enuncia este patrón tres veces en unos noventa segundos 00:03:47, 00:04:49, 00:05:51. Esa repetición es la señal. Son cuatro ingredientes:
- La cláusula de restricción — «Answer based only on the following context.» (responde basándote solo en el contexto siguiente).
- La cláusula de fallback — «If the context doesn't contain the answer, say 'I don't have information about that'» (o «I don't know»; es decir: si el contexto no contiene la respuesta, que lo diga con esa frase fija).
{context}— de la rama del retriever.{question}— de la rama de passthrough.
Eso es todo.
Por qué merece la pena hacerlo lo primero, antes que cualquier otra cosa de la guía: el prompt es la única palanca de grounding que no cuesta nada accionar. Cambiarlo no requiere ni reentrenar, ni reindexar, ni infraestructura nueva — editas un string, haces el deploy y el comportamiento cambia en la siguiente request. Todos los demás arreglos de esta guía (chunking semántico, búsqueda híbrida, reranking, contextual retrieval) requieren hacer re-embed de un corpus, levantar un componente, o ambas cosas.
«Esta es la fruta al alcance de la mano en lo que respecta al prompt engineering.» 00:05:51
Y el corolario, que es donde la mayoría de los profesionales se equivocan de verdad: es «la fruta al alcance de la mano... Y sin embargo mucha gente se olvida de ella o no le presta atención» 00:05:51. El fallo no es que la gente escriba una mala cláusula de restricción. Es que no escribe ninguna, y luego recurre al reranking y a mejores embeddings para arreglar un problema que dos frases de prompt habrían contenido.
El ejemplo práctico de la computación cuántica
Este es el ejemplo que hace que la idea cale 00:04:49. El mismo modelo, la misma pregunta, el mismo contexto (irrelevante o vacío). La única diferencia es una frase del prompt.
| Sin la instrucción | Con la instrucción | |
|---|---|---|
| Pregunta | «What is quantum computing?» | «What is quantum computing?» |
| Respuesta | «Quantum computing uses qubits…» — y luego sigue, inventando | «I don't have enough information pertaining to this topic.» |
| Corrección | Fluida, coherente, sin anclaje en las fuentes | Correcta |
Fíjate bien en lo que hace la salida fallida. Empieza con una afirmación verdadera. La computación cuántica sí usa qubits. La invención crece a partir de una semilla correcta, en el registro seguro de sí mismo habitual del modelo, en una prosa bien construida.
La alucinación suele empezar por una semilla verdadera. Eso es lo que hace que sea difícil detectarla leyendo.
De aquí salen dos reglas, y son la razón de que existan las Partes 7 y 13:
Negarse a responder es una funcionalidad que tienes que pedir explícitamente. Los modelos no se abstienen por defecto — su entrenamiento premia ser útil y seguir adelante. Un «no lo sé» honesto es la salida deseada en producción, no un fallo del sistema, y tienes que pedirlo por escrito.
Coherencia no es corrección.
«Aunque pueda sonar coherente, está alucinando, lo que significa que simplemente se está inventando cosas.» 00:04:49
Esta es la frase más transferible de todo el material original. Significa que no puedes hacer QA de un sistema RAG leyendo las respuestas. La fluidez es aquello para lo que está optimizado el modelo; no tiene correlación con el anclaje en las fuentes. Cualquier proceso de QA basado en «las respuestas tienen buena pinta» está midiendo la variable equivocada, y precisamente por eso esta guía coloca la observabilidad y las evals (Parte 7) por delante de las cosas tras las que se suelen poner, y por eso la checklist de la Parte 13 las convierte en tests con aserciones en lugar de dashboards que alguien quizá mire.
El patrón, en ejecutable
El prompt de demo_basic_rag() de más arriba ya incluye las dos cláusulas. La demo dedicada al fallback hace explícita la negativa y — esto es importante — trae un diseño de test que deberías copiar:
# production-course-main-code/rag_pipeline.py — demo_rag_with_fallback()
prompt = ChatPromptTemplate.from_template(
"""
Answer the question based ONLY on the following context.
If the answer is not in the context, respond with: "I don't have information about that in my knowledge base."
Context:
{context}
Question: {question}
Answer:"""
)
questions = [
"What is the pricing for LangSmith?", # In knowledge base
"What is the stock price of OpenAI?", # Not in knowledge base
"How do I deploy LangChain to AWS?", # Not in knowledge base
]
El resto de esa demo es la chain canónica sin cambios — un format_docs simple, un retriever con k=2, prompt | llm | StrOutputParser(). Lo único que difiere de demo_basic_rag() es el texto del prompt, y esa es la gracia: el comportamiento de negativa se compra entero con la segunda frase de un template.
Esa lista de preguntas es una sonda 1 dentro / 2 fuera, y es la versión ejecutable del contraste de la computación cuántica. Una pregunta que el corpus puede responder (el precio de $39/month de LangSmith), dos que no. Una ejecución correcta responde la primera y se niega a responder las otras dos. Un sistema que responde las tres está alucinando, y lo has descubierto en tres segundos sin un framework de evals.
Fíjate en que las dos preguntas fuera del corpus están elegidas con cuidado. «What is the stock price of OpenAI?» trata de una entidad cercana que el corpus menciona, y «How do I deploy LangChain to AWS?» trata del propio tema del corpus en una dirección que nunca cubre. Ambas son el tipo de casi-acierto para el que el retriever devolverá encantado algo. Una sonda hecha con preguntas sobre biología marina pasaría trivialmente y no te diría nada.
Fuentes, citas y la cadena de confianza
Un grounding que no puedes demostrar es solo una afirmación. Las fuentes son la prueba.
«queremos asegurarnos de que también añadimos algunas fuentes» 00:06:52
Un Document recuperado son dos campos: page_content (el texto del chunk) y metadata (un diccionario que lleva source — doc.pdf en el ejemplo de la diapositiva). Los metadatos no son decoración; son el canal de las citas, y solo existen si la ingesta los puso ahí.
format_docs frente a format_docs_with_sources
La diferencia son cuatro líneas, y es la diferencia entre un sistema que se puede auditar y uno que no.
# production-course-main-code/rag_pipeline.py — the sources-free formatter
def format_docs(docs):
return "\n\n".join([doc.page_content for doc in docs])
# production-course-main-code/rag_pipeline.py — demo_rag_with_sources()
def format_docs_with_sources(docs):
formatted = []
for i, doc in enumerate(docs):
source = doc.metadata.get("source", "unknown")
formatted.append(f"[{i+1}] {source}:\n{doc.page_content}")
return "\n\n".join(formatted)
Cada chunk se convierte en [n] <source>:\n<page_content>, y los chunks numerados se unen en un único string. Ese string es el {context} que lee el LLM. Cuatro líneas, cero llamadas extra a la API, ninguna dependencia nueva — el instructor acierta al llamarlo la forma canónica de hacer RAG con fuentes, y no hay ninguna razón defendible para poner en producción la primera versión en su lugar.
Además, el prompt tiene que pedirlas. La demo de fuentes hace las dos mitades:
# production-course-main-code/rag_pipeline.py — demo_rag_with_sources()
prompt = ChatPromptTemplate.from_template(
"""
Answer the question based on the context below. Include which sources you used.
Context:
{context}
Question: {question}
Answer (include sources):"""
)
rag_chain = (
{
"context": retriever | format_docs_with_sources,
"question": RunnablePassthrough(),
}
| prompt
| llm
| StrOutputParser()
)
Fíjate aquí en retriever = vectorstore.as_retriever(search_kwargs={"k": 3}) — tres chunks, así que tres fuentes numeradas. Y fíjate en que el final "Answer (include sources):" está haciendo un trabajo real: el formateador hace que la cita sea posible, el prompt hace que ocurra. Pon en producción uno sin el otro y no obtienes nada.
En el mismo repo vienen dos variantes de la misma idea con más sabor a producción, y merece la pena robar las dos:
# production-course-main-code/research_assistant.py — _format_docs_for_context()
def _format_docs_for_context(self, docs) -> str:
"""Format retrieved documents into a string for the prompt."""
if not docs:
return "No relevant documents found."
formatted = []
for i, doc in enumerate(docs):
source = doc.metadata.get("source", "Unknown")
formatted.append(f"[Source {i+1}: {source}]\n{doc.page_content}")
return "\n\n---\n\n".join(formatted)
Las mejoras respecto a la versión de la demo: una rama explícita para el resultado vacío (los retrievers devuelven [] más a menudo de lo que esperas — basta con un filtro de metadatos estrecho o un umbral de score agresivo, y un string vacío en {context} es una invitación a alucinar), y un separador --- visible para que los límites entre chunks no sean ambiguos para el modelo. La demo estructurada usa una tercera forma, f"[{doc.metadata.get('source', 'unknown')}]: {doc.page_content}", combinada con un campo sources_used: List[str] para que las citas vuelvan como datos y no como prosa.
Por qué importan de verdad las fuentes
«La razón por la que importan las fuentes es que los usuarios van a poder verificar esas respuestas.» 00:07:53
La cadena es: fuentes → citas → verificabilidad → confianza. Y el último eslabón es el que merece que pienses a fondo. Quien hace la verificación final es el usuario. El trabajo del sistema no es que le crean; es hacer que comprobar sea barato. Dale a alguien un nombre de fichero, una página y un encabezado, y comprobará tres respuestas al azar, verá que son correctas y empezará a confiar en el sistema. Dale un párrafo seguro de sí mismo sin procedencia, y tendrá que fiarse a ciegas o rehacer él mismo la investigación — y esa segunda opción es justo lo que el sistema venía a evitar.
Las citas reformulan la «exactitud» como «auditabilidad» — y la auditabilidad es una propiedad que puedes diseñar de verdad, mientras que la exactitud es una propiedad que solo puedes medir.
Hay además un segundo público, y es el que la gente olvida: el propio sistema. La procedencia es lo que permite al pipeline registrar qué documentos dieron lugar a qué respuesta, filtrar por permisos antes de la generación, deduplicar chunks casi idénticos y — algo crucial — depurar. El instructor lo formula como el monólogo interior del sistema:
«Así sabe: vale, tengo esta respuesta, pero ¿de dónde la he sacado?» 00:06:52
Fíjate en la pista sobre la granularidad que da en la misma frase — «basándose en este documento, en este encabezado, en este sitio». La granularidad de la fuente puede ser más fina que el fichero. Un splitter de encabezados Markdown que escribe la ruta de encabezados en los metadatos te da citas a nivel de sección gratis, que es una técnica de la Parte 3 con una motivación de la Parte 1.
El modelo mental: dos fases, un envoltorio, tres presupuestos
Todo lo que hay en las quince partes restantes modifica exactamente una caja de esta imagen. Cada parte te dirá cuál.
ASCII original
PHASE A — INDEX (offline, once per document, amortized)
Load ──► Split ──► [Contextualize] ──► Embed ──► Store + Index
Part 2 Part 3 Part 14 Part 4 Parts 4, 8, 10
PHASE B — QUERY (online, once per request, recurring)
Gate ──► Cache ──► Embed query ──► Retrieve ──► Fuse/Filter ──► Compress/Rerank
P12 P9,P11 P4 P4,P6,P16 P6 P6
──► Assemble prompt ──► Generate ──► Validate output ──► Return + citations
P1, P5, P9 P5, P11 P11 P1, P6
┌──────────────────────────────────────────────────────────┐
│ OBSERVABILITY (traces · metrics · evals · JSON logs) │
│ wraps everything, changes nothing Part 7 │
└──────────────────────────────────────────────────────────┘
Governed by three budgets, always in tension: QUALITY · LATENCY · MONEYLa división en dos fases es la distinción individual más útil de la ingeniería RAG, porque las dos fases tienen una economía completamente distinta. La Phase A se ejecuta una vez por documento y su coste se amortiza entre todas las queries futuras. La Phase B se ejecuta una vez por request, para siempre. Esa asimetría es una instrucción de diseño: empuja el trabajo hacia la izquierda. Todo lo que puedas precalcular en tiempo de indexación — resúmenes contextuales, metadatos extraídos, embeddings en cache, un segundo índice de palabras clave — te compra un camino de lectura más ligero a cambio de una factura única.
El envoltorio de observabilidad se dibuja fuera de las cajas a propósito. Lo observa todo y no cambia nada. Cuando la Parte 7 lo construye, el camino de fallo registra y vuelve a lanzar — una capa de monitorización que se traga una excepción, hace un retry o altera una respuesta ha dejado de ser monitorización y se ha convertido en lógica de negocio no documentada. La Parte 13 convierte después lo que el envoltorio puede ver en aserciones, que es el paso que la mayoría de los equipos se saltan: un dashboard que no despierta a nadie es decoración.
Los tres presupuestos son la razón por la que no hay respuestas correctas universales en esta guía. Cada técnica sobre la que vas a leer compra uno y gasta otro. El reranking compra calidad y gasta latencia y dinero. El caching compra latencia y dinero y pone en riesgo la calidad (datos obsoletos). Los embeddings más grandes compran calidad y gastan dinero, latencia y almacenamiento. Cada vez que una parte te da un valor por defecto, es un valor por defecto para un punto concreto de ese triángulo, y dice cuál.
Fíjate también en dónde coloca sus capas de hardening el pipeline de requests de producción — primero los rechazos baratos, al final la inferencia cara: Client → Rate limiter → Security (injection + PII) → Cache → Model (+retry +fallback) → Output validation → Metrics/logging → JSON response. Rechazar una request hostil o duplicada antes de que llegue a un LLM es la diferencia entre un incidente y una línea de log.
Las seis invariantes
Se cumplen en toda esta guía. Cuando una parte posterior parezca contradecir alguna, estará haciendo una excepción explícita y argumentada — y lo dirá.
1. La calidad se hereda hacia delante y nunca se recupera aguas abajo. Chunking → embeddings → retrieval → respuesta. Puedes tener el mejor embedding model, la base de datos vectorial más rápida y el LLM más listo, y aun así obtener basura si el chunking está mal. Depura la primera etapa rota, no el síntoma visible. El síntoma visible es casi siempre la respuesta; la etapa rota casi nunca es el generador.
2. Un solo embedding model, a ambos lados del pipe, para siempre. El mismo modelo tiene que generar los embeddings de tus documentos y de tus queries — y la versión importa. Cambiarlo invalida el índice entero. Las dimensiones que no coinciden fallan de forma ruidosa, que es el caso bueno. Misma dimensión con distinto modelo falla en silencio, porque los dos modelos no comparten sistema de coordenadas: tu búsqueda sigue devolviendo k resultados, ordenados con seguridad, y sin sentido. Fíjate en la asimetría: el modelo de generación se puede cambiar a voluntad; el modelo de embedding es una decisión de schema.
3. El coste en tiempo de indexación es único; el coste en tiempo de query se repite en cada request. Empuja el trabajo hacia la izquierda. Mantén ligero el camino de lectura.
4. Los fallos son silenciosos. Nada lanza excepciones. Tu tasa de errores puede ser un 0% impecable mientras tu corrección es pésima. Un retrieval que devuelve los chunks equivocados es un HTTP 200 correcto. Por eso en esta guía la observabilidad va antes de la optimización, y no después.
5. Cada capa es un «elige 2». El índice elige dos entre precisión / velocidad / memoria. La infraestructura elige dos entre dinero / carga operativa / control. La técnica elige dos entre calidad / coste / complejidad. Si un diseño parece ganar en los tres, es que todavía no has encontrado el eje en el que está gastando.
6. La monitorización observa y nunca debe cambiar el comportamiento. El camino de fallo registra y vuelve a lanzar.
Lo que la Parte 1 no resuelve
Tres cosas que esta parte deja abiertas deliberadamente, para que no las confundas con cuestiones resueltas:
- Los cinco modos de fallo son una taxonomía docente, no una partición. Los incidentes reales los combinan — el chunking deficiente provoca ruido en el retrieval, que a su vez provoca desbordamiento de contexto. Usa la taxonomía para nombrar la causa más temprana, no para clasificar el ticket.
- Las cifras de mejora que se citan más adelante son orientativas, no contractuales. El 67% menos de fallos de retrieval del contextual retrieval y el 10–12% de mejora de precisión del late chunking salen del README de la Parte 6, que no cita ni metodología ni corpus. Son hipótesis que debes probar con tus propios datos, y la Parte 14 las trata como tales.
- El curso original coloca la observabilidad después del escalado. Esta guía no. Todos los disparadores de escalado y de coste de las Partes 8–9 presuponen una instrumentación capaz de ver una latencia p95 o un recall que deriva. Enseñarlos en el orden original te deja con disparadores que no puedes medir. Es una reordenación deliberada, señalada aquí para que sepas que es nuestra.
Decisiones que tomar antes de la Parte 2
Resuélvelas ahora. Todas son caras de cambiar una vez que has generado los embeddings de un corpus.
- Elige tu embedding model — y apunta su string de versión exacto. Es una decisión de schema, no un valor de configuración (invariante 2). Decláralo una vez como constante a nivel de módulo; nunca pongas el string de un modelo directamente en el punto de llamada. La Parte 4 te da la tabla de dimensiones y precios para elegir.
- Diseña tu schema de metadatos antes de ingerir nada. Como mínimo,
source. Plantéate muy en seriopage,section/header,doc_type,created_aty una clave de tenant o de permisos. No puedes filtrar ni citar por un campo que no almacenaste, y el arreglo es una reindexación completa. - Decide si tu corpus es estructurado o fluido. Los encabezados y las secciones claras apuntan a chunking recursivo; el texto fluido no estructurado, en el que los temas cambian sin marcadores, apunta al semántico. La Parte 3 muestra un A/B medido en el que la técnica «mejor» pierde 1–4.
- Construye un corpus de evaluación a escala de producción, no a escala de demo. Si
kes una fracción significativa de tu corpus de prueba, tu retrieval está sin probar. - Escribe hoy la sonda fuera del corpus. Tres preguntas que tu corpus no puede responder de forma demostrable, más el string exacto de negativa, con aserciones en un test. Ponla en producción antes de la primera query real.
- Adopta el patrón de prompt como constante compartida. Cláusula de restricción + cláusula de fallback +
{context}+{question}. Una sola definición, importada en todas partes. - Elige
format_docs_with_sourcesen lugar deformat_docsdesde el primer commit. Añadir citas a posteriori significa añadir metadatos a posteriori, lo que significa reindexar. - Acuerda la regla de orden con quien sea responsable de la hoja de ruta: construir → depurar → optimizar → escalar. Déjalo por escrito antes de que alguien te pida que «simplemente lo escales» encima de un retriever que nadie ha medido.
Checklist de la Parte 1
Cada línea de esta lista se puede comprobar contra algo que existe — un fichero, un test, un grep — y no contra la sensación de haber entendido la sección.
- Los dos repos se clonan e importan:
uv run python -c "import langchain_chroma"funciona en cada uno de los dos entornos virtuales. git grep -n "langchain_community import Chroma"sobre tu propio código no devuelve nada.- Puedes escribir de memoria la chain canónica —
{"context": retriever | format_docs, "question": RunnablePassthrough()} | prompt | llm | StrOutputParser()— y explicar por qué el literal de diccionario es unRunnableParallel. - Nada en tu rama
questionmodifica el string. La reescritura de queries, si la haces, vive únicamente en la rama de retrieval. - Tu prompt template es una constante con nombre en un único módulo, incluye una cláusula de restricción y una cláusula de fallback, y la importan todos los servicios que hablan con el corpus.
- La cláusula de fallback nombra una frase de negativa exacta, y ese mismo string literal aparece en un fichero de test.
- Existe un test con al menos tres preguntas que tu corpus no puede responder de forma demostrable, con aserciones sobre ese string de negativa, y se ejecuta en CI.
- Tu ingesta fija
metadata["source"]en elDocumentantes desplit_documents(), y has impreso un chunk recuperado para confirmar que el campo sobrevivió al splitting. - Tu formateador emite marcadores
[n] <source>:dentro del string de contexto y tu prompt le pide al modelo que los cite. Las dos mitades, o no funciona ninguna. - Del último cambio que hiciste, puedes decir en qué caja del diagrama de dos fases vive y cuál de los tres presupuestos gastó.
- Puedes nombrar los cinco modos de fallo y la parte de esta guía que arregla cada uno, sin mirar.
- Has dejado de tratar una tasa de errores del 0% como prueba de nada.
Así plantea el propio instructor para qué sirve todo esto:
«Al final, tendrás un [RAG] listo para producción que funciona de verdad.» 00:01:44
Fíjate en que la formulación — que funciona de verdad — remite directamente a los sistemas que ya has construido y que no funcionaban. Ese es el contrato que hereda esta guía.
Siguiente: la Parte 2 prepara el taller —
uv, claves de proveedor, disciplina con el.env— y convierte documentos reales en unalist[Document]uniforme que lleva los metadatos que se convierten en estas citas. Como dice la fuente al final de esa misma frase: «Muy bien, vamos a construir.»