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

Per què RAG falla en producció i com encaixen les peces

Identifica els modes de fallada i entén el mapa complet, la chain canònica i els sis invariants.

42 min de lectura 25 seccions Fonaments
Resum en àudio · 4:34 · CA
Per què RAG falla en producció i com encaixen les peces

Ja has construït sistemes RAG. Funcionaven. En vas fer una demostració, les respostes eren bones i, quan els vas connectar al corpus real, van deixar de ser-ho: sense llançar cap excepció, sense cap línia vermella als logs i sense que es mogués cap mètrica. Aquesta experiència concreta és el punt de partida de tota la guia i també de l'inici del curs original 00:00:12. L'objectiu declarat és la transició del prototip a la producció, no una introducció a RAG, i aquesta distinció condiciona tot el que ve després. No t'ensenyen què és un embedding; t'ensenyen per què el teu no es recupera.

Aquesta part té dos objectius. Primer, identifica les fallades amb prou precisió perquè qualsevol part posterior pugui assenyalar-ne una i dir: aquest és el component que estic corregint. Segon, presenta el mapa: la visió de conjunt, la chain canònica de la qual les quinze parts restants només substitueixen algun component i els sis invariants que regeixen tota la resta. Llegeix aquesta part una vegada de principi a fi. Després, fes-la servir com a índex de referència quan alguna cosa falli.

El precipici: de deu documents a deu mil

«Funcionava amb 10 documents, però després decideixes afegir-hi 10,000 documents i tot deixa de funcionar.» 00:00:12

El detall important d'aquesta frase és justament el que no hi apareix: el codi no ha canviat. El mateix loader, el mateix splitter, el mateix model d'embeddings, el mateix vector store i el mateix prompt. L'única variable que ha canviat és la mida del corpus, que s'ha multiplicat per mil, i el sistema ha passat de ser útil a no servir.

L'incís que l'instructor afegeix tot seguit, «et sona?» 00:00:19, també té una funció. Topar amb aquest mur és el resultat habitual de seguir un tutorial; no demostra que hagis fet una bestiesa. El mur és una propietat de l'arquitectura, no una qüestió de la teva disciplina.

I tampoc és un error en el sentit al qual estàs acostumat. És una propietat de la manera com RAG es degrada. Un corpus de deu documents amaga tots els defectes del pipeline perquè no hi ha competència pels llocs del top-k. La base de coneixement de demostració que trobaràs més endavant en aquesta part és una cadena Markdown de 1,010 caràcters dividida amb chunk_size=500; després, la demostració fa la recuperació amb k=2. Sigui quin sigui el resultat del splitter, una fracció considerable de tot el corpus arriba al prompt amb cada pregunta. La resposta correcta hi és per casualitat. La qualitat de la recuperació no s'està posant a prova: s'està esquivant.

Amb deu mil documents, que fàcilment poden generar centenars de milers de fragments, cadascun d'aquests defectes esdevé decisiu. Ara hi ha milers de fragments que podrien tractar de la teva consulta, i la funció de classificació realment ha d'encertar. Un fragment tallat a mitja frase perd davant d'un altre que conserva la frase sencera. Una consulta formulada amb el vocabulari de l'usuari queda desconnectada de documents redactats amb el vocabulari de l'empresa. No es produeix cap error. El sistema simplement comença a respondre, sense avisar, a partir de dos fragments equivocats.

L'afirmació del 90% i la part que val la pena conservar

«El 90% dels sistemes [RAG] que hi ha fallen en producció.» 00:00:22 «I tots fallen pels mateixos motius.» 00:00:24

Cal explicar amb honestedat què representa aquesta xifra. És una estimació de l'instructor basada en la seva experiència docent, presentada com una afirmació categòrica sense cap font. El README de la part-6 la reformula com a *«per què el 90% dels projectes RAG fallen en producció»*: projectes a la font escrita i sistemes a l'àudio. La mateixa afirmació, dos substantius i cap estudi que avali ni l'un ni l'altre. No la traslladis a un document de disseny com si fos un fet.

La segona afirmació sí que mereix un lloc a la guia. Si les fallades de RAG fossin particulars de cada sistema, si cada sistema fallés d'una manera nova i pròpia, no hi podria haver cap programa formatiu, llista de comprovació ni procés de reforç per a producció. Si es pot escriure una guia com aquesta és perquè el conjunt de fallades és petit, finit i enumerable. El mateix curs, en el README de la part-6, atribueix aquesta classificació a l'experiència de formar 300K+ estudiants i observar repetidament els mateixos problemes, i en fixa el nombre en cinc. Que el nombre real sigui cinc o set no és el més important; el que importa és que és acotat, i un conjunt acotat de fallades es pot convertir en un procediment de diagnòstic.

A qui s'adreça i quins coneixements pressuposa

En un incís a 00:00:29, l'instructor deixa entendre que l'alumne previst ja ha construït sistemes RAG que no funcionen. Això defineix amb precisió el nivell, i aquesta guia parteix del mateix supòsit:

RequisitNivell
PythonDomini de funcions, classes i gestió de paquets
APIConeixements bàsics de REST
LLMÉs útil conèixer-los, però no és imprescindible
Coneixements previs d'ML / IANo són necessaris
GPUNo és necessària: tot el codi s'executa amb CPU; l'única excepció, ColPali a la Part 16, és opcional

No ets principiant a l'hora de construir sistemes. Ets principiant a l'hora de fer que resisteixin el contacte amb un corpus real, usuaris reals, una factura real i un adversari real. Per això aquesta guia no comença explicant «què és un embedding».

Abans de posar nom als conceptes, cal fixar-se en un altre aspecte del plantejament de la font: la introducció oral no esmenta cap proveïdor, model o biblioteca. Ni OpenAI, ni LangChain, ni Chroma: només apareixen al títol del vídeo. Els modes de fallada es descriuen com a propietats de RAG, no d'una pila tecnològica concreta. Per això els diagnòstics d'aquesta part continuen sent vàlids encara que substitueixis tots els components: les correccions són arquitectòniques i només els exemples de codi són específics de LangChain.

Procedència i criteris de confiança per a tot el que segueix

Tot el contingut d'aquesta guia deriva d'una font amb defectes coneguts. Abans de confiar en cap de les seves xifres, has de conèixer les característiques d'aquesta font.

PropietatValor
FontfreeCodeCamp, Production RAG with LangChain & Vector Databases – Full Course, publicat el 2026-05-26
InstructorPaulo Dichone (350,000+ estudiants, 70+ cursos, desenvolupant IA en producció des del 2015, segons el README de la part-6; no s'esmenta oralment)
Durada07:38:38 distribuïdes en 32 capítols
Transcripció10,598 línies de subtítols · 73,539 paraules, generades automàticament
Vídeo1.26 GB p.webm, AV1, 1920×1080, àudio Opus
Repositori complementari Aproduction-course-main-code: requires-python = ">=3.12", projecte langc-course; el seu README.md és buit (0 bytes)
Repositori complementari Bfcc-production-rag-part-6: requires-python = ">=3.13", projecte fcc-production-rag, capçalera dels requisits datada a «abril de 2026»; l'únic README amb contingut dels dos repositoris

Els dos capítols en què es basa aquesta part són els dos capítols didàctics més curts del curs: el capítol 1 té 1 min 44 s / 276 paraules de plantejament pur, sense codi ni demostració, i el capítol 2 té 6 min 43 s / 1,133 paraules de comentari de diapositives, també sense programació en directe. Tot el codi executable que apareix a continuació és l'equivalent, al repositori, del que mostraven les diapositives: s'ha obert i llegit, no s'ha reconstruït a partir de la narració. L'instructor no va escriure a la pantalla cap del codi d'aquesta part i no se n'ha reconstruït cap fragment a partir de l'àudio.

Les versions exactes de les dependències dels dos repositoris

production-course-main-code/pyproject.toml (requires-python = ">=3.12", nom del projecte langc-course):

TOML
dependencies = [
    "langchain-community>=0.4.1",
    "langchain>=1.2.7",
    "langchain-anthropic>=1.3.1",
    "langchain-core>=1.2.7",
    "langchain-openai>=1.1.7",
    "langgraph>=1.0.7",
    "python-dotenv>=1.2.1",
    "bs4>=0.0.2",
    "pypdf>=6.6.2",
    "langchain-ollama>=1.0.1",
    "langchain-chroma>=1.1.0",
    "rank-bm25>=0.2.2",
    "langgraph-checkpoint-sqlite>=3.0.3",
    "pytest>=9.0.2",
    "fastapi>=0.129.0",
    "uvicorn>=0.40.0",
]

fcc-production-rag-part-6/pyproject.toml (requires-python = ">=3.13", nom del projecte fcc-production-rag):

TOML
dependencies = [
    "langchain>=1.2.0,<2.0.0",
    "langchain-chroma>=1.1.0,<2.0.0",
    "langchain-openai>=1.1.0,<2.0.0",
    "langchain-text-splitters>=1.1.2",
    "networkx>=3.6.1",
    "openai>=2.32.0",
    "python-dotenv>=1.0.0",
    "tiktoken>=0.12.0",
]

El requirements.txt de la part-6 també fixa langgraph>=1.1.0, chromadb>=1.5.0, langchain-classic>=1.0.0, pypdf>=6.0.0, pyvis>=0.3.2, pillow>=11.0.0, sentence-transformers>=5.0.0 i langchain-anthropic>=0.4.0: les dependències de grafs, visió i embeddings locals que només necessita la Part 16. Dos repositoris impliquen dos entorns virtuals; el material de la Part 16 realment requereix el segon.

Quatre contradiccions concretes que trobaràs si clones els repositoris:

  • El README afirma que cal Python 3.10+. Els fitxers pyproject.toml reals fixen ≥3.12 i ≥3.13. Fes cas del codi.
  • El README inclou Streamlit a la pila tecnològica. No apareix en cap dels fitxers de dependències; el repositori principal inclou FastAPI + uvicorn.
  • L'ordre del README git clone https://github.com/pdichone/production-rag-course.git i l'estructura code/part1-foundation/ que descriu no coincideixen amb el contingut publicat: la còpia de treball de la part-6 té una estructura plana a l'arrel del repositori i el seu pyproject.toml declara name = "fcc-production-rag".
  • El pas 3 del README és cp .env.example .env. Cap dels dos repositoris conté un .env.example. Has de crear el .env des de zero; la Part 2 explica què hi ha d'anar. Tots dos repositoris sí que inclouen un uv.lock, de manera que aquest codi s'ha desenvolupat amb uv, no amb la combinació python -m venv + pip que indica el README. Aquesta guia fa servir uv a tot arreu.

L'ordre de construcció és una regla, no un temari

Quatre verbs, en aquest ordre 00:00:35:

  1. Construeix: aconsegueix un pipeline que funcioni de principi a fi.
  2. Depura: esbrina per què retorna una resposta incorrecta.
  3. Optimitza: corregeix la qualitat de la recuperació.
  4. Escala: només ara, fes que sigui ràpid i econòmic amb volum.

«Optimitzarem la qualitat i després escalarem per a producció.» 00:01:00

L'ecosistema de tutorials s'atura al primer verb. L'ordre dels altres tres és una prescripció, no una qüestió d'estil. No pots optimitzar allò que no pots observar; per això aquesta guia situa l'observabilitat abans que el curs. I no has d'escalar allò que no has optimitzat, per un motiu que convé dir sense embuts:

Escalar un recuperador de baixa qualitat produeix respostes incorrectes més de pressa, en més quantitat i amb un cost més alt. L'escala multiplica el que ja tens, inclosos els errors.

Si combines els tres «reptes que els tutorials habituals ignoren» de la descripció del curs —escalat, depuració i seguretat— amb l'objectiu del full de ruta d'«optimitzar la qualitat», obtens els quatre eixos que estructuren la llista de comprovació per a producció d'aquesta guia:

EixPregunta que responParts que el tracten
QualitatRecupera la informació i respon correctament?Parts 3–6
EscalatContinua sent correcte, ràpid i assequible quan augmenta el volum?Parts 8–10
Observabilitat / facilitat de depuracióQuan s'equivoca, pots esbrinar per què?Parts 7, 13
SeguretatResisteix un usuari hostil?Parts 12, 13

El curs original deixa clar amb el temps que hi dedica quin d'aquests eixos considera més difícil: el bloc de seguretat ocupa aproximadament 67 minuts, el bloc més extens d'un curs de 7½ hores, i el capítol d'optimització, de 35 minuts, és el capítol tècnic individual més llarg. Els fonaments, que constitueixen gairebé tot el contingut de la majoria de tutorials, reben uns noranta minuts de les set hores i mitja.

Els criteris d'acceptació del mateix curs per considerar un sistema «a punt per al desplegament» són robust, segur i preparat. Fixa't que ràpid i econòmic no són deliberadament els conceptes principals. Ho són la correcció sota càrrega i la seguretat.

Les sis parts de la font i les setze parts d'aquesta guia

El curs presenta un recorregut de sis parts entre 00:00:44 i 00:01:44. Aquesta guia el reorganitza en setze parts, seguint l'ordre de construcció, però el recorregut és el mateix. Val la pena veure'n la correspondència per poder trobar el material original quan el necessitis.

Part del cursTemaResultat que proporcionaAquesta guia
1Construeix els fonamentsUn pipeline RAG complet des de zeroParts 2–5
2Depura les fallades de RAGCorregeix els 5 modes de falladaParts 3, 5, 7
3Optimitza la qualitatChunking semàntic, reranking i recuperació amb múltiples consultesParts 3, 6, 9
4Escala per a produccióMemòria cau, monitoratge i bases de dades vectorials de produccióParts 7–10
5Projecte de produccióUna aplicació RAG completa preparada per a produccióParts 11–13
6RAG avançat 2026Agentic RAG, GraphRAG, contextual retrieval i recuperació multimodalParts 14–16

La part 1 del curs identifica quatre elements fonamentals en l'ordre del pipeline: documents, fragments, embeddings i vector stores 00:00:44. Aquest ordre és, per si mateix, el model mental de la fase d'indexació: es carrega un document, es divideix en fragments, es calcula l'embedding de cada fragment i els vectors es desen en un magatzem. Les Parts 2–4 d'aquesta guia executen exactament aquesta seqüència.

La part 6 del curs identifica quatre tècniques d'avantguarda: agentic RAG 00:01:22, GraphRAG, contextual retrieval i RAG multimodal 00:01:44. El repositori, però, conté sis fitxers de lliçons: també s'hi ensenyen la comparació entre context llarg i RAG i el late chunking, tot i que no s'anuncien. Les Parts 14–16 tracten totes sis tècniques.

Els cinc modes de fallada

Aquesta és la classificació a la qual es remet tota la resta de la guia. L'instructor hi fa referència entre 00:00:52 i 00:01:00, quan parla d'«els cinc modes de fallada principals», però no els enumera oralment. La llista es troba al README de la part-6 i aquí es reprodueix indicant la part de la guia que tracta cada correcció.

#Mode de falladaQuè passaCom es corregeixOn es tracta
1Chunking deficientEs recupera context incorrecte; els fragments es tallen a mitja fraseChunking semàntic i solapament adequatPart 3
2Desajust dels embeddingsL'usuari diu «cancel·lar» i els documents parlen de «política de rescissió»Reformulació de consultes i cerca híbridaParts 4–6
3Soroll en la recuperacióEs recuperen 10 documents, però només 2 són rellevantsReranking i filtratgePart 6
4Desbordament de contextS'omple massa el prompt i el LLM n'ignora la meitatTruncament controlat i map-reducePart 9
5Al·lucinacióLa resposta és al context i, tot i així, el LLM s'inventa informacióPrompts restrictius i citesAquesta part; detecció a la Part 7, proves a la Part 13 i autoavaluació a la Part 15

Llegeix-los una vegada amb atenció, perquè la formulació té importància.

1. Chunking deficient. El splitter talla una frase, un bloc de codi, una fila de taula o, encara pitjor, el mig d'un procediment. Després, el model d'embeddings codifica fidelment el fragment. No falla cap component; el vector representa amb tota precisió una idea incompleta. La Part 3 ho mostra amb un document d'API de 50 pàgines en què la resposta sobre OAuth2 queda repartida entre els fragments 47 i 48, i cap de les dues meitats es pot recuperar com a resposta.

2. Desajust dels embeddings. El vocabulari de l'usuari i el del corpus són dialectes diferents. «Cancel·lar» i «política de rescissió» signifiquen el mateix per a una persona, però queden en zones diferents de l'espai vectorial. La recuperació purament densa no té cap ancoratge lèxic que ho resolgui. Les correccions són reformular la consulta amb el vocabulari del corpus i afegir un canal de paraules clau (BM25) que es combini de manera híbrida amb el canal dens.

3. Soroll en la recuperació. Has demanat deu fragments i només dos són rellevants. Els altres vuit no són simplement inútils: són distractors actius que consumeixen pressupost de context i donen al model material incorrecte, però aparentment plausible, a partir del qual elaborar la resposta. La correcció és aplicar un reranker en una segona etapa i filtrar per metadades.

4. Desbordament de context. Has intentat resoldre el soroll recuperant més informació i ara el prompt és enorme i el model se'n salta la part central. A partir d'un cert punt, més context no implica més fonamentació. Les correccions són un truncament que tingui en compte què descarta i estratègies map-reduce que resumeixin abans d'elaborar la resposta final.

5. Al·lucinació. És la que sorprèn més, per la precisió de la formulació: la resposta és al context i el model s'inventa informació igualment. No és una fallada de recuperació. La recuperació ha fet la seva feina. Simplement, no s'ha indicat al model que no pot anar més enllà del que ha rebut. La correcció és un prompt restrictiu i cites; és la correcció més barata de tota la classificació i per això s'ensenya en aquesta part, en lloc de deixar-la per a més endavant.

La visió de conjunt, de principi a fi

Aquest és el sistema complet, en l'ordre que segueixen les dades quan s'executa una consulta 00:01:44:

Figura 1La chain RAG bàsica: recupera el context, omple el prompt i genera una resposta fonamentada
ASCII original
user query ──► retriever ──► vector store ──► context
     │                                          │
     └──────── question ────────────────────────┤
                                                ▼
                                         prompt template
                                                │
                                                ▼
                                              LLM
                                                │
                                                ▼
                                     grounded response (+ citations)

Cinc observacions sobre aquest esquema seran fonamentals més endavant.

La consulta fa dues funcions alhora. És tant la pregunta que l'usuari vol que es respongui com la clau de recuperació; per això apareix dues vegades al diagrama, però només una a l'entrada. Una cadena, dos consumidors. Aquesta doble funció és precisament el motiu pel qual la pregunta ha de travessar el pipeline sense modificar-se; hi tornarem quan arribem a RunnablePassthrough.

A la plantilla del prompt hi conflueixen tres elements i només en surt un. La pregunta, el context recuperat i les instruccions de la mateixa plantilla es combinen en una única cadena amb els valors incorporats. Aquesta cadena és l'únic artefacte que veu el model. La resta del diagrama —el recuperador, el magatzem, les metadades i les puntuacions calculades amb cura— només existeix per decidir què hi entra. Si un fet no apareix en aquesta cadena, el model no el té; si un marcador de cita no hi apareix, el model no el pot citar.

El recuperador és una interfície mínima; el vector store és el motor.

«Tot això, és clar, ho impulsa el vector store.» 00:01:44

Un recuperador és un objecte petit amb un contracte invoke(question) -> list[Document]. Pràcticament no incorpora intel·ligència pròpia. Totes les propietats que t'interessen —recall, latència, compatibilitat amb filtres i capacitat de cerca híbrida— són propietats del magatzem i de l'índex que hi ha a sota. Quan la recuperació és deficient, no busquis el problema al recuperador.

Calcular embeddings no és indexar. 00:02:46 L'instructor descriu el magatzem com un lloc que conté documents dels quals s'han calculat embeddings i que s'han indexat per fer cerques. Aquesta «i» uneix dues propietats diferents; no repeteix la mateixa idea:

  • El càlcul d'embeddings converteix text en vectors. És una decisió de model: quin model, quantes dimensions i quin cost té per milió de tokens.
  • La indexació construeix l'estructura de cerca sobre aquests vectors: HNSW, IVF. És una decisió d'infraestructura, amb paràmetres propis (M, ef_construction, ef_search) i un compromís propi entre precisió, velocitat i memòria.

Pots tenir embeddings excel·lents dins d'un índex mal ajustat i obtenir cerques lentes amb un recall baix. Pots tenir un graf HNSW ajustat a la perfecció sobre un model d'embeddings inadequat i obtenir resultats ràpids, contundents i absurds. Confondre les dues coses és el que porta a «millorar el model d'embeddings» per intentar resoldre un problema de latència. Aquesta sola distinció és l'origen de tot el recorregut d'ajust de l'índex de la Part 8.

La sortida està *fonamentada* en les fonts, i aquesta fonamentació mitiga el problema, però no el resol.

«RAG fonamenta les respostes dels grans models de llenguatge en documents reals, cosa que redueix les al·lucinacions.» 00:02:46

El verb és redueix. No elimina, no evita, no resol. Qualsevol pàgina de proveïdor, article de blog o revisió d'arquitectura que afirmi que RAG elimina les al·lucinacions s'equivoca. La resta d'aquesta guia —depuració, avaluació, validació de la sortida i seguretat— existeix precisament perquè el risc residual és prou important per requerir enginyeria.

La chain canònica

Tot el que hem vist es concreta en unes deu línies d'LCEL. Aquesta és l'estructura que trobaràs a totes les parts de la guia i, aquesta és l'afirmació important, l'únic element que canvia és el contingut de la posició context.

Python
# production-course-main-code/rag_pipeline.py — demo_basic_rag()
rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

Quatre etapes: {context, question} → plantilla del prompt → LLM → parser de sortida 00:02:46. Vegem-les d'una en una.

Abans, mira d'on provenen aquests noms. Val la pena veure una vegada el bloc d'importacions, perquè tot el contingut de les Parts 2–6 parteix del mateix conjunt i els principiants perden hores important la classe correcta des del paquet equivocat. Aquest és l'inici de rag_pipeline.py, sense modificar:

Python
# production-course-main-code/rag_pipeline.py
from langchain_openai.embeddings import OpenAIEmbeddings
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough, RunnableParallel
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain.chat_models import init_chat_model

from langchain_chroma import Chroma
from langchain_core.documents import Document
from langchain_text_splitters import RecursiveCharacterTextSplitter
from pydantic import BaseModel, Field
from typing import List
from dotenv import load_dotenv
import tempfile

Llegeix aquest bloc com un mapa de l'ecosistema: langchain_core conté els elements de composició bàsics —prompts, runnables, parsers i Document—; langchain conté la factoria independent del proveïdor init_chat_model; langchain_openai conté la integració amb OpenAI; langchain_chroma conté el magatzem, i langchain_text_splitters és un paquet independent perquè la divisió del text no depèn de cap dels altres components. Chroma prové de langchain_chroma, no de langchain_community: és la trampa que hem assenyalat abans.

També conté tres detalls que convé identificar, perquè probablement tu també els produiràs: OpenAIEmbeddings s'importa dues vegades des de dues rutes diferents; ChatOpenAI s'importa però no s'utilitza mai, perquè el fitxer fa servir init_chat_model, i RunnableParallel s'importa però tampoc no s'utilitza, perquè el literal de diccionari ja en fa la funció. Res d'això impedeix que el codi funcioni; tot plegat és habitual en un repositori docent real. Fes cas del codi abans que del README, però llegeix el codi també amb esperit crític.

Etapa 1: el literal de diccionari és un RunnableParallel implícit

«Això arribarà, és clar, com a entrades en paral·lel.» 00:02:46

Aquest {"context": ..., "question": ...} no és un diccionari de Python que es passa com a argument. Dins d'una cadena d'operadors LCEL, un literal de diccionari es converteix en un RunnableParallel: cada valor és un runnable, tots reben la mateixa entrada i s'executen en paral·lel. La sortida és un diccionari amb les mateixes claus i els resultats de les branques com a valors.

Això és important tant mecànicament com conceptualment. Mecànicament, la recuperació no es fa «abans» de tractar la pregunta: les dues branques consumeixen simultàniament la mateixa cadena d'entrada i es combinen en un únic diccionari, que és el que rep la plantilla del prompt. Conceptualment, permet veure tot l'acrònim a la pantalla. La branca context és la Recuperació. El moment en què les dues branques es combinen en un diccionari és l'Augmentació: l'instructor assenyala precisament aquest pas i en diu «la part d'augmentar» 00:03:47. L'etapa | llm és la Generació. Tres lletres, tres posicions en una sola expressió. Si pots assenyalar cadascuna d'aquestes posicions al codi, entens què fa RAG; si no pots, cap ajust no t'ajudarà.

«El context i la pregunta aniran de bracet.» 00:02:46

Si prefereixes la forma explícita —i l'hauries de preferir quan estàs aprenent o quan necessites donar nom a les branques per registrar-ne les traces—, chains_v1.py escriu el mateix de manera desenvolupada amb un recuperador de prova, cosa que permet aïllar el concepte de passthrough de qualsevol vector store. L'instructor introdueix RunnablePassthrough dient «si ho recordeu» 00:03:47: aquest és un curs de producció, no un curs introductori de LangChain 101, i pressuposa familiaritat amb LCEL. Aquesta guia parteix del mateix supòsit, però aquí tens el recordatori que ell omet. Fixa't que el model d'aquest exemple es construeix amb init_chat_model(model="gpt-4o-mini", temperature=0): zero, no el 0.2 de les demostracions de RAG, perquè les demostracions del funcionament de les chains busquen determinisme.

Python
# production-course-main-code/chains_v1.py — demo_passthrough_chain()
prompt = ChatPromptTemplate.from_template(
    "Original question: {question}\n"
    "Context: {context}\n\n"
    "Answer the question based on the context."
)

# simulate a retrieve operation
def fake_retriever(input_dict):
    return " LangChain was created by Harrison Chase in 2022."

chain = (
    RunnableParallel(
        context=RunnableLambda(fake_retriever), question=RunnablePassthrough()
    )
    | RunnableLambda(
        lambda x: {"context": x["context"], "question": x["question"]["question"]}
    )
    | prompt
    | model
    | StrOutputParser()
)

result = chain.invoke({"question": "Who created LangChain?"})

Fixa't en el RunnableLambda addicional del mig. Com que aquesta chain es crida amb un diccionari, i no amb una cadena sola, RunnablePassthrough() reenvia tot el diccionari. Per tant, la clau question conté {"question": "..."} i se n'ha d'extreure el valor abans que el prompt el rebi. A rag_pipeline.py, la chain es crida amb una cadena sola (rag_chain.invoke(q)), de manera que el passthrough retorna directament la cadena i no cal aquest pas d'extracció. El mateix operador, amb un tipus d'entrada diferent, requereix una connexió diferent: aquest és el petit entrebanc més habitual d'LCEL.

Etapa 1b: RunnablePassthrough vol dir «no toquis això»

«No modifiqueu res pel que fa a la pregunta.» 00:03:47

Mecànicament, reenvia l'entrada sense modificar-la. Semànticament, és un contracte, i aquesta és la interpretació que convé interioritzar: la formulació exacta de l'usuari ha d'arribar al prompt. Si en aquesta branca «ajudes» netejant, ampliant, traduint o resumint la pregunta, has canviat sense avisar la pregunta que respon el model, i el banc d'avaluació puntuarà respostes a una pregunta que l'usuari no ha fet mai.

Etapa 2: la plantilla del prompt conté informació i instruccions

Dos marcadors de posició, dues procedències 00:04:49: {context} prové de la branca de recuperació i {question}, de la branca de passthrough. Però la plantilla no és només un formatador de cadenes: és el lloc on fonamentes el model en les fonts, de manera que conté tant la informació, els fragments recuperats, com les instruccions, què n'ha de fer. La secció següent està dedicada íntegrament a aquestes instruccions.

Etapes 3 i 4: el model i el parser que no hauries d'ometre

El model és gpt-4o-mini amb temperature=0.2 a rag_pipeline.py, construït mitjançant la factoria independent del proveïdor:

Python
# production-course-main-code/rag_pipeline.py
llm = init_chat_model(model="gpt-4o-mini", temperature=0.2)
embeddings_model = OpenAIEmbeddings(model="text-embedding-3-small")

init_chat_model és la factoria independent del proveïdor: l'identificador del model és un argument de cadena, de manera que substituir OpenAI per Anthropic només requereix canviar un element i la chain que l'envolta no es modifica. És una concreció de l'asimetria de l'invariant 2: el model de generació es pot substituir; el model d'embeddings de la línia següent, no. Fixa't també que aquest repositori executa les demostracions de RAG amb temperature=0.2 i les demostracions del funcionament de les chains amb temperature=0. Tria el valor de manera deliberada i deixa'l documentat, perquè una temperatura diferent de zero fa que les execucions d'avaluació no siguin reproduïbles.

En un model de xat, .invoke() retorna un objecte de missatge, no una cadena: el text és a .content, juntament amb el consum de tokens i el motiu de finalització. StrOutputParser() és l'adaptador d'una línia que n'extreu el text. L'instructor diu dels parsers de sortida que «en la majoria de casos ens cal això» 00:02:46. El motiu més profund per conservar aquesta posició és que constitueix un punt de control: substitueix StrOutputParser per un parser estructurat i obtindràs un objecte amb tipus en lloc de prosa. rag_pipeline.py mostra precisament aquest cas i val la pena veure'l ara, perquè és l'origen de la capa de validació de la sortida de la Part 11:

Sortida estructurada: la mateixa chain amb un contracte de tipus en lloc d'una cadena
Python
# production-course-main-code/rag_pipeline.py — demo_structured_rag()
# (in the repo every name below is defined inside the demo function; the body is verbatim)
vectorstore = create_kb()
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

class RAGResponse(BaseModel):
    """Structured RAG response."""

    answer: str = Field(description="The answer to the question")
    confidence: str = Field(description="high, medium, or low")
    sources_used: List[str] = Field(description="List of sources referenced")
    follow_up: str = Field(description="Suggested follow-up question")

structured_llm = llm.with_structured_output(RAGResponse)

prompt = ChatPromptTemplate.from_template(
    """
Based on the context below, answer the question.

Context:
{context}

Question: {question}

Provide a structured response."""
)

def format_docs(docs):
    return "\n\n".join(
        f"[{doc.metadata.get('source', 'unknown')}]: {doc.page_content}"
        for doc in docs
    )

rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | structured_llm
)
result = rag_chain.invoke("What is LangGraph?")
print(f"Answer: {result.answer}")
print(f"Confidence: {result.confidence}")
print(f"Sources: {result.sources_used}")

Tres idees que n'has d'extreure. Primera: quan l'etapa final és with_structured_output(...), no hi ha cap StrOutputParser; el model estructurat ja retorna una instància de RAGResponse i afegir-hi un parser de cadenes faria fallar el procés. Segona: l'única instrucció d'aquest prompt és «proporciona una resposta estructurada». L'esquema fa la feina que altrament hauria de fer la prosa, i és precisament per això que la sortida estructurada és més fàcil de validar que el text lliure. Tercera: sources_used: List[str] fa que les cites es retornin com a dades i no com a prosa que després hauries d'extreure d'un paràgraf.

Una precaució sobre el camp confidence: és una autoavaluació del model, induïda per la descripció del camp, no una probabilitat calibrada. Tracta-la com un indici per decidir el camí que cal seguir —envia low a una persona o activa una nova recuperació—, però mai com una mesura. La confiança real prové de les puntuacions de recuperació (Part 4) i de l'avaluació (Part 7).

El fitxer executable complet, com a referència

Aquí tens la demostració de principi a fi, perquè puguis veure on se situen la base de coneixement, el splitter i la configuració del recuperador respecte de la chain:

demo_basic_rag() i la seva base de coneixement: el recorregut complet i executable
Python
# production-course-main-code/rag_pipeline.py
# (imports as listed earlier in this part)
load_dotenv()
embeddings_model = OpenAIEmbeddings(model="text-embedding-3-small")

KNOWLEDGE_BASE = """# LangChain Framework
... 1,010 characters of Markdown: Core Components, LangGraph, Pricing, Getting Started ...
"""

llm = init_chat_model(model="gpt-4o-mini", temperature=0.2)


def create_kb():
    """Create a vector store from knowledge base."""
    splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
    doc = Document(
        page_content=KNOWLEDGE_BASE, metadata={"source": "langchain_knowledge_base.md"}
    )
    chunks = splitter.split_documents([doc])
    vector_store = Chroma.from_documents(
        documents=chunks,
        embedding=embeddings_model,
        persist_directory=tempfile.mkdtemp(),
    )
    return vector_store


def demo_basic_rag():
    vector_store = create_kb()
    retriever = vector_store.as_retriever(
        search_type="similarity", search_kwargs={"k": 2}
    )

    prompt = ChatPromptTemplate.from_template(
        """
Answer the question based only on the following context:

{context}

Question: {question}

Answer:


Make sure to answer in a concise manner, 
and if you don't know the answer, just say "I don't know."""
    )

    def format_docs(docs):
        return "\n\n".join([doc.page_content for doc in docs])

    rag_chain = (
        {"context": retriever | format_docs, "question": RunnablePassthrough()}
        | prompt
        | llm
        | StrOutputParser()
    )

    questions = [
        "What is LangChain?",
        "Who created LangChain?",
        "What is LangGraph used for?",
    ]
    for q in questions:
        answer = rag_chain.invoke(q)
        print(f"Q: {q}")
        print(f"A: {answer}\n")

Tres aspectes que cal observar i que es convertiran en capítols més endavant:

  • metadata={"source": ...} es defineix durant la ingestió, abans de dividir el text. Aquesta és la línia que fa possibles les cites en el moment de la consulta; split_documents() la propaga a cada fragment. Si la perds aquí, cap codi posterior no se la pot inventar.
  • persist_directory=tempfile.mkdtemp() vol dir que aquesta demostració torna a calcular els embeddings de tot el corpus en cada execució. És acceptable per a una base de coneixement de 1,010 caràcters; a escala real, comporta una factura considerable i un límit de latència. Fes servir un directori estable en qualsevol procés que executis més d'una vegada: aquest mateix antipatró es repeteix en gairebé tots els fitxers de demostració del repositori.
  • k=2 a la demostració bàsica, k=3 a les demostracions de fonts i de sortida estructurada, i de nou k=2 a la demostració del mecanisme de reserva. Són valors de demostració triats per a un corpus diminut, no valors per defecte que hagis d'adoptar.

La base de coneixement de demostració és una petita cadena Markdown sobre LangChain i conté dos fets essencials per a les demostracions: LangChain va ser creat per Harrison Chase l'octubre de 2022 i LangSmith té un nivell gratuït i plans de pagament a partir de $39 al mes. Aquests són els valors de referència amb què es comproven les demostracions de preguntes i respostes. La dada $39/month és, concretament, la prova amb resposta dins del corpus que utilitza la demostració del mecanisme de reserva que veurem a continuació.

Val la pena llegir l'última funció del fitxer, encara que estigui presentada com un exercici, perquè és la primera vegada que les idees del capítol s'empaqueten com un component reutilitzable i no com un script: un objecte que és propietari del magatzem, del recuperador i de la chain, i que exposa un únic mètode:

DocumentQA: la mateixa chain encapsulada en una classe que realment podries importar
Python
# production-course-main-code/rag_pipeline.py — exercise_document_qa()
class DocumentQA:
    def __init__(self, document: str, source_name: str = "document"):
        # Split document
        splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
        doc = Document(page_content=document, metadata={"source": source_name})
        chunks = splitter.split_documents([doc])

        # Create vector store
        self.vectorstore = Chroma.from_documents(
            documents=chunks,
            embedding=OpenAIEmbeddings(model="text-embedding-3-small"),
        )
        self.retriever = self.vectorstore.as_retriever(search_kwargs={"k": 3})

        # Create chain
        self.llm = init_chat_model(model="gpt-4o-mini", temperature=0.2)

        self.prompt = ChatPromptTemplate.from_template(
            """
Answer based on the context. Rate your confidence (high/medium/low).

Context: {context}
Question: {question}

Format: [Confidence: X] Answer"""
        )

        def format_docs(docs):
            return "\n".join(d.page_content for d in docs)

        self.chain = (
            {
                "context": self.retriever | format_docs,
                "question": RunnablePassthrough(),
            }
            | self.prompt
            | self.llm
            | StrOutputParser()
        )

    def ask(self, question: str) -> str:
        return self.chain.invoke(question)

Les mateixes quatre etapes, el mateix k=3 i el mateix splitter 500/50. source_name és un argument del constructor perquè qui el crida ha de decidir les metadades durant la ingestió: l'invariant és que no pots citar allò que no has etiquetat.

Dues observacions abans de copiar-lo. Primera: al repositori, aquesta classe es declara dins de la funció exercise_document_qa(). Per tant, tot i la seva estructura, no es pot importar tal com està escrita; el primer canvi que hi has de fer és moure-la a l'àmbit del mòdul.

Segona: aquesta crida a Chroma.from_documents(...) no passa cap persist_directory, de manera que el magatzem és en memòria i desapareix quan acaba el procés. Cada construcció de DocumentQA(...) torna a calcular els embeddings de tot el document i te'ls factura. Assigna-li un directori estable identificat pel hash del contingut del document i la segona construcció no tindrà aquest cost.

El patró de prompt per reduir les al·lucinacions

L'instructor enuncia aquest patró tres vegades en aproximadament noranta segons: 00:03:47, 00:04:49 i 00:05:51. Aquesta repetició és el senyal. Consta de quatre ingredients:

  1. La clàusula restrictiva: «Respon únicament a partir del context següent.»
  2. La clàusula de reserva: «Si el context no conté la resposta, digues 'No tinc informació sobre això'.» O bé: «No ho sé».
  3. {context}: prové de la branca de recuperació.
  4. {question}: prové de la branca de passthrough.

Això és tot.

Per què val la pena començar per això abans de fer res més de la guia? Perquè el prompt és l'únic mecanisme de fonamentació que pots ajustar sense cost addicional d'implementació. Canviar-lo no requereix tornar a entrenar, reindexar ni afegir infraestructura: modifiques una cadena, tornes a desplegar i el comportament canvia a la petició següent. Totes les altres correccions d'aquesta guia —chunking semàntic, cerca híbrida, reranking i contextual retrieval— requereixen recalcular els embeddings d'un corpus, posar en marxa un component o totes dues coses.

«És la millora més fàcil d'aplicar en enginyeria de prompts.» 00:05:51

I el corol·lari, que és on la majoria de professionals realment s'equivoquen: és «la millora més fàcil d'aplicar... Tot i així, molta gent se n'oblida o no hi presta atenció» 00:05:51. La fallada no és que s'escrigui una clàusula restrictiva deficient. És que no se n'escriu cap i després s'intenta resoldre amb reranking i embeddings millors un problema que dues frases de prompt haurien pogut contenir.

L'exemple pràctic de la computació quàntica

Aquest és l'exemple que fixa la idea 00:04:49. El mateix model, la mateixa pregunta i el mateix context, irrellevant o buit. L'única diferència és una frase del prompt.

Sense la instruccióAmb la instrucció
Pregunta«Què és la computació quàntica?»«Què és la computació quàntica?»
Resposta«La computació quàntica utilitza qubits…» I continua, inventant informació«No tinc prou informació sobre aquest tema.»
CorreccióFluida, coherent i sense fonamentacióCorrecta

Observa bé què fa la sortida incorrecta: comença amb una afirmació certa. La computació quàntica sí que utilitza qubits. La invenció creix a partir d'una llavor correcta, amb el to segur habitual del model i una prosa ben construïda.

L'al·lucinació acostuma a començar a partir d'una llavor certa. Per això costa detectar-la només llegint.

D'aquí se'n desprenen dues regles, i són el motiu pel qual existeixen les Parts 7 i 13:

Has de demanar explícitament l'abstenció. Els models no s'abstenen per defecte: el seu entrenament premia ser útils i continuar. Un «no ho sé» honest és la sortida desitjada en producció, no una fallada del sistema, i l'has de demanar per escrit.

Coherència no és el mateix que correcció.

«Encara que pugui semblar coherent, està al·lucinant; és a dir, s'està inventant coses.» 00:04:49

És la frase més generalitzable de tot el material original. Vol dir que no pots verificar la qualitat d'un sistema RAG limitant-te a llegir-ne les respostes. El model està optimitzat per a la fluïdesa, que no està correlacionada amb la fonamentació en les fonts. Qualsevol procés de qualitat basat en «les respostes fan bona pinta» mesura la variable equivocada. Precisament per això aquesta guia situa l'observabilitat i les avaluacions (Part 7) abans de les etapes que habitualment les precedeixen, i per això la llista de comprovació de la Part 13 les converteix en proves amb assercions, no en panells que algú potser consultarà.

El patró, executable

El prompt de demo_basic_rag() que hem vist abans ja conté les dues clàusules. La demostració específica del mecanisme de reserva fa explícita l'abstenció i, cosa important, inclou un disseny de prova que hauries de copiar:

Python
# production-course-main-code/rag_pipeline.py — demo_rag_with_fallback()
prompt = ChatPromptTemplate.from_template(
    """
Answer the question based ONLY on the following context.
If the answer is not in the context, respond with: "I don't have information about that in my knowledge base."

Context:
{context}

Question: {question}

Answer:"""
)

questions = [
    "What is the pricing for LangSmith?",  # In knowledge base
    "What is the stock price of OpenAI?",  # Not in knowledge base
    "How do I deploy LangChain to AWS?",   # Not in knowledge base
]

La resta d'aquesta demostració és la chain canònica sense canvis: un format_docs senzill, un recuperador amb k=2 i prompt | llm | StrOutputParser(). Només el text del prompt difereix de demo_basic_rag(), i aquesta és la idea: el comportament d'abstenció s'aconsegueix íntegrament amb la segona frase d'una plantilla.

Aquesta llista de preguntes és una prova 1-dins / 2-fora i constitueix la versió executable de la comparació de la computació quàntica. Una pregunta que el corpus pot respondre —el preu de LangSmith de $39/month— i dues que no pot respondre. Una execució correcta respon la primera i s'absté en les altres dues. Un sistema que respon totes tres està al·lucinant, i ho has descobert en tres segons sense cap framework d'avaluació.

Fixa't que les dues preguntes fora del corpus s'han triat amb cura. «Quina és la cotització borsària d'OpenAI?» tracta d'una entitat relacionada que el corpus esmenta, i «Com desplego LangChain a AWS?» tracta del mateix tema del corpus, però en una direcció que no cobreix. Totes dues són preguntes prou properes perquè el recuperador retorni de bon grat alguna cosa. Una prova amb preguntes sobre biologia marina passaria sense dificultat i no t'aportaria cap informació.

Fonts, cites i cadena de confiança

Una fonamentació que no pots demostrar és només una afirmació. Les fonts en són la prova.

«Ens volem assegurar d'afegir-hi també algunes fonts.» 00:06:52

Un Document recuperat té dos camps: page_content, el text del fragment, i metadata, un diccionari que conté source, amb el valor doc.pdf a l'exemple de la diapositiva. Les metadades no són decoració: són el canal de les cites i només existeixen si s'han incorporat durant la ingestió.

format_docs i format_docs_with_sources

La diferència són quatre línies, i és la diferència entre un sistema auditable i un que no ho és.

Python
# production-course-main-code/rag_pipeline.py — the sources-free formatter
def format_docs(docs):
    return "\n\n".join([doc.page_content for doc in docs])
Python
# production-course-main-code/rag_pipeline.py — demo_rag_with_sources()
def format_docs_with_sources(docs):
    formatted = []
    for i, doc in enumerate(docs):
        source = doc.metadata.get("source", "unknown")
        formatted.append(f"[{i+1}] {source}:\n{doc.page_content}")
    return "\n\n".join(formatted)

Cada fragment es converteix en [n] <source>:\n<page_content> i els fragments numerats s'uneixen en una sola cadena. Aquesta cadena és el {context} que llegeix el LLM. Quatre línies, cap crida addicional a l'API i cap dependència nova: l'instructor té raó d'anomenar-ho la manera canònica de fer RAG amb fonts, i no hi ha cap motiu defensable per publicar la primera versió en lloc d'aquesta.

El prompt també ha de demanar les cites. La demostració de fonts cobreix totes dues parts:

Python
# production-course-main-code/rag_pipeline.py — demo_rag_with_sources()
prompt = ChatPromptTemplate.from_template(
    """
Answer the question based on the context below. Include which sources you used.

Context:
{context}

Question: {question}

Answer (include sources):"""
)

rag_chain = (
    {
        "context": retriever | format_docs_with_sources,
        "question": RunnablePassthrough(),
    }
    | prompt
    | llm
    | StrOutputParser()
)

Fixa't en retriever = vectorstore.as_retriever(search_kwargs={"k": 3}): tres fragments i, per tant, tres fonts numerades. Fixa't també que el final "Answer (include sources):" té una funció real: el formatador fa possible citar; el prompt fa que es citi. Si publiques només una de les dues peces, no obtindràs el resultat.

El mateix repositori inclou dues variants d'aquesta idea més orientades a producció, i val la pena aprofitar-les totes dues:

Python
# production-course-main-code/research_assistant.py — _format_docs_for_context()
def _format_docs_for_context(self, docs) -> str:
    """Format retrieved documents into a string for the prompt."""
    if not docs:
        return "No relevant documents found."

    formatted = []
    for i, doc in enumerate(docs):
        source = doc.metadata.get("source", "Unknown")
        formatted.append(f"[Source {i+1}: {source}]\n{doc.page_content}")
    return "\n\n---\n\n".join(formatted)

Les millores respecte de la versió de demostració són una branca explícita per a resultats buits —els recuperadors retornen [] més sovint del que et penses: n'hi ha prou amb un filtre de metadades molt restrictiu o un llindar de puntuació agressiu, i una cadena buida a {context} convida a al·lucinar— i un separador visible ---, que deixa clars al model els límits dels fragments. La demostració estructurada utilitza una tercera forma, f"[{doc.metadata.get('source', 'unknown')}]: {doc.page_content}", combinada amb un camp sources_used: List[str] perquè les cites es retornin com a dades i no com a prosa.

Per què les fonts són realment importants

«Les fonts són importants perquè els usuaris podran verificar aquestes respostes.» 00:07:53

La cadena és: fonts → cites → verificabilitat → confiança. L'últim enllaç és el que mereix una reflexió especial. L'usuari fa la verificació final. La funció del sistema no és que se'l creguin, sinó fer que comprovar-lo sigui poc costós. Dona a algú un nom de fitxer, una pàgina i un encapçalament, i comprovarà tres respostes, veurà que són correctes i començarà a confiar en el sistema. Dona-li un paràgraf contundent sense procedència i haurà de confiar-hi a cegues o repetir la recerca pel seu compte; aquesta segona opció és justament la feina que el sistema havia d'estalviar.

Les cites reformulen la «precisió» com a «auditabilitat». I l'auditabilitat és una propietat que realment pots construir amb enginyeria, mentre que la precisió és una propietat que només pots mesurar.

També hi ha un segon destinatari, i és el que sovint s'oblida: el mateix sistema. La procedència permet al pipeline registrar quins documents han determinat cada resposta, filtrar per permisos abans de generar, eliminar fragments gairebé idèntics i, cosa fonamental, depurar. L'instructor ho expressa com si fos el monòleg intern del sistema:

«Així sap: d'acord, he obtingut aquesta resposta, però d'on l'he tret?» 00:06:52

Fixa't en la referència a la granularitat que hi afegeix tot seguit: «a partir d'aquest document, d'aquest encapçalament, d'aquest lloc». La granularitat de la font pot ser més fina que el fitxer. Un splitter d'encapçalaments Markdown que escrigui la ruta dels encapçalaments a les metadades et dona cites a nivell de secció sense feina addicional: és una tècnica de la Part 3 amb una motivació de la Part 1.

El model mental: dues fases, una capa d'observació i tres pressupostos

Tot el contingut de les quinze parts restants modifica exactament un component d'aquest esquema. Cada part t'indicarà quin.

Figura 2El mapa general: les dues fases del pipeline, les parts que expliquen cada pas i l'observabilitat
ASCII original
PHASE A — INDEX (offline, once per document, amortized)
  Load ──► Split ──► [Contextualize] ──► Embed ──► Store + Index
  Part 2    Part 3        Part 14        Part 4      Parts 4, 8, 10

PHASE B — QUERY (online, once per request, recurring)
  Gate ──► Cache ──► Embed query ──► Retrieve ──► Fuse/Filter ──► Compress/Rerank
  P12       P9,P11       P4          P4,P6,P16        P6              P6
     ──► Assemble prompt ──► Generate ──► Validate output ──► Return + citations
          P1, P5, P9          P5, P11          P11              P1, P6

        ┌──────────────────────────────────────────────────────────┐
        │  OBSERVABILITY  (traces · metrics · evals · JSON logs)    │
        │  wraps everything, changes nothing           Part 7       │
        └──────────────────────────────────────────────────────────┘

  Governed by three budgets, always in tension: QUALITY · LATENCY · MONEY

La separació en dues fases és la distinció més útil en l'enginyeria de RAG, perquè les dues fases tenen economies completament diferents. La Fase A s'executa una vegada per document i el seu cost s'amortitza entre totes les consultes futures. La Fase B s'executa una vegada per petició, indefinidament. Aquesta asimetria és una instrucció de disseny: avança la feina cap a la indexació. Tot el que puguis precalcular durant la indexació —resums contextuals, metadades extretes, embeddings en memòria cau o un segon índex de paraules clau— simplifica el camí de lectura a canvi d'una despesa inicial.

La capa d'observabilitat es dibuixa fora dels components de manera deliberada. Ho observa tot i no canvia res. Quan la Part 7 la construeix, el camí de fallada registra l'excepció i la torna a llançar. Una capa de monitoratge que es menja una excepció, reintenta una operació o altera una resposta ha deixat de ser monitoratge i s'ha convertit en lògica de negoci no documentada. La Part 13 converteix després allò que aquesta capa pot observar en assercions, un pas que la majoria d'equips ometen: un panell que no activa cap avís a ningú és decoració.

Els tres pressupostos expliquen per què aquesta guia no ofereix respostes correctes universals. Cada tècnica que llegiràs millora un aspecte i en consumeix un altre. El reranking guanya qualitat i consumeix latència i diners. La memòria cau millora la latència i el cost, però posa en risc la qualitat perquè pot quedar obsoleta. Els embeddings més grans guanyen qualitat i consumeixen diners, latència i emmagatzematge. Quan una part proporciona un valor per defecte, correspon a un punt concret d'aquest triangle i s'indica quin és.

Fixa't també on situa el pipeline de peticions de producció les seves capes de reforç: primer, els rebutjos de baix cost; al final, la inferència costosa. Client → Limitador de freqüència → Seguretat (injecció + PII) → Memòria cau → Model (+reintents +alternativa) → Validació de la sortida → Mètriques/logs → Resposta JSON. Rebutjar una petició hostil o duplicada abans que arribi al LLM és la diferència entre una incidència i una línia de log.

Els sis invariants

Es compleixen a tota la guia. Quan una part posterior sembli contradir-ne un, estarà fent una excepció explícita i argumentada, i ho indicarà.

1. La qualitat es transmet cap endavant i no es recupera en les etapes posteriors. Chunking → embeddings → recuperació → resposta. Pots tenir el millor model d'embeddings, la base de dades vectorial més ràpida i el LLM més capaç i, tot i així, obtenir brossa si el chunking és deficient. Depura la primera etapa que falla, no el símptoma visible. El símptoma visible gairebé sempre és la resposta; l'etapa que falla gairebé mai no és el generador.

2. Un sol model d'embeddings als dos costats del pipeline, de manera permanent. El mateix model ha de calcular els embeddings dels documents i de les consultes, i la versió importa. Canviar-lo invalida tot l'índex. Les dimensions incompatibles provoquen una fallada explícita, que és el cas favorable. La mateixa dimensió amb un model diferent falla en silenci, perquè els dos models no comparteixen un sistema de coordenades: la cerca continua retornant k resultats, classificats amb seguretat però sense sentit. Fixa't en l'asimetria: el model de generació es pot substituir quan vulguis; el model d'embeddings és una decisió d'esquema.

3. El cost d'indexació es paga una vegada; el cost de consulta es repeteix amb cada petició. Avança la feina cap a la indexació. Mantén lleuger el camí de lectura.

4. Les fallades són silencioses. No es llança cap excepció. La taxa d'errors pot ser un impecable 0% mentre la correcció és pèssima. Una recuperació que retorna fragments equivocats és un HTTP 200 correcte. Per això aquesta guia situa l'observabilitat abans de l'optimització, i no després.

5. Cada capa obliga a «triar-ne 2». L'índex en tria dos entre precisió / velocitat / memòria. La infraestructura en tria dos entre diners / càrrega operativa / control. La tècnica en tria dos entre qualitat / cost / complexitat. Si sembla que un disseny guanya en tots tres, encara no has trobat en quin eix assumeix el cost.

6. El monitoratge observa i no ha de canviar mai el comportament. El camí de fallada registra l'excepció i la torna a llançar.

Què no resol la Part 1

Aquesta part deixa expressament tres qüestions obertes, perquè no les donis per resoltes:

  • Els cinc modes de fallada són una classificació didàctica, no categories excloents. Les incidències reals els combinen: un chunking deficient provoca soroll en la recuperació, que provoca desbordament de context. Fes servir la classificació per identificar la causa més primerenca, no per arxivar la incidència.
  • Les xifres de millora que es citen més endavant són orientatives, no compromisos contractuals. El 67% menys de fallades de recuperació del contextual retrieval i la millora de precisió del 10–12% del late chunking provenen del README de la part-6, que no cita cap metodologia ni corpus. Són hipòtesis que has de posar a prova amb les teves dades, i la Part 14 les tracta com a tals.
  • El curs original situa l'observabilitat després de l'escalat. Aquesta guia, no. Tots els criteris per decidir canvis d'escala i de cost a les Parts 8–9 pressuposen una instrumentació capaç d'observar una latència p95 o una deriva del recall. Ensenyar-los en l'ordre original et deixa amb criteris que no pots mesurar. És una reordenació deliberada, que assenyalem aquí perquè sàpigues que és nostra.

Decisions que cal prendre abans de la Part 2

Resol-les ara. Totes són cares de canviar després d'haver calculat els embeddings d'un corpus.

  1. Tria el model d'embeddings i anota'n la cadena de versió exacta. És una decisió d'esquema, no un valor de configuració (invariant 2). Declara'l una sola vegada com a constant a nivell de mòdul; no escriguis mai directament la cadena del model en un punt de crida. La Part 4 proporciona la taula de dimensions i preus per triar-lo.
  2. Dissenya l'esquema de metadades abans d'ingerir res. Com a mínim, source. Considera seriosament incloure-hi page, section/header, doc_type, created_at i una clau de client o de permisos. No pots filtrar ni citar a partir d'un camp que no has desat, i corregir-ho requereix una reindexació completa.
  3. Decideix si el corpus és estructurat o text continu. Els encapçalaments i les seccions clares afavoreixen el chunking recursiu; un text continu sense estructura, en què els temes canvien sense marcadors, afavoreix el semàntic. La Part 3 mostra una prova A/B mesurada en què la tècnica suposadament «millor» perd 1–4.
  4. Construeix un corpus d'avaluació a escala de producció, no de demostració. Si k representa una fracció significativa del corpus de prova, la recuperació encara no s'ha posat realment a prova.
  5. Escriu avui la prova de preguntes fora del corpus. Tres preguntes que es pugui demostrar que el corpus no pot respondre, més la cadena exacta d'abstenció, comprovada amb assercions en una prova. Incorpora-la abans de la primera consulta real.
  6. Adopta el patró de prompt com una constant compartida. Clàusula restrictiva + clàusula de reserva + {context} + {question}. Una sola definició, importada a tot arreu.
  7. Tria format_docs_with_sources en lloc de format_docs des del primer commit. Afegir cites després implica afegir metadades després, cosa que implica reindexar.
  8. Acorda la regla d'ordre amb qui sigui responsable del full de ruta: construir → depurar → optimitzar → escalar. Deixa-la per escrit abans que algú et demani que «simplement ho escalis» sobre un recuperador que ningú no ha mesurat.

Llista de comprovació de la Part 1

Cada punt es pot comprovar contra un element existent —un fitxer, una prova o un grep—, no contra la sensació d'haver entès la secció.

  1. Els dos repositoris es poden clonar i les importacions funcionen: uv run python -c "import langchain_chroma" s'executa correctament en cadascun dels dos entorns virtuals.
  2. Executar git grep -n "langchain_community import Chroma" sobre el teu codi no retorna cap resultat.
  3. Pots escriure de memòria la chain canònica —{"context": retriever | format_docs, "question": RunnablePassthrough()} | prompt | llm | StrOutputParser()— i explicar per què el literal de diccionari és un RunnableParallel.
  4. Res de la branca question modifica la cadena. Si reformules la consulta, ho fas únicament a la branca de recuperació.
  5. La plantilla del prompt és una constant amb nom en un únic mòdul, conté una clàusula restrictiva i una clàusula de reserva, i la importen tots els serveis que consulten el corpus.
  6. La clàusula de reserva especifica una frase d'abstenció exacta, i la mateixa cadena literal apareix en un fitxer de proves.
  7. Existeix una prova amb almenys tres preguntes que es pugui demostrar que el corpus no pot respondre, que comprova la cadena d'abstenció amb assercions i que s'executa a CI.
  8. Durant la ingestió, defineixes metadata["source"] al Document abans de cridar split_documents(), i has mostrat un fragment recuperat per confirmar que el camp s'ha conservat després de dividir el text.
  9. El formatador emet marcadors [n] <source>: dins de la cadena de context i el prompt demana al model que els citi. Calen totes dues parts; amb una de sola no funciona.
  10. Pots identificar en quin component del diagrama de dues fases se situa l'últim canvi que has fet i quin dels tres pressupostos ha consumit.
  11. Pots anomenar els cinc modes de fallada i la part d'aquesta guia que corregeix cadascun, sense consultar-la.
  12. Has deixat de considerar que una taxa d'errors del 0% demostri res per si sola.

Així explica el mateix instructor per a què serveix tot plegat:

«Al final tindràs un [RAG] preparat per a producció que realment funciona.» 00:01:44

Fixa't en la formulació, que realment funciona: remet directament als sistemes que ja has construït i que no funcionaven. Aquest és el compromís que assumeix aquesta guia.

A continuació, la Part 2 prepara l'entorn de treball —uv, claus dels proveïdors i gestió rigorosa del .env— i incorpora documents reals a una list[Document] uniforme que conté les metadades que donaran lloc a aquestes cites. Com diu la font al final de la mateixa intervenció: «Molt bé, construïm-ho.»