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

Prepara l'entorn de treball i incorpora les dades

Prepara el projecte amb uv, les credencials i la capa de loaders que converteix qualsevol fitxer en Documents.

32 min de lectura 17 seccions Fonaments

Aquesta és l'única part de la guia que no construeix res d'intel·ligent. Cobreix aproximadament vint minuts del curs original, de 00:08:27 a 00:28:27, i produeix dos artefactes: un projecte Python capaç de fer crides a dos proveïdors de models i una capa de càrrega que converteix fitxers de qualsevol tipus en l'única estructura de dades que pressuposen totes les etapes posteriors.

En el model mental de la Part 1, aquesta part s'ocupa del primer component de la Fase A:

Figura 1Fase A (indexació): aquesta part explica el pas Load
ASCII original
PHASE A — INDEX
  Load ──► Split ──► [Contextualize] ──► Embed ──► Store + Index
   ▲
   └── you are here

També estableix la base sobre la qual es construeix tota la resta: les credencials, el gestor de paquets i una manera rigorosa de carregar l'entorn. Res d'això és vistós. Tot és fonamental: el diccionari metadata que un loader afegeix en aquesta part és, literalment, la cita que l'usuari veu a la Part 6, i el .env que crees aquí és el fitxer que tots els clients dels proveïdors de les catorze parts restants llegeixen sense avisar.

Llegeix aquesta part una vegada, fes-ne la configuració una vegada i no hi hagis de tornar a pensar. Una configuració que has de continuar replantejant acabarà desajustada i et costarà una sessió de depuració a la Part 8 que no tindrà res a veure amb la recuperació.

Les credencials, abans que el codi

El curs no comença la part pràctica en un editor, sinó en dues consoles de proveïdors, i l'ordre és precisament la lliçó. La primera dependència d'una aplicació amb LLM no és una biblioteca, sinó un secret. No pots verificar res del que ve després —cap crida d'embeddings, cap crida de xat ni cap prova de recuperació— fins que disposis d'una clau. Si primer escrius el codi, la primera execució fallarà per un motiu que no té res a veure amb el codi.

Necessites almenys dues claus: una d'OpenAI i una d'Anthropic 00:09:31. El motiu declarat no és la redundància ni la comparació de rendiment.

«La idea és que tinguem almenys una manera d'executar inferències amb models.» 00:09:31

El requisit és la capacitat, no la marca. L'instructor deixa clar que es pot utilitzar un altre proveïdor i que això no és el que importa. El codi es basa en els paquets d'integració de proveïdors de LangChain, de manera que substituir-ne un més endavant només implica canviar una importació i la cadena del model, no reescriure l'aplicació. Dos proveïdors simplement permeten demostrar aquesta possibilitat de substitució a la prova bàsica de funcionament que estàs a punt d'escriure.

Les dues consoles difereixen en un aspecte important per a l'operació: l'àmbit al qual queda vinculada una clau.

ProveïdorRuta a la consolaÀmbit de la clauQuè tries en crear-la
OpenAISettings → API keys → Create new secret keyProjecteNom de la clau + projecte (el curs fa servir Default project)
Anthropicplatform.claude.com → Manage → API keys → Create KeyEspai de treballNom de la clau + espai de treball (si només en tens un, el predeterminat és adequat)

Procediment A: clau d'OpenAI. Inicia la sessió, deixa enrere les pestanyes Dashboard / Docs / API i entra a Settings. Obre API keys, prem Create new secret key, posa-hi un nom, tria el projecte (Default project al curs), prem Create secret key i copia'n el valor 00:08:30.

Procediment B: clau d'Anthropic. Ves a platform.claude.com i segueix la navegació esquerra → Manage → API keys. Aquesta pàgina mostra la teva organització i les claus existents. Prem Create Key, assigna-hi un nom, tria l'espai de treball i confirma 00:08:30.

La cadena d'eines: uv i només uv

uv és el gestor de paquets i projectes de tota la guia. No pip, ni Poetry, ni conda. El curs dona aquesta decisió per presa i no la torna a plantejar. L'instructor fa la demostració amb macOS i executa un instal·lador amb curl sense llegir-ne l'URL en veu alta; per això, l'ordre següent és una reconstrucció canònica a partir de la documentació d'uv, no una citació literal.

Cinc ordres cobreixen tot el que faràs:

OrdreQuè fa
uv initCrea l'estructura inicial d'un projecte al directori actual: pyproject.toml, main.py, README.md, .python-version, .gitignore i un repositori git
uv venvCrea l'entorn virtual del projecte a .venv
source .venv/bin/activateL'activa (forma per a macOS/Linux; a Windows és diferent)
uv add <pkg>Resol la dependència, l'escriu a pyproject.toml, actualitza uv.lock i la instal·la
uv run <script>Executa un script dins de l'entorn del projecte, després de sincronitzar-lo; no cal activar-lo manualment

Procediment C: inicialitza el projecte.

bash
# Install uv if you don't have it (macOS/Linux; Windows uses a PowerShell installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

# The course's project is named langc-course
# (audio says "lang course"; pyproject.toml says name = "langc-course")
mkdir langc-course && cd langc-course
ls                      # confirm it is empty first
uv init                 # scaffold
uv venv                 # create .venv
source .venv/bin/activate

uv add langchain langchain-core langgraph \
       langchain-openai langchain-anthropic python-dotenv

touch .env
uv run main.py          # prints "Hello from langc-course!" from the scaffold

Val la pena executar aquesta última línia abans de tocar res. Demostra que l'intèrpret, l'entorn virtual i l'estructura inicial del projecte són coherents, i et proporciona un punt de partida verificat que després pots modificar 00:11:34.

Fixa't que uv venv + source .venv/bin/activate són estrictament redundants, ja que totes les execucions del curs es fan amb uv run main.py: uv run resol i sincronitza l'entorn per tu. Tot i així, l'instructor fa totes dues coses, i és un hàbit raonable: un entorn virtual activat fa visible l'entorn a l'intèrpret d'ordres, al selector d'intèrpret de l'editor i a qualsevol eina que no conegui uv.

Windows és l'única excepció de plataforma del capítol, i l'instructor l'assenyala dues vegades: tant l'ordre d'instal·lació d'uv com la d'activació de l'entorn virtual són diferents, i no en mostra cap 00:09:31, 00:10:33.

Paquets principals i paquets d'integració

La llista d'instal·lació de sis paquets no és arbitrària: reflecteix el model de distribució de paquets de LangChain 1.x, que és el que fa que substituir proveïdors sigui senzill.

PaquetCapaPer què hi és
langchainFrameworkEl paquet que agrupa el conjunt
langchain-coreFrameworkAbstraccions independents del proveïdor: Runnables, missatges, prompts i Document
langgraphFrameworkOrquestració amb grafs i màquines d'estats
langchain-openaiIntegracióInclou ChatOpenAI i OpenAIEmbeddings
langchain-anthropicIntegracióInclou ChatAnthropic
python-dotenvUtilitatCarrega .env a l'entorn del procés

El nucli es manté independent del proveïdor; cada proveïdor té la seva pròpia distribució langchain-<vendor>. Per això ChatOpenAI s'importa des de langchain_openai i ChatAnthropic, des de langchain_anthropic, i mai des de langchain. Substituir proveïdors implica canviar una importació i una cadena de model: és precisament l'asimetria que la Part 4 convertirà en una regla: el model de generació es pot substituir; el model d'embeddings, no.

langgraph s'instal·la des del primer dia, encara que la guia no el faci servir fins a la Part 15. És un senyal deliberat: l'orquestració amb grafs es considera part de la pila de base, no un complement que s'afegeix quan el pipeline incorpora comportament d'agent. A la prova bàsica de funcionament se'n mostra la versió al costat de la de langchain-core.

Aquests sis paquets són el punt de partida. Al final d'aquesta part n'hauràs afegit tres més: langchain-community, per als loaders; pypdf, el parser de PDF que utilitza PyPDFLoader, i bs4, BeautifulSoup, amb què WebBaseLoader analitza l'HTML. Aquest últim consta entre les versions fixades al repositori, però no s'instal·la mai davant de la càmera. La resta de production-course-main-code/pyproject.toml, que fixa name = "langc-course" i requires-python = ">=3.12", és una taula de continguts del que construirem:

Paquet amb versió fixadaS'incorpora aFinalitat
langchain-community>=0.4.1aquesta partCarregadors de documents
pypdf>=6.6.2aquesta partEl parser de PyPDFLoader
bs4>=0.0.2aquesta partL'anàlisi d'HTML de WebBaseLoader
langchain-chroma>=1.1.0Part 4El vector store
rank-bm25>=0.2.2Part 6La meitat lèxica de la cerca híbrida
langchain-ollama>=1.0.1Parts 9–10Models locals, quan la factura importa
langgraph-checkpoint-sqlite>=3.0.3Més endavantL'estat dels agents de LangGraph
fastapi>=0.129.0, uvicorn>=0.40.0Part 11Exposar el pipeline com a servei
pytest>=9.0.2Part 13La bateria de proves

Secrets: .env, load_dotenv() i la regla d'ordre

Crea .env i desa-hi les dues claus:

text
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Després, al codi:

Python
# production-course-main-code/main.py, lines 1-4
from dotenv import load_dotenv
from importlib.metadata import version

load_dotenv()

«Ara ja tenim totes les claus disponibles per fer-les servir.» 00:11:34

Fixa't en allò que no es fa enlloc del repositori: les claus no es passen mai com a arguments a ChatOpenAI(...) ni a ChatAnthropic(...). Els SDK dels proveïdors llegeixen OPENAI_API_KEY i ANTHROPIC_API_KEY directament de l'entorn del procés en el moment de construir el client.

La regla d'higiene corresponent no es diu mai davant de la càmera, però està escrita al .gitignore del repositori, just al començament:

text
# Environment variables — NEVER commit these
.env

# Python
__pycache__/
*.pyc
*.pyo
.venv/
venv/

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db
.claude
chroma_db/

Tres d'aquestes entrades fan una funció real més enllà de mantenir l'ordre. .env és l'òbvia. .venv/ evita incorporar a l'historial uns centenars de megabytes de binaris específics de cada plataforma. chroma_db/ manté un índex vectorial generat fora de git, i aquest és un criteri genuí de producció: l'índex és informació derivada, és gran, és específic de la màquina i s'ha de poder reconstruir a partir dels documents originals i del codi. Si mai tens ganes de fer commit d'un índex, el que realment necessites és un script d'ingestió reproduïble.

El .env creixerà. Les variables de registre de traces de LangSmith arriben a la Part 7; les credencials de Supabase/pgvector, a la Part 10, i els secrets d'autenticació de l'API, a les Parts 11–12. Adopta l'hàbit ara.

La prova bàsica de funcionament i el seu criteri d'acceptació de quatre línies

Aquest és el resultat complet del capítol de configuració: 32 línies, reproduïdes literalment del repositori:

Python
# production-course-main-code/main.py
from dotenv import load_dotenv
from importlib.metadata import version

load_dotenv()

core_version = version("langchain-core")
lg_version = version("langgraph")
from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic


print(f"langchain-core version: {core_version}")
print(f"langgraph version: {lg_version}")


def main():

    # Test openai
    llm = ChatOpenAI(model_name="gpt-4o-mini", temperature=0)
    response = llm.invoke("Say 'setup complete!' in one word")
    print(f"Response from ChatOpenAI: {response}")

    # Test anthropic
    llm_anthropic = ChatAnthropic(model="claude-sonnet-4-5-20250929", temperature=0)
    response_anthropic = llm_anthropic.invoke("Say 'setup complete!' in one word")
    print(f"Response from ChatAnthropic: {response_anthropic}")

    print("Setup complete!")


if __name__ == "__main__":
    main()

Aquestes 32 línies contenen més aprenentatge del que suggereix el temps de la demostració.

Comprovar versions de manera que funcioni. La manera intuïtiva falla:

Python
# DOES NOT WORK — many LangChain 1.x packages export no __version__
from langchain_core import __version__ as core_version
from langgraph import __version__ as lg_version

La manera que funciona utilitza la biblioteca estàndard:

Python
from importlib.metadata import version
core_version = version("langchain-core")   # hyphen: DISTRIBUTION name
lg_version   = version("langgraph")

L'instructor en diu «només un petit canvi» 00:13:38, però la regla generalitzable és important: consulta la versió d'una distribució a les metadades del paquet, no a l'atribut __version__ del mòdul.

Per què cal mostrar les versions? Perquè en un ecosistema que avança tan de pressa, el comportament canvia entre versions principals i una guia escrita per a 1.x no coincidirà amb l'experiència d'un lector que utilitzi 2.x. El curs relativitza repetidament les seves xifres: només descriu langchain-core i langgraph com a versions «superiors a 1.0» i situa la publicació estable de la 1.0 un parell de mesos abans de l'enregistrament 00:14:38. Les versions realment fixades al repositori són langchain-core 1.2.7 i langgraph 1.0.7. Tracta les versions que es mostren com una instantània que has de registrar, no com un objectiu al qual t'hagis de fixar.

«És clar que, quan estigueu mirant aquest vídeo, això podria ser diferent.» 00:14:38

.predict() ja no és l'API vigent. L'instructor es corregeix a mitja explicació mentre escriu la crida d'OpenAI 00:12:37: .predict() és l'API antiga, anterior a LCEL, que rep i retorna cadenes. La interfície Runnable de LangChain 1.x és .invoke(), acompanyada de .batch(), .stream() i les variants asíncrones. Totes les crides a models de la resta d'aquesta guia, i totes les chains de la composició LCEL de la Part 1, utilitzen .invoke().

.invoke() retorna un objecte de missatge, no una cadena. L'script mostra la resposta completa, que produeix una representació de tipus AIMessage: el text més el consum de tokens, l'identificador del model i el motiu de finalització. El text en si és a .content, tal com l'instructor assenyala a la pantalla 00:14:38. Això fa ensopegar qui espera un str, i torna a ser important a la chain de la Part 1, en què StrOutputParser() existeix precisament per extreure'n el text.

Rigor en la prova bàsica de funcionament. El prompt, "Say 'setup complete!' in one word", és deliberadament trivial i idèntic byte per byte en tots dos proveïdors. L'objectiu no és la resposta, sinó que funcioni tot el recorregut: trobar la clau, accedir a la xarxa, utilitzar un identificador de model vàlid i interpretar la resposta. Mantenir el mateix prompt vol dir que qualsevol diferència de resultat és una diferència del proveïdor, no del prompt.

Valors per defecte de cost i determinisme. Es tria explícitament gpt-4o-mini perquè la comprovació sigui barata 00:12:37: és la primera aparició al curs d'una preocupació pel cost que tornarà amb força a les Parts 8 i 9. Tots dos clients utilitzen temperature=0, un valor per defecte raonable per a un script de verificació i, com argumentarà la Part 5, per a la generació RAG fonamentada en les fonts en general.

Quatre detalls més d'aquest fitxer que l'àudio no esmenta:

  • Les importacions de les línies 8–9 apareixen després de les instruccions executables de les línies 6–7. Des del punt de vista de l'estil,

és poc elegant; a la pràctica, vol dir que si falta langchain-anthropic, la fallada es produeix després que ja s'hagi mostrat la capçalera de versions. Sembla un problema de versions, però no ho és.

  • Les instruccions que mostren les versions són a l'àmbit del mòdul, no dins de main(). S'executen durant la importació, de manera que qualsevol

altre mòdul que importi main també mostra la capçalera com a efecte secundari.

  • No hi ha cap comprovació amb os.getenv. L'script requereix totes dues claus i retorna directament un error

d'autenticació de l'SDK si en falta alguna. Una configuració amb un sol proveïdor falla la prova bàsica sense indicar clarament que «et falta una clau».

  • L'identificador del model d'Anthropic porta data (claude-sonnet-4-5-20250929) i en algun moment es

retirarà. Preveu haver-lo d'actualitzar: un error 404 per a aquesta cadena és un esdeveniment del cicle de vida del model, no un error de la teva configuració.

Executa'l:

bash
uv run main.py

La prova d'acceptació. L'entorn està preparat quan una execució de main.py mostra quatre elements: dues cadenes de versió, una resposta d'OpenAI sense errors, una resposta d'Anthropic sense errors i la línia final Setup complete!. Amb menys d'això, no has acabat, per molt correcte que sembli el codi.

Per què existeix una capa de càrrega

Amb un entorn funcional, el pipeline pot començar. La primera etapa és la càrrega, i es justifica amb una frase: un LLM només coneix allò que poses a la seva finestra de context, i aquest context ha de sortir d'algun lloc 00:15:35.

«Els grans models de llenguatge necessiten context, i el context prové de dades, documents i altres fonts.» 00:15:35

La categoria d'entrada és fitxers sense processar: PDF, TXT, HTML, DOCX, CSV i qualsevol altre format que tinguis 00:15:35. Cinc formats identificats que no tenen res en comú. Cinc parsers, cinc API, cinc formes d'error i cinc convencions de metadades. Tota la funció de la capa de càrrega és reduir aquesta heterogeneïtat a una única estructura perquè totes les etapes posteriors —splitters, càlcul d'embeddings, vector stores i recuperadors— només hagin de treballar amb un tipus.

El segon aspecte és decidir entre construir o aprofitar el que ja existeix. LangChain ja inclou els adaptadors, de manera que no hauries d'escriure parsers de PDF a mà. Però fixa't en el significat literal d'«adaptador»: LangChain proporciona una interfície uniforme i delega l'anàlisi real a una biblioteca de tercers que no instal·la per tu. Aquest únic fet explica totes dues fallades de la demostració en directe d'aquest capítol i és el motiu pel qual més endavant hi ha una secció sobre dependències absents.

L'objecte Document

Tots els loaders retornen una llista d'objectes Document, i cada Document té exactament dues parts:

CampTipusContingut
page_contentstrEl text extret
metadatadictLa procedència que afegeix el loader: source, número de pàgina, autor, data de creació, …

Aquest és tot el contracte. També és la via d'escapament: un Document és simplement una classe de dades, de manera que en pots construir un amb les metadades que vulguis:

Python
# production-course-main-code/document_loaders.py:74-89
def doc_structure():
    doc = Document(
        page_content="This is a sample document.",
        metadata={
            "source": "manual_creation.txt",
            "author": "Paulo",
            "length": 30,
            "tags": ["sample", "test"],
            "created_at": "2024-06-01",
        },
    )

    print("Document Structure:")
    print(f"  page_content (type): {type(doc.page_content)}")
    print(f"  page_content: {doc.page_content}")
    print(f"  metadata: {doc.metadata}")

S'importa des de core, no des de community: from langchain_core.documents import Document.

Fixa't en "tags": ["sample", "test"]: per a LangChain, el diccionari de metadades admet claus arbitràries i valors no escalars. Que el teu vector store els accepti és una altra qüestió, i la majoria no ho fan. Chroma, que s'utilitza a la Part 4, només desa valors escalars de metadades; per tant, abans d'indexar, converteix les llistes en una cadena amb delimitadors o en un conjunt d'indicadors booleans. Aquesta construcció manual és precisament el recurs que utilitza la Part 5 quan un loader no proporciona els camps que necessites.

El patró universal de dues línies

Tots els loaders de LangChain tenen la mateixa estructura, i aquesta uniformitat és el que fa que valgui la pena aprendre l'abstracció:

Python
loader = SomeLoader(source)   # 1. instantiate with the source
docs   = loader.load()        # 2. call .load() → list[Document]

Això és tot. La ruta, l'URL o el directori es passen al constructor; .load() retorna els documents 00:17:37. Aquesta uniformitat tampoc no és una simple convenció: la imposa la classe base. langchain_core.document_loaders.BaseLoader.load() és literalment return list(self.lazy_load()), i les subclasses han d'implementar lazy_load() i deixar load() sense modificar. Per tant, qualsevol loader que trobis és un generador més una línia que en materialitza els resultats.

Aquest és el catàleg tal com el presenta el curs:

LoaderFontObservacions
TextLoaderLa ruta d'un .txtEl cas més senzill possible: 1 fitxer → 1 Document
PyPDFLoaderLa ruta d'un PDF1 pàgina → 1 Document
DirectoryLoaderLa ruta d'una carpetaUn distribuïdor: rep glob + loader_cls
WebBaseLoaderUn URL o diversosDescarrega i extreu HTML
UnstructuredLoaderFormats complexos o mixtosLa via alternativa (MD, TXT i altres)

El mateix text del PDF de demostració que apareix a la pantalla n'esmenta tres més que l'àudio no tracta: CSVLoader, que crea documents per files; JSONLoader, amb extracció de tipus jq, i YouTubeLoader, per a transcripcions. Existeixen; simplement queden fora de l'abast del curs, i el patró de dues línies s'hi aplica sense canvis.

Pràctica 1: TextLoader i la primera dependència absent

La programació en directe d'aquest capítol es fa en un fitxer específic, document_loaders.py. La primera importació falla:

bash
uv add langchain-community

Els carregadors de documents són a langchain-community, no a langchain-core. L'instructor justifica la instal·lació dient que el paquet community és on hi ha els text splitters 00:21:44: aquesta explicació és incorrecta i no s'ha de reproduir. Els text splitters es distribueixen a langchain-text-splitters, fixat separadament al repositori a la versió 1.1.0. L'acció és correcta; el motiu que s'hi atribueix, no. El que langchain_community proporciona aquí és langchain_community.document_loaders.

Les importacions del fitxer:

Python
# production-course-main-code/document_loaders.py:1-15
import os
import tempfile
from pathlib import Path
from langchain_core.documents import Document
from langchain_community.document_loaders import (
    TextLoader,
    WebBaseLoader,
    DirectoryLoader,
    PyPDFLoader,
)
from bs4 import BeautifulSoup

from dotenv import load_dotenv

load_dotenv()

Importar aquest mòdul ja mostra un avís abans d'executar cap línia del teu codi: USER_AGENT environment variable not set, consider setting it to identify your requests. Prové de langchain_community.utils.user_agent i val la pena entendre'l en lloc de silenciar-lo, perquè és una trampa d'ordre exactament del mateix tipus que load_dotenv(). web_base.py construeix el seu default_header_template durant la importació; per tant, la variable d'entorn ja ha d'estar definida quan s'executa la línia 5, mentre que aquí load_dotenv() és a la línia 15. Així doncs, afegir USER_AGENT a .env no serveix de res en aquest fitxer: totes les peticions utilitzen DefaultLangchainUserAgent, que alguns llocs web rebutgen directament. Exporta la variable a l'intèrpret d'ordres, defineix os.environ["USER_AGENT"] abans de les importacions dels loaders o passa un header_template= explícit al loader per deixar de dependre del valor global.

I la primera demostració:

Python
# production-course-main-code/document_loaders.py:18-42
def load_text_file():
    # Create a temporary text file for demonstration
    with tempfile.NamedTemporaryFile(delete=False, suffix=".txt") as temp_file:
        temp_file.write(
            b"Hello, this is a sample text file.\nThis file is used to demonstrate the TextLoader."
        )
        temp_file_path = temp_file.name

    try:
        # Load the text file using TextLoader
        loader = TextLoader(temp_file_path)
        documents = loader.load()

        print(f"Loaded {len(documents)} document(s)")
        print(f"Content preview: {documents[0].page_content[:100]}...")
        print(f"Metadata: {documents[0].metadata}")

        # Print the loaded documents
        # for doc in documents:
        #     print("Document Content:")
        #     print(doc)
        #     print(doc.page_content)
    finally:
        # Clean up the temporary file
        os.remove(temp_file_path)

El bloc comentat de la part inferior no és codi abandonat: és la primera versió, conservada. La versió inicial de l'instructor mostrava tot l'objecte Document per fer-ne visible l'estructura; després la va substituir per tres dades concretes: len(documents), una previsualització de 100 caràcters del contingut i el diccionari de metadades 00:24:50. Val la pena fer totes dues coses, en aquest ordre: mostra l'objecte complet una vegada per conèixer el tipus i després selecciona els camps que realment t'interessen.

Resultat: un fitxer de text → exactament un Document 00:24:50, i les seves metadades tenen exactament una clau:

Python
{'source': '/tmp/tmpop0y38v3.txt'}

Això és tot el que afegeix TextLoader: la seva implementació acaba amb metadata = {"source": str(self.file_path)} i produeix un únic Document. L'instructor també llegeix una marca temporal de creació de la pantalla 00:23:48; la versió fixada langchain-community 0.4.1 no en genera cap, de manera que no hi has de basar el disseny. La lliçó és generalitzable: abans de construir res que en depengui, mostra una vegada el diccionari de metadades que produeix la teva versió.

Dos detalls més: NamedTemporaryFile(delete=False) deixa realment el fitxer sense eliminar, i per això existeix finally: os.remove(...) i no és opcional. La longitud de la previsualització és [:100]: la frase de la transcripció «els primers 1,00 o 100 caràcters» 00:24:50 és un lapsus; el codi és la referència.

Pràctica 2: PyPDFLoader i el comportament que fa fallar el codi ingenu

Les mateixes dues línies amb un altre loader: aquesta uniformitat és la lliçó 00:25:52. Però primer apareix la segona dependència absent:

bash
uv add pypdf

LangChain és un adaptador de pypdf; no l'inclou. Espera el mateix patró en qualsevol altre loader que utilitzi un parser: pymupdf per a PyMuPDFLoader, unstructured per a la família Unstructured. En aquesta capa, les dependències de parsers absents són la norma, no l'excepció.

Python
# production-course-main-code/document_loaders.py:92-99
def pdf_loader(pdf_path: str):
    loader = PyPDFLoader(pdf_path)
    documents = loader.load()

    print(f"Loaded {len(documents)} document(s) from PDF")
    for i, doc in enumerate(documents):
        print(f"Document {i+1} Content Preview: {doc.page_content[:100]}...")
        print(f"Metadata: {doc.metadata}")

Es crida com a pdf_loader("./docs/langchain_demo.pdf"): és el punt d'entrada actiu del repositori, amb les altres quatre demostracions comentades. El fitxer de prova és un PDF generat pel mateix instructor de 3 pàgines i 4.5 KB, el text del qual enumera el catàleg de loaders i cinc bones pràctiques. La Part 3 el reutilitzarà perquè la pàgina 2 conté el pangrama «The quick brown fox jumps over the lazy dog» com a dada de prova del chunking.

El parser omple automàticament les metadades. Executar el codi del repositori amb el PDF de demostració produeix exactament això per a la primera pàgina:

Python
{
    'producer': 'PyPDF',
    'creator': 'PyPDF',
    'creationdate': '2026-02-02T21:45:08+00:00',
    'source': './docs/langchain_demo.pdf',
    'total_pages': 3,
    'page': 0,
    'page_label': '1',
}

Set camps, tres dels quals amaguen trampes.

El fitxer de prova també hi contribueix sense fer-ho evident. El mateix exemple pràctic del PDF, imprès a la pàgina 1, formata una cita amb print(f"Page: {doc.metadata['page']}"), el camp indexat des de 0. L'exemple de codi que llegeixes mentre aprens l'API ja conté l'error.

El bucle del mateix repositori repeteix el problema d'una altra manera: mostra Document {i+1} a partir d'enumerate i genera un comptador començat a 1, còmode per a les persones però sense relació amb la clau page que apareix just al costat a la mateixa sortida. Si copies aquest bucle, no utilitzis el número que es mostra com a cita.

source és la cadena que has escrit, no una ruta normalitzada. El diccionari anterior indica './docs/langchain_demo.pdf' perquè és l'argument literal que ha passat el punt d'entrada. No s'ha resolt la ruta, no s'ha fet absoluta ni s'ha normalitzat. Dos scripts d'ingestió que escriguin de manera diferent el mateix fitxer produeixen dues cadenes de cita diferents, dos valors diferents per als filtres de metadades i cap manera d'eliminar-ne els duplicats. Normalitza una sola vegada durant la ingestió, amb str(Path(p).resolve()), i fes-ho abans del primer embedding: la Part 4 mostrarà que només pots filtrar segons allò que has desat durant la indexació.

producer i creator no indiquen la procedència intel·lectual del document. Aquí tots dos contenen PyPDF per un motiu ordinari: l'instructor ha generat el PDF de demostració amb pypdf, de manera que la biblioteca que ha escrit el fitxer i la que l'ha llegit són la mateixa. Aquests camps descriuen eines, no autoria. No els mostris als usuaris com «el creador del document» ni hi construeixis filtres esperant obtenir un senyal significatiu 00:27:57.

Les metadades depenen del parser; no són una veritat absoluta. T'expliquen què ha vist el pipeline, que és precisament el que necessites per depurar i el que no has de confondre amb allò que el document és.

Com triar un loader de PDF

Els PDF són el cas en què realment importa triar el loader, perquè PDF és un format de maquetació que es presenta com si fos un format de document. El curs compara tres opcions 00:18:41:

LoaderVelocitatMetadadesMés adequat per a
PyPDFLoaderRàpidBàsiquesPDF senzills. Comença per aquí.
PyMuPDFLoaderEl més ràpidBonesVolum elevat; l'opció polivalent que tria l'instructor
UnstructuredPDFLoaderEl més lentLes més riques i detalladesTaules i maquetacions complexes

La lliçó real és la forma d'aquesta corba: guanyes fidelitat a canvi de latència i tries un punt per a cada cas d'ús, no una vegada per sempre.

«Si tens documents amb taules i maquetacions, UnstructuredPDFLoader serà la millor opció.» 00:19:41

El curs comença deliberadament amb PyPDFLoader i ho explicita:

«Segons el teu cas d'ús, pots canviar a una altra opció.» 00:19:41

Una observació que el curs no fa, però la Part 16 sí: cap d'aquests tres loaders resol completament les taules i els gràfics; simplement els degrada menys. UnstructuredPDFLoader proporciona més estructura amb què treballar, però l'extracció de text continua destruint un gràfic. La resposta basada en visió és la recuperació multimodal, i això és una arquitectura diferent, no un altre loader.

Càrrega de contingut web

WebBaseLoader rep un URL o diversos alhora. La versió executable del repositori no es va arribar a executar davant de la càmera:

Python
# production-course-main-code/document_loaders.py:45-54
def web_loader():
    loader = WebBaseLoader(
        "https://en.wikipedia.org/wiki/Web_scraping", bs_kwargs={"parse_only": None}
    )
    documents = loader.load()

    print(f"Loaded {len(documents)} document(s) from web")
    print(f"Source: {documents[0].metadata.get('source', 'N/A')}")
    print(f"Content length: {len(documents[0].page_content)} characters")
    print(f"Preview: {documents[0].page_content[:200]}...")

La diapositiva mostrava tres pàgines de example.com i l'instructor suggeria, amb reserves, que es descarregaven en paral·lel 00:19:41. La lectura del loader publicat resol la qüestió, i la resposta és un detall realment important per a producció:

Càrrega de directoris, glob i lazy_load()

DirectoryLoader no és pròpiament un loader, sinó un distribuïdor. Rep tres paràmetres 00:20:41:

  1. la ruta: la carpeta que ha de recórrer;
  2. el glob: quins fitxers ha de seleccionar, inclosa la profunditat de la recursió (**/*.pdf per a tots els PDF

de tots els subdirectoris);

  1. loader_cls: quina classe de loader analitza cada fitxer seleccionat.

«Això és el que anomenem un patró glob: filtra fitxers.» 00:20:41

La versió del repositori el combina amb una altra eina que l'àudio no esmenta: lazy_load().

Python
# production-course-main-code/document_loaders.py:57-71
def lazy_loader():

    # Create temp directory with sample files
    with tempfile.TemporaryDirectory() as tmpdir:
        # Create sample files
        for i in range(5):
            path = Path(tmpdir) / f"doc_{i}.txt"
            path.write_text(f"This is document {i}. It contains sample content.")

        loader = DirectoryLoader(tmpdir, glob="*.txt", loader_cls=TextLoader)

        print("Initialized lazy loader for directory:", tmpdir)
        for doc in loader.lazy_load():
            print("Document Content Preview:", doc.page_content[:50], "...")
            print("Metadata:", doc.metadata["source"])

Cinc fitxers, amb una previsualització de 50 caràcters de cadascun. La línia important és loader.lazy_load():

MètodeRetornaMemòriaQuan s'ha d'utilitzar
.load()list[Document]: tot el conjunt, materialitzatO(corpus)Conjunts petits i coneguts; quan necessites len() o accés aleatori
.lazy_load()Un generador, un Document cada vegadaO(1) per documentIngestions grans; quan envies directament els documents a un splitter i al càlcul d'embeddings

Com que el bucle anterior descarta cada doc després de mostrar-lo, no s'acumula res a la RAM. Aquesta és la propietat important: en una ingestió de 50,000 documents, .load() construeix tot el corpus en memòria abans de calcular l'embedding del primer fragment; .lazy_load() permet encadenar càrrega → divisió → embeddings → emmagatzematge, un document cada vegada. La mateixa pàgina «Best Practices» del PDF de demostració diu el mateix: «Per a conjunts grans de documents, utilitza lazy_load() en lloc de load().»

Un altre paràmetre que convé conèixer abans de carregar un directori gran: use_multithreading=False per defecte, amb max_concurrency=4 quan l'actives. L'anàlisi dels documents és el coll d'ampolla de la majoria d'ingestions, de manera que sovint aquesta és la millora de velocitat menys costosa disponible. I, com qualsevol opció de concurrència, també és la manera més ràpida de convertir una suposició sobre l'ordre en un error.

Les metadades són la base de les cites

Aquesta és la part de la capa de càrrega que dona fruit més tard i que més importa. El PDF de demostració ho explica a la seva pròpia pàgina 2, una coincidència ben útil:

«Els loaders conserven metadades com ara els números de pàgina, les rutes dels fitxers i les fonts. Utilitza aquesta informació per a les cites.»

La cadena és: el loader afegeix metadades → el splitter les propaga → el vector store les desa → el recuperador les retorna → el formatador les representa com a [n] source dins de la cadena de context que llegeix el model. La Part 1 ha establert que les fonts viatgen dins del context, no per un canal separat; la Part 3 mostrarà que split_documents() propaga les metadades del document pare mentre que split_text() les perd; la Part 4 mostrarà que només pots filtrar segons les metadades que has desat durant la indexació.

D'aquí en surt una regla amb una conseqüència incòmoda:

I un hàbit que val la pena adoptar immediatament, sense cost addicional:

Mostra doc.metadata['source'] al costat de cada resultat recuperat, en tots els scripts de depuració que escriguis a partir d'ara. Costa una línia i és el que fa possible la depuració de la Part 5.

On la font es queda curta

Tres qüestions que aquesta part hereta del curs com a mancances, no com a respostes, exposades amb claredat:

  • Es recomana PyMuPDFLoader com a opció polivalent, però no s'utilitza mai. Cap fitxer de cap dels dos repositoris

l'importa. El veredicte que és la millor opció en tots els aspectes 00:18:41 és el criteri de l'instructor, no el resultat d'una mesura mostrada a la pantalla.

  • UnstructuredLoader / UnstructuredPDFLoader es descriuen, però no s'instal·len ni s'executen mai.

La cadena de dependències d'unstructured és pesada: inclou biblioteques de sistema per a OCR i formats ofimàtics, i el curs no mostra cap d'aquests costos de configuració. A més, és, de manera poc convenient, el loader_cls per defecte de DirectoryLoader.

  • WebBaseLoader i DirectoryLoader apareixen en diapositives i en codi del repositori que no s'ha executat. Ningú

no els ha vist funcionar. El paràmetre bs_kwargs sense efecte que hem vist abans és el tipus de defecte que perdura quan s'escriu codi però no se'n fa cap demostració. La qüestió de la descàrrega seqüencial o asíncrona s'ha hagut de resoldre llegint la biblioteca, no mirant el curs.

Res d'això invalida la capa. Sí que vol dir que, quan utilitzes alguna cosa més enllà de TextLoader i PyPDFLoader, superes el que la font ha verificat i ho has de comprovar tu mateix: amb un len(documents) i una visualització de les metadades, que és precisament el ritual d'inspecció que ensenya aquest capítol.

Llista de comprovació

Entorn:

  1. Clau d'OpenAI creada a Settings → API keys, limitada a un projecte; secret copiat en el moment de

crear-la al teu gestor de contrasenyes.

  1. Clau d'Anthropic creada a platform.claude.com → Manage → API keys, limitada a un

espai de treball; secret copiat en el moment de crear-la.

  1. uv init + uv venv + source .venv/bin/activate en un directori net.
  2. `uv add langchain langchain-core langgraph langchain-openai langchain-anthropic

python-dotenv` — sis paquets, una sola ordre.

  1. .env creat amb OPENAI_API_KEY i ANTHROPIC_API_KEY; .env inclòs a

.gitignore juntament amb .venv/, __pycache__/ i chroma_db/. (USER_AGENT va a l'entorn de l'intèrpret d'ordres, no a .env: es llegeix en el moment de la importació.)

  1. load_dotenv() és la primera instrucció executable de cada punt d'entrada, abans de construir cap

client.

  1. Versions llegides mitjançant importlib.metadata.version("langchain-core"), mai

from langchain_core import __version__.

  1. uv run main.py mostra quatre coses: dues versions, una resposta d'OpenAI, una resposta

d'Anthropic, Setup complete!.

  1. Totes les crides al model fan servir .invoke(); saps que el retorn és un objecte de missatge i que el text és

.content.

  1. Has establert com a criteri fer servir model= (sense dependre mai del valor predeterminat de la classe) i temperature=0

per a tot allò que vulguis que sigui reproduïble.

Càrrega:

  1. uv add langchain-community (carregadors), uv add pypdf (anàlisi de PDF), uv add bs4

(WebBaseLoader): preveu que et falti un analitzador per cada format nou.

  1. La instanciació dels carregadors es concentra en una única funció de fàbrica, de manera que substituir-ne un requereixi canviar una sola línia.
  2. Cada ingesta mostra len(documents) i documents[0].metadata almenys una vegada, amb la teva

pròpia versió instal·lada, abans de donar-ne el resultat per bo.

  1. Cap camí del codi fa documents[0] en carregar un PDF.
  2. Les citacions mostren page_label; els filtres fan servir page.
  3. source es normalitza una sola vegada durant la ingesta (str(Path(p).resolve()) o un identificador de negoci estable):

mai no és un nom de tempfile sense tractar ni la cadena literal que algú hagi escrit en fer la crida.

  1. DirectoryLoader sempre rep un loader_cls explícit, un recursive explícit i, o bé

autodetect_encoding, o bé silent_errors juntament amb un recompte dels elements omesos que efectivament registris als logs.

  1. Tot allò que depengui de l'ordre dels documents ordena les rutes per si mateix en lloc de confiar en

lazy_load().

  1. Les ingestes grans fan servir .lazy_load(); les ingestes web de múltiples URL fan servir .alazy_load() i configuren

requests_per_second, continue_on_failure i raise_for_status de manera deliberada.

Decisions que cal prendre

DecisióValor predeterminatQuan cal canviar-lo
Gestor de paquetsuv, exclusivamentMai, dins d'aquesta guia
Versió mínima de Python>=3.12 (repositori principal); >=3.13 per al material de les parts 14–16L'entorn de desplegament t'obliga a fer servir una versió anterior: aleshores comprova totes les versions fixades
ProveïdorsOpenAI + AnthropicQualsevol parella de proveïdors als quals puguis fer crides; el codi és independent del proveïdor per disseny
Model per a la prova bàsica de funcionamentgpt-4o-mini, temperature=0No facis servir mai un model de frontera per comprovar les connexions entre components
Carregador de PDFPyPDFLoaderVolum elevat → PyMuPDFLoader; taules/maquetació → UnstructuredPDFLoader
load() o lazy_load()load() mentre el corpus sigui petitQuan el corpus ja no càpiga còmodament a la RAM
Esquema de metadadessource (normalitzat) + page/page_label + qualsevol camp pel qual hagis de filtrarDecideix-ho abans de la primera ingesta: canviar-ho implica tornar a generar els embeddings de tot

A continuació: els documents que acabes de carregar encara són documents sencers, i no són documents sencers el que indexes. La part 3 els divideix i mostra la comparació A/B mesurada en què el segmentador teòricament millor perd per 1–4.