Monta el taller y mete los datos
Montar el proyecto con uv, las credenciales y la capa de loaders que convierte cualquier fichero en Documents.
Esta es la única parte de la guía que no construye nada inteligente. Cubre unos veinte minutos del curso original — de 00:08:27 a 00:28:27 — y produce dos artefactos: un proyecto Python capaz de llamar a dos proveedores de modelos, y una capa de loaders que convierte ficheros arbitrarios en la única estructura de datos que dan por supuesta todas las etapas posteriores.
En el modelo mental de la Parte 1, esta parte se encarga de la primera caja de la Phase A:
ASCII original
PHASE A — INDEX Load ──► Split ──► [Contextualize] ──► Embed ──► Store + Index ▲ └── you are here
También coloca el sustrato sobre el que se apoya todo lo demás: credenciales, el gestor de paquetes y la disciplina de carga del entorno. Nada de esto es glamuroso. Todo es estructural — el diccionario metadata que un loader adjunta en esta parte es, literalmente, la cita que ve el usuario en la Parte 6, y el .env que creas aquí es el fichero del que leen en silencio todos los clientes de proveedores de las catorce partes restantes.
Lee esta parte una vez, hazla una vez y no vuelvas a pensar en ella. Una configuración que tienes que volver a decidir una y otra vez es una configuración que acabará desincronizándose y te costará, en la Parte 8, una sesión de depuración que no tiene nada que ver con el retrieval.
Credenciales antes que código
El curso abre su parte práctica no en un editor, sino en dos consolas de vendor, y ese orden es la lección. La primera dependencia de una aplicación LLM no es una librería, es un secreto. Nada de lo que viene después — ninguna llamada de embedding, ninguna llamada de chat, ningún test de retrieval — se puede verificar hasta que existe una clave. Escribe primero el código y tu primera ejecución fallará por una razón que no tiene nada que ver con tu código.
Necesitas al menos dos claves: una de OpenAI y una de Anthropic 00:09:31. La razón que se da no es la redundancia ni el benchmarking.
«La cuestión es que tengamos al menos una forma de hacer inferencia con modelos.» 00:09:31
El requisito es la capacidad, no la marca. El instructor deja claro que otro proveedor sirve igual y que eso no es lo importante — el código se escribe contra los paquetes de integración de proveedores de LangChain, así que cambiar de vendor más adelante es un import y un cambio en el string del modelo, no una reescritura. Dos proveedores es simplemente lo que permite demostrar esa intercambiabilidad en el smoke test que estás a punto de escribir.
Las dos consolas difieren en algo que importa a nivel operativo: el ámbito al que queda vinculada una clave.
| Proveedor | Ruta en la consola | Ámbito de la clave | Qué eliges al crearla |
|---|---|---|---|
| OpenAI | Settings → API keys → Create new secret key | Project (proyecto) | Nombre de la clave + proyecto (el curso usa Default project) |
| Anthropic | platform.claude.com → Manage → API keys → Create Key | Workspace (espacio de trabajo) | Nombre de la clave + workspace (el predeterminado sirve si solo tienes uno) |
Procedimiento A — clave de OpenAI. Inicia sesión, pasa de las pestañas Dashboard / Docs / API a Settings, abre API keys, haz clic en Create new secret key, ponle nombre, elige el proyecto (Default project en el curso), haz clic en Create secret key y copia el valor 00:08:30.
Procedimiento B — clave de Anthropic. Ve a platform.claude.com, menú lateral izquierdo → Manage → API keys. Esa página muestra tu organización y las claves que ya existan. Haz clic en Create Key, dale un nombre, elige el workspace y confirma 00:08:30.
La toolchain: uv, y solo uv
uv es el gestor de paquetes y de proyectos de toda la guía. Ni pip, ni Poetry, ni conda. El curso lo trata como algo ya decidido y nunca vuelve sobre ello. El instructor hace las demos en macOS y ejecuta un instalador con curl sin leer la URL en voz alta, así que el comando de abajo es la reconstrucción canónica a partir de la documentación de uv, no una cita.
Cinco comandos cubren todo lo que vas a hacer:
| Comando | Qué hace |
|---|---|
uv init | Genera el esqueleto de un proyecto en el directorio actual: pyproject.toml, main.py, README.md, .python-version, .gitignore y un repo git |
uv venv | Crea el entorno virtual del proyecto en .venv |
source .venv/bin/activate | Lo activa (forma de macOS/Linux; en Windows es distinto) |
uv add <pkg> | Resuelve la dependencia, la escribe en pyproject.toml, actualiza uv.lock y la instala |
uv run <script> | Ejecuta un script dentro del entorno del proyecto, sincronizándolo antes — no hace falta activarlo a mano |
Procedimiento C — arrancar el proyecto.
# 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
Merece la pena ejecutar esa última línea antes de tocar nada. Demuestra que el intérprete, el venv y el esqueleto están de acuerdo, y te da una base que sabes que funciona para empezar a romperla 00:11:34.
Fíjate en que uv venv + source .venv/bin/activate son estrictamente redundantes, dado que todas las ejecuciones del curso son uv run main.py — uv run resuelve y sincroniza el entorno por ti. El instructor hace las dos cosas de todos modos, y es un hábito razonable: un venv activado hace visible el entorno para tu shell, para el selector de intérprete de tu editor y para cualquier herramienta que no conozca uv.
Windows es la única advertencia de plataforma del capítulo, y el instructor la señala dos veces: tanto el comando de instalación de uv como el de activación del venv son distintos, y no se muestra ninguno de los dos 00:09:31, 00:10:33.
Paquetes core frente a paquetes de integración
La lista de seis paquetes a instalar no es arbitraria — refleja el modelo de empaquetado de LangChain 1.x, que es la razón por la que cambiar de proveedor sale barato.
| Paquete | Capa | Por qué está |
|---|---|---|
langchain | Framework | El paquete paraguas |
langchain-core | Framework | Abstracciones independientes del proveedor: Runnables, mensajes, prompts, Document |
langgraph | Framework | Orquestación con grafos / máquinas de estados |
langchain-openai | Integración | Incluye ChatOpenAI, OpenAIEmbeddings |
langchain-anthropic | Integración | Incluye ChatAnthropic |
python-dotenv | Utilidad | Carga .env en el entorno del proceso |
El core se mantiene neutral respecto al vendor; cada vendor vive en su propia distribución langchain-<vendor>. Por eso ChatOpenAI se importa de langchain_openai y ChatAnthropic de langchain_anthropic, y nunca de langchain. Cambiar de proveedor es un cambio de import más un string de modelo — que es exactamente la asimetría que la Parte 4 convertirá en regla: el modelo de generación es intercambiable, el embedding model no.
langgraph se instala el primer día aunque nada en esta guía lo use hasta la Parte 15. Es una señal deliberada: la orquestación basada en grafos se trata como parte del stack base y no como un añadido que acoplas cuando el pipeline se vuelve agéntico. Su versión se imprime en el smoke test junto a la de langchain-core.
Esos seis son el arranque. Al final de esta parte habrás añadido tres más: langchain-community (los loaders), pypdf (el parser de PDF que hay detrás de PyPDFLoader) y bs4 (BeautifulSoup, con el que WebBaseLoader parsea el HTML — está en los pins del repo pero nunca se instala delante de la cámara). El resto de production-course-main-code/pyproject.toml, que fija name = "langc-course" y requires-python = ">=3.12", es un índice de contenidos de la construcción:
| Paquete fijado | Llega en | Para |
|---|---|---|
langchain-community>=0.4.1 | esta parte | Loaders de documentos |
pypdf>=6.6.2 | esta parte | El parser de PyPDFLoader |
bs4>=0.0.2 | esta parte | El parseo de HTML de WebBaseLoader |
langchain-chroma>=1.1.0 | Parte 4 | El vector store |
rank-bm25>=0.2.2 | Parte 6 | La mitad léxica de la búsqueda híbrida |
langchain-ollama>=1.0.1 | Partes 9–10 | Modelos locales, cuando la factura importa |
langgraph-checkpoint-sqlite>=3.0.3 | Más adelante | Estado de agentes en LangGraph |
fastapi>=0.129.0, uvicorn>=0.40.0 | Parte 11 | Servir el pipeline |
pytest>=9.0.2 | Parte 13 | La batería de tests |
Secretos: .env, load_dotenv() y la regla de orden
Crea .env y pon en él las dos claves:
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...Después, en el código:
# production-course-main-code/main.py, lines 1-4
from dotenv import load_dotenv
from importlib.metadata import version
load_dotenv()
«Así que ahora todas las claves están disponibles para usarlas.» 00:11:34
Fíjate en lo que no se hace en ninguna parte del repo: las claves nunca se pasan como argumentos a ChatOpenAI(...) ni a ChatAnthropic(...). Los SDK de los proveedores leen OPENAI_API_KEY y ANTHROPIC_API_KEY directamente del entorno del proceso en el momento de construir el cliente.
La regla de higiene correspondiente nunca se dice en cámara, pero está escrita en el .gitignore del repo, que empieza precisamente por ella:
# Environment variables — NEVER commit these
.env
# Python
__pycache__/
*.pyc
*.pyo
.venv/
venv/
# IDE
.vscode/
.idea/
# OS
.DS_Store
Thumbs.db
.claude
chroma_db/Tres de esas entradas hacen un trabajo real más allá del orden. .env es la evidente. .venv/ mantiene fuera del historial unos cuantos cientos de megabytes de binarios específicos de la plataforma. chroma_db/ mantiene fuera de git un índice vectorial generado — y ese es un instinto de producción genuino: el índice son datos derivados, es grande, es específico de la máquina y tiene que poder reconstruirse a partir de los documentos fuente más el código. Si alguna vez te descubres queriendo hacer commit de un índice, lo que en realidad quieres es un script de ingesta reproducible.
Tu .env va a crecer. Las variables de tracing de LangSmith llegan en la Parte 7, las credenciales de Supabase/pgvector en la Parte 10 y los secretos de autenticación de la API en las Partes 11–12. Coge el hábito ahora.
El smoke test y su criterio de aceptación de cuatro líneas
Este es todo el entregable del capítulo de configuración — 32 líneas, literales del repo:
# 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()
En esas 32 líneas hay más enseñanza de la que sugiere su duración.
Una comprobación de versiones que funciona de verdad. La forma intuitiva 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 forma que funciona es la de la librería estándar:
from importlib.metadata import version
core_version = version("langchain-core") # hyphen: DISTRIBUTION name
lg_version = version("langgraph")
El instructor lo llama «solo un cambio menor» 00:13:38, pero la regla generalizable es real: pregunta a los metadatos del paquete por la versión de una distribución, no al módulo por un atributo __version__.
¿Para qué imprimir versiones? Porque en un ecosistema que se mueve tan rápido, el comportamiento cambia entre versiones mayores, y una guía escrita para 1.x no va a coincidir con lo que ve un lector en 2.x. El propio curso matiza sus cifras una y otra vez: describe langchain-core y langgraph solo como «por encima de 1.0» y sitúa la versión estable 1.0 un par de meses antes de la grabación 00:14:38. Las versiones realmente fijadas en el repo son langchain-core 1.2.7 y langgraph 1.0.7. Trata las versiones impresas como una instantánea que registras, no como un objetivo al que fijarte.
«Claro que, para cuando estés viendo este vídeo, esto podría ser distinto.» 00:14:38
.predict() está muerto. El instructor se corrige a mitad de frase mientras escribe la llamada a OpenAI 00:12:37: .predict() es la API heredada, anterior a LCEL, de string de entrada y string de salida. La interfaz Runnable de LangChain 1.x es .invoke(), con .batch(), .stream() y variantes async junto a ella. Todas las llamadas a modelos del resto de esta guía — y todas las chains de la composición LCEL de la Parte 1 — son .invoke().
.invoke() devuelve un objeto mensaje, no un string. El script imprime la respuesta entera, lo que vuelca un repr al estilo de AIMessage: el texto más el uso de tokens, el id del modelo y el motivo de parada. El texto en sí está en .content, como señala el instructor en pantalla 00:14:38. Esto hace tropezar a cualquiera que espere un str, y volverá a importar en la chain de la Parte 1, donde StrOutputParser() existe precisamente para desenvolverlo.
Higiene del smoke test. El prompt — "Say 'setup complete!' in one word" — es deliberadamente trivial e idéntico byte a byte en ambos proveedores. Lo importante no es la respuesta; es que el viaje de ida y vuelta funciona: se encuentra la clave, la red responde, el id del modelo es válido y la respuesta se parsea. Mantener el prompt idéntico significa que cualquier diferencia en el resultado es una diferencia del proveedor, no del prompt.
Valores por defecto de coste y determinismo. Se elige gpt-4o-mini explícitamente para que la comprobación sea barata 00:12:37 — la primera aparición en el curso de la preocupación por el coste, un tema que vuelve con fuerza en las Partes 8 y 9. Los dos clientes usan temperature=0, que es el valor por defecto sensato para un script de verificación y, como defenderá la Parte 5, para la generación RAG anclada en las fuentes en general.
Cuatro cosas más sobre este fichero que el audio nunca menciona:
- Los imports de las líneas 8–9 están después de sentencias ejecutables en las líneas 6–7. Estilísticamente
es feo; en la práctica, significa que si falta langchain-anthropic el fallo llega después de que se haya impreso el banner de versiones, lo que parece un problema de versiones y no lo es.
- Los prints de versiones están a nivel de módulo, no dentro de
main(). Se ejecutan al importar, así que cualquier
otro módulo que importe main recibe el banner como efecto secundario.
- No hay ninguna guarda con
os.getenv. El script requiere las dos claves y te devuelve un error de autenticación
en bruto del SDK si falta cualquiera de ellas. Una configuración con un solo proveedor falla el smoke test de una forma que no dice «te falta una clave».
- El id del modelo de Anthropic lleva fecha (
claude-sonnet-4-5-20250929) y en algún momento será
retirado. Cuenta con tener que actualizarlo; un 404 con ese string es un evento del ciclo de vida del modelo, no un bug de tu configuración.
Ejecútalo:
uv run main.py
El test de aceptación. Tu entorno está listo cuando una ejecución de
main.pyimprime cuatro cosas: dos strings de versión, una respuesta de OpenAI sin error, una respuesta de Anthropic sin error y la línea finalSetup complete!. Con menos que eso no has terminado, por muy bien que parezca el código.
Por qué existe una capa de loaders
Con un entorno que funciona, el pipeline puede arrancar. La primera etapa es la carga, y su justificación cabe en una frase: un LLM solo sabe lo que pones en su context window, y ese contexto tiene que salir de alguna parte 00:15:35.
«Los grandes modelos de lenguaje necesitan contexto, y el contexto sale de los datos, de los documentos, etcétera.» 00:15:35
La categoría de entrada son los ficheros en bruto: PDF, TXT, HTML, DOCX, CSV y cualquier otra cosa que tengas por ahí 00:15:35 — cinco formatos con nombre que no tienen nada en común. Cinco parsers, cinco APIs, cinco formas de error, cinco convenciones de metadatos. Todo el trabajo de la capa de loaders es reducir esa heterogeneidad a una sola forma, para que cada etapa posterior — splitters, embedders, vector stores, retrievers — solo tenga que hablar un único tipo.
El segundo punto va de construir frente a comprar. LangChain ya trae los wrappers, así que no deberías estar escribiendo a mano parsers de PDF. Pero fíjate en lo que significa literalmente «envolver»: LangChain proporciona la interfaz uniforme y delega el parseo real en una librería de terceros que no instala por ti. Ese único hecho explica los dos fallos en directo de este capítulo, y es la razón de que exista la sección de más abajo sobre dependencias ausentes.
El objeto Document
Todos los loaders devuelven una lista de objetos Document, y todo Document tiene exactamente dos partes:
| Campo | Tipo | Contenido |
|---|---|---|
page_content | str | El texto extraído |
metadata | dict | Procedencia que adjunta el loader: source, número de página, autor, fecha de creación, … |
Ese es todo el contrato. También es la vía de escape — un Document no es más que una clase de datos, así que puedes construir uno tú mismo con los metadatos que quieras:
# 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}")
Se importa desde core, no desde community: from langchain_core.documents import Document.
Fíjate en "tags": ["sample", "test"] — para LangChain, el diccionario de metadatos admite claves arbitrarias y valores no escalares. Que tu vector store los acepte es otra cuestión, y la mayoría no lo hace: Chroma, que es lo que usa la Parte 4, solo almacena valores de metadatos escalares, así que aplana las listas a un string con delimitadores o a un conjunto de flags booleanos antes de indexar. Esta vía de construcción a mano es exactamente a la que recurre la Parte 5 cuando un loader no te puede dar los campos que necesitas.
El patrón universal de dos líneas
Todos los loaders de LangChain tienen la misma forma, y esa uniformidad es la razón de que merezca la pena aprender la abstracción:
loader = SomeLoader(source) # 1. instantiate with the source
docs = loader.load() # 2. call .load() → list[Document]
Eso es todo. La ruta, la URL o el directorio van en el constructor; .load() devuelve documentos 00:17:37. La uniformidad tampoco es una convención — la impone la clase base. langchain_core.document_loaders.BaseLoader.load() es literalmente return list(self.lazy_load()), y a las subclases se les indica que implementen lazy_load() y dejen load() en paz. Todos los loaders que te encuentres serán, por tanto, un generador más un materializador de una línea.
Este es el catálogo tal como lo presenta el curso:
| Loader | Origen | Notas |
|---|---|---|
TextLoader | Una ruta a un .txt | El caso más simple posible; 1 fichero → 1 Document |
PyPDFLoader | Una ruta a un PDF | 1 página → 1 Document |
DirectoryLoader | Una ruta a una carpeta | Un dispatcher: recibe glob + loader_cls |
WebBaseLoader | Una URL o varias | Descarga el HTML y extrae su contenido |
UnstructuredLoader | Formatos complejos / mixtos | La vía de escape (MD, TXT y otros) |
El propio texto en pantalla del PDF de la demo nombra tres más de los que el audio nunca habla — CSVLoader (documentos por filas), JSONLoader (extracción al estilo jq) y YouTubeLoader (transcripciones). Existen; simplemente quedan fuera del alcance del curso, y el patrón de dos líneas se les aplica sin cambios.
Práctica 1: TextLoader y la primera dependencia ausente
La programación en directo del capítulo ocurre en un fichero dedicado, document_loaders.py. El primer import falla:
uv add langchain-community
Los loaders de documentos viven en langchain-community, no en langchain-core. El instructor justifica la instalación diciendo que el paquete community es donde viven los text splitters 00:21:44 — esa razón es errónea y no hay que propagarla. Los text splitters vienen en langchain-text-splitters (fijado por separado en el repo, en la 1.1.0). La acción es correcta; la causa que se da, no. Lo que langchain_community te aporta realmente aquí es langchain_community.document_loaders.
Los imports del fichero:
# 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 este módulo imprime un aviso antes de ejecutar una sola línea de tu código: USER_AGENT environment variable not set, consider setting it to identify your requests. Viene de langchain_community.utils.user_agent, y merece la pena entenderlo en lugar de silenciarlo, porque es una trampa de orden exactamente de la misma especie que load_dotenv(). web_base.py construye su default_header_template en tiempo de import, así que la variable de entorno ya tiene que estar fijada cuando se ejecuta la línea 5 — y aquí load_dotenv() está en la línea 15. Poner USER_AGENT en el .env no sirve, por tanto, de nada para este fichero; obtienes DefaultLangchainUserAgent en cada request, y algunos sitios lo rechazan directamente. Expórtala en el shell (o fija os.environ["USER_AGENT"] por encima de los imports de los loaders), o pasa un header_template= explícito al loader y deja de depender de la variable global.
Y la primera demo:
# 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 bloque comentado del final no es código muerto — es la primera pasada, conservada. La versión inicial del instructor imprimía el objeto Document entero para que vieras su forma, y después la sustituyó por tres datos concretos: len(documents), una vista previa de 100 caracteres del contenido y el diccionario de metadatos 00:24:50. Merece la pena hacer las dos cosas, en ese orden: vuelca el objeto una vez para conocer el tipo y después extrae los campos que realmente te importan.
Resultado: un fichero de texto → exactamente un Document 00:24:50, y sus metadatos tienen exactamente una clave:
{'source': '/tmp/tmpop0y38v3.txt'}
Eso es todo lo que adjunta TextLoader — su implementación termina con metadata = {"source": str(self.file_path)} y produce un único Document. El instructor también lee en su pantalla una marca de tiempo de creación 00:23:48; el langchain-community 0.4.1 fijado no la produce, así que no diseñes contando con ella. La lección se generaliza: imprime una vez el diccionario de metadatos, con tu propia versión, antes de construir nada encima.
Dos cosas menores: NamedTemporaryFile(delete=False) deja de verdad el fichero huérfano, y por eso existe el finally: os.remove(...) y no es opcional. Y la longitud de la vista previa es [:100] — el «los primeros 1,00 o 100 caracteres» de la transcripción 00:24:50 es un lapsus; el código manda.
Práctica 2: PyPDFLoader y el comportamiento que rompe el código ingenuo
Las mismas dos líneas, otro loader — y esa uniformidad es la lección 00:25:52. Pero antes, la segunda dependencia ausente:
uv add pypdf
LangChain envuelve pypdf; no lo incluye. Cuenta con el mismo patrón para cualquier otro loader que se apoye en un parser (pymupdf para PyMuPDFLoader, unstructured para la familia Unstructured). En esta capa, que falten dependencias de parsers es la norma, no la excepción.
# 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}")
Se llama como pdf_loader("./docs/langchain_demo.pdf") — el punto de entrada activo del repo, con las otras cuatro demos comentadas. El fixture es un PDF autogenerado de 3 páginas y 4.5 KB cuyo propio texto resulta que enumera el catálogo de loaders y cinco buenas prácticas; la Parte 3 lo reutilizará, porque la página 2 contiene el pangrama «The quick brown fox jumps over the lazy dog» como datos de prueba de chunking.
Los metadatos los rellena automáticamente el parser. Ejecutar el código del repo sobre el PDF de la demo da exactamente esto para 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',
}
Siete campos, tres de ellos trampas.
El fixture es cómplice en silencio. El propio ejemplo práctico del PDF de la demo, impreso en su página 1, formatea una cita como print(f"Page: {doc.metadata['page']}") — el campo que empieza en 0. El código de ejemplo que lees mientras aprendes la API ya trae el bug dentro.
El propio bucle del repo lo repite de otra forma: imprime Document {i+1} a partir de enumerate, lo que produce un contador amigable que empieza en 1 y que no tiene ninguna relación con la clave page que aparece justo al lado en la misma salida. Si copias ese bucle, no uses el número impreso como cita.
source es el string que tecleaste, no una ruta. El diccionario de arriba dice './docs/langchain_demo.pdf' porque ese es el argumento literal que pasó el punto de entrada. No se resuelve, no se convierte en absoluto y no se normaliza. Dos scripts de ingesta que escriben el mismo fichero de forma distinta producen dos strings de cita distintos, dos valores distintos para los filtros de metadatos y ninguna forma de deduplicar. Normaliza una vez en la ingesta — str(Path(p).resolve()) — y hazlo antes del primer embedding, porque la Parte 4 mostrará que solo puedes filtrar por lo que fijaste en tiempo de indexación.
producer y creator no son procedencia. Aquí los dos dicen PyPDF por una razón prosaica: el instructor generó el PDF de la demo con pypdf, así que la librería que escribió el fichero y la que lo leyó son la misma. Estos campos describen herramientas, no autoría. No se los muestres a los usuarios como «el creador del documento» ni construyas filtros sobre ellos esperando una señal con sentido 00:27:57.
Los metadatos dependen del parser, no son la verdad. Te dicen lo que vio el pipeline, que es justo lo que quieres para depurar — y justo lo que no debes confundir con lo que el documento es.
Elegir un loader de PDF
Los PDF son donde la elección del loader importa de verdad, porque el PDF es un formato de maquetación que se hace pasar por formato de documento. El curso ofrece una comparación a tres bandas 00:18:41:
| Loader | Velocidad | Metadatos | Ideal para |
|---|---|---|---|
PyPDFLoader | Rápido | Básicos | PDF sencillos. Empieza por aquí. |
PyMuPDFLoader | El más rápido | Buenos | Gran volumen; la opción todoterreno del instructor |
UnstructuredPDFLoader | El más lento | Los más ricos / detallados | Tablas y maquetaciones complejas |
La verdadera lección es la forma de esa curva: compras fidelidad con latencia, y eliges un punto para cada caso de uso, no uno para siempre.
«Si tienes documentos con tablas y maquetaciones,
UnstructuredPDFLoaderva a ser tu mejor opción.» 00:19:41
El curso empieza con PyPDFLoader deliberadamente, y lo dice:
«Según tu caso de uso, puedes cambiar a otra cosa.» 00:19:41
Una advertencia que el curso no hace pero la Parte 16 sí: ninguno de estos tres loaders resuelve las tablas y los gráficos; solo se degradan algo menos. UnstructuredPDFLoader te da más estructura con la que trabajar; un gráfico sigue quedando destrozado por la extracción de texto. La respuesta basada en visión es el retrieval multimodal, y es otra arquitectura, no otro loader.
Carga desde la web
WebBaseLoader recibe una URL, o varias a la vez. La versión ejecutable del repo nunca se ejecutó en cámara:
# 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 mostraba tres páginas de example.com y el instructor dejó caer, sin comprometerse, que se descargan en paralelo 00:19:41. Leer el loader publicado lo zanja, y la respuesta es un detalle de producción genuino:
Carga de directorios, glob y lazy_load()
DirectoryLoader no es realmente un loader, es un dispatcher. Recibe tres parámetros 00:20:41:
- la ruta — la carpeta que recorrer;
- el glob — qué ficheros casar, incluida la profundidad de la recursión (
**/*.pdfpara todos los PDF
de todos los subdirectorios);
loader_cls— qué clase de loader parsea cada fichero que casa.
«Esto es lo que llamamos patrón glob — filtra ficheros.» 00:20:41
La versión del repo lo combina con la otra cosa que el audio nunca menciona: 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"])
Cinco ficheros, una vista previa de 50 caracteres de cada uno. La línea importante es loader.lazy_load():
| Método | Devuelve | Memoria | Úsalo cuando |
|---|---|---|---|
.load() | list[Document] — todo, materializado | O(corpus) | Conjuntos pequeños y conocidos; necesitas len() o acceso aleatorio |
.lazy_load() | Un generador, un Document cada vez | O(1) por documento | Ingestas grandes; estás enviando el flujo directamente a un splitter/embedder |
Como el bucle de arriba descarta cada doc después de imprimirlo, no se acumula nada en RAM. Esa es la propiedad que hay que vender: en una ingesta de 50,000 documentos, .load() construye el corpus entero en memoria antes de que se genere el embedding del primer chunk; .lazy_load() te permite encadenar carga → splitting → embedding → almacenamiento documento a documento. La propia página de «Best Practices» del PDF de la demo dice lo mismo: «Para conjuntos grandes de documentos, usa lazy_load() en lugar de load().»
Un ajuste más que conviene conocer antes de tu primer directorio grande: use_multithreading=False por defecto, con max_concurrency=4 cuando lo activas. En la mayoría de las ingestas el cuello de botella es el parseo, así que esta suele ser la aceleración más barata disponible — y, como cualquier interruptor de concurrencia, la forma más rápida de convertir una suposición sobre el orden en un bug.
Los metadatos son el sustrato de las citas
Esta es la parte de la capa de loaders que más tarda en dar fruto y la que más importa. El PDF de la demo lo explica en su propia página 2, lo cual es una casualidad simpática:
«Los loaders conservan metadatos como números de página, rutas de fichero y fuentes. Usa esta información para las citas.»
La cadena es: el loader adjunta metadatos → el splitter los propaga → el vector store los persiste → el retriever los devuelve → el formateador los muestra como [n] source dentro del string de contexto que lee el modelo. La Parte 1 estableció que las fuentes viajan dentro del contexto, no por un canal aparte; la Parte 3 mostrará que split_documents() propaga los metadatos del documento padre mientras que split_text() los destruye; la Parte 4 mostrará que solo puedes filtrar por los metadatos que fijaste en tiempo de indexación.
Eso te deja una regla con una consecuencia incómoda:
Y un hábito que conviene adoptar de inmediato, a coste cero:
Imprime
doc.metadata['source']junto a cada resultado recuperado, en todos los scripts de depuración que escribas a partir de ahora. Cuesta una línea y es lo que hace posible la depuración de la Parte 5.
Dónde se queda corta la fuente
Tres cosas que esta parte hereda del curso como lagunas y no como respuestas, dichas sin rodeos:
PyMuPDFLoaderse recomienda como opción todoterreno y nunca se usa. Ningún fichero de ninguno de los dos repos
lo importa. El veredicto de «el mejor en todos los frentes» 00:18:41 es el criterio del instructor, no una medición mostrada en pantalla.
UnstructuredLoader/UnstructuredPDFLoaderse describen pero nunca se instalan ni se ejecutan.
La cadena de dependencias de unstructured es pesada — librerías del sistema para OCR y formatos ofimáticos — y nada de ese coste de configuración aparece en el curso. Además, para no ayudar, es el loader_cls por defecto de DirectoryLoader.
WebBaseLoaderyDirectoryLoaderson diapositivas más código del repo que nunca se ejecutó. Nadie
los vio funcionar. El bs_kwargs que no hace nada, de más arriba, es el tipo de defecto que sobrevive cuando el código se escribe pero nunca se muestra en una demo; la cuestión de la descarga secuencial frente a la async hubo que zanjarla leyendo la librería, no el curso.
Nada de eso invalida la capa. Sí significa que, cuando recurras a algo más allá de TextLoader y PyPDFLoader, habrás pasado el punto que la fuente verificó, y deberías verificarlo tú — con un len(documents) y un volcado de metadatos, que es exactamente el ritual de inspección que enseña este capítulo.
Checklist
Entorno:
- Clave de OpenAI generada en Settings → API keys, vinculada a un proyecto; secreto copiado en el momento
de crearla en tu gestor de contraseñas.
- Clave de Anthropic generada en platform.claude.com → Manage → API keys, vinculada a un
workspace; secreto copiado en el momento de crearla.
uv init+uv venv+source .venv/bin/activateen un directorio limpio.- `uv add langchain langchain-core langgraph langchain-openai langchain-anthropic
python-dotenv` — seis paquetes, un comando.
.envcreado conOPENAI_API_KEYyANTHROPIC_API_KEY;.envpresente en
.gitignore junto a .venv/, __pycache__/ y chroma_db/. (USER_AGENT va en el entorno del shell, no en .env — se lee en tiempo de import.)
load_dotenv()es la primera sentencia ejecutable de cada punto de entrada, antes de construir
ningún cliente.
- Versiones leídas con
importlib.metadata.version("langchain-core"), nunca
from langchain_core import __version__.
uv run main.pyimprime cuatro cosas: dos versiones, una respuesta de OpenAI, una respuesta
de Anthropic y Setup complete!.
- Todas las llamadas a modelos usan
.invoke(); sabes que lo que se devuelve es un objeto mensaje y que el texto está en
.content.
- Has estandarizado en
model=(sin depender nunca del valor por defecto de la clase) y entemperature=0
para todo lo que quieras que sea reproducible.
Carga:
uv add langchain-community(loaders),uv add pypdf(parseo de PDF),uv add bs4
(WebBaseLoader) — cuenta con que falte un parser por cada formato nuevo.
- La instanciación de loaders vive en una única función factoría, de modo que un cambio es una línea.
- Cada ingesta imprime
len(documents)ydocuments[0].metadataal menos una vez, con tu
propia versión instalada, antes de que te fíes de ella.
- Ningún camino del código hace
documents[0]sobre la carga de un PDF. - Las citas muestran
page_label; los filtros usanpage. sourcese normaliza una vez en la ingesta (str(Path(p).resolve())o un id de negocio estable) —
nunca un nombre de tempfile en bruto ni el string literal que haya tecleado quien llama.
DirectoryLoaderrecibe siempre unloader_clsexplícito, unrecursiveexplícito y, o bien
autodetect_encoding, o bien silent_errors más un recuento de omitidos que de verdad registras en el log.
- Todo lo que depende del orden de los documentos ordena las rutas por su cuenta en lugar de fiarse de
lazy_load().
- Las ingestas grandes usan
.lazy_load(); las ingestas web de varias URLs usan.alazy_load()y fijan
requests_per_second, continue_on_failure y raise_for_status deliberadamente.
Decisiones que tomar
| Decisión | Por defecto | Cámbiala cuando |
|---|---|---|
| Gestor de paquetes | uv, en exclusiva | Nunca, dentro de esta guía |
| Versión mínima de Python | >=3.12 (repo principal); >=3.13 para el material de las Partes 14–16 | Tu entorno de deploy te obliga a una más antigua — entonces revisa todos los pins |
| Proveedores | OpenAI + Anthropic | Dos cualesquiera a los que puedas llamar de verdad; el código es independiente del proveedor por construcción |
| Modelo del smoke test | gpt-4o-mini, temperature=0 | No uses nunca un modelo frontera para comprobaciones de fontanería |
| Loader de PDF | PyPDFLoader | Gran volumen → PyMuPDFLoader; tablas/maquetación → UnstructuredPDFLoader |
load() frente a lazy_load() | load() mientras el corpus sea pequeño | El corpus deja de caber holgadamente en RAM |
| Schema de metadatos | source (normalizado) + page/page_label + todo aquello por lo que vayas a filtrar | Decídelo antes de la primera ingesta — cambiarlo significa hacer re-embed de todo |
Siguiente: los documentos que acabas de cargar siguen siendo documentos completos, y los documentos completos no son lo que indexas. La Parte 3 los divide — y muestra el A/B medido en el que el chunker teóricamente mejor pierde 1–4.