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.
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:
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ïdor | Ruta a la consola | Àmbit de la clau | Què tries en crear-la |
|---|---|---|---|
| OpenAI | Settings → API keys → Create new secret key | Projecte | Nom de la clau + projecte (el curs fa servir Default project) |
| Anthropic | platform.claude.com → Manage → API keys → Create Key | Espai de treball | Nom 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:
| Ordre | Què fa |
|---|---|
uv init | Crea l'estructura inicial d'un projecte al directori actual: pyproject.toml, main.py, README.md, .python-version, .gitignore i un repositori git |
uv venv | Crea l'entorn virtual del projecte a .venv |
source .venv/bin/activate | L'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.
# 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.
| Paquet | Capa | Per què hi és |
|---|---|---|
langchain | Framework | El paquet que agrupa el conjunt |
langchain-core | Framework | Abstraccions independents del proveïdor: Runnables, missatges, prompts i Document |
langgraph | Framework | Orquestració amb grafs i màquines d'estats |
langchain-openai | Integració | Inclou ChatOpenAI i OpenAIEmbeddings |
langchain-anthropic | Integració | Inclou ChatAnthropic |
python-dotenv | Utilitat | Carrega .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ó fixada | S'incorpora a | Finalitat |
|---|---|---|
langchain-community>=0.4.1 | aquesta part | Carregadors de documents |
pypdf>=6.6.2 | aquesta part | El parser de PyPDFLoader |
bs4>=0.0.2 | aquesta part | L'anàlisi d'HTML de WebBaseLoader |
langchain-chroma>=1.1.0 | Part 4 | El vector store |
rank-bm25>=0.2.2 | Part 6 | La meitat lèxica de la cerca híbrida |
langchain-ollama>=1.0.1 | Parts 9–10 | Models locals, quan la factura importa |
langgraph-checkpoint-sqlite>=3.0.3 | Més endavant | L'estat dels agents de LangGraph |
fastapi>=0.129.0, uvicorn>=0.40.0 | Part 11 | Exposar el pipeline com a servei |
pytest>=9.0.2 | Part 13 | La bateria de proves |
Secrets: .env, load_dotenv() i la regla d'ordre
Crea .env i desa-hi les dues claus:
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...Després, al codi:
# 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:
# 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:
# 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:
# 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:
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:
uv run main.py
La prova d'acceptació. L'entorn està preparat quan una execució de
main.pymostra quatre elements: dues cadenes de versió, una resposta d'OpenAI sense errors, una resposta d'Anthropic sense errors i la línia finalSetup 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:
| Camp | Tipus | Contingut |
|---|---|---|
page_content | str | El text extret |
metadata | dict | La 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:
# 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ó:
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:
| Loader | Font | Observacions |
|---|---|---|
TextLoader | La ruta d'un .txt | El cas més senzill possible: 1 fitxer → 1 Document |
PyPDFLoader | La ruta d'un PDF | 1 pàgina → 1 Document |
DirectoryLoader | La ruta d'una carpeta | Un distribuïdor: rep glob + loader_cls |
WebBaseLoader | Un URL o diversos | Descarrega i extreu HTML |
UnstructuredLoader | Formats complexos o mixtos | La 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:
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:
# 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ó:
# 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:
{'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:
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ó.
# 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:
{
'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:
| Loader | Velocitat | Metadades | Més adequat per a |
|---|---|---|---|
PyPDFLoader | Ràpid | Bàsiques | PDF senzills. Comença per aquí. |
PyMuPDFLoader | El més ràpid | Bones | Volum elevat; l'opció polivalent que tria l'instructor |
UnstructuredPDFLoader | El més lent | Les més riques i detallades | Taules 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,
UnstructuredPDFLoaderserà 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:
# 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:
- la ruta: la carpeta que ha de recórrer;
- el glob: quins fitxers ha de seleccionar, inclosa la profunditat de la recursió (
**/*.pdfper a tots els PDF
de tots els subdirectoris);
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().
# 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ètode | Retorna | Memòria | Quan s'ha d'utilitzar |
|---|---|---|---|
.load() | list[Document]: tot el conjunt, materialitzat | O(corpus) | Conjunts petits i coneguts; quan necessites len() o accés aleatori |
.lazy_load() | Un generador, un Document cada vegada | O(1) per document | Ingestions 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
PyMuPDFLoadercom 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/UnstructuredPDFLoaderes 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.
WebBaseLoaderiDirectoryLoaderapareixen 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:
- 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.
- 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.
uv init+uv venv+source .venv/bin/activateen un directori net.- `uv add langchain langchain-core langgraph langchain-openai langchain-anthropic
python-dotenv` — sis paquets, una sola ordre.
.envcreat ambOPENAI_API_KEYiANTHROPIC_API_KEY;.envinclò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ó.)
load_dotenv()és la primera instrucció executable de cada punt d'entrada, abans de construir cap
client.
- Versions llegides mitjançant
importlib.metadata.version("langchain-core"), mai
from langchain_core import __version__.
uv run main.pymostra quatre coses: dues versions, una resposta d'OpenAI, una resposta
d'Anthropic, Setup complete!.
- Totes les crides al model fan servir
.invoke(); saps que el retorn és un objecte de missatge i que el text és
.content.
- Has establert com a criteri fer servir
model=(sense dependre mai del valor predeterminat de la classe) itemperature=0
per a tot allò que vulguis que sigui reproduïble.
Càrrega:
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.
- 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.
- Cada ingesta mostra
len(documents)idocuments[0].metadataalmenys una vegada, amb la teva
pròpia versió instal·lada, abans de donar-ne el resultat per bo.
- Cap camí del codi fa
documents[0]en carregar un PDF. - Les citacions mostren
page_label; els filtres fan servirpage. sourcees 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.
DirectoryLoadersempre rep unloader_clsexplícit, unrecursiveexplícit i, o bé
autodetect_encoding, o bé silent_errors juntament amb un recompte dels elements omesos que efectivament registris als logs.
- Tot allò que depengui de l'ordre dels documents ordena les rutes per si mateix en lloc de confiar en
lazy_load().
- 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 predeterminat | Quan cal canviar-lo |
|---|---|---|
| Gestor de paquets | uv, exclusivament | Mai, dins d'aquesta guia |
| Versió mínima de Python | >=3.12 (repositori principal); >=3.13 per al material de les parts 14–16 | L'entorn de desplegament t'obliga a fer servir una versió anterior: aleshores comprova totes les versions fixades |
| Proveïdors | OpenAI + Anthropic | Qualsevol 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 funcionament | gpt-4o-mini, temperature=0 | No facis servir mai un model de frontera per comprovar les connexions entre components |
| Carregador de PDF | PyPDFLoader | Volum elevat → PyMuPDFLoader; taules/maquetació → UnstructuredPDFLoader |
load() o lazy_load() | load() mentre el corpus sigui petit | Quan el corpus ja no càpiga còmodament a la RAM |
| Esquema de metadades | source (normalitzat) + page/page_label + qualsevol camp pel qual hagis de filtrar | Decideix-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.