Document Loaders

En LangChain, un Document es una estructura que representa una unidad de información compuesta por dos elementos: el contenido del texto (page_content) y un conjunto de metadatos (metadata) que aportan contexto adicional, como el origen, identificadores o fechas.

Este formato estandarizado permite trabajar de manera uniforme con distintos tipos de datos, ya provengan de archivos, páginas web, bases de datos o otras aplicaciones. Para obtener estos documentos desde fuentes reales, LangChain utiliza los llamados Document Loaders, que son componentes diseñados para cargar información desde múltiples orígenes y convertirla automáticamente en objetos Document que posteriormente serán utilizados en pipelines de Retrieval-Augmented Generation (RAG).

BaseLoader

Antes de trabajar con loaders concretos, es importante entender que todos ellos heredan de una clase base común: BaseLoader. Esta clase define el comportamiento estándar que deben seguir todos los loaders dentro del ecosistema de LangChain.

BaseLoader no es un loader que se utilice directamente, sino una interfaz (clase abstracta) que establece cómo deben implementarse los métodos de carga de documentos. El propósito principal de BaseLoader es garantizar que todos los loaders:

• Devuelvan datos en formato Document
• Sigan un patrón consistente
• Sean intercambiables dentro del pipeline

BaseLoader → <Name>Loader

BaseLoader → <Name>Loader

Ejemplos:

• TextLoader
• PyPDFLoader
• WebBaseLoader

Su salida siempre es una colección de objetos:

• Document.page_content → contenido textual
• Document.metadata → información contextual

Este diseño permite que cualquier loader sea intercambiable dentro del pipeline. De esta forma, los datos externos se integran fácilmente en los flujos de trabajo con modelos de lenguaje, siendo la base para aplicaciones más avanzadas como sistemas de recuperación de información (RAG), análisis de datos o asistentes inteligentes.

Lazy loading

El diseño de BaseLoader está orientado a evitar cargar todos los documentos en memoria de golpe. Por eso, el método fundamental que deben implementar los loaders es: lazy_load()

Métodos de BaseLoader

Loaders

En cualquier sistema RAG, el punto de partida es siempre el mismo: los datos. Antes de hablar de embeddings, retrieval o generación de respuestas, es necesario convertir las fuentes de información en un formato que el sistema pueda procesar. En este contexto, los documentos PDF representan uno de los formatos más habituales en entornos empresariales.

En el ecosistema de LangChain, los loaders forman parte de la capa de ingestión de datos. Su función no es solo “leer archivos”, sino preparar la información para que pueda ser utilizada posteriormente en procesos de segmentación, embedding y recuperación.

Unstructured’s Loaders

Los loaders denominados Unstructured dentro del ecosistema de LangChain son herramientas especializadas que permiten mejorar significativamente la extracción. Este tipo de loader no se limita a leer el texto plano, sino que intenta interpretar la estructura del documento. El resultado es un contenido más limpio, menos fragmentado y semánticamente más consistente, lo que impacta directamente en la calidad de los embeddings y en la eficacia del sistema RAG.

Ventajas principales:

• Mejor interpretación del layout: Este loader intenta entender la estructura del documento, no solo extraer texto plano. Esto permite preservar mejor párrafos, títulos y bloques de contenido.
• Menor fragmentación del texto: Reduce significativamente los problemas de palabras separadas o saltos de línea artificiales.
• Mayor calidad semántica: Al generar texto más coherente, los embeddings resultantes son más representativos, lo que mejora la recuperación en RAG.
• Preparado para documentos reales:  Está diseñado para trabajar con documentos del mundo empresarial: informes, contratos, manuales, etc.

Consideraciones

• Mayor coste computacional
• Puede requerir dependencias adicionales
• No siempre necesario para documentos simples

Modo de operación

Los loaders Unstructured suelen trabajar en dos modos:

• single: Devuelve todo el documento como un único Document.
• elements (recomendado): Divide el contenido en elementos estructurados:
  • Title
  • NarrativeText
  • ListItem
  • Table

loader = UnstructuredPDFLoader("file.pdf", mode="single" | "elements")

loader = UnstructuredPDFLoader("file.pdf", mode="single" | "elements")

Loaders de archivos locales

Sintaxis general para los loaders de ficheros locales

Se cumple en el 90% de loaders de archivos locales, debes ver la documentación al utilizarlo.

loader = Loader(ruta_o_fuente)
documents = loader.load()

loader = Loader(ruta_o_fuente)
documents = loader.load()

Ejemplo conceptual:

from langchain_community.document_loaders import <Loader>
loader = <Loader>("ruta/al/archivo")
documents = loader.load()

from langchain_community.document_loaders import <Loader>

loader = <Loader>("ruta/al/archivo")
documents = loader.load()

En el momento de utilizarlos debes consultar la documentación de los parámetros adicionales en cada caso. Ejemplo para extracción de datos en un DataFrame de Pandas.

from langchain_community.document_loaders import DataFrameLoader
loader = DataFrameLoader(df, page_content_column="text")
documents = loader.load()

from langchain_community.document_loaders import DataFrameLoader

loader = DataFrameLoader(df, page_content_column="text")
documents = loader.load()

Web Loaders

Los Web Loaders permiten incorporar información directamente desde internet a un sistema RAG. Esto incluye páginas web, blogs, documentación técnica o cualquier contenido accesible mediante una URL.

A diferencia de los loaders de archivos locales, aquí no trabajas con un documento estático, sino con contenido dinámico, estructurado en HTML y, en muchos casos, generado parcialmente mediante JavaScript. Para cada caso debes seleccionar el tipo correcto diferenciado en cómo acceden y procesan el contenido:

• Loaders básicos → funcionan bien con páginas estáticas
• Loaders con renderizado JS → necesarios para webs modernas
• Crawlers → permiten recorrer múltiples páginas automáticamente

Problemas específicos del contenido web:

• Ruido HTML: El contenido incluye elementos que no aportan valor:
  • menús de navegación
  • banners de cookies
  • footers
  • enlaces secundarios

• Contenido dinámico: Muchas webs modernas no cargan todo el contenido directamente en el HTML, sino que lo generan mediante JavaScript. El resultado es:
  • loaders básicos no ven el contenido
  • necesitas loaders con renderizado (Playwright, Selenium)

• Riesgos de seguridad (SSRF): Los loaders tipo crawler pueden acceder a múltiples URLs automáticamente. Esto conlleva riesgos como:
  • acceso a recursos internos
  • carga de URLs maliciosas
  • problemas de seguridad en producción

Buenas prácticas para trabajar correctamente con Web Loaders en RAG:

• No indexar páginas completas sin filtrar
• Validar siempre el contenido extraído
• Aplicar limpieza antes del chunking
• Usar renderizado JS cuando sea necesario
• Limitar el uso de crawlers a dominios controlados

Aquí tienes la sección completa de Loaders de bases de datos, lista para integrar en tu unidad:

Loaders de bases de datos

Los loaders de bases de datos permiten integrar datos estructurados directamente en un sistema RAG. A diferencia de los documentos tradicionales (PDF, web), aquí la información proviene de tablas, donde cada fila representa una unidad lógica de datos, o sea cada fila → un Document. Esto convierte datos estructurados en texto procesable por el modelo.

Sintaxis:

loader = Loader(conexion, query=...)
documents = loader.load()

loader = Loader(conexion, query=...)
documents = loader.load()

from langchain_community.document_loaders import SQLDatabaseLoader
from langchain_community.utilities import SQLDatabase
db = SQLDatabase.from_uri("sqlite:///mi_base.db")
loader = SQLDatabaseLoader(db, query="SELECT * FROM reservas")
documents = loader.load()

from langchain_community.document_loaders import SQLDatabaseLoader
from langchain_community.utilities import SQLDatabase

db = SQLDatabase.from_uri("sqlite:///mi_base.db")

loader = SQLDatabaseLoader(db, query="SELECT * FROM reservas")
documents = loader.load()

Buenas prácticas (nivel pro)

• Convertir datos a texto limpio
• No hacer SELECT * en producción
• Limitar resultados (LIMIT)
• Elegir columnas relevantes

Loaders de sistemas empresariales (SaaS)

Los loaders de sistemas empresariales permiten integrar información directamente desde herramientas utilizadas en entornos corporativos. En lugar de trabajar con archivos locales o bases de datos, estos loaders acceden a plataformas como sistemas de documentación, almacenamiento en la nube o herramientas de colaboración. A diferencia de otros loaders, aquí necesitas acceso a sistemas externos.

• API tokens
• OAuth
• credenciales de usuario
• cookies de sesión

Ejemplo básico (Notion)

from langchain_community.document_loaders import NotionDBLoader
loader = NotionDBLoader(
    integration_token="your_token",
    database_id="your_database_id"
)
documents = loader.load()

from langchain_community.document_loaders import NotionDBLoader

loader = NotionDBLoader(
    integration_token="your_token",
    database_id="your_database_id"
)

documents = loader.load()

Consideraciones importantes

• Calidad del contenido: estos sistemas suelen contener texto desordenado, duplicados y mensajes irrelevantes por lo que es necesaria una limpieza posterior
• El volumen de datos puede ser muy alto: miles de mensajes, documentos largos y múltiples fuentes. En este caso el filtrado es importante.
• Privacidad y seguridad: Dado que trabajas con datos sensibles como información interna, conversaciones privadas y documentos confidenciales, es fundamental controlar accesos.

Buenas prácticas

• Filtrar por fechas o relevancia
• Usar metadata (autor, canal, fecha)
• Limpiar antes de embeddings
• Limitar el scope de datos

Loaders de repositorios y código

Los loaders de repositorios permiten trabajar con código fuente y artefactos asociados (issues, documentación) dentro de un sistema RAG. Son especialmente útiles para construir asistentes técnicos, copilots o sistemas de búsqueda sobre bases de código.

Estos loaders extraen archivos de repositorios locales o remotos y los convierten en objetos Document, manteniendo información relevante como rutas de archivo, nombres o metadatos del repositorio.

Características clave

• Cada archivo → un Document
• Cada issue → un Document
• Metadata incluye ruta, repositorio, contexto técnico

Ejemplo básico (GitLoader)

from langchain_community.document_loaders import GitLoader
loader = GitLoader(
    repo_path="./mi_repo",
    branch="main"
)
documents = loader.load()

from langchain_community.document_loaders import GitLoader

loader = GitLoader(
    repo_path="./mi_repo",
    branch="main"
)

documents = loader.load()

Consideraciones importantes

• Código ≠ texto normal: El código tiene estructura lógica (funciones, clases, sintaxis) por lo que requiere chunking específico y cuidado en embeddings
• Ruido en repositorios: archivos irrelevantes (.gitignore, configs…), dependencias y código duplicado. Es importante filtrar archivos.
• Contexto técnico: El valor no está solo en el texto, sino en la estructura del proyecto, la relación entre archivos y el contexto de uso

Buenas prácticas

• Filtrar extensiones (.py, .js, .md)
• Excluir carpetas innecesarias (node_modules, .git)
• Usar metadata (ruta del archivo)
• Adaptar el chunking al código

Loaders de contenido multimedia (audio, imagen, vídeo)

Los loaders de contenido multimedia permiten incorporar a un sistema RAG información que originalmente no está en formato de texto, como audio, imágenes o vídeos. Dado que los modelos de lenguaje trabajan con texto, estos loaders realizan una transformación previa: convierten contenido multimedia en texto procesable. Esto se consigue mediante tecnologías como:

• transcripción de audio (speech-to-text)
• OCR (reconocimiento de texto en imágenes)
• generación automática de descripciones

Tipos de transformación

• Audio → texto: Convierte voz en texto como llamadas, podcast o reuniones.
• Imagen → texto: En esta caso hay dos enfoques:
  • OCR → extrae texto real
  • Captioning → describe la imagen
• Vídeo → texto: generalmente mediante: transcripción del audio o subtítulos

Ejemplo básico (YouTube)

from langchain_community.document_loaders import YoutubeLoader
loader = YoutubeLoader.from_youtube_url(
    "https://www.youtube.com/watch?v=XXXX",
    add_video_info=True
)
documents = loader.load()

from langchain_community.document_loaders import YoutubeLoader

loader = YoutubeLoader.from_youtube_url(
    "https://www.youtube.com/watch?v=XXXX",
    add_video_info=True
)

documents = loader.load()

Ejemplo básico (audio)

from langchain_community.document_loaders import AssemblyAIAudioTranscriptLoader
loader = AssemblyAIAudioTranscriptLoader(
    file_path="audio.mp3"
)
documents = loader.load()

from langchain_community.document_loaders import AssemblyAIAudioTranscriptLoader

loader = AssemblyAIAudioTranscriptLoader(
    file_path="audio.mp3"
)

documents = loader.load()

Consideraciones importantes

• Calidad del texto generado: La calidad depende del modelo de conversión ya que puede haber errores en transcripción, ruido en audio o OCR imperfecto lo que impacta directamente en embeddings.
• Coste y latencia: Estos procesos suelen ser más lentos y más costosos debido a APIs externas.
• Contexto limitado: El texto generado puede perder matices, simplificar contenido y omitir información visual.

Buenas prácticas

• Revisar la calidad de la transcripción
• Limpiar el texto antes de embeddings
• Añadir metadata (fuente, timestamp, tipo)
• Dividir correctamente en chunks

Aquí tienes la sección completa, alineada con el resto de tu unidad:

Loaders de datos públicos y fuentes externas

Los loaders de datos públicos permiten integrar información procedente de fuentes abiertas como enciclopedias, repositorios científicos o plataformas de contenido online. A diferencia de los loaders empresariales, aquí se trabaja con datos accesibles públicamente, lo que facilita la experimentación y el desarrollo de prototipos.

from langchain_community.document_loaders import WikipediaLoader
loader = WikipediaLoader(query="LangChain", load_max_docs=2)
documents = loader.load()

from langchain_community.document_loaders import WikipediaLoader

loader = WikipediaLoader(query="LangChain", load_max_docs=2)
documents = loader.load()

Consideraciones importantes

• Calidad variable del contenido: dependiendo de la fuente, el contenido puede ser generalista, informal o altamente técnico.
• Ruido y relevancia: No todo lo que se carga es útil se puede cargar comentarios irrelevantes, contenido duplicado o información no estructurada
• Dependencia externa: APIs , límites de uso y disponibilidad del servicio

Buenas prácticas

• Limitar número de documentos (load_max_docs)
• Filtrar por relevancia
• Limpiar contenido antes de embeddings
• Usar metadata para contexto (fuente, fecha, autor)

Loaders empresariales avanzados

Los loaders empresariales avanzados permiten integrar sistemas especializados que forman parte del stack tecnológico de una empresa. A diferencia de los loaders SaaS más generales (como Notion o Slack), estos se centran en herramientas específicas de negocio, como CRM, analítica, diseño o procesamiento de datos.

Para utilizar Airbyte<Name>Loader, se necesita instalar el paquete airbyte-cdk que es el Connector Development Kit (CDK) de Airbyte. Una librería de Python diseñada para construir conectores (sources) de datos de forma estandarizada.

airbyte-cdk es una herramienta de bajo nivel para crear conectores de datos robustos y escalables. Dentro de un sistema RAG, su papel no es directo, sino que actúa como capa intermedia que permite integrar fuentes externas complejas de forma estandarizada.

Si estás construyendo sistemas avanzados o integraciones personalizadas, es una pieza clave. Si estás consumiendo datos con loaders ya existentes, probablemente ni siquiera necesites interactuar con él directamente.

Ejemplo: cargar datos de HubSpot en RAG

from langchain_community.document_loaders import AirbyteHubspotLoader
loader = AirbyteHubspotLoader(
    api_key="TU_API_KEY",
    stream_name="contacts"  # también: deals, companies
)
documents = loader.load()

from langchain_community.document_loaders import AirbyteHubspotLoader

loader = AirbyteHubspotLoader(
    api_key="TU_API_KEY",
    stream_name="contacts"  # también: deals, companies
)

documents = loader.load()

Devuelve cada registro de HubSpot como un Document. Puedes cambiar el tipo de dato a extraer (“companies”, “deals”, etc. )

Document(
    page_content="firstname: Juan, lastname: Pérez, email: juan@email.com, company: Hotel Sol",
    metadata={
        "source": "hubspot",
        "object_type": "contact"
    }
)

Document(
    page_content="firstname: Juan, lastname: Pérez, email: [email protected], company: Hotel Sol",
    metadata={
        "source": "hubspot",
        "object_type": "contact"
    }
)

Mejora clave (nivel pro)

Cuando trabajas con datos de sistemas como HubSpot, el contenido suele venir en formato técnico:

firstname: Juan, lastname: Pérez, company: Hotel Sol, email: juan@email.com

firstname: Juan, lastname: Pérez, company: Hotel Sol, email: [email protected]

Básicamente funciona, pero no es óptimo. Los modelos de lenguaje funcionan mejor cuando el texto tiene estructura natural y contexto semántico.

firstname = doc.metadata.get("firstname", "")
lastname = doc.metadata.get("lastname", "")
company = doc.metadata.get("company", "")
email = doc.metadata.get("email", "")
doc.page_content = (
    f"Cliente {firstname} {lastname} trabaja en {company}. "
    f"Su email es {email}."
)

firstname = doc.metadata.get("firstname", "")
lastname = doc.metadata.get("lastname", "")
company = doc.metadata.get("company", "")
email = doc.metadata.get("email", "")

doc.page_content = (
    f"Cliente {firstname} {lastname} trabaja en {company}. "
    f"Su email es {email}."
)

Texto natural mejor para embedding.

Cliente Juan Pérez trabaja en Hotel Sol. Su email es juan@email.com.

Cliente Juan Pérez trabaja en Hotel Sol. Su email es [email protected].

Consideraciones importantes

• Dependencia de APIs: considera tener límites de uso, latencia y cambios en endpoints
• Calidad del dato: estos sistemas contienen datos incompletos, campos técnicos y estructuras complejas, por lo que requieren transformación antes de embeddings.
• Seguridad: datos sensibles (clientes, pagos, logs) o credenciales de acceso. Es imprescindible gestionar permisos correctamente

Buenas prácticas

• Seleccionar solo campos relevantes
• Transformar datos en lenguaje natural
• Añadir metadata útil (fecha, tipo, origen)
• Limitar volumen de datos

Loaders de almacenamiento y cloud

Los loaders de almacenamiento y cloud permiten cargar documentos desde sistemas de almacenamiento remoto, como servicios en la nube o buckets de archivos. En lugar de acceder a archivos locales, estos loaders trabajan con datos alojados en infraestructuras externas.

Ejemplo básico (S3)

from langchain_community.document_loaders import S3FileLoader
loader = S3FileLoader(
    bucket="mi-bucket",
    key="ruta/archivo.pdf"
)
documents = loader.load()

from langchain_community.document_loaders import S3FileLoader

loader = S3FileLoader(
    bucket="mi-bucket",
    key="ruta/archivo.pdf"
)

documents = loader.load()

Consideraciones importantes

• Autenticación: Necesitas credenciales configuradas como AWS credentials, roles IAM, tokens, etc.
• Tipos de archivos: Estos loaders no procesan directamente el contenido solo lo recuperan, luego necesitarás un loader según el tipo de archivo objetivo (PDF loader, text loader, etc.)
• Latencia: acceso remoto + transferencias de archivos que pueden ser más lento que en entornos locales.

Buenas prácticas

• Limitar el número de archivos
• Filtrar por tipo (PDF, TXT…)
• Combinar con otros loaders
• Aplicar limpieza posterior

Loaders de comunicación y chats

Los loaders de comunicación y chats permiten incorporar conversaciones reales dentro de un sistema RAG. Estas fuentes incluyen mensajes de plataformas como WhatsApp, Telegram, Discord o Facebook, donde el conocimiento no está en documentos formales, sino en interacciones entre personas.

Ejemplo básico (WhatsApp)

El loader WhatsAppChatLoader no accede a la app ni a la API de WhatsApp. Trabaja sobre exportaciones de chats generadas manualmente.

from langchain_community.document_loaders import WhatsAppChatLoader
loader = WhatsAppChatLoader("data/chat_whatsapp.txt")
documents = loader.load()

from langchain_community.document_loaders import WhatsAppChatLoader

loader = WhatsAppChatLoader("data/chat_whatsapp.txt")
documents = loader.load()

Ejemplo archivo exportado:

[10/01/2024, 10:30] Juan: ¿Tenemos disponibilidad este fin de semana?
[10/01/2024, 10:32] Hotel: Sí, tenemos habitaciones libres.
[10/01/2024, 10:33] Juan: Perfecto, ¿precio?

[10/01/2024, 10:30] Juan: ¿Tenemos disponibilidad este fin de semana?
[10/01/2024, 10:32] Hotel: Sí, tenemos habitaciones libres.
[10/01/2024, 10:33] Juan: Perfecto, ¿precio?

Resultado:

Document(
    page_content="Juan pregunta por disponibilidad. El hotel responde que hay habitaciones disponibles.",
    metadata={"source": "whatsapp", "date": "2024-01-10"}
)

Document(
    page_content="Juan pregunta por disponibilidad. El hotel responde que hay habitaciones disponibles.",
    metadata={"source": "whatsapp", "date": "2024-01-10"}
)

Preprocesamiento (El texto raw no es óptimo).

clean_docs = []
for doc in documents:
    text = doc.page_content
    
    # limpieza básica
    text = " ".join(text.split())
    
    doc.page_content = text
    clean_docs.append(doc)

clean_docs = []

for doc in documents:
    text = doc.page_content
    
    # limpieza básica
    text = " ".join(text.split())
    
    doc.page_content = text
    clean_docs.append(doc)

Problemas típicos

• Ruido conversacional: saludos, emojis, mensajes irrelevantes.
• Fragmentación: El contexto está dividido en múltiples mensajes y necesitas reconstruir la conversación.
• Lenguaje informal: abreviaturas, errores, frases incompletas.
• Necesidad de preprocesamiento: Aquí la limpieza es especialmente importante:
  • unir mensajes relacionados
  • eliminar ruido
  • resumir conversaciones
  • estructurar el contexto

Buenas prácticas

• agrupar mensajes por conversación
• filtrar mensajes irrelevantes
• añadir metadata (usuario, fecha)
• convertir a lenguaje más estructurado

Aquí tienes la sección completa, coherente con el resto del bloque:

Loaders utilitarios

Los loaders utilitarios no están diseñados para una fuente de datos específica, sino para optimizar y gestionar el proceso de carga. Actúan como herramientas auxiliares que permiten trabajar con múltiples documentos, combinar fuentes o mejorar el rendimiento del sistema. No cargan datos por sí mismos, sino que orquestan otros loaders.

Estos loaders permiten:

• cargar grandes volúmenes de archivos
• combinar múltiples fuentes en un solo flujo
• mejorar el rendimiento mediante paralelización

Ejemplo carga masiva con DirectoryLoader:

from langchain_community.document_loaders import DirectoryLoader
loader = DirectoryLoader(
    path="./data",
    glob="**/*.pdf"
)
documents = loader.load()

from langchain_community.document_loaders import DirectoryLoader

loader = DirectoryLoader(
    path="./data",
    glob="**/*.pdf"
)

documents = loader.load()

Ejemplo combinar fuentes:

from langchain_community.document_loaders import MergedDataLoader
from langchain_community.document_loaders import PyPDFLoader, TextLoader
loader1 = PyPDFLoader("file.pdf")
loader2 = TextLoader("file.txt")
merged_loader = MergedDataLoader(loaders=[loader1, loader2])
documents = merged_loader.load()

from langchain_community.document_loaders import MergedDataLoader
from langchain_community.document_loaders import PyPDFLoader, TextLoader

loader1 = PyPDFLoader("file.pdf")
loader2 = TextLoader("file.txt")

merged_loader = MergedDataLoader(loaders=[loader1, loader2])

documents = merged_loader.load()

Ejemplo paralelización:

from langchain_community.document_loaders import ConcurrentLoader
loader = ConcurrentLoader.from_loaders([
    PyPDFLoader("file1.pdf"),
    PyPDFLoader("file2.pdf")
])
documents = loader.load()

from langchain_community.document_loaders import ConcurrentLoader

loader = ConcurrentLoader.from_loaders([
    PyPDFLoader("file1.pdf"),
    PyPDFLoader("file2.pdf")
])

documents = loader.load()

Consideraciones importantes

• Control del volumen: Cargar demasiados archivos puede saturar la memoria y ralentizar el sistema.
• Mezcla de fuentes: al combinar loaders pueden tener formatos distintos y requerir limpieza unificada
• Paralelización: mejora velocidad pero aumenta consumo de recursos

Buenas prácticas

• filtrar archivos antes de cargar.
• controlar el tamaño del dataset
• aplicar limpieza homogénea
• usar paralelización solo cuando sea necesario