Tu primer sistema RAG real, y cómo depurarlo cuando miente
Montar la primera chain de punta a punta con LCEL y depurarla con método cuando responde mal.
Las Partes 2 a 4 construyeron las piezas por separado: un loader que convierte archivos en objetos Document, un splitter que los corta en chunks, un embedding model que convierte los chunks en vectores y una colección de Chroma que los almacena y los busca. Cada una de ellas era una función de demo independiente. Ninguna respondía a una pregunta.
Esta parte hace dos cosas, en el mismo orden que el curso original, porque el orden es la lección.
Primero ensambla: el capítulo 9 [01:24:32–01:33:16] conecta las cinco etapas en una única chain LCEL runnable que recibe un string y devuelve una respuesta. El instructor lo dice sin rodeos: no hay nada nuevo; son los mismos componentes de antes, ahora en un solo sitio 01:30:38. A este nivel, RAG es un problema de ensamblaje, no de algoritmos. Tendrás un sistema funcionando en unas cuarenta líneas.
Después destruye la ilusión: el capítulo 10 [01:33:16–01:53:46] es el capítulo de la ducha fría. La demo que acabas de construir responde bien a tres preguntas sobre un único string Markdown, y eso no demuestra prácticamente nada. El capítulo nombra las cinco formas en que el RAG de tutorial muere a escala y, sobre todo, enseña el método: cómo trabajar hacia atrás desde una respuesta errónea hasta la etapa que la produjo, cuando ninguna etapa lanzó una excepción.
Esa segunda mitad es la que la mayoría de ingenieros se salta y luego necesita a las dos de la madrugada. El Invariante 4 de la Parte 1 hace aquí todo el trabajo: los fallos son silenciosos. Tu tasa de errores puede ser un 0% impecable mientras tu corrección es pésima. El depurador no es un stack trace; es una disciplina.
La arquitectura de dos funciones
Abre rag_pipeline.py. Su forma se corresponde uno a uno con las dos fases del modelo mental de la Parte 1:
| Función | Fase | Se ejecuta | Perfil de coste |
|---|---|---|---|
create_kb() | Phase A — Index (offline) | Una vez por corpus | Único, amortizado |
demo_basic_rag() | Phase B — Query (online) | Una vez por pregunta | Recurrente, por request |
No es una elección de estilo. Es el Invariante 3 —el coste en tiempo de indexación es único; el coste en tiempo de query se repite— expresado como una frontera entre funciones de Python. Todo el trabajo que puedas mover de la segunda función a la primera, deberías moverlo.
El preámbulo del módulo prepara las dos cosas que tienen que ser globales:
# rag_pipeline.py:6-22 — the module preamble, verbatim (nothing removed)
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
load_dotenv()
embeddings_model = OpenAIEmbeddings(model="text-embedding-3-small")
Dos cosas en las que fijarse antes de seguir, porque ambas son trampas.
load_dotenv() se ejecuta en la línea 21, antes de que se construya OpenAIEmbeddings(...) en la línea 22. El SDK lee OPENAI_API_KEY del entorno del proceso en el momento de la construcción; invierte esas dos líneas y obtendrás un error de autenticación que parece una clave incorrecta.
Y embeddings_model es una constante a nivel de módulo, declarada exactamente una vez. Es el Invariante 2 hecho físico: un único embedding model, a ambos lados de la tubería, para siempre. Escribe el nombre del modelo en línea en algún punto de llamada y habrás creado un futuro bug de fallo silencioso: dos modelos con las mismas 1536 dimensiones producen vectores que se comparan sin dar error y se ordenan sin ningún sentido.
La base de conocimiento es un string, no un archivo
El corpus es una constante de string de Python, KNOWLEDGE_BASE (líneas 25–57): un documento Markdown de 1,010 caracteres sobre LangChain, que el splitter 500/50 convierte exactamente en tres chunks de 488, 414 y 123 caracteres. Su contenido importa, porque cada respuesta que produce la demo tiene que salir de aquí y de ningún otro sitio, y eso es lo que lo convierte en un test fixture útil; y su tamaño importa igual, porque un corpus de tres chunks no puede exhibir ni uno solo de los fallos de los que trata el siguiente capítulo:
| Dato en la KB | Se usa como |
|---|---|
| LangChain, creado por Harrison Chase, octubre de 2022 | Respuesta a la pregunta de prueba 2 |
| 5 componentes principales: Models, Prompts, Chains, Agents, Memory | Respuesta a la demo de fuentes |
| LangGraph: gestión de estado, ciclos y bucles, human-in-the-loop, persistencia | Respuesta a la pregunta de prueba 3 |
| LangSmith: plan gratuito, planes de pago desde $39/mes | La sonda dentro de la KB para la demo de fallback |
pip install langchain langchain-openai; «first chain in under 10 lines of code» | Relleno que no debe recuperarse |
Hay dos datos de ese split en los que merece la pena detenerse, porque ambos son diagnósticos que reutilizarás con tu propio corpus.
Primero, la aritmética: 488 + 414 + 123 = 1,025 frente a una fuente de 1,010 caracteres. Si los chunks suman más que la entrada, el overlap realmente se ha aplicado. Aquí se aplicó una vez: el chunk 2 termina en el encabezado ## Getting Started y el chunk 3 empieza repitiéndolo, 18 caracteres duplicados frente a los separadores que consumió el splitter, con un excedente neto de 15. Si los chunks suman menos que la entrada, todos los cortes cayeron sobre un separador y el overlap no te aportó nada.
Segundo, y menos cómodo: el corpus no es el fixture limpio que parece.
create_kb(): toda la ruta de indexación, en dieciocho líneas
# rag_pipeline.py:61-78
def create_kb():
"""Create a vector store from knowledge base."""
# split the knowledge base into chunks
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])
# create a vector store from the chunks
vector_store = Chroma.from_documents(
documents=chunks,
embedding=embeddings_model,
persist_directory=tempfile.mkdtemp(),
)
return vector_store
Ahí dentro hay cuatro decisiones, y tres de ellas son trampas.
1. chunk_size=500, chunk_overlap=50. Splitting recursivo a 500 caracteres con 50 de overlap —un 10%—, reutilizado de la Parte 3 sin volver a justificarlo. Es el valor por defecto de «todavía no tienes mejor información». No es una recomendación para tu corpus; la Parte 3 midió que el recursivo ganaba al semántico 4–1 en texto estructurado por encabezados, y los capítulos 10 y 14 tratan de ajustar estos dos números con evidencia.
2. El Document construido a mano. No hay ningún archivo que cargar, así que el instructor construye él mismo un Document con page_content= el string en bruto y metadata= un diccionario. Lo importante es su comentario al margen:
«como estoy creando yo mismo el documento, puedo pasarle metadatos como vimos antes» 01:25:36
Un Document no es más que una dataclass. Cuando un loader no te dé los metadatos que necesitan tus citas, construye tú el objeto y añádele lo que quieras. El valor de source aquí —langchain_knowledge_base.md— es ficticio; elige .md porque el string es Markdown, de modo que la atribución de fuentes posterior se comporta igual que lo haría con un archivo real.
3. split_documents([doc]), nunca split_text(...). Lo señala explícitamente ante la cámara en 01:25:36, y es la única razón de que exista el paso 2.
split_text(str)devuelve una lista de strings sin más. Los metadatos se destruyen.split_documents([Document, ...])devuelve una lista de Documents y **copia los metadatos
del padre en cada chunk**.
Envuelve el string en un Document para que split_documents tenga algo que propagar. Y fíjate en los corchetes: split_documents recibe una lista, incluso para un solo documento. Pasar el Document suelto es uno de los errores más comunes de esta API.
4. Chroma.from_documents(...) hace tres cosas en una sola llamada: genera el embedding de cada chunk con embeddings_model, escribe vectores + texto + metadatos en una colección y te devuelve un handle vivo al store. Solo documents y embedding son obligatorios.
La ruta de query
El retriever es un adaptador fino
# rag_pipeline.py:83-86
vector_store = create_kb()
retriever = vector_store.as_retriever(
search_type="similarity", search_kwargs={"k": 2}
)
Un vector store no es un componente de chain. .as_retriever() lo adapta a un Runnable cuyo contrato es str → List[Document], lo único que puede consumir una tubería LCEL. Aquí se usan dos parámetros, y vale la pena discutir los dos:
search_type="similarity": top-k simple de vecinos más cercanos. Las alternativas existen y
no se usan: "mmr" (con search_kwargs={"k": 3, "fetch_k": 5} en vector_stores.py, recupera cinco y devuelve tres diversos) y "similarity_score_threshold", que es la única que puede devolver menos de k cuando nada es lo bastante bueno.
search_kwargs={"k": 2}: dos chunks por query 01:26:36. (Los subtítulos automáticos transcriben
search_kwargs como «the quirs», un recordatorio útil de que el código del repo, no la transcripción, es la referencia para cada nombre de esta guía).
search_kwargs es también donde va un filtro de metadatos: {"k": 4, "filter": {"topic": "database"}} es la versión en forma de retriever de la llamada similarity_search(query, k=5, filter=...) de la Parte 4. Ninguna demo de este archivo usa uno, y conviene saberlo: el retriever que estás a punto de construir no tiene ningún guardrail temático.
init_chat_model, y la ruta de import en la que es fácil equivocarse
# rag_pipeline.py:58 (module level, immediately after KNOWLEDGE_BASE)
llm = init_chat_model(model="gpt-4o-mini", temperature=0.2)
En el vídeo, esta línea se escribe dentro de demo_basic_rag(); en el archivo del commit está a nivel de módulo, que es donde la quieres: un único cliente, compartido por las cuatro demos, construido una vez por proceso.
El instructor empieza a escribir ChatOpenAI, se detiene y cambia 01:26:36, y luego busca a la vista de todos el import —prueba langchain_core.chat_models, murmura «chat loaders»— antes de dar con él. La línea correcta es:
from langchain.chat_models import init_chat_model
No está en langchain_core. init_chat_model es una factoría agnóstica del proveedor: le das un string de modelo y te devuelve el objeto de chat model adecuado, sin importar ninguna clase específica del proveedor. La justificación que da es pura ergonomía —es más rápido de escribir 01:27:37—, pero el beneficio real es la asimetría del Invariante 2: el modelo de generación es intercambiable, así que merece un constructor intercambiable. El embedding model no lo es, así que recibe una constante de módulo fija en el código.
temperature=0.2, no el valor por defecto, y elegido explícitamente por determinismo 01:27:37. Fíjate en que es 0.2, no 0: se deja un pequeño margen de variabilidad. El razonamiento es de diagnóstico, no estético: si la temperatura del modelo es alta, dos ejecuciones de la misma pregunta producen respuestas distintas, y ya no puedes saber si una respuesta cambiada viene de tu cambio en el retrieval o del ruido del muestreo. Una temperatura cercana a cero es un requisito previo para poder depurar el retrieval. (chains_v1.py va más allá y usa temperature=0 en sus demos sin RAG).
El prompt: tres movimientos deliberados
# rag_pipeline.py:88-102
# RAG Prompt Template
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."""
)
ChatPromptTemplate.from_template() construye un chat prompt a partir de un único string de plantilla con variables de entrada {}. Las dos variables —{context} y {question}— se rellenan en tiempo de ejecución a partir de las claves del diccionario paralelo que precede al prompt en la chain. El instructor nombra el mecanismo explícitamente en 01:31:38: sustituir esas variables en tiempo de ejecución es el acto de anclar (grounding) el modelo.
Grounding = inyectar en el prompt, en tiempo de ejecución, la evidencia recuperada para que el modelo responda a partir de tus datos y no de sus pesos. Es una operación en tiempo de prompt. Sin reentrenamiento, sin fine-tuning, nunca.
Tres decisiones de diseño, cada una con un trabajo concreto:
- «based only on the following context»: la cláusula de restricción. Reduce la superficie
de respuestas válidas al texto recuperado.
- «answer in a concise manner»: control de la longitud de salida. Barato, y mantiene la respuesta
dentro de un presupuesto de tokens predecible.
- «if you don't know the answer, just say 'I don't know.'»: la vía de escape para rechazar.
La tercera es la que la gente omite, y omitirla es un bug. «Responde solo a partir del contexto» le dice al modelo lo que no puede hacer; no le dice qué hacer en su lugar. Sin una salida alternativa autorizada, un LLM al que se le pide que responda, responderá. El rechazo es un comportamiento que tienes que pedir explícitamente.
format_docs: el pegamento en la frontera de tipos
# rag_pipeline.py:104-106
# Format retrieved docs
def format_docs(docs):
return "\n\n".join([doc.page_content for doc in docs])
El retriever emite List[Document]. La plantilla de prompt necesita un str. format_docs es el adaptador: une el texto de cada chunk con una línea en blanco entre ellos para que las fronteras entre chunks sigan siendo visibles para el modelo 01:31:38.
La lección general va más allá de esta función: toda chain LCEL necesita pegamento en sus fronteras de tipos, y LangChain lo hace indoloro: una función de Python sin más colocada en una tubería | se convierte automáticamente en un RunnableLambda. Nunca escribes el wrapper. Nada en el código lo dice, y por eso hay que decirlo.
Esa conversión es un caso de la regla que hace legible todo el archivo. Cada componente de aquí —retriever, plantilla de prompt, chat model, output parser, tu propia función— implementa la misma interfaz Runnable: .invoke(), más .batch() y .stream() gratis. Como comparten una interfaz, | puede componer dos cualesquiera de ellos, y eso es todo lo que es LangChain Expression Language. La consecuencia práctica para depurar: cualquier posición de la chain se puede invocar por sí sola, con el mismo .invoke() que usas con la chain completa. Eso es lo que hace posible la bisección que veremos más adelante en esta parte.
El corazón: un literal de diccionario es un paso paralelo
# rag_pipeline.py:108-114
# Rag chain
rag_chain = (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| prompt
| llm
| StrOutputParser()
)
«Y aquí está el corazón. Aquí es donde creamos la rag chain propiamente dicha». 01:31:38
Un diccionario de Python normal dentro de una chain LCEL se convierte implícitamente en un RunnableParallel. La misma entrada —el string en bruto con la pregunta del usuario— se reparte a cada valor del diccionario, cada rama se ejecuta de forma concurrente y las salidas se recogen en un diccionario cuyas claves coinciden con las variables de entrada del prompt. Dos claves, dos ramas:
"context":question → retriever → List[Document] → format_docs → str"question":question → RunnablePassthrough() → the same question, untouched
RunnablePassthrough() es el Runnable identidad, y es estructural, no decorativo. El diccionario paralelo consume la entrada única; sin una rama identidad explícita, la rama de retrieval destruye la pregunta original y {question} se renderiza vacío (o la plantilla lanza un error de variable ausente). La forma en que lo expresa el instructor en 01:29:38 es exactamente la correcta: su trabajo es asegurarse de que la pregunta entrante no cambia.
Hay una segunda razón, más sutil, por la que tiene que ser un passthrough y no, por ejemplo, un reescritor: la redacción exacta del usuario es lo que se está respondiendo. Parafraséala en silencio y habrás cambiado la pregunta sin avisar a nadie.
StrOutputParser() cierra la chain desenvolviendo el objeto de mensaje del modelo en un string simple, de modo que rag_chain.invoke(q) devuelve algo imprimible 01:30:38.
El flujo de datos completo, tal como se narra en 01:31:38–01:32:39:
ASCII original
question (str)
→ {context: retriever | format_docs, question: RunnablePassthrough()} # parallel dict
→ prompt (ChatPromptTemplate fills {context} and {question})
→ llm (gpt-4o-mini, temperature=0.2)
→ StrOutputParser()
→ answer (str)El orden en la tubería tampoco es negociable. retriever | format_docs recupera y después convierte a string; inviértelos y format_docs recibirá un string que intentará recorrer. Los desajustes de tipo en una frontera | son el error LCEL de toda la vida.
Ejecutarlo
# rag_pipeline.py:116-128
# Test the RAG chain
# Test
questions = [
"What is LangChain?",
"Who created LangChain?",
"What is LangGraph used for?",
]
print("Basic RAG Demo:\n")
for q in questions:
answer = rag_chain.invoke(q)
print(f"Q: {q}")
print(f"A: {answer}\n")
Tres preguntas, un bucle simple, un .invoke() por pregunta. El objeto chain es reutilizable y no guarda estado entre invocaciones: sin memoria, sin historial de chat, cada pregunta totalmente independiente. En 01:30:38 las tres se responden correctamente.
Ese es todo el contrato del RAG básico: str → str, con el retrieval escondido dentro. También es el techo del RAG básico: sin memoria, sin citas, sin confianza, sin rechazo más allá de lo que pida el prompt.
Listado completo: demo_basic_rag() (rag_pipeline.py:81-128)
def demo_basic_rag():
vector_store = create_kb()
retriever = vector_store.as_retriever(
search_type="similarity", search_kwargs={"k": 2}
)
# RAG Prompt Template
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."""
)
# Format retrieved docs
def format_docs(docs):
return "\n\n".join([doc.page_content for doc in docs])
# Rag chain
rag_chain = (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| prompt
| llm
| StrOutputParser()
)
# Test the RAG chain
# Test
questions = [
"What is LangChain?",
"Who created LangChain?",
"What is LangGraph used for?",
]
print("Basic RAG Demo:\n")
for q in questions:
answer = rag_chain.invoke(q)
print(f"Q: {q}")
print(f"A: {answer}\n")
La revisión en seis pasos: relee tu propia chain en este orden
Cuando el instructor revisa la chain terminada en 01:31:38–01:32:39, la recorre en un orden fijo, y es un buen hábito porque sigue los datos y no el archivo fuente:
- Primero el prompt.
from_template, dos variables de entrada, sustituidas en tiempo de ejecución → grounding. - El formateador. ¿Cómo se convierten los documentos recuperados en un único string limpio?
- El diccionario de la chain.
contextyquestion: el corazón. ¿Qué rama consume la entrada
en bruto y cuál la conserva?
- La plantilla de prompt recibe el diccionario. ¿Coinciden exactamente las claves del diccionario
con las variables de la plantilla? Un desajuste aquí es el error en tiempo de ejecución más común en LCEL.
- El LLM recibe el prompt renderizado. ¿Qué modelo, qué temperatura?
- El parser convierte la respuesta en el tipo final.
StrOutputParserpara un string, o
with_structured_output para un objeto; nunca ambos.
Si no puedes narrar esos seis pasos de tu propia chain sin hacer scroll, la chain está haciendo algo que no tienes controlado.
Entorno, según el pyproject.toml del mismo repo: requires-python >=3.12 (y un pin de .python-version a 3.12), langchain>=1.2.7, langchain-core>=1.2.7, langchain-openai>=1.1.7, langchain-chroma>=1.1.0, langchain-community>=0.4.1, python-dotenv>=1.2.1. Fíjate en el paquete del vector store: langchain-chroma, no langchain-community. El README publicado del curso —que pertenece al segundo repo, fcc-production-rag-part-6, fijado a >=3.13— dice «Python 3.10+». Fíate de los pins, no de la prosa.
Tres mejoras que vienen en el mismo archivo
El vídeo del capítulo 9 se detiene en demo_basic_rag(), pero rag_pipeline.py contiene tres chains más que son puntos de partida claramente mejores para cualquier cosa real. Ninguna se muestra en cámara. Las tres merecen adoptarse desde el primer día.
1. Citas: las fuentes viajan dentro del string de contexto
# rag_pipeline.py:148-163 (demo_rag_with_sources, k=3)
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)
rag_chain = (
{
"context": retriever | format_docs_with_sources,
"question": RunnablePassthrough(),
}
| prompt
| llm
| StrOutputParser()
)
Cada chunk se convierte en [n] <source>:\n<page_content>, el prompt le pide al modelo «Include which sources you used», y la demo hace una sola pregunta —«What are the core components of LangChain?»—, cuya respuesta es la lista de cinco componentes de la KB. El mecanismo es lo importante: las etiquetas de fuente forman parte del texto que lee el LLM. No se pasan por un canal aparte ni se adjuntan como metadatos que el modelo nunca ve. Si el modelo no puede ver la etiqueta, no puede citarla.
Usar .metadata.get("source", "unknown") en lugar de ["source"] es programación defensiva deliberada: un chunk cuyo loader no estableció source se degrada al string unknown en lugar de lanzar KeyError en mitad de una request.
2. Fallback: forzar un string de rechazo que puedas buscar con grep
# rag_pipeline.py:176-210 (demo_rag_with_fallback, k=2)
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
]
La mejora respecto a «just say 'I don't know'» es que el rechazo es un string fijo y exacto. Eso convierte la abstención en algo medible: cuenta las apariciones de esa frase en tus logs y tendrás una tasa de rechazo. Un rechazo vago no se puede medir; uno canónico es una métrica.
Las tres preguntas de sondeo son un eval set en miniatura: una dentro del corpus (la línea de LangSmith a $39/mes) y dos fuera del corpus (la cotización de OpenAI, el deploy en AWS). Construye este set para tu propio corpus antes de construir nada más. Cuesta tres líneas y es lo único que se interpone entre tú y «parecía que funcionaba cuando lo probé».
3. Structured output: sustituir el parser por un esquema
# rag_pipeline.py:213-251 (demo_structured_rag, k=3)
def demo_structured_rag():
"""RAG with structured output."""
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)
# ...
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
)
Fíjate en lo que falta: no hay StrOutputParser(). with_structured_output(RAGResponse) hace que el modelo emita un objeto Pydantic validado, así que la chain termina en el modelo y result.answer / result.confidence / result.sources_used / result.follow_up son atributos, no texto que tengas que parsear, que es exactamente lo que imprime la demo tras invocar la chain con "What is LangGraph?". Esta es la forma que quieres en cuanto el RAG está detrás de una API (Parte 11) y no de un terminal.
El prompt que lo acompaña es deliberadamente escueto: «Based on the context below, answer the question… Provide a structured response.» Son los strings description= de los campos los que llevan las instrucciones. Ese es el patrón: con structured output, el esquema es parte del prompt, así que pon la redacción donde están los campos, no en una prosa que el modelo tenga que conciliar con un esquema.
confidence es autodeclarado y, por tanto, no es una probabilidad calibrada: trátalo como una señal débil para el enrutamiento (p. ej., «baja → escalar a una persona») y nunca como una garantía de corrección.
El ejercicio para el lector: DocumentQA, todo el pipeline en una sola clase (rag_pipeline.py:271-312)
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)
Se prueba con un texto breve de cuatro datos sobre Python (Guido van Rossum, primera versión en 1991, Python 3.12 publicado en octubre de 2023, nombre inspirado en Monty Python) y tres preguntas. Chunking 500/50, k=3, gpt-4o-mini a temperatura 0.2 y un formato de salida [Confidence: X] Answer.
Dos defectos que corregir antes de reutilizarlo. El store de Chroma se construye sin persist_directory: vive en memoria, desaparece al terminar el proceso y se vuelve a hacer re-embed en cada construcción. Y aquí format_docs une con "\n" en lugar de "\n\n", lo que fusiona visualmente los chunks adyacentes en lo que parece un único pasaje continuo; el doble salto de línea de demo_basic_rag existe precisamente para que las fronteras entre chunks sigan siendo visibles para el modelo.
La ducha fría
El capítulo 9 termina a mitad de frase, en la línea de planteamiento: seguiste un tutorial de RAG en internet y todo funciona 01:32:39. El capítulo 10 completa la frase en 01:33:18:
«en el momento en que añades 10,000 documentos, todo se rompe. Todo, absolutamente todo, se rompe».
Esa misma frase es el epígrafe del segundo repo del curso, fcc-production-rag-part-6: «Seguiste un tutorial de RAG. Funcionó con 10 documentos. Luego probaste con 10,000... y todo se rompió». La demo funcional del capítulo 9 está colocada deliberadamente como la línea base ingenua que los veintitrés capítulos restantes desmontan.
Léelo con atención, porque la forma de la afirmación es la clave del diagnóstico. Nada en el pipeline cambió. El código es idéntico. El chunk size es idéntico. El embedding model es idéntico. Lo único que cambió es el número de vecinos que compiten por los puestos del top-k.
Por eso el éxito con un corpus pequeño no es evidencia. Con diez documentos casi no hay nada detrás de lo que pueda esconderse una respuesta errónea: recupera dos de diez y tendrás el 20% del corpus en el contexto; recupera dos de diez mil y tendrás el 0.02%. Cada defecto de chunking, cada desajuste de vocabulario, cada debilidad de ranking queda enmascarado con una N pequeña y expuesto con una N grande.
La afirmación que vertebra el capítulo es el titular del curso: el 90% de los sistemas RAG fallan en producción, y todos fallan por las mismas cinco razones 01:33:18.
Los cinco modos de fallo
| # | Fallo | Síntoma que observas | Etapa rota | Solución | Se trata en |
|---|---|---|---|---|---|
| 1 | Chunking deficiente | La respuesta es parcial, o se basa en un fragmento que parece una frase a medias | Split | Fronteras semánticas + overlap | Parte 3 |
| 2 | Desajuste de embeddings (deriva semántica) | El chunk correcto existe y nunca se recupera; vocabulario del usuario ≠ vocabulario del documento | Embed / Retrieve | Búsqueda híbrida, reescritura de queries, contextual retrieval | Partes 6, 14 |
| 3 | Ruido en el retrieval | El chunk correcto sí se recupera, pero enterrado entre vecinos irrelevantes; la respuesta se diluye | Retrieve / Fuse | Reranking, filtrado, compresión | Parte 6 |
| 4 | Desbordamiento de contexto | Se recuperó todo; el modelo ignora la mitad y la respuesta se trunca | Assemble prompt | Truncado inteligente, presupuesto de tokens, map-reduce | Parte 9 |
| 5 | Alucinación | La respuesta contradice un chunk que se recuperó correctamente y se entregó correctamente | Generate | Prompts restringidos + citas (aquí), evals que la detectan (Parte 7), validación de la salida (Parte 12), retrieval autocorrectivo (Parte 15) | Partes 7, 12, 15 |
El instructor promete en 01:34:19 diseccionar, diagnosticar y corregir cada uno. En la práctica, el capítulo 10 corrige el n.º 1, disecciona el n.º 2 sin corregirlo, le pasa el n.º 3 al capítulo 11 y deja los modos n.º 4 y n.º 5 para más adelante. Conviene saberlo para no esperar dentro de este capítulo una resolución que nunca llega.
N.º 1: el chunking deficiente destruye el significado, en silencio
La definición operativa de un chunk bueno que usa el capítulo es semántica, no basada en el tamaño:
Un chunk es bueno si sigue significando algo por sí solo después de haber sido arrancado del documento.
El ejemplo de la diapositiva es una política de teletrabajo de RR. HH. cortada por el sitio equivocado:
- chunk A: «nuestra política permite hasta»
- chunk B: «3 días por semana individualmente»
Ninguno de los dos responde a «¿cuántos días de teletrabajo tengo?». El chunk A tiene el sujeto y no el número; el chunk B tiene el número y no el sujeto. El corte ha destruido el significado 01:35:20. El nombre técnico es contexto disjunto.
La propiedad crítica es que la capa de retrieval funciona perfectamente. Encuentra y devuelve fielmente el vector más cercano. Lo que está roto es la unidad que recupera. Es el Invariante 1 en su forma más cruda: depura la primera etapa rota, no el síntoma visible.
N.º 2: desajuste de embeddings: el usuario dice «cancelar», el documento dice «política de rescisión»
«Cuando las queries de los usuarios usan palabras distintas de las que aparecen en tus documentos, la búsqueda semántica falla». 01:45:32
Para una persona, las dos expresiones significan lo mismo. Para un embedding model pueden estar lo bastante separadas en el espacio vectorial como para que el chunk correcto no llegue nunca a entrar en el top-k: la query y el corpus no son, en palabras del instructor, congruentes 01:33:18.
Lo que hace que este sea especialmente desagradable es que es invisible desde la respuesta. El modelo te da una respuesta segura y bien formada construida a partir de los chunks equivocados, y no hay ninguna señal en ninguna parte de que existía un chunk mejor que se pasó por alto. El capítulo 10 no lo corrige: te lleva de visita por la mecánica (embedding individual → batch → coseno → ranking) para que veas numéricamente dónde se produce el fallo. Los remedios reales llegan más adelante: BM25 detecta el fallo léxico (Parte 6), la reescritura de queries genera el vocabulario que no usaste (Parte 6) y el contextual retrieval reescribe el propio chunk (Parte 14, con una mejora de precisión declarada del 15–20%).
N.º 3: ruido en el retrieval: los LLM sí se confunden
La ilustración de 01:33:18 es concreta y merece memorizarse como proporción: al retriever se le pide que traiga 10 documentos, devuelve obedientemente 10, y solo 2 son realmente relevantes.
La respuesta está ahí. Eso es lo que lo diferencia del n.º 2. El fallo es la dilución: ocho vecinos irrelevantes sentados junto a los dos buenos.
«Y entonces el LLM se confunde de verdad. Sí, los LLM se confunden». 01:52:41
Ese comentario de pasada corrige una suposición muy común y muy equivocada: que una context window más grande hace irrelevante la calidad del retrieval. Los chunks irrelevantes de más no son relleno gratuito; son distractores activos. Subir k para compensar un retriever débil lo empeora, no lo mejora.
N.º 4: desbordamiento de contexto
Se mete demasiado material en el prompt, el LLM ignora la mitad y las respuestas se truncan 01:34:19. Fíjate en el doble sentido que usa el instructor sin aclararlo: se trunca el contexto (límites duros de tokens) y se truncan las respuestas (al modelo se le acaba el presupuesto o la atención). Es el problema de lost-in-the-middle expresado de manera informal.
N.º 5: la alucinación sobrevive a un retrieval perfecto
«Los large language models son muy buenos alucinando porque son buenos ignorando el contexto aunque la respuesta esté justo ahí». 01:34:19
Por eso la alucinación figura como un modo de fallo propio y no como un síntoma de los otros cuatro. Puedes corregir el chunking, cerrar la brecha de vocabulario, eliminar el ruido, mantenerte dentro del presupuesto de tokens, entregarle al modelo exactamente el párrafo correcto… y aun así puede inventarse una respuesta. El grounding reduce la alucinación; no la elimina. Cualquier afirmación de que el RAG elimina la alucinación es sencillamente falsa.
Por qué nada lanza excepciones
Esta es la propiedad que hace que depurar RAG sea distinto de depurar software convencional, y merece su propio encabezado porque todas las técnicas del resto de esta parte existen para sortearla.
Los cinco modos de fallo producen una respuesta HTTP 200 bien formada.
- Chunking deficiente: el embedding model codifica fielmente el fragmento. El vector no está mal:
es una representación precisa de un fragmento incompleto.
- Desajuste de embeddings: el retriever devuelve los k vectores más cercanos. Siempre hay k vectores
más cercanos.
- Ruido en el retrieval: el retriever devuelve exactamente lo que le pediste.
kdocumentos. - Desbordamiento de contexto: el prompt es válido, el modelo responde.
- Alucinación: el modelo produce un texto fluido, verosímil y gramaticalmente perfecto.
Tu tasa de errores es del 0%. Tu latencia es correcta. Tus dashboards están en verde. Y tus respuestas son erróneas. Este es el Invariante 4, y es la razón por la que en esta guía la observabilidad va antes de la optimización (Parte 7) y no después.
Coherencia no es corrección. No puedes hacer QA de un sistema RAG leyendo la respuesta y decidiendo que suena bien. Todas las respuestas erróneas que produzca este sistema sonarán bien: para eso está el modelo de lenguaje.
La disciplina de depuración
El método que enseña el capítulo, hecho explícito 01:33:16–01:53:46:
- Reproduce a escala, no con el corpus de juguete. Un pipeline validado con diez documentos no te dice
casi nada. Si no puedes reproducir con 10,000, reproduce al menos con un corpus lo bastante grande como para que el chunk correcto tenga competencia real.
- Clasifica en uno de los cinco cajones antes de tocar el código. Adivinar qué etapa se rompió
y luego editarla es la manera de pasarte una semana ajustando un splitter para un problema de embeddings.
- Inspecciona los chunks recuperados, no la respuesta. Este es todo el truco, y merece
la siguiente sección.
- Corrige la primera etapa rota. Los defectos de chunking no se pueden compensar aguas abajo.
De nuevo el Invariante 1.
El paso 3 es todo el truco: bisecciona el pipeline
Una chain RAG tiene exactamente una costura que puedes cortar limpiamente: la frontera entre retrieval y generación. Todo lo que está aguas arriba de format_docs es retrieval. Todo lo que está aguas abajo es generación. Corta ahí y convertirás una pregunta sin respuesta («¿por qué esta respuesta está mal?») en dos preguntas que sí se pueden responder:
¿Se recuperó el chunk correcto?
- No → el bug está aguas arriba. Etapa: split (n.º 1), embed/retrieve (n.º 2). El LLM es inocente.
- Sí → el bug está aguas abajo. Etapa: assemble (n.º 3, n.º 4) o generate (n.º 5).
Es la regla de la Parte 4 reformulada en términos operativos —el curso afirma que el 90% de los fallos de RAG son fallos de retrieval, no de generación— y la razón por la que tienes que probar el retrieval por separado antes de culpar al modelo. Cambiar gpt-4o-mini por un modelo frontera para arreglar un bug de retrieval es la operación inútil más cara de este campo: si recuperas los documentos equivocados, ningún modelo de generación puede salvarte.
El retriever es un Runnable, así que puedes invocarlo por sí solo. Sin chain, sin LLM, sin más coste que el embedding de una query:
# Guide-authored diagnostic, built from the real APIs used in rag_pipeline.py
# and vector_stores.py. Run this BEFORE you touch the prompt.
def inspect_retrieval(vector_store, query, k=4):
"""Print exactly what the generation stage is about to be handed."""
retriever = vector_store.as_retriever(
search_type="similarity", search_kwargs={"k": k}
)
docs = retriever.invoke(query)
print(f"QUERY: {query}")
print(f"RETURNED: {len(docs)} of k={k}") # k is a ceiling, not a quota
for i, doc in enumerate(docs):
src = doc.metadata.get("source", "unknown")
print(f"\n[{i+1}] source={src} len={len(doc.page_content)} chars")
print(doc.page_content)
# Scores are a separate call: (Document, float) TUPLES, not Documents.
print("\n--- with scores ---")
for doc, score in vector_store.similarity_search_with_score(query, k=k):
# Chroma returns DISTANCE: 0 = identical, larger = worse.
similarity = 1 / (1 + score)
print(f" dist={score:.4f} sim={similarity:.4f} {doc.page_content[:70]}...")
Lo que te da ese único print, mapeado directamente sobre la taxonomía:
| Lo que ves | Diagnóstico |
|---|---|
| Un chunk que parece una frase a medias, o que termina a mitad de una idea | N.º 1, chunking deficiente: ve a arreglar el splitter |
| El chunk correcto no aparece en absoluto, y las palabras de la query no aparecen nunca en tu corpus | N.º 2, desajuste de embeddings |
| El chunk correcto aparece en la posición 3 o 4, rodeado de basura | N.º 3, ruido en el retrieval: haz rerank o filtra |
| El chunk correcto aparece en la posición 1 y aun así la respuesta lo contradice | N.º 5, alucinación: el LLM lo ignoró |
RETURNED es menor que k | Un filtro o un umbral de score recortó la lista: k es un techo, no una cuota, y el código posterior que dé por hecho len(docs) == k se romperá |
Instrumentar la propia chain
A veces la costura que necesitas está dentro de la chain. chains_v1.py incluye tres técnicas, y son la mitad puramente LangChain de lo que la Parte 7 sustituye después con LangSmith:
# chains_v1.py:144-176
def demo_debbuging():
prompt = ChatPromptTemplate.from_template("Say hello to {name}")
chain = prompt | model | StrOutputParser()
# Method 1: Get configuration
print("Chain input schema:", chain.input_schema.model_json_schema())
print("Chain output schema:", chain.output_schema.model_json_schema())
# Method 2: Use with_config for tacing
result = chain.with_config(
run_name="greeting_chain",
# tags="demo,debugging",
).invoke({"name": "Alice"})
print(f"Greeting: {result}")
# Method 3: Inspect intermediate steps
# Using RunnableLambda for logging
def log_step(x, step_name=""):
print(f"[{step_name}] {type(x).__name__}: {str(x)[:100]}")
return x
debug_chain = (
prompt
| RunnableLambda(lambda x: log_step(x, "after_prompt"))
| model
| RunnableLambda(lambda x: log_step(x, "after_model"))
| StrOutputParser()
)
print("\nDebug chain execution:")
result = debug_chain.invoke({"name": "Debug"})
print(f"Greeting: {result}")
Método 1: esquemas. chain.input_schema.model_json_schema() y .output_schema te dicen qué cree la chain que acepta y devuelve. Así es como zanjas sin adivinar la discusión de antes entre string en bruto y diccionario.
Método 2: with_config(run_name=...). Le pone nombre a la ejecución para que, cuando actives el tracing (Parte 7), el span tenga una etiqueta legible en lugar de un UUID. Fíjate en que tags="demo,debugging" está comentado por una razón: with_config(tags=...) espera un list[str], no un string con comas. Si lo vuelves a activar, escribe tags=["demo", "debugging"].
Método 3: escuchas de log con RunnableLambda. La propiedad importante, y la razón por la que este patrón se generaliza: log_step devuelve x sin cambios. Es un observador puro empalmado en la tubería. Es el Invariante 6 —la monitorización observa y nunca debe cambiar el comportamiento— implementado en tres líneas. Coloca una de estas entre retriever y format_docs y obtendrás los documentos recuperados impresos en cada request sin alterar la semántica de la chain.
chains_v1.py también contiene un esqueleto de RAG con un retriever falso (demo_passthrough_chain) que resulta realmente útil para aislar problemas: ejecuta toda la forma de la chain con un string de contexto fijo en el código y sin ningún vector store:
# chains_v1.py:86-100
# similuatee 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()
)
Sustituye el retriever por un stub que devuelva el chunk que sabes que es correcto. Si la respuesta sigue estando mal, el retrieval nunca fue el problema y estás ante un n.º 4 o un n.º 5. Si de repente la respuesta es correcta, todo lo que hay aguas arriba es sospechoso. Es una bisección limpia, y cuesta una llamada al LLM.
(El doble desenvoltorio x["question"]["question"] de la línea 95 es un artefacto de que este archivo invoca con un diccionario: RunnablePassthrough() deja pasar todo el diccionario de entrada. El estilo de string en bruto de rag_pipeline.py lo evita, e itemgetter("question") es el idiom más limpio si necesitas el estilo de diccionario).
Forense de la etapa 1: el splitter bajo el microscopio
Cuando la bisección dice «el chunk recuperado es un fragmento», estás depurando el splitter. text_splitters.py te da los instrumentos.
Por qué el recursivo es el valor por defecto fiable
Cuatro propiedades relacionadas, de 01:39:26–01:40:26:
- Preserva la coherencia semántica al dividir jerárquicamente a través de una lista ordenada de
separadores, en lugar de cortar cada N caracteres.
- La jerarquía codifica una teoría del significado. Primero párrafos, luego frases, luego
palabras, porque un párrafo debería contener una idea, y una frase también 01:39:26. El splitter solo pasa a un separador más fino cuando el más grueso no puede cumplir chunk_size.
- Respeta las fronteras naturales: no emitirá «unsupervised» para luego cortar antes de
«learning», porque medio término no es un término.
- El beneficio llega aguas abajo, no en tiempo de indexación. La calidad del chunking nunca se observa cuando
haces el chunking; se observa semanas después, en la calidad de las respuestas. Por eso precisamente es el defecto más difícil de atribuir.
# text_splitters.py:89-100
def recursive_splitter():
splitter = RecursiveCharacterTextSplitter(
chunk_size=500,
chunk_overlap=50,
separators=["\n\n", "\n", " ", ""],
)
chunks = splitter.split_text(SAMPLE_TEXT)
print(f"Original length: {len(SAMPLE_TEXT)} chars")
print(f"Number of chunks: {len(chunks)}")
print(f"Chunk sizes: {[len(c) for c in chunks]}")
print(f"\nFirst chunk preview:\n{chunks[0][:200]}...")
SAMPLE_TEXT es un manual básico de machine learning en Markdown —un título #, secciones ## y dos subsecciones ###, con listas de algoritmos con viñetas—, y esa es la gracia: tiene una estructura real de encabezados que los separadores pueden encontrar.
La lista de separadores ["\n\n", "\n", " ", ""] es párrafos → líneas → palabras → caracteres. (Los subtítulos automáticos lo transcriben como «double new lines, new lines also empty string and quotes», y por eso la referencia es el código, no la transcripción). El string vacío es el último recurso: cortar a nivel de carácter, que es chunking de tamaño fijo con otro nombre y produce la basura a mitad de palabra contra la que advierte la Parte 3.
split_text es correcto aquí, y solo aquí, porque SAMPLE_TEXT es un string en bruto sin metadatos que perder; el instructor lo dice mientras lo escribe 01:37:25. La regla de create_kb sigue en pie: los pipelines reales manejan objetos Document y usan split_documents.
Ejecutarlo contra el archivo publicado imprime:
Original length: 887 chars
Number of chunks: 2
Chunk sizes: [462, 423]Lee esos tres números como un diagnóstico, no como una curiosidad: es la misma aritmética que hicimos con KNOWLEDGE_BASE, que esta vez sale al revés. 462 + 423 = 885 frente a una fuente de 887 caracteres: el corte cayó sobre un \n\n, que se consume, y no se duplicó nada; el splitter solo arrastra un fragmento final hacia delante cuando ese fragmento cabe dentro del presupuesto de overlap de 50 caracteres, y los párrafos completos no caben. Así que chunk_overlap=50 no te aportó nada en este documento. A la inversa, cuando los tamaños de tus chunks suman notablemente más que la fuente, el splitter está cortando dentro de los párrafos y estás pagando overlap en cada frontera. Dos números, y ya sabes cómo fue el split.
El overlap es un seguro barato
«Así que el overlap es, en esencia, lo que llamamos un seguro barato». 01:43:31
La idea más potente del capítulo 10. Overlap significa que los N caracteres finales del chunk i se repiten como los N caracteres iniciales del chunk i+1. Su propósito es garantizar que el significado que queda a caballo de una frontera aparezca entero en al menos un chunk, de modo que el contexto de una frontera nunca quede huérfano 01:45:32.
El fallo que evita es concreto y exasperante: una redundancia pequeña y barata es lo que impide que tu sistema RAG tenga la respuesta y sea incapaz de encontrarla 01:43:31.
El ejemplo práctico de la API key 01:44:32–01:45:32: reprodúcelo mentalmente cada vez que fijes chunk_overlap. Texto fuente:
«La API key caduca a las 24 horas. Debes renovarla usando el endpoint de tokens».
Sin overlap:
| Chunk | Contenido | Contiene |
|---|---|---|
| 1 | «La API key caduca a las 24 horas» | El problema, sin solución |
| 2 | «Debes renovarla usando el endpoint de tokens» | La solución, nunca dice «caducidad» |
El usuario pregunta: «¿Cómo gestiono la caducidad de la API?» El retriever hace match con el chunk 1 —contiene «caduc…»— y lo devuelve. El match es correcto. La respuesta es inútil. El chunk 2, que contiene la solución real, obtiene un score bajo porque nunca menciona la caducidad.
Con overlap: el chunk 2 también lleva «…caduca a las 24 horas. Debes renovarla», así que ambos chunks contienen el problema y la solución, y elija el que elija el retriever, el LLM recibe un contexto completo y accionable.
«Es la diferencia entre encontrar una respuesta y encontrar una respuesta completa. Son dos cosas distintas». 01:45:32
La demo que hace visible el overlap:
# text_splitters.py:115-133
def overlap_importance():
text = "The quick brown fox jumps over the lazy dog. " * 10 # Repeated text
# without overlap
no_overlap = RecursiveCharacterTextSplitter(chunk_size=50, chunk_overlap=0)
# with overlap
with_overlap = RecursiveCharacterTextSplitter(chunk_size=50, chunk_overlap=20)
chunks_no_overlap = no_overlap.split_text(text)
chunks_with_overlap = with_overlap.split_text(text)
print("Without overlap:")
print(f" Chunk 1 end: ...{chunks_no_overlap[0][-20:]}")
print(f" Chunk 2 start: {chunks_no_overlap[1][:20]}...")
print("\nWith overlap:")
print(f" Chunk 1 end: ...{chunks_with_overlap[0][-20:]}")
print(f" Chunk 2 start: {chunks_with_overlap[1][:20]}...")
Dos splitters que difieren exactamente en un parámetro —overlap 0 frente a 20— sobre un string deliberadamente repetitivo de 450 caracteres, imprimiendo una ventana de 20 caracteres a cada lado de la primera frontera. La salida real:
Without overlap:
Chunk 1 end: ...er the lazy dog. The
Chunk 2 start: quick brown fox jump...
With overlap:
Chunk 1 end: ...er the lazy dog. The
Chunk 2 start: the lazy dog. The qu...Sin overlap, los dos chunks son estrictamente contiguos y no comparten nada: la frase «the lazy dog. The quick brown fox» existe en el corpus y en ningún chunk individual. Con overlap, el chunk 2 repite visiblemente la cola del chunk 1, así que una query sobre «lazy dog» ahora da con un chunk que contiene la frase entera en lugar de con dos chunks que contienen cada uno la mitad.
Ese es el beneficio. La demo también enseña la factura, si cuentas: el mismo string de 450 caracteres produce 10 chunks con overlap 0 y 15 con overlap 20. El overlap no es gratis: en este documento supone un 50% más de vectores que embeber, almacenar y buscar. «Seguro barato» es una afirmación sobre la proporción, no sobre que el coste sea cero.
Hacer un barrido del parámetro que estás a punto de adivinar
# text_splitters.py:103-112
def chunk_size_comparison():
sizes = [200, 500, 1000]
print("=== Chunk Size Comparison ===")
for size in sizes:
splitter = RecursiveCharacterTextSplitter(
chunk_size=size, chunk_overlap=size // 5
) # 20% overlap
chunks = splitter.split_text(SAMPLE_TEXT)
print(f" Size {size}: {len(chunks)} chunks")
Esta función no se ejecuta en cámara y vale más que la mayoría de las que sí. Hace un barrido de 200 / 500 / 1000 y deriva el overlap como size // 5: una regla práctica del 20%, en el extremo superior de la franja del 10–20% de la Parte 3. Contra el SAMPLE_TEXT publicado de 887 caracteres imprime:
=== Chunk Size Comparison ===
Size 200: 6 chunks
Size 500: 3 chunks
Size 1000: 1 chunksCompara esa línea central con recursive_splitter(), que usa el mismo chunk size y el mismo documento y produce 2 chunks, no 3. La única diferencia es el overlap: 50 frente a 500 // 5 = 100. Subir el overlap fabricó un chunk extra. Es el discreto efecto de segundo orden del parámetro que todo el mundo ajusta primero: el número de chunks, el gasto en embeddings y el tamaño del índice dependen de ambos números, y con chunk_size=1000 todo el documento se colapsa en un único chunk, momento en el que has dejado de hacer retrieval por completo.
Ejecuta esto contra tu propio corpus, luego ejecuta el inspect_retrieval de antes contra cada configuración y compara lo que vuelve de verdad. Ese es el bucle: barrido, retrieval, leer los chunks. El número de chunks por sí solo no te dirá qué configuración es mejor.
El resto de text_splitters.py: importado, publicado y nunca ejecutado en este capítulo
El archivo importa cuatro clases de splitter más el enum Language, y este capítulo hace la demo de exactamente uno de los splitters. Conoce para qué sirven los demás antes de necesitarlos (la Parte 3 desarrolla el argumento completo):
MarkdownHeaderTextSplitter:markdown_splitter()(líneas 136–149) divide por
[("#","h1"), ("##","h2"), ("###","h3")] y lleva la ruta de encabezados a chunk.metadata. Sobre SAMPLE_TEXT produce 4 chunks cuyos metadatos son del tipo {'h1': 'Introduction to Machine Learning', 'h2': 'Types of Machine Learning', 'h3': 'Supervised Learning'}: un rastro de migas de pan por chunk. Esos metadatos son los que hacen posibles las citas a nivel de encabezado. Nunca se ejecuta en cámara.
- Enum
Language+from_language:code_splitter()(líneas 152–160) usa
RecursiveCharacterTextSplitter.from_language(language=Language.PYTHON, chunk_size=500, chunk_overlap=50) sobre SAMPLE_CODE (797 caracteres: un quicksort y un binary_search) y lo corta en 2 chunks de 390 y 402 caracteres, una función cada uno, que es de lo que se trata. Hacer chunking de código con un splitter genérico corta funciones por la mitad y hace que ambas mitades sean inútiles como contexto.
document_splitter()(líneas 163–180): la única función del archivo que usa
split_documents, sobre PyPDFLoader("./docs/langchain_demo.pdf"), e imprime los metadatos del primer y del último chunk. Esta es la forma que tiene un pipeline real.
CharacterTextSplitteryTokenTextSplitterse importan y no se usan en ninguna parte de
el archivo.
document_splitter() es la única función que queda descomentada en __main__, así que clonar el repo y ejecutar python text_splitters.py lanza la demo del PDF, no las dos demos que recorre este capítulo. El PDF viene con el repo en docs/langchain_demo.pdf, pero la ruta es relativa, así que la demo solo funciona desde la raíz del repo.
Forense de la etapa 2: los embeddings sin la carcasa
Cuando la bisección dice «el chunk correcto nunca se recuperó y el vocabulario es distinto», estás depurando la etapa de embedding. embeddings_deep.py es una desabstracción deliberada: reconstruye el retrieval desde numpy para que puedas ver los números.
Comprueba la norma antes de fiarte de ningún score
Imprime np.linalg.norm(vector) de cualquier embedding que recibas.
- Los embeddings de OpenAI están normalizados a 1.0. En cámara la norma se imprime como
1; con el string de formato
f"{...:.4f}" del archivo publicado verás 1.0000.
- Sin normalización, la magnitud en bruto filtra la longitud del documento en los scores de similitud, y los documentos largos ganan por ser largos y no por ser relevantes.
- La regla de diagnóstico: norma == 1 → normalizado (bien); norma != 1 → sin normalizar. No todos los modelos normalizan, y los que no lo hacen no te lo van a decir.
El instructor resume la razón de la normalización en 01:48:36:
«evitará que los documentos más largos tengan vectores más grandes solo porque tienen más contenido».
Es un problema real de portabilidad, no teórico. Cambia OpenAIEmbeddings por HuggingFaceEmbeddings("sentence-transformers/all-MiniLM-L6-v2") (384 dimensiones) o por OllamaEmbeddings(model="llama2-7b-embedding-q4_0") —ambos mencionados en embeddings.py— y puede que pases en silencio a un espacio sin normalizar en el que tus umbrales cuidadosamente ajustados no significan nada.
Para text-embedding-3-small, la demo imprime 1536 dimensiones y los 5 primeros componentes del vector, para que compruebes a simple vista que has recibido floats y no un objeto de error. (Primero tienes que reparar el archivo —consulta el aviso del bug más abajo—, porque las dos funciones que imprimen dimensiones y normas son exactamente las dos que están rotas en el archivo publicado).
| Modelo | Dimensiones | Coste / 1M tokens | Ideal para |
|---|---|---|---|
text-embedding-3-small | 1536 | $0.02 | Uso general: el valor por defecto de la guía |
text-embedding-3-large | 3072 | $0.13 | Alta precisión (6.5× el precio) |
text-embedding-ada-002 | 1536 | $0.10 | Legacy |
all-MiniLM-L6-v2 (HuggingFace) | 384 | local | Barato/offline; comprueba la normalización |
embed_query frente a embed_documents
embed_query(text)→ un vector, para una query.embed_documents([t1, t2, t3])→ una lista de vectores, para documentos. La demo de batch usa
3 textos.
La observación del instructor en 01:48:36 es que llamarlos se siente idéntico: el único cambio es que embed_documents recibe una lista. La razón real para usar la forma batch es que el proveedor empaqueta toda la lista en un único viaje de ida y vuelta a la API.
Pero hay una razón más profunda por la que LangChain mantiene separados los dos métodos, y el capítulo no la menciona: algunos embedding models aplican prefijos o instrucciones asimétricos a las queries frente a los pasajes. Llamar a embed_documents con una query, o al revés, puede llevarte en silencio a una región ligeramente distinta del espacio. Usa el método que corresponda al papel del texto.
El sistema pre-RAG
# embeddings_deep.py:35-65
def similarity_search():
# Documents
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}")
La fórmula se escribe a mano en lugar de importarse, y esa es la gracia:
cos(a, b) = dot(a, b) / (‖a‖ · ‖b‖)Cinco documentos, una query, coseno contra cada uno, ordenar de mayor a menor, imprimir. Eso es un retriever sin la carcasa. Fíjate en la pequeña ironía de ese denominador: si los vectores de OpenAI están realmente normalizados a norma unitaria, ambas normas valen 1 y la división no hace nada; la similitud coseno degenera en un simple producto escalar. Escribirla de todos modos es código defensivo correcto, porque en el momento en que cambies a un modelo que no normalice, la fórmula seguirá siendo válida y solo cambiarán los números.
«Así que esto es, en esencia, nuestro sistema pre-RAG». 01:51:39 — «aunque sea rudimentario … imita exactamente lo que hace el retrieval y cómo funciona».
El ranking es la evidencia:
| Posición | Documento | Lectura |
|---|---|---|
| 1 (≈ 0.44) | «Python is a programming language» | Coincidencia temática directa |
| 2 | «JavaScript is used for web development» | También es un lenguaje de programación: semánticamente cercano |
| 3–4 | «Machine learning enables AI applications» / «Deep learning uses neural networks» | Mismo dominio general, tema equivocado |
| 5 | «Cats are popular pets» | No tiene nada que ver con los lenguajes de programación |
Los dos primeros son exactamente los que elegiría una persona, y ni la palabra «Python» ni «JavaScript» aparecen en la query. Ese es el superpoder de la búsqueda semántica en una sola salida, y merece recordarse, porque la Parte 6 empieza mostrando cómo ese mismo mecanismo falla estrepitosamente con SKU y códigos de error, donde la exactitud léxica es todo el requisito.
Solo se lee en voz alta el primer score, 0.44; los otros cuatro no. Trata 0.44 como aproximado: una nueva ejecución contra text-embedding-3-small variará en el tercer o cuarto decimal.
La ejecución también recuerda la regla de simetría 01:51:39: tanto la query como los documentos deben convertirse en embeddings con el mismo modelo y en el mismo espacio. Es el Invariante 2, impreso.
Forense de la etapa 3: el chunk correcto está ahí, pero enterrado
Si inspect_retrieval muestra el chunk correcto en la posición 3 o 4, rodeado de ruido de aspecto plausible, tienes el fallo n.º 3 y el splitter es inocente. El capítulo 10 se lo pasa al capítulo 11, pero advanced_rag.py, en el mismo repo, ya contiene la escalera de escalado, y conviene saber qué existe antes de ponerte a construir algo.
advanced_rag.py incluso trae el test fixture adecuado. INFO_BURIED es un corpus de dos documentos en el que la respuesta está ahogada a propósito: un párrafo sobre LangChain metido dentro de un documento de historia de la empresa ACME lleno de financiación Serie B, política de vacaciones, cifras de ingresos y aportaciones al 401(k), y un párrafo sobre LangGraph en medio de un runbook de plataforma de cinco capítulos sobre EKS, Auth0 y DataDog. Así es el ruido en el retrieval convertido en datos: construye lo mismo para tu corpus.
| Técnica | Qué corrige | Código real | Coste |
|---|---|---|---|
| Multi-query | N.º 2, desajuste de vocabulario: genera varias formulaciones de la pregunta | MultiQueryRetriever.from_llm(retriever=..., llm=...) sobre k=2 | +1 llamada al LLM por query |
| Compresión contextual | N.º 3, ruido; n.º 4, desbordamiento: extrae de cada chunk solo las frases relevantes para la query | ContextualCompressionRetriever(base_compressor=LLMChainExtractor.from_llm(llm), base_retriever=...k=4) | 1 llamada al LLM por documento recuperado |
| Híbrido / ensemble | N.º 2, fallos léxicos: palabras clave BM25 + vector denso | EnsembleRetriever(retrievers=[bm25, semantic], weights=[0.4, 0.6]), ambos con k=3 | +20–50 ms |
| Parent-document | N.º 1, fragmentos: busca chunks pequeños, devuelve chunks grandes | ParentDocumentRetriever(child_splitter=200/20, parent_splitter=800/100) | Docstore adicional |
# advanced_rag.py:260-273 (demo_ensemble_hybrid_search) — hybrid search, the failure-#2/#3 workhorse
vectorstore = create_base_vectorstore()
# BM25 keyword retriever
bm25_retriever = BM25Retriever.from_documents(TECH_DOCS)
bm25_retriever.k = 3
# Semantic retriever
semantic_retriever = vectorstore.as_retriever(search_kwargs={"k": 3})
# Ensemble combines both
ensemble_retriever = EnsembleRetriever(
retrievers=[bm25_retriever, semantic_retriever],
weights=[0.4, 0.6], # 40% keyword, 60% semantic
)
Fíjate en que los pesos publicados son [0.4, 0.6] —40% palabras clave, 60% semántico—, mientras que la narración del curso recomienda empezar con [0.5, 0.5]. Ambos son defendibles; lo importante es que el peso es un dial que ajustas contra un test set, y la Parte 6 se encarga de ese argumento junto con la fusión RRF, k=4 y la falta de actualizaciones incrementales de BM25.
# advanced_rag.py:346-348 (demo_parent_document_retriever) — parent-document: small to search, large to answer
# Splitters
parent_splitter = RecursiveCharacterTextSplitter(chunk_size=800, chunk_overlap=100)
child_splitter = RecursiveCharacterTextSplitter(chunk_size=200, chunk_overlap=20)
Los hijos pequeños (200/20) dan matches vectoriales precisos; los padres grandes (800/100) le dan al LLM una idea completa. Es una respuesta estructural a la misma enfermedad que el overlap trata químicamente.
La chain avanzada completa apila dos de ellas —multi-query para el recall y después compresión para la precision— y luego reutiliza exactamente la misma forma LCEL que construiste al principio de esta parte:
# advanced_rag.py:397-430 (demo_advanced_rag_chain, excerpt)
# Multi-query for better recall
multi_retriever = MultiQueryRetriever.from_llm(
retriever=vectorstore.as_retriever(search_kwargs={"k": 3}), llm=llm
)
# Compression to focus on relevant info
compressor = LLMChainExtractor.from_llm(llm)
advanced_retriever = ContextualCompressionRetriever(
base_compressor=compressor, base_retriever=multi_retriever
)
# ...
rag_chain = (
{"context": advanced_retriever | format_docs, "question": RunnablePassthrough()}
| prompt
| llm
| StrOutputParser()
)
Esa es la recompensa de la forma LCEL. Cada mejora de las Partes 6 a 16 es una sustitución en una posición de este pipeline: un retriever distinto, un formateador distinto, un parser distinto. La chain que escribiste en cuarenta líneas es la última pieza de arquitectura que escribes.
Recorrer la taxonomía hacia atrás
Imprime esta tabla. Es el índice que va del síntoma a la etapa.
| Síntoma | Primera comprobación | Modo probable | Ir a |
|---|---|---|---|
| La respuesta es un fragmento o se queda a medias | Lee el texto del chunk recuperado | N.º 1, chunking | Parte 3 |
| La respuesta es errónea con total seguridad; el chunk correcto no está en el conjunto recuperado; la redacción de la query difiere del corpus | inspect_retrieval: ¿falta el chunk objetivo? | N.º 2, desajuste de embeddings | Partes 6, 14 |
| Chunk correcto recuperado en la posición 3–4 entre basura | Posición en el ranking del chunk objetivo | N.º 3, ruido en el retrieval | Parte 6 |
| Contexto largo; la respuesta ignora la parte central o se trunca | Número de tokens del prompt ensamblado | N.º 4, desbordamiento de contexto | Parte 9 |
| Chunk correcto en la posición 1; la respuesta lo contradice | Compara la respuesta con docs[0].page_content | N.º 5, alucinación | Partes 7, 12, 15 |
| La respuesta cambia entre ejecuciones idénticas | temperature | No es un bug de RAG | Fíjala en 0–0.2 |
Menos resultados que k | Un filter o un umbral de score | No es un bug: k es un techo | Parte 4 |
| Ayer funcionaba todo, hoy nada, sin cambios de código | ¿Ha cambiado el embedding model o su versión? | Violación del Invariante 2 | Reindexar |
Y la regla que rige el orden en que trabajas:
Construir → depurar → optimizar → y luego escalar. Escalar un retriever de baja calidad produce respuestas erróneas más rápido y más caras. Todas las partes que siguen a esta dan por hecho que ya sabes identificar qué etapa se rompió.
Nota sobre el material fuente
Dos correcciones que esta parte aplica a la fuente, expuestas con claridad en lugar de disimuladas:
- **La diapositiva 07 (
07-why-llm-debugging-is-hard.png) está indexada en el capítulo 10 y no pertenece
a él.** Su contenido —no determinista, errores en cascada, fallos silenciosos, sorpresas de coste— no aparece en ninguna parte de la transcripción del capítulo 10, y los cuatro términos aparecen en el capítulo 12 (observabilidad, 02:21:10). Se usa en la Parte 7 de esta guía. Las diapositivas que se ven realmente en pantalla en el capítulo 10 —la lista de los cinco modos de fallo, la ilustración de «nuestra política permite hasta / 3 días por semana» y el ejemplo de overlap de la API key— no se capturaron en pantallazos.
- El anuncio del «truncado inteligente» en 01:53:42 está mal clasificado como solución al ruido
en el retrieval; se presenta al final del capítulo 11 como solución al desbordamiento de contexto. Consulta el aviso anterior.
El capítulo 10 termina a mitad de frase, en la línea de transición hacia la búsqueda híbrida 01:53:42:
«Sabemos que la búsqueda vectorial es increíble».
Ahí es donde empieza la Parte 6: con los casos en los que no lo es.
Checklist
Cada punto indica la comprobación, no solo el objetivo. Si no puedes ejecutar la comprobación, la casilla no está marcada.
Antes de decir que el sistema «funciona»:
load_dotenv()aparece por encima del primer constructor de cliente del archivo. Lee el bloque de imports de arriba abajo y confirma el orden.- El embedding model es una constante a nivel de módulo, declarada una sola vez.
grep -c 'OpenAIEmbeddings(' yourfile.pydevuelve 1. - Usaste
split_documents([doc])—con la lista—, nosplit_text. Luego comprueba con un assert quechunks[0].metadata["source"]existe; si lanza un error, usaste el método equivocado. - Cada chunk lleva un
sourcecon sentido. Todo aquello por lo que más adelante quieras filtrar o citar está en los metadatos en tiempo de indexación: no se puede añadir después sin reindexar. persist_directoryapunta a una ruta estable, no atempfile.mkdtemp(). Ejecuta el indexador dos veces y confirma que la segunda ejecución no hace ninguna llamada a la API de embeddings.- Imprime las fronteras de los chunks una vez, a mano.
[len(c.page_content) for c in chunks]más los primeros y los últimos 60 caracteres de cada uno. Si una lista numerada, una tabla o una definición queda cortada por la mitad, arregla el splitter ya: el corpus de la demo de este mismo capítulo no pasa esta comprobación. temperaturevale 0 o 0.2. Haz la misma pregunta dos veces y compara las respuestas; si difieren, no puedes atribuir nada.- El prompt tiene los cuatro ingredientes: cláusula de restricción, cláusula de rechazo,
{context},{question}. - El string de rechazo es exacto y se puede buscar con grep, así que un
grep -csobre tus logs es una tasa de rechazo. - Sabes si tu chain recibe un string en bruto o un diccionario, y lo comprobaste con
chain.input_schema.model_json_schema()en lugar de probar las dos cosas. - Tienes tres preguntas de sondeo —una que seguro que está en el corpus y dos que seguro que no— y viven en el repo, no en el historial de tu shell.
Antes de decir que una respuesta errónea es un bug del LLM:
- Ejecutaste el retriever solo y leíste el texto de los chunks, no la respuesta.
- Imprimiste
doc.metadata['source']junto a cada resultado. - Comprobaste la polaridad de tu score —¿distancia o similitud?— antes de aplicar ningún umbral.
- Comprobaste
len(docs)frente ak(un filtro o un umbral de score puede haberlo recortado). - Comprobaste
np.linalg.norm(vector)si has cambiado de proveedor de embeddings. - Empalmaste una escucha de log con
RunnableLambdaentreretrieveryformat_docsy miraste lo que realmente se le entregó al prompt, en lugar de lo que supones que se le entregó. - Sustituiste el retriever por un stub que devuelve el chunk que sabes que es correcto. Sigue mal → el bug es un n.º 4 o un n.º 5 y está aguas abajo. De repente está bien → todo lo que hay aguas arriba es sospechoso.
- Clasificaste el fallo en uno de los cinco cajones antes de editar el código, y puedes decir en voz alta el número del cajón.
- Corregiste la primera etapa rota, no la más visible.
- Cambiaste exactamente una variable y volviste a lanzar las mismas preguntas de sondeo.
Decisiones que debes tomar ahora y que luego son caras de cambiar:
| Decisión | Valor por defecto para empezar | ¿Reversible? |
|---|---|---|
| Embedding model + versión | text-embedding-3-small, 1536 dimensiones, $0.02/1M | No: cambiarlo invalida todo el índice |
| Qué va en los metadatos del chunk | Como mínimo source; añade todo aquello por lo que puedas filtrar o citar | No: requiere reindexar |
| Chunk size / overlap | 500 / 50 caracteres, y luego barrido de 200/500/1000 con un 20% de overlap | Sí, pero requiere reindexar |
k | 4, no 2; súbelo solo después de arreglar la calidad del ranking | Sí, gratis |
| Persistencia | persist_directory estable desde el primer día | Sí, pero tienes que hacer re-embed |
| Modelo de generación | gpt-4o-mini, temperatura 0.2 | Sí: cámbialo con libertad, esa es la asimetría |
| Forma de la salida | StrOutputParser para el terminal; with_structured_output detrás de una API | Sí |