oriolrius.me Production RAGGuia de referència
Part 05·Fonaments

El teu primer sistema RAG real i com depurar-lo quan menteix

Munta la primera chain completa amb LCEL i depura-la de manera sistemàtica quan respongui malament.

51 min de lectura 13 seccions Fonaments
Resum en àudio · 3:31 · CA
El teu primer sistema RAG real i com depurar-lo quan menteix

Les parts 2 a 4 han construït les peces per separat: un carregador que converteix fitxers en objectes Document, un segmentador que els talla en fragments, un model d'embeddings que converteix els fragments en vectors i una col·lecció Chroma que els emmagatzema i permet cercar-hi. Cadascuna era una funció de demostració independent. Cap no responia cap pregunta.

Aquesta part fa dues coses, en l'ordre en què les fa el curs d'origen, perquè l'ordre és la lliçó.

Primer munta el sistema: el capítol 9 [01:24:32–01:33:16] connecta les cinc etapes en una cadena LCEL executable que rep una cadena de text i retorna una resposta. L'instructor diu clarament que no hi ha res de nou: són els mateixos components d'abans, ara en un sol lloc 01:30:38. A aquest nivell, RAG és un problema de muntatge, no d'algoritmes. Tindràs un sistema que funciona en unes quaranta línies.

Després destrueix la il·lusió: el capítol 10 [01:33:16–01:53:46] és el de la dutxa freda. La demostració que acabes de construir respon correctament tres preguntes sobre una sola cadena Markdown, i això no demostra pràcticament res. El capítol anomena les cinc maneres com el RAG de tutorial fracassa a escala i, sobretot, ensenya el mètode: com remuntar des d'una resposta incorrecta fins a l'etapa que l'ha produïda, quan cap etapa no ha llançat una excepció.

Aquesta segona meitat és la que la majoria d'enginyers se salten i després necessiten a les 2 de la matinada. L'invariant 4 de la part 1 és el que ho explica tot aquí: les fallades són silencioses. La taxa d'errors pot ser un impecable 0% mentre la correcció és pèssima. El depurador no és una traça de pila: és una disciplina.

L'arquitectura de dues funcions

Obre rag_pipeline.py. La seva estructura es correspon punt per punt amb les dues fases del model mental de la part 1:

FuncióFaseS'executaPerfil de cost
create_kb()Fase A — Indexació (fora de línia)Una vegada per corpusÚnic, amortitzat
demo_basic_rag()Fase B — Consulta (en línia)Una vegada per preguntaRecurrent, per petició

No és una tria d'estil. És l'invariant 3 —el cost d'indexació és únic, el de consulta es repeteix— expressat com un límit entre funcions de Python. Tota la feina que puguis moure de la segona funció a la primera, l'hi hauries de moure.

El preàmbul del mòdul configura les dues coses que han de ser globals:

Python
# 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 aspectes que cal observar abans de continuar, perquè tots dos són paranys.

load_dotenv() s'executa a la línia 21, abans de construir OpenAIEmbeddings(...) a la línia 22. L'SDK llegeix OPENAI_API_KEY de l'entorn del procés en el moment de la construcció; inverteix aquestes dues línies i obtindràs un error d'autenticació que sembla una clau incorrecta.

I embeddings_model és una constant de nivell de mòdul, declarada exactament una vegada. És l'invariant 2 fet tangible: un sol model d'embeddings, als dos extrems del circuit, per sempre. Escriu directament la cadena del model al punt d'una crida i hauràs creat un futur error de fallada silenciosa: dos models amb les mateixes 1536 dimensions produeixen vectors que es comparen sense donar error i s'ordenen sense sentit.

La base de coneixement és una cadena, no un fitxer

El corpus és una constant de cadena de Python, KNOWLEDGE_BASE (línies 25–57): un document Markdown de 1,010 caràcters sobre LangChain que el segmentador 500/50 converteix exactament en tres fragments de 488, 414 i 123 caràcters. El contingut importa, perquè totes les respostes de la demostració han de venir d'aquí i d'enlloc més, cosa que el converteix en un conjunt de prova útil; i la seva mida importa igualment, perquè un corpus de tres fragments no pot exhibir ni una de les fallades de què tracta el capítol següent:

Fet de la base de coneixementEs fa servir com a
LangChain creat per Harrison Chase, octubre de 2022Resposta a la pregunta de prova 2
5 components principals: models, prompts, cadenes, agents, memòriaResposta a la demostració amb fonts
LangGraph: gestió de l'estat, cicles i bucles, intervenció humana en el procés, persistènciaResposta a la pregunta de prova 3
Pla gratuït de LangSmith, plans de pagament des de $39/mesLa consulta de comprovació amb resposta a la base de coneixement per a la demostració del mecanisme de reserva
pip install langchain langchain-openai; «primera cadena en menys de 10 línies de codi»Text de farciment que no s'ha de recuperar

Hi ha dos fets d'aquesta divisió en què val la pena aturar-se, perquè tots dos són eines de diagnòstic que reutilitzaràs al teu corpus.

Primer, l'aritmètica: 488 + 414 + 123 = 1,025 davant d'una font de 1,010 caràcters. Que els fragments sumin més que l'entrada vol dir que el solapament s'ha aplicat efectivament. Aquí s'ha aplicat una vegada: el fragment 2 acaba amb l'encapçalament ## Getting Started i el fragment 3 comença repetint-lo, 18 caràcters duplicats menys els separadors que el segmentador ha consumit, amb un excedent net de 15. Que els fragments sumin menys que l'entrada vol dir que tots els talls han caigut en un separador i el solapament no t'ha aportat res.

Segon, i menys còmode, el corpus no és el conjunt de prova net que sembla.

create_kb(): tot el camí d'indexació, en divuit línies

Python
# 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

Aquí es concentren quatre decisions, i tres són paranys.

1. chunk_size=500, chunk_overlap=50. Divisió recursiva de 500 caràcters amb 50 de solapament —10%—, reutilitzada de la part 3 sense tornar-la a justificar. És l'opció predeterminada de «encara no tens informació millor». No és una recomanació per al teu corpus; la part 3 ha mesurat que el recursiu supera el semàntic per 4–1 en text estructurat amb encapçalaments, i els capítols 10 i 14 tracten d'ajustar aquestes dues xifres amb proves.

2. El Document construït a mà. No hi ha cap fitxer per carregar, de manera que l'instructor construeix ell mateix un Document amb page_content= la cadena original i metadata= un diccionari. El comentari que fa de passada és la part important:

«com que creo jo mateix el document, puc passar metadades tal com hem vist abans» 01:25:36

Un Document és simplement una dataclass. Quan un carregador no et doni les metadades que necessiten les citacions, construeix tu mateix l'objecte i adjunta-hi el que vulguis. El valor de source aquí —langchain_knowledge_base.md— és fictici; tria .md perquè la cadena és Markdown, de manera que l'atribució posterior de fonts es comporta com ho faria amb un fitxer real.

3. split_documents([doc]), mai split_text(...). S'assenyala explícitament davant la càmera a 01:25:36, i és tot el motiu pel qual existeix el pas 2.

  • split_text(str) retorna una llista de cadenes simples. Les metadades es destrueixen.
  • split_documents([Document, ...]) retorna una llista de Documents i **copia les metadades del document pare

a tots els fragments**.

Embolcalla la cadena en un Document perquè split_documents tingui alguna cosa per propagar. I observa els claudàtors: split_documents rep una llista, encara que només hi hagi un document. Passar el Document directament és un dels errors més habituals d'aquesta API.

4. Chroma.from_documents(...) fa tres coses en una sola crida: genera l'embedding de cada fragment amb embeddings_model, escriu vectors + text + metadades en una col·lecció i retorna un objecte de magatzem actiu. Només són obligatoris documents i embedding.

El camí de consulta

El recuperador és un adaptador lleuger

Python
# rag_pipeline.py:83-86
vector_store = create_kb()
retriever = vector_store.as_retriever(
    search_type="similarity", search_kwargs={"k": 2}
)

Un magatzem vectorial no és un component de cadena. .as_retriever() l'adapta a un Runnable amb el contracte str → List[Document], l'únic que pot consumir una canonada LCEL. Aquí es fan servir dos paràmetres ajustables, i tots dos mereixen ser qüestionats:

  • search_type="similarity": simple cerca top-k de veïns més propers. Hi ha alternatives i

no s'exerciten: "mmr" (amb search_kwargs={"k": 3, "fetch_k": 5} a vector_stores.py, n'obté cinc i en retorna tres de diversos) i "similarity_score_threshold", que és l'única que pot retornar menys de k quan res no és prou bo.

  • search_kwargs={"k": 2}: dos fragments per consulta 01:26:36. (Els subtítols automàtics transcriuen

search_kwargs com «the quirs», un recordatori útil que el codi del repositori, i no la transcripció, és la font d'autoritat per a tots els noms d'aquesta guia.)

search_kwargs també és on va un filtre de metadades: {"k": 4, "filter": {"topic": "database"}} és la forma de recuperador de la crida similarity_search(query, k=5, filter=...) de la part 4. Cap demostració d'aquest fitxer no en fa servir cap, i convé saber-ho: el recuperador que estàs a punt de construir no té cap protecció temàtica.

init_chat_model i la ruta d'importació en què és fàcil equivocar-se

Python
# rag_pipeline.py:58 (module level, immediately after KNOWLEDGE_BASE)
llm = init_chat_model(model="gpt-4o-mini", temperature=0.2)

Davant la càmera, aquesta línia s'escriu dins de demo_basic_rag(); al fitxer versionat és a nivell de mòdul, que és on la vols: un sol client, compartit per les quatre demostracions, construït una vegada per procés.

L'instructor comença a escriure ChatOpenAI, s'atura i canvia 01:26:36, i després busca visiblement la importació —prova langchain_core.chat_models, murmura «chat loaders»— fins que la troba. La línia correcta és:

Python
from langchain.chat_models import init_chat_model

No és a langchain_core. init_chat_model és una fàbrica independent del proveïdor: dona-li una cadena de model i obtén l'objecte de model de xat adequat, sense importar cap classe específica del proveïdor. La justificació que dona és simplement ergonòmica —és més ràpid d'escriure 01:27:37—, però el benefici real és l'asimetria de l'invariant 2: el model de generació és intercanviable, de manera que es mereix un constructor intercanviable. El model d'embeddings no ho és, i per això té una constant de mòdul fixada al codi.

temperature=0.2, no el valor predeterminat, i triat explícitament per al determinisme 01:27:37. Observa que és 0.2, no 0: s'hi deixa una petita variabilitat. El raonament és diagnòstic, no estètic: si la temperatura del model és alta, dues execucions de la mateixa pregunta produeixen respostes diferents i ja no pots saber si una resposta ha canviat per la modificació de recuperació o pel soroll del mostreig. Una temperatura propera a zero és un requisit previ per poder depurar la recuperació. (chains_v1.py va més enllà i fa servir temperature=0 a les demostracions que no són de RAG.)

El prompt: tres decisions deliberades

Python
# 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() construeix un prompt de xat a partir d'una sola cadena de plantilla amb variables d'entrada {}. Les dues variables —{context} i {question}— s'emplenen en temps d'execució a partir de les claus del diccionari paral·lel que precedeix el prompt a la cadena. L'instructor anomena explícitament el mecanisme a 01:31:38: substituir aquestes variables en temps d'execució és l'acte de fonamentar el model en les fonts.

Fonamentació en les fonts = injectar evidència recuperada al prompt en temps d'execució perquè el model respongui a partir de les teves dades en lloc dels seus pesos. És una operació en preparar el prompt. Sense reentrenament ni fine-tuning, mai.

Tres decisions de disseny, cadascuna amb una feina concreta:

  1. «basant-te només en el context següent»: la clàusula de restricció. Limita l'àmbit de respostes

admeses al text recuperat.

  1. «respon de manera concisa»: control de la longitud de sortida. És barat i manté la resposta

dins d'un pressupost de tokens predictible.

  1. «si no saps la resposta, digues simplement 'No ho sé.'»: la via de sortida del rebuig.

La tercera és la que la gent omet, i ometre-la és un error. «Respon només a partir del context» diu al model què no pot fer; no li diu què ha de fer en lloc d'això. Sense una sortida alternativa autoritzada, un LLM al qual es demana que respongui respondrà. El rebuig és un comportament que has de demanar explícitament.

format_docs: l'enllaç al límit entre tipus

Python
# rag_pipeline.py:104-106
    # Format retrieved docs
    def format_docs(docs):
        return "\n\n".join([doc.page_content for doc in docs])

El recuperador emet List[Document]. La plantilla del prompt necessita un str. format_docs és l'adaptador: uneix el text de tots els fragments amb una línia en blanc entre ells perquè els límits dels fragments continuïn sent visibles per al model 01:31:38.

La lliçó general va més enllà d'aquesta funció: tota cadena LCEL necessita enllaços als límits entre tipus, i LangChain ho facilita; una funció simple de Python situada en un pipeline | es converteix automàticament en un RunnableLambda. Mai no escrius l'embolcall. Res del codi no ho diu, i per això cal explicar-ho.

Aquesta conversió és un cas de la regla que fa llegible tot el fitxer. Tots els components d'aquí —recuperador, plantilla de prompt, model de xat, analitzador de sortida, funció pròpia— implementen la mateixa interfície Runnable: .invoke(), més .batch() i .stream() de franc. Com que comparteixen una interfície, | pot compondre dos components qualssevol, i això és tot el que és LangChain Expression Language. La conseqüència pràctica per depurar: qualsevol posició de la cadena es pot invocar per separat, amb el mateix .invoke() que fas servir per al conjunt. Això és el que fa possible la bisecció més endavant en aquesta part.

El nucli: un literal de diccionari és un pas paral·lel

Python
# rag_pipeline.py:108-114
    # Rag chain
    rag_chain = (
        {"context": retriever | format_docs, "question": RunnablePassthrough()}
        | prompt
        | llm
        | StrOutputParser()
    )

«I aquí tenim el nucli. Aquí és on creem la cadena RAG real.» 01:31:38

Un diccionari simple de Python dins d'una cadena LCEL es converteix implícitament en un RunnableParallel. La mateixa entrada —la cadena original de la pregunta de l'usuari— es distribueix a tots els valors del diccionari, cada branca s'executa concurrentment i les sortides es recullen en un diccionari amb claus que coincideixen amb les variables d'entrada del prompt. Dues claus, dues branques:

  • "context": question → retriever → List[Document] → format_docs → str
  • "question": question → RunnablePassthrough() → the same question, untouched

RunnablePassthrough() és el Runnable identitat i té una funció essencial, no decorativa. El diccionari paral·lel consumeix l'entrada única; sense una branca d'identitat explícita, la branca de recuperació destrueix la pregunta original i {question} es mostra buit (o la plantilla llança un error de variable absent). La formulació de l'instructor a 01:29:38 és exacta: la seva feina és assegurar que la pregunta entrant no canviï.

Hi ha un segon motiu, més subtil, pel qual ha de ser un passthrough i no, per exemple, un reescriptor: allò que es respon és la formulació exacta de l'usuari. Parafraseja-la silenciosament i hauràs canviat la pregunta sense dir-ho a ningú.

StrOutputParser() tanca la cadena extraient el contingut de l'objecte de missatge del model com una cadena simple, de manera que rag_chain.invoke(q) produeix una cosa que es pot mostrar 01:30:38.

El flux de dades complet, tal com es narra a 01:31:38–01:32:39:

Figura 1La chain LCEL: un diccionari en paral·lel alimenta el prompt, seguit del LLM i del parser de sortida
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)

L'ordre de la canonada tampoc no és negociable. retriever | format_docs recupera i després converteix en cadena; inverteix-los i format_docs rebrà una cadena que intentarà recórrer. Les incompatibilitats de tipus en un límit | són l'error habitual de LCEL.

Executar-ho

Python
# 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 preguntes, un bucle simple, .invoke() per pregunta. L'objecte cadena es pot reutilitzar i no conserva estat entre invocacions: sense memòria ni historial de xat, cada pregunta és completament independent. A 01:30:38, totes tres es responen correctament.

Aquest és tot el contracte del RAG bàsic: str → str, amb la recuperació amagada a dins. També és el sostre del RAG bàsic: sense memòria, citacions ni confiança, i sense cap rebuig més enllà del que demana el prompt.

demo_basic_rag() complet (rag_pipeline.py:81-128)
Python
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ó en sis passos: rellegeix la teva cadena en aquest ordre

Quan l'instructor revisa la cadena acabada a 01:31:38–01:32:39, la recorre en un ordre fix, i és un bon hàbit perquè segueix les dades en lloc del fitxer font:

  1. Primer, el prompt. from_template, dues variables d'entrada substituïdes en temps d'execució → fonamentació en les fonts.
  2. El formatador. Com es converteixen els documents recuperats en una sola cadena neta?
  3. El diccionari de la cadena. context i question: el nucli. Quina branca consumeix l'entrada

original i quina la conserva?

  1. La plantilla del prompt rep el diccionari. Les claus del diccionari coincideixen exactament amb les variables

de la plantilla? Un desajust aquí és l'error de temps d'execució més habitual de LCEL.

  1. L'LLM rep el prompt renderitzat. Quin model, quina temperatura?
  2. L'analitzador converteix la resposta en el tipus final. StrOutputParser per a una cadena, o

with_structured_output per a un objecte: mai tots dos.

Si no pots narrar aquests sis passos de la teva cadena sense desplaçar-te pel codi, la cadena fa alguna cosa que no has tingut en compte.

Entorn, segons pyproject.toml del mateix repositori: requires-python >=3.12 (i una versió fixada de 3.12 a .python-version), 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. Observa el paquet del magatzem vectorial: langchain-chroma, no langchain-community. El README publicat del curs —que pertany al segon repositori, fcc-production-rag-part-6, amb la versió fixada a >=3.13— diu «Python 3.10+». Confia en les versions fixades, no en la prosa.

Tres millores que es distribueixen al mateix fitxer

El vídeo del capítol 9 s'atura a demo_basic_rag(), però rag_pipeline.py conté tres cadenes més que són punts de partida estrictament millors per a qualsevol ús real. Cap no es demostra davant la càmera. Val la pena adoptar-les totes tres des del primer dia.

1. Citacions: les fonts viatgen dins de la cadena de context

Python
# 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 fragment es converteix en [n] <source>:\n<page_content>, el prompt demana al model «Inclou quines fonts has fet servir» i la demostració fa una pregunta: «Quins són els components principals de LangChain?», amb resposta a la llista de cinc components de la base de coneixement. El mecanisme és tota la qüestió: les etiquetes de les fonts formen part del text que llegeix l'LLM. No es passen per un canal separat ni s'adjunten com a metadades que el model no veu mai. Si el model no pot veure l'etiqueta, no la pot citar.

.metadata.get("source", "unknown") en lloc de ["source"] és programació defensiva deliberada: un fragment amb un carregador que no hagi establert source es degrada a la cadena unknown en lloc de llançar un KeyError a mitja petició.

2. Mecanisme de reserva: forçar una cadena de rebuig que puguis cercar amb grep

Python
# 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 millora respecte de «digues simplement 'No ho sé'» és que el rebuig és una cadena fixa i exacta. Això converteix l'abstenció en una cosa mesurable: compta les aparicions d'aquesta frase als logs i tindràs una taxa de rebuig. Un rebuig vague no es pot mesurar; un de canònic és una mètrica.

Les tres preguntes de comprovació són un conjunt d'avaluació en miniatura: una amb resposta al corpus (la línia de LangSmith de $39/mes) i dues fora del corpus (la cotització d'OpenAI, el desplegament a AWS). Construeix aquest conjunt per al teu corpus abans de construir res més. Costa tres línies i és l'únic que et separa de «semblava que funcionava quan ho vaig provar».

3. Sortida estructurada: substituir l'analitzador per un esquema

Python
# 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
    )

Observa què falta: no hi ha StrOutputParser(). with_structured_output(RAGResponse) fa que el model emeti un objecte Pydantic validat, de manera que la cadena acaba al model i result.answer / result.confidence / result.sources_used / result.follow_up són atributs, no text que hagis d'analitzar, que és exactament el que mostra la demostració després d'invocar la cadena amb "What is LangGraph?". Aquesta és la forma que vols tan bon punt RAG és darrere d'una API (part 11) en lloc d'un terminal.

El prompt que l'acompanya és deliberadament mínim: «Basant-te en el context següent, respon la pregunta… Proporciona una resposta estructurada.» Les cadenes description= dels camps porten les instruccions. Aquest és el patró: amb sortida estructurada, l'esquema és part del prompt, de manera que has de posar la redacció allà on són els camps, no en una prosa que el model hagi de conciliar amb un esquema.

confidence és autodeclarada i, per tant, no és una probabilitat calibrada: tracta-la com un senyal feble per a l'encaminament (per exemple, «baixa → escalar a una persona») i mai com una garantia de correcció.

L'exercici del lector — DocumentQA, tot el pipeline en una sola classe (rag_pipeline.py:271-312)
Python
    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)

Provat sobre un text breu amb quatre fets sobre Python (Guido van Rossum, publicat per primera vegada el 1991, Python 3.12 publicat l'octubre de 2023, anomenat així per Monty Python) amb tres preguntes. Chunking 500/50, k=3, gpt-4o-mini a temperatura 0.2 i un format de sortida [Confidence: X] Answer.

Dos defectes que cal corregir abans de reutilitzar-lo. El magatzem Chroma es construeix sense persist_directory: és en memòria, desapareix en sortir del procés i torna a generar els embeddings en cada construcció. I aquí format_docs uneix amb "\n" en lloc de "\n\n", cosa que fusiona visualment els fragments adjacents en el que sembla un passatge continu; el doble salt de línia de demo_basic_rag existeix precisament per mantenir visibles per al model els límits dels fragments.

La dutxa freda

El capítol 9 acaba a mitja frase, amb el plantejament: has seguit un tutorial de RAG en línia i tot funciona 01:32:39. El capítol 10 completa la frase a 01:33:18:

«en el moment que hi afegeixes 10,000 documents, tot es trenca. Tot, realment tot es trenca.»

Aquesta mateixa frase és l'epígraf del segon repositori del curs, fcc-production-rag-part-6: «Has seguit un tutorial de RAG. Funcionava amb 10 documents. Després has provat amb 10,000… i tot s'ha trencat.» La demostració funcional del capítol 9 es posiciona deliberadament com la base ingènua que els vint-i-tres capítols restants desmunten.

Llegeix-ho amb atenció, perquè la forma de l'afirmació és la idea diagnòstica. No ha canviat res al pipeline. El codi és idèntic. La mida dels fragments és idèntica. El model d'embeddings és idèntic. L'únic que ha canviat és el nombre de veïns que competeixen per les posicions top-k.

Per això l'èxit amb un corpus petit no és cap prova. Amb deu documents, gairebé no hi ha res darrere del qual es pugui amagar una resposta incorrecta: recupera'n dos de deu i tens el 20% del corpus al context; recupera'n dos de deu mil i tens el 0.02%. Qualsevol defecte de chunking, desajust de vocabulari o feblesa d'ordenació queda emmascarat amb N petit i exposat amb N gran.

L'afirmació que organitza el capítol és el titular del curs: el 90% dels sistemes RAG fallen en producció i tots fallen pels mateixos cinc motius 01:33:18.

Els cinc modes de fallada

#FalladaSímptoma que observesEtapa que fallaSolucióEs tracta a
1Chunking inadequatLa resposta és parcial o es construeix a partir d'un fragment que sembla un tros de fraseDivisióLímits semàntics + solapamentPart 3
2Desajust d'embeddings (deriva semàntica)El fragment adequat existeix i no es recupera mai; vocabulari de l'usuari ≠ vocabulari del documentGeneració d'embeddings / RecuperacióCerca híbrida, reescriptura de consultes, recuperació contextualParts 6, 14
3Soroll en la recuperacióEl fragment adequat sí que es recupera, enterrat entre veïns irrellevants; la resposta es dilueixRecuperació / FusióReranking, filtratge, compressióPart 6
4Desbordament del contextS'ha recuperat tot; el model n'ignora la meitat i la resposta es truncaMuntatge del promptTruncament intel·ligent, pressupost de tokens, map-reducePart 9
5Al·lucinacióLa resposta contradiu un fragment que s'ha recuperat i proporcionat correctamentGeneracióPrompts restrictius + citacions (aquí), avaluacions que ho detecten (part 7), validació de sortida (part 12), recuperació amb autocorrecció (part 15)Parts 7, 12, 15

L'instructor promet a 01:34:19 disseccionar, diagnosticar i corregir cadascuna de les fallades. A la pràctica, el capítol 10 corregeix la #1, dissecciona la #2 sense corregir-la, deriva la #3 al capítol 11 i deixa els modes #4 i #5 per a més endavant. Convé saber-ho per no esperar dins d'aquest capítol una resolució que no arriba mai.

#1 — Un chunking inadequat destrueix el significat silenciosament

La definició operativa del capítol d'un bon fragment és semàntica, no basada en la mida:

Un fragment és bo si encara significa alguna cosa per si sol després d'haver estat arrencat del document.

L'exemple de la diapositiva és una política de teletreball de recursos humans tallada al lloc equivocat:

  • fragment A: «la nostra política permet fins a»
  • fragment B: «3 dies per setmana individualment»

Cap dels dos no respon «quants dies de teletreball em pertoquen?». El fragment A té el subjecte i cap xifra; el fragment B té la xifra i cap subjecte. El tall ha destruït el significat 01:35:20. El nom tècnic és context desconnectat.

La propietat crítica és que la capa de recuperació funciona perfectament. Troba i retorna fidelment el vector més proper. La unitat que recupera està malmesa. És l'invariant 1 en la seva forma més crua: depura la primera etapa que falla, no el símptoma visible.

#2 — Desajust d'embeddings: l'usuari diu «cancel·lar» i el document diu «política de rescissió»

«Quan les consultes dels usuaris fan servir paraules diferents de les que es troben als documents, la cerca semàntica falla.» 01:45:32

Per a una persona, totes dues expressions signifiquen el mateix. Per a un model d'embeddings, poden quedar prou allunyades a l'espai vectorial perquè el fragment adequat no entri mai als top-k: la consulta i el corpus, en paraules de l'instructor, no són congruents 01:33:18.

El que fa especialment problemàtic aquest cas és que és invisible des de la resposta. El model dona una resposta segura i ben formada construïda a partir dels fragments equivocats, i no hi ha cap senyal enlloc que existia un fragment millor que s'ha passat per alt. El capítol 10 no ho resol: et fa recórrer la mecànica (embedding individual → lot → cosinus → ordenació) perquè puguis veure numèricament on es produeix l'error. Les solucions reals arriben després: BM25 detecta la manca de coincidència lèxica (part 6), la reescriptura de consultes genera el vocabulari que no has fet servir (part 6) i la recuperació contextual reescriu el fragment mateix (part 14, amb una millora de precisió declarada del +15–20%).

#3 — Soroll en la recuperació: els LLM sí que es confonen

L'exemple de 01:33:18 és concret i val la pena memoritzar-lo com a proporció: es demana al recuperador que obtingui 10 documents, en retorna obedientment 10 i només 2 són realment rellevants.

La resposta hi és. Això és el que diferencia aquest cas del #2. La fallada és la dilució: vuit veïns irrellevants al costat dels dos bons.

«I aleshores l'LLM realment es confon. Sí, els LLM es confonen.» 01:52:41

Aquest comentari de passada corregeix una suposició molt habitual i molt equivocada: que una finestra de context més gran fa irrellevant la qualitat de la recuperació. Els fragments irrellevants addicionals no són farciment gratuït: són distractors actius. Augmentar k per compensar un recuperador feble ho empitjora, no ho millora.

#4 — Desbordament del context

S'omple el prompt amb massa material, l'LLM n'ignora la meitat i les respostes es trunquen 01:34:19. Observa el doble sentit que fa servir l'instructor i que no desambigua: es trunca el context (límits estrictes de tokens) i es trunquen les respostes (el model es queda sense pressupost o sense atenció). És el problema de la informació perduda al mig, exposat informalment.

#5 — L'al·lucinació persisteix amb una recuperació perfecta

«Els grans models de llenguatge són molt bons al·lucinant perquè són bons ignorant el context encara que la resposta sigui allà mateix.» 01:34:19

Per això l'al·lucinació figura com un mode de fallada propi en lloc de ser un símptoma dels altres quatre. Pots corregir el chunking, corregir el desajust de vocabulari, eliminar el soroll, mantenir-te dins del pressupost de tokens i lliurar al model exactament el paràgraf adequat, i encara es pot inventar una resposta. Fonamentar en les fonts redueix les al·lucinacions; no les elimina. Qualsevol afirmació que RAG elimina les al·lucinacions és simplement falsa.

Per què res no llança excepcions

Aquesta és la propietat que fa que depurar RAG sigui diferent de depurar programari ordinari, i mereix un encapçalament propi perquè totes les tècniques de la resta d'aquesta part existeixen per compensar-la.

Tots cinc modes de fallada produeixen una resposta HTTP 200 ben formada.

  • Chunking inadequat: el model d'embeddings codifica fidelment el fragment. El vector no és incorrecte:

és una representació precisa d'un fragment incomplet.

  • Desajust d'embeddings: el recuperador retorna els k vectors més propers. Sempre hi ha k vectors

més propers.

  • Soroll en la recuperació: el recuperador retorna exactament el que has demanat. k documents.
  • Desbordament del context: el prompt és vàlid, el model respon.
  • Al·lucinació: el model produeix text fluid, plausible i gramaticalment perfecte.

La taxa d'errors és del 0%. La latència és bona. Els quadres de comandament estan en verd. I les respostes són incorrectes. És l'invariant 4, i és el motiu pel qual l'observabilitat precedeix l'optimització en aquesta guia (part 7) en lloc de venir després.

Coherència no és correcció. No pots comprovar la qualitat d'un sistema RAG llegint la resposta i decidint que sona bé. Totes les respostes incorrectes que produeixi aquest sistema sonaran bé: aquesta és la funció del model de llenguatge.

La disciplina de depuració

El mètode que ensenya el capítol, fet explícit 01:33:16–01:53:46:

  1. Reprodueix-ho a escala, no sobre el corpus de joguina. Un pipeline validat amb deu documents no et diu

gairebé res. Si no pots reproduir-ho amb 10,000, almenys fes-ho sobre un corpus prou gran perquè el fragment adequat tingui competència real.

  1. Classifica-ho en una de les cinc categories abans de tocar el codi. Endevinar quina etapa ha fallat

i després editar-la és la manera de passar una setmana ajustant un segmentador per un problema d'embeddings.

  1. Inspecciona els fragments recuperats, no la resposta. Aquest és tot el truc, i es mereix

la secció següent.

  1. Corregeix la primera etapa que falla. Els defectes de chunking no es poden compensar en etapes posteriors.

Un altre cop, l'invariant 1.

El pas 3 és tot el truc: divideix el pipeline en dos

Una cadena RAG té exactament una unió que pots tallar de manera neta: el límit entre recuperació i generació. Tot el que hi ha abans de format_docs és recuperació. Tot el que hi ha després és generació. Talla aquí i convertiràs una pregunta irresoluble («per què aquesta resposta és incorrecta?») en dues que es poden respondre:

S'ha recuperat el fragment adequat?

  • No → l'error és en una etapa anterior. Etapa: divisió (#1), generació d'embeddings/recuperació (#2). L'LLM és innocent.
  • Sí → l'error és en una etapa posterior. Etapa: muntatge (#3, #4) o generació (#5).

És la regla de la part 4 reformulada operativament —l'afirmació del curs és que el 90% de les fallades de RAG són de recuperació, no de generació— i el motiu pel qual has de provar la recuperació per separat abans de culpar el model. Substituir gpt-4o-mini per un model de frontera per corregir un error de recuperació és l'operació sense efecte més cara d'aquest àmbit: si recuperes els documents equivocats, cap model de generació no et pot salvar.

El recuperador és un Runnable, de manera que el pots invocar per separat. Sense cadena, sense LLM, sense cap cost més enllà d'un embedding de consulta:

Python
# 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]}...")

El que extreu aquesta única visualització, relacionat directament amb la taxonomia:

Què veusDiagnòstic
Un fragment que sembla un tros de frase o que acaba a mitja idea#1 chunking inadequat: ves a corregir el segmentador
El fragment adequat és completament absent i les paraules de la consulta no apareixen mai al corpus#2 desajust d'embeddings
El fragment adequat és a la posició 3 o 4, envoltat de material inútil#3 soroll en la recuperació: aplica reranking o un filtre
El fragment adequat és a la posició 1 i la resposta encara el contradiu#5 al·lucinació: l'LLM l'ha ignorat
RETURNED és inferior a kUn filtre o un llindar de puntuació ha retallat la llista: k és un màxim, no una quota, i el codi posterior que assumeixi len(docs) == k fallarà

Instrumentar la cadena mateixa

De vegades, la unió que necessites és dins de la cadena. chains_v1.py inclou tres tècniques, i són la meitat basada només en LangChain del que la part 7 substituirà després per LangSmith:

Python
# 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ètode 1 — Esquemes. chain.input_schema.model_json_schema() i .output_schema t'indiquen què creu la cadena que accepta i retorna. Així és com resols la qüestió anterior de cadena directa o diccionari sense endevinar.

Mètode 2 — with_config(run_name=...). Dona nom a l'execució perquè, quan activis el seguiment de traces (part 7), el tram tingui una etiqueta humana en lloc d'un UUID. Observa que tags="demo,debugging" està comentat per un motiu: with_config(tags=...) espera una list[str], no una cadena amb comes. Si el tornes a activar, escriu tags=["demo", "debugging"].

Mètode 3 — Punts de registre amb RunnableLambda. La propietat important, i el motiu pel qual aquest patró es generalitza, és que log_step retorna x sense canvis. És un observador pur intercalat a la canonada. És l'invariant 6 —la monitorització observa i no ha de canviar mai el comportament— implementat en tres línies. Insereix-ne un entre retriever i format_docs i veuràs els documents recuperats en cada petició sense alterar la semàntica de la cadena.

chains_v1.py també conté un esquelet RAG amb un recuperador simulat (demo_passthrough_chain) que és molt útil per aïllar problemes: executa tota l'estructura de la cadena amb una cadena de context fixada al codi i sense cap magatzem vectorial:

Python
# 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()
    )

Substitueix-lo per un recuperador de prova que retorni el fragment que saps que és correcte. Si la resposta encara és incorrecta, la recuperació mai no ha estat el problema i estàs davant del #4 o el #5. Si la resposta de sobte és correcta, tot el que hi ha abans és sospitós. És una bisecció neta i costa una crida a l'LLM.

(La doble extracció x["question"]["question"] de la línia 95 és un artefacte del fet que aquest fitxer invoca amb un diccionari: RunnablePassthrough() deixa passar tot el diccionari d'entrada. L'estil de cadena directa de rag_pipeline.py ho evita, i itemgetter("question") és l'expressió més neta si necessites l'estil de diccionari.)

Anàlisi forense de l'etapa 1: el segmentador sota el microscopi

Quan la bisecció diu «el fragment recuperat és incomplet», estàs depurant el segmentador. text_splitters.py et proporciona els instruments.

Per què el recursiu és l'opció predeterminada fiable

Quatre propietats connectades, de 01:39:26–01:40:26:

  1. Conserva la coherència semàntica dividint jeràrquicament mitjançant una llista ordenada de

separadors, en lloc de tallar cada N caràcters.

  1. La jerarquia codifica una teoria del significat. Primer paràgrafs, després frases i després

paraules, perquè un paràgraf hauria de contenir una idea, i una frase també 01:39:26. El segmentador passa a un separador més fi només quan el més gruixut no pot satisfer chunk_size.

  1. Respecta els límits naturals: no emetrà «unsupervised» i després tallarà abans de

«learning», perquè mig terme no és un terme.

  1. El benefici arriba en les etapes posteriors, no en indexar. La qualitat del chunking no és observable quan

fragmentes; és observable setmanes després, en la qualitat de les respostes. Precisament per això és el defecte més difícil d'atribuir.

Python
# 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 és una introducció a l'aprenentatge automàtic en Markdown —un títol #, seccions ## i dues subseccions ###, amb llistes d'algoritmes amb vinyetes—, i aquesta és la qüestió: té una estructura real d'encapçalaments que els separadors poden trobar.

La llista de separadors ["\n\n", "\n", " ", ""] és paràgrafs → línies → paraules → caràcters. (Els subtítols automàtics ho transcriuen com «dobles salts de línia, salts de línia també cadena buida i cometes», i per això el codi és la font d'autoritat, no la transcripció.) La cadena buida és l'últim recurs: tallar a nivell de caràcter, que és chunking de mida fixa amb un altre nom i produeix els fragments inútils tallats al mig de paraules de què adverteix la part 3.

split_text és correcte aquí, i només aquí, perquè SAMPLE_TEXT és una cadena original sense metadades que es puguin perdre: l'instructor ho diu mentre ho escriu 01:37:25. La regla de create_kb continua vigent: els pipelines reals contenen objectes Document i fan servir split_documents.

Executar-ho amb el fitxer distribuït mostra:

text
Original length: 887 chars
Number of chunks: 2
Chunk sizes: [462, 423]

Llegeix aquestes tres xifres com un diagnòstic, no com una curiositat: és la mateixa aritmètica que hem aplicat a KNOWLEDGE_BASE, aquesta vegada amb el resultat contrari. 462 + 423 = 885 davant d'una font de 887 caràcters: el tall ha caigut en un \n\n, que es consumeix, i no s'ha duplicat res; el segmentador només arrossega un fragment final quan aquest cap dins del pressupost de solapament de 50 caràcters, i els paràgrafs sencers no hi caben. Per tant, chunk_overlap=50 no t'ha aportat res en aquest document. En canvi, quan les mides dels fragments sumen clarament més que la font, el segmentador talla dins dels paràgrafs i pagues solapament a cada límit. Dues xifres i ja saps com ha anat la divisió.

El solapament és una assegurança barata

«Per tant, el solapament és essencialment el que anomenem una assegurança barata.» 01:43:31

La idea més potent del capítol 10. Solapament vol dir que els N caràcters finals del fragment i es repeteixen com els N caràcters inicials del fragment i+1. L'objectiu és assegurar que el significat situat a banda i banda d'un límit aparegui complet almenys en un fragment, perquè el context d'un límit no quedi mai orfe 01:45:32.

La fallada que evita és concreta i exasperant: una redundància petita i barata és el que impedeix que el teu sistema RAG tingui la resposta i sigui incapaç de trobar-la 01:43:31.

L'exemple resolt de la clau d'API 01:44:32–01:45:32: reprodueix-lo mentalment cada vegada que estableixis chunk_overlap. Text d'origen:

«La clau d'API caduca al cap de 24 hores. L'has de renovar fent servir l'endpoint de tokens.»

Sense solapament:

FragmentContingutConté
1«La clau d'API caduca al cap de 24 hores»El problema, cap solució
2«L'has de renovar fent servir l'endpoint de tokens»La solució, no diu mai «caducitat»

L'usuari pregunta: «Com gestiono la caducitat de l'API?» El recuperador troba coincidència amb el fragment 1 —conté «caduc…»— i el retorna. La coincidència és correcta. La resposta és inútil. El fragment 2, que conté la solució real, puntua malament perquè no esmenta mai la caducitat.

Amb solapament: el fragment 2 també conté «…caduca al cap de 24 hores. L'has de renovar», de manera que tots dos fragments contenen el problema i la solució, i, sigui quin sigui el que triï el recuperador, l'LLM rep un context complet que permet actuar.

«És la diferència entre trobar una resposta i trobar una resposta completa. Són dues coses diferents.» 01:45:32

La demostració que fa visible el solapament:

Python
# 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 segmentadors que difereixen exactament en un paràmetre —solapament 0 contra 20— sobre una cadena deliberadament repetitiva de 450 caràcters, mostrant una finestra de 20 caràcters a cada banda del primer límit. La sortida real:

text
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...

Sense solapament, els dos fragments són estrictament contigus i no comparteixen res: la frase «the lazy dog. The quick brown fox» existeix al corpus però en cap fragment individual. Amb solapament, el fragment 2 repeteix visiblement el final del fragment 1, de manera que una consulta sobre «lazy dog» ara troba un fragment que conté tota l'expressió en lloc de dos que en contenen una meitat cadascun.

Aquest és el benefici. La demostració també mostra la factura, si comptes: la mateixa cadena de 450 caràcters produeix 10 fragments amb solapament 0 i 15 amb solapament 20. El solapament no és gratuït: en aquest document, és un augment del 50% dels vectors que cal generar, emmagatzemar i cercar. «Assegurança barata» és una afirmació sobre la proporció, no sobre un cost nul.

Explorar el paràmetre que estàs a punt de triar a ull

Python
# 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")

Aquesta funció no s'executa davant la càmera i val més que moltes de les que sí que s'hi executen. Recorre 200 / 500 / 1000 i deriva el solapament com size // 5: una regla pràctica del 20%, a l'extrem superior de la franja de 10–20% de la part 3. Sobre el SAMPLE_TEXT distribuït de 887 caràcters, mostra:

text
=== Chunk Size Comparison ===
 Size 200: 6 chunks
 Size 500: 3 chunks
 Size 1000: 1 chunks

Compara aquesta línia del mig amb recursive_splitter(), que fa servir la mateixa mida de fragment i el mateix document i produeix 2 fragments, no 3. L'única diferència és el solapament: 50 contra 500 // 5 = 100. Augmentar el solapament ha fabricat un fragment addicional. És l'efecte silenciós de segon ordre del paràmetre que tothom ajusta primer: el nombre de fragments, la despesa en embeddings i la mida de l'índex són funcions de totes dues xifres, i amb chunk_size=1000 tot el document es redueix a un sol fragment; en aquest punt has deixat de fer recuperació.

Executa-ho sobre el teu corpus, després executa l'inspect_retrieval anterior amb cada configuració i compara què retorna realment. Aquest és el cicle: explorar, recuperar i llegir els fragments. Els recomptes de fragments, per si sols, no et diran quina configuració és millor.

La resta de text_splitters.py: importat, distribuït i mai executat en aquest capítol

El fitxer importa quatre classes de segmentador més l'enumeració Language, i aquest capítol demostra exactament un dels segmentadors. Coneix per a què serveix la resta abans de necessitar-los (la part 3 en desenvolupa tota l'argumentació):

  • MarkdownHeaderTextSplitter: markdown_splitter() (línies 136–149) divideix per

[("#","h1"), ("##","h2"), ("###","h3")] i porta la ruta d'encapçalaments a chunk.metadata. Sobre SAMPLE_TEXT produeix 4 fragments amb metadades com {'h1': 'Introduction to Machine Learning', 'h2': 'Types of Machine Learning', 'h3': 'Supervised Learning'}: una ruta de navegació per fragment. Aquestes metadades són el que permet citar a nivell d'encapçalament. No s'executa mai davant la càmera.

  • Enumeració Language + from_language: code_splitter() (línies 152–160) fa servir

RecursiveCharacterTextSplitter.from_language(language=Language.PYTHON, chunk_size=500, chunk_overlap=50) sobre SAMPLE_CODE (797 caràcters: un quicksort i un binary_search) i el divideix en 2 fragments de 390 i 402 caràcters, una funció cadascun, que és la qüestió. Fragmentar codi amb un segmentador genèric talla les funcions per la meitat i fa que totes dues meitats siguin inútils com a context.

  • document_splitter() (línies 163–180): l'única funció del fitxer que fa servir

split_documents, sobre PyPDFLoader("./docs/langchain_demo.pdf"), mostrant les metadades del primer i de l'últim fragment. Aquesta és la forma d'un pipeline real.

  • CharacterTextSplitter i TokenTextSplitter s'importen i no es fan servir mai enlloc del

fitxer.

document_splitter() és l'única funció que queda descomentada a __main__; per tant, clonar el repositori i executar python text_splitters.py executa la demostració de PDF, no les dues que recorre aquest capítol. El PDF s'inclou al repositori a docs/langchain_demo.pdf, però la ruta és relativa, de manera que la demostració només s'executa des de l'arrel del repositori.

Anàlisi forense de l'etapa 2: els embeddings al descobert

Quan la bisecció diu «el fragment adequat no s'ha recuperat mai i el vocabulari difereix», estàs depurant l'etapa d'embeddings. embeddings_deep.py elimina deliberadament les abstraccions: reconstrueix la recuperació amb numpy perquè puguis observar les xifres.

Comprova la norma abans de confiar en cap puntuació

Mostra np.linalg.norm(vector) de qualsevol embedding que rebis.

  • Els embeddings d'OpenAI estan normalitzats a 1.0. Davant la càmera, la norma es mostra com 1; la cadena

de format f"{...:.4f}" distribuïda fa que vegis 1.0000.

  • Sense normalització, la magnitud original introdueix la longitud del document a les puntuacions de similitud, i els documents llargs guanyen per ser llargs en lloc de ser rellevants.
  • La regla diagnòstica: norma == 1 → normalitzat (bé); norma != 1 → no normalitzat. No tots els models normalitzen, i els que no ho fan no t'ho diran.

L'instructor exposa el motiu de la normalització de manera compacta a 01:48:36:

«evitarà que els documents més llargs tinguin vectors més grans només perquè tenen més contingut.»

És un parany real de portabilitat, no teòric. Substitueix OpenAIEmbeddings per HuggingFaceEmbeddings("sentence-transformers/all-MiniLM-L6-v2") (384 dimensions) o OllamaEmbeddings(model="llama2-7b-embedding-q4_0") —tots dos referenciats a embeddings.py— i pots passar silenciosament a un espai no normalitzat on els llindars que has ajustat amb tanta cura no signifiquen res.

Per a text-embedding-3-small, la demostració mostra 1536 dimensions i els primers 5 components del vector, perquè puguis comprovar a ull que has rebut nombres de coma flotant i no un objecte d'error. (Primer has de reparar el fitxer —consulta el requadre de l'error més avall— perquè les dues funcions que mostren dimensions i normes són exactament les dues que no funcionen tal com es distribueixen.)

ModelDimensionsCost / 1M de tokensMés adequat per a
text-embedding-3-small1536$0.02Ús general: l'opció predeterminada de la guia
text-embedding-3-large3072$0.13Precisió elevada (6.5× el preu)
text-embedding-ada-0021536$0.10Llegat
all-MiniLM-L6-v2 (HuggingFace)384localBarat/fora de línia; comprova la normalització

embed_query o embed_documents

  • embed_query(text) → un vector, per a una consulta.
  • embed_documents([t1, t2, t3]) → una llista de vectors, per a documents. La demostració per lots fa servir

3 textos.

L'observació de l'instructor a 01:48:36 és que cridar-los sembla idèntic: l'únic canvi és que embed_documents rep una llista. El motiu real per fer servir la forma per lots és que el proveïdor empaqueta tota la llista en un sol intercanvi amb l'API.

Però hi ha un motiu més profund pel qual LangChain manté els dos mètodes separats, i el capítol no el diu: alguns models d'embeddings apliquen prefixos o instruccions asimètrics a les consultes i als passatges. Cridar embed_documents sobre una consulta, o a l'inrevés, pot portar-te silenciosament a una regió lleugerament diferent de l'espai. Fes servir el mètode que coincideixi amb el paper del text.

El sistema pre-RAG

Python
# 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 s'escriu a mà en lloc d'importar-la, i aquesta és la qüestió:

text
cos(a, b) = dot(a, b) / (‖a‖ · ‖b‖)

Cinc documents, una consulta, cosinus contra cadascun, ordenació descendent, visualització. És un recuperador al descobert. Observa la petita ironia d'aquest denominador: si els vectors d'OpenAI realment estan normalitzats a la unitat, totes dues normes són 1 i la divisió no té efecte; la similitud del cosinus es redueix a un simple producte escalar. Escriure-la igualment és programació defensiva correcta, perquè tan bon punt hi substitueixes un model que no normalitza, la fórmula continua sent vàlida i només canvien les xifres.

«Per tant, aquest és essencialment el nostre sistema pre-RAG.» 01:51:39 — «encara que sigui rudimentari… imita exactament què fa la recuperació i com funciona.»

L'ordenació és la prova:

PosicióDocumentInterpretació
1 (≈ 0.44)«Python és un llenguatge de programació»Coincidència temàtica directa
2«JavaScript es fa servir per al desenvolupament web»També és un llenguatge de programació: semànticament proper
3–4«L'aprenentatge automàtic fa possibles aplicacions d'IA» / «L'aprenentatge profund fa servir xarxes neuronals»Mateix àmbit general, tema equivocat
5«Els gats són animals de companyia populars»Cap relació amb els llenguatges de programació

Els dos primers són exactament els que triaria una persona, i ni la paraula «Python» ni «JavaScript» no apareixen a la consulta. És el superpoder de la cerca semàntica en una sola sortida, i convé recordar-lo, perquè la part 6 comença mostrant el mateix mecanisme fallant catastròficament amb SKU i codis d'error, on l'exactitud lèxica és tot el requisit.

Només es llegeix en veu alta la primera puntuació, 0.44; les altres quatre, no. Considera 0.44 aproximat: una nova execució amb text-embedding-3-small diferirà al tercer o quart decimal.

L'execució també reitera la regla de simetria 01:51:39: tant la consulta com els documents s'han de convertir en embeddings amb el mateix model, dins del mateix espai. És l'invariant 2, mostrat en pantalla.

Anàlisi forense de l'etapa 3: el fragment adequat hi és, però enterrat

Si inspect_retrieval mostra el fragment correcte a la posició 3 o 4, envoltat de soroll d'aparença plausible, tens la fallada #3 i el segmentador és innocent. El capítol 10 ho deriva al capítol 11, però advanced_rag.py del mateix repositori ja conté l'escala de solucions, i val la pena saber què existeix abans de construir res.

advanced_rag.py fins i tot inclou les dades de prova adequades. INFO_BURIED és un corpus de dos documents en què la resposta està deliberadament ofegada: un paràgraf sobre LangChain dins d'un document d'història de l'empresa ACME ple de finançament de sèrie B, política de permisos retribuïts, xifres d'ingressos i aportacions empresarials al pla 401(k), i un paràgraf sobre LangGraph al mig d'un manual operatiu de plataforma de cinc capítols sobre EKS, Auth0 i DataDog. Això és l'aspecte del soroll de recuperació com a dades: construeix el mateix per al teu corpus.

TècnicaQuè resolCodi realCost
Multiconsulta#2 desajust de vocabulari: genera diverses formulacions de la preguntaMultiQueryRetriever.from_llm(retriever=..., llm=...) sobre k=2+1 crida a l'LLM per consulta
Compressió contextual#3 soroll, #4 desbordament: extreu només les frases rellevants per a la consulta de cada fragmentContextualCompressionRetriever(base_compressor=LLMChainExtractor.from_llm(llm), base_retriever=...k=4)1 crida a l'LLM per document recuperat
Híbrida / conjunt de recuperadors#2 manca de coincidències lèxiques: paraules clau BM25 + vector densEnsembleRetriever(retrievers=[bm25, semantic], weights=[0.4, 0.6]), tots dos amb k=3+20–50 ms
Document pare#1 fragments incomplets: cerca fragments petits, retorna'n de gransParentDocumentRetriever(child_splitter=200/20, parent_splitter=800/100)Magatzem de documents addicional
Python
# 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
    )

Observa que els pesos distribuïts són [0.4, 0.6] —40% paraules clau, 60% semàntica—, mentre que la narració del curs recomana començar amb [0.5, 0.5]. Tots dos són defensables; la qüestió és que el pes és un paràmetre que ajustes contra un conjunt de prova, i la part 6 desenvolupa aquesta argumentació juntament amb la fusió RRF, k=4 i la manca d'actualitzacions incrementals de BM25.

Python
# 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)

Els fills petits (200/20) donen coincidències vectorials precises; els pares grans (800/100) donen a l'LLM una idea completa. És una resposta estructural a la mateixa malaltia que el solapament tracta químicament.

La cadena avançada completa n'apila dues —multiconsulta per a l'exhaustivitat i després compressió per a la precisió— i després reutilitza exactament la mateixa estructura LCEL que has construït al començament d'aquesta part:

Python
# 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()
    )

Aquest és el benefici de l'estructura LCEL. Totes les millores de les parts 6 a 16 són una substitució en una posició d'aquest pipeline: un recuperador diferent, un formatador diferent, un analitzador diferent. La cadena que has escrit en quaranta línies és l'última peça d'arquitectura que escrius.

Recórrer la taxonomia a l'inrevés

Imprimeix aquesta taula. És l'índex que va del símptoma a l'etapa.

SímptomaPrimera comprovacióMode probableVes a
La resposta és un fragment incomplet o s'interromp a mitja ideaLlegeix el text del fragment recuperat#1 chunkingPart 3
La resposta és incorrecta però segura; el fragment adequat no és al conjunt recuperat; la formulació de la consulta difereix del corpusinspect_retrieval: falta el fragment objectiu?#2 desajust d'embeddingsParts 6, 14
El fragment adequat es recupera a la posició 3–4 entre material inútilPosició del fragment objectiu en l'ordenació#3 soroll en la recuperacióPart 6
Context llarg; la resposta ignora el mig o es truncaRecompte de tokens del prompt muntat#4 desbordament del contextPart 9
Fragment adequat a la posició 1; la resposta el contradiuCompara la resposta amb docs[0].page_content#5 al·lucinacióParts 7, 12, 15
La resposta canvia entre execucions idèntiquestemperatureNo és un error de RAGEstableix 0–0.2
Menys resultats que kUn filter o un llindar de puntuacióNo és cap error: k és un màximPart 4
Ahir tot funcionava, avui res, sense canvis de codiHa canviat el model d'embeddings o la seva versió?Vulneració de l'invariant 2Torna a indexar

I la regla que governa l'ordre de treball:

Construeix → depura → optimitza → després escala. Escalar un recuperador de baixa qualitat produeix respostes incorrectes més ràpidament i a més cost. Totes les parts posteriors pressuposen que ja saps distingir quina etapa ha fallat.

Nota sobre el material d'origen

Dues correccions que aquesta part aplica a la font, exposades clarament en lloc de dissimular-les:

  1. **La diapositiva 07 (07-why-llm-debugging-is-hard.png) està indexada al capítol 10 i no pertany

aquí.** El contingut —no-determinisme, errors en cascada, fallades silencioses, sorpreses de cost— no apareix enlloc de la transcripció del capítol 10, i tots quatre termes apareixen al capítol 12 (observabilitat, 02:21:10). Es fa servir a la part 7 d'aquesta guia. Les diapositives reals en pantalla del capítol 10 —la llista dels cinc modes de fallada, l'exemple «la nostra política permet fins a / 3 dies per setmana» i l'exemple de solapament de la clau d'API— no es van capturar com a imatges.

  1. L'anunci de «truncament intel·ligent» a 01:53:42 està mal classificat com a solució per al soroll

en la recuperació; es proporciona al final del capítol 11 com a solució per al desbordament del context. Vegeu el requadre anterior.

El capítol 10 acaba a mitja frase, amb el traspàs a la cerca híbrida 01:53:42:

«Sabem que la cerca vectorial és increïble.»

Aquí és on comença la part 6: amb els casos en què no ho és.

Llista de comprovació

Cada element anomena la comprovació, no només l'objectiu. Si no pots executar la comprovació, la casella no està marcada.

Abans de dir que el sistema «funciona»:

  • load_dotenv() apareix abans del primer constructor de client del fitxer. Llegeix el bloc d'importacions de dalt a baix i confirma l'ordre.
  • El model d'embeddings és una constant de nivell de mòdul, declarada una vegada. grep -c 'OpenAIEmbeddings(' yourfile.py retorna 1.
  • Has fet servir split_documents([doc]) —amb la llista—, no split_text. Després comprova amb una asserció que existeix chunks[0].metadata["source"]; si llança una excepció, has fet servir el mètode equivocat.
  • Cada fragment porta un source significatiu. Tot allò que després puguis voler fer servir per filtrar o citar és a les metadades en el moment de la indexació: no s'hi pot afegir després sense tornar a indexar.
  • persist_directory apunta a una ruta estable, no a tempfile.mkdtemp(). Executa l'indexador dues vegades i confirma que la segona execució no fa cap crida a l'API d'embeddings.
  • Mostra els límits dels fragments una vegada, a mà. [len(c.page_content) for c in chunks] més els primers i últims 60 caràcters de cadascun. Si una llista numerada, una taula o una definició queda tallada per la meitat, corregeix ara el segmentador: el corpus de demostració d'aquest mateix capítol no supera aquesta comprovació.
  • temperature és 0 o 0.2. Fes la mateixa pregunta dues vegades i compara les respostes; si difereixen, no pots atribuir res.
  • El prompt té els quatre ingredients: clàusula de restricció, clàusula de rebuig, {context}, {question}.
  • La cadena de rebuig és exacta i es pot cercar amb grep, de manera que grep -c sobre els logs dona una taxa de rebuig.
  • Saps si la cadena rep una cadena de text directa o un diccionari, i ho has comprovat amb chain.input_schema.model_json_schema() en lloc de provar totes dues opcions.
  • Tens tres preguntes de comprovació —una amb resposta segura al corpus i dues clarament fora— i són al repositori, no a l'historial de l'intèrpret d'ordres.

Abans de dir que una resposta incorrecta és un error de l'LLM:

  • Has executat el recuperador sol i has llegit el text dels fragments, no la resposta.
  • Has mostrat doc.metadata['source'] al costat de cada resultat.
  • Has comprovat la polaritat de la puntuació —distància o similitud?— abans d'aplicar cap llindar.
  • Has comparat len(docs) amb k (un filtre o un llindar de puntuació pot haver retallat la llista).
  • Has comprovat np.linalg.norm(vector) si has canviat de proveïdor d'embeddings.
  • Has intercalat un punt de registre RunnableLambda entre retriever i format_docs i has mirat què s'ha lliurat realment al prompt, en lloc del que suposes que se li ha lliurat.
  • Has substituït el recuperador per un recuperador de prova que retorna el fragment que saps que és correcte. Encara és incorrecta → l'error és el #4 o el #5 i és en una etapa posterior. De sobte és correcta → tot el que hi ha abans és sospitós.
  • Has classificat la fallada en una de les cinc categories abans d'editar el codi i pots dir en veu alta el número de la categoria.
  • Has corregit la primera etapa que falla, no la més visible.
  • Has canviat exactament una variable i has tornat a executar les mateixes preguntes de comprovació.

Decisions que cal prendre ara i que són cares de canviar després:

DecisióValor inicialReversible?
Model d'embeddings + versiótext-embedding-3-small, 1536 dimensions, $0.02/1MNo: canviar-lo invalida tot l'índex
Què s'inclou a les metadades dels fragmentssource com a mínim; afegeix tot allò que puguis fer servir per filtrar o citarNo: requereix tornar a indexar
Mida del fragment / solapament500 / 50 caràcters, després explora 200/500/1000 amb un 20% de solapamentSí, però requereix tornar a indexar
k4, no 2; augmenta'l només després de corregir la qualitat de l'ordenacióSí, de franc
Persistènciapersist_directory estable des del primer diaSí, però tornes a generar els embeddings
Model de generaciógpt-4o-mini, temperatura 0.2Sí: substitueix-lo lliurement, aquesta és l'asimetria
Forma de la sortidaStrOutputParser per al terminal; with_structured_output darrere d'una APISí