Tutorial de Crawl4AI: una guía para usar la IA para scraping, extracción y RAG

Crawl4AI es una librería de crawling (rastreo web) y scraping de código abierto diseñada con principios AI-first. Esto significa que desde el inicio está pensada para integrarse con modelos de lenguaje y flujos de machine learning. Sus objetivos principales incluyen:

Markdown limpio y listo para IA: genera contenido en formato Markdown bien estructurado y conciso, optimizado para sistemas de Retrieval-Augmented Generation (RAG) y consumo directo por LLMs apidog.com. Esto implica eliminar elementos irrelevantes (p. ej. menús, anuncios, pies de página) y conservar el texto principal de la página de forma que un modelo de lenguaje lo pueda procesar fácilmente apidog.com.
Extracción de datos estructurados: permite extraer datos específicos en formato estructurado (por ejemplo JSON) usando métodos tradicionales (selectores CSS o XPath) o estrategias impulsadas por LLMs para tareas más complejas o semánticas apidog.com. En otras palabras, puedes obtener información puntual de una página (títulos, precios, enlaces, etc.) mediante selectores, o incluso hacer que un modelo de IA interprete la página y devuelva JSON con los datos deseados.
Alto rendimiento asíncrono: está construido sobre Python asyncio y utiliza Playwright (un motor de automatización de navegador) para realizar crawling de forma asíncrona y rápida apidog.com. Esto le permite cargar múltiples páginas concurrentemente aprovechando operaciones de I/O sin bloquear el programa, ideal para rastrear gran cantidad de URLs de manera eficiente.
Control avanzado del navegador: ofrece control detallado sobre la navegación web, incluyendo soporte para ejecutar JavaScript personalizado, manejar contenido dinámico (páginas SPA con scroll infinito, botones Load more, etc.), administrar sesiones (cookies, almacenamiento local), usar proxies, y simular distintos entornos de usuario (agentes de usuario, tamaños de viewport, ubicación geográfica, etc.) apidog.com. Esto facilita interactuar con páginas complejas, autenticarse si es necesario, y evitar bloqueos al camuflar la automatización.
Flexibilidad y despliegue sencillo: es totalmente de código abierto (licencia Apache 2.0) sin muros de pago ni claves de API obligatorias para funciones básicas apidog.com. Se puede instalar como paquete Python o usar mediante una imagen Docker oficial, lo que simplifica su integración en distintos entornos. Por ejemplo, existe una imagen Docker con una interfaz FastAPI para usar Crawl4AI como microservicio escalable medium.com.

En resumen, Crawl4AI busca democratizar el acceso a datos web al proporcionar una herramienta gratuita, potente y fácil de usar, ideal para desarrolladores, científicos de datos y entusiastas que necesiten extraer información de la web de forma eficiente y prepararla para pipelines de IA docs.crawl4ai.com.

Instalación de la librería ¶

Requisitos previos: Necesitarás Python 3.8+ instalado en tu sistema. Crawl4AI funciona de forma asíncrona apoyándose en Playwright (que utiliza navegadores web como Chromium). El instalador de Crawl4AI se encargará de configurar Playwright automáticamente.

Instalación vía pip: La forma recomendada de instalar Crawl4AI es usando pip en tu entorno Python. Ejecuta en la terminal:

Esto instalará la última versión estable publicada en PyPI apidog.com. Una vez instalada la librería, debes ejecutar un paso de configuración post-instalación para descargar los navegadores necesarios (Chromium por defecto) que usa Playwright. Para ello, ejecuta:

bashcrawl4ai-setup

Este comando descargará e instalará el navegador headless requerido. Puedes verificar que todo está correcto ejecutando el diagnóstico:

bashcrawl4ai-doctor

Si por alguna razón crawl4ai-setup presenta problemas (por ejemplo, restricciones de red), puedes instalar manualmente las dependencias de Playwright ejecutando:

Esto asegura que Chromium y sus dependencias estén disponibles en tu sistema apidog.com apidog.com.

Alternativa: instalación mediante Docker: Si no deseas instalar nada localmente o planeas usar Crawl4AI como un servicio, puedes optar por Docker. Existe una imagen oficial en Docker Hub. Para usarla, simplemente descarga la imagen y ejecútala. Por ejemplo:

La imagen Docker levanta un servidor FastAPI en el puerto 11235 listo para recibir solicitudes de rastreo vía HTTP apidog.com apidog.com. Incluso incluye una interfaz web (Playground) accesible en http://localhost:11235/playground donde puedes probar peticiones de crawling de forma interactiva. Hablaremos más sobre el despliegue en Docker en secciones posteriores, pero ten en cuenta que esta opción facilita ejecutar Crawl4AI en entornos de servidor o integrarlo en microservicios.

Nota: Crawl4AI instala por defecto su versión asíncrona basada en Playwright (alta velocidad). Existió una versión síncrona (usando Selenium) para usos especiales, instalable con pip install crawl4ai[sync], pero está deprecada y se eliminará en el futuro github.com. Se recomienda usar siempre la versión asíncrona para aprovechar al máximo el rendimiento de la librería.

Primeros pasos con Python: tu primer crawl ¶

Una vez instalada la librería, probemos a realizar un crawling básico de una página web con Python. Crawl4AI proporciona la clase principal AsyncWebCrawler para manejar las operaciones. Como es asíncrona, utilizaremos async/await para interactuar con ella. A continuación se muestra un ejemplo mínimo de cómo extraer el contenido de una página y obtener su Markdown:

Explicación: En este código, utilizamos AsyncWebCrawler dentro de un bloque async with para que se encargue de iniciar y cerrar el navegador automáticamente apidog.com. Llamamos a crawler.arun(url="...") pasando la URL objetivo (en este caso example.com) – esta es la función que realiza el crawl de una sola página y devuelve un objeto CrawlResult con el resultado apidog.com. Comprobamos result.success para ver si la operación fue exitosa. Si todo va bien, result.markdown.fit_markdown contendrá el contenido extraído en Markdown “limpio”, es decir, el texto principal de la página con formato Markdown y sin basura (navegación, anuncios, etc.) apidog.com. En el ejemplo imprimimos solo los primeros 300 caracteres de ese Markdown para no abrumar la salida. Si hubiese fallado (result.success es False), mostramos el mensaje de error proporcionado.

Al ejecutar este script, deberías ver impreso en consola un fragmento del contenido de la página en Markdown. Por ejemplo, para example.com, el resultado incluirá el texto “Example Domain…” en formato Markdown.

¿Qué ha ocurrido internamente? Crawl4AI abrió una sesión de navegador headless (Chromium) mediante Playwright, cargó la URL solicitada, extrajo el contenido de la página aplicando heurísticas para generar Markdown, y luego cerró la sesión (gracias al contexto async with). Todo esto sucedió de forma transparente para el usuario.

El objeto CrawlResult (result en el código) contiene múltiples atributos útiles. Algunos de los más importantes son:

result.markdown.raw_markdown: el Markdown bruto de toda la página.
result.markdown.fit_markdown: el Markdown filtrado/enfocado en el contenido principal (lo que imprimimos arriba).
result.markdown.word_count: cantidad de palabras del fit markdown, útil para saber cuánta info se extrajo apidog.com.
result.extracted_content: si se realizó una extracción estructurada (lo veremos más adelante), aquí vendría la data en JSON u otro formato.
result.url: la URL que se crawleó (tras posibles redirecciones).
result.status: el código HTTP obtenido (200, 404, etc.).
result.error_message: mensaje de error en caso de fallo (result.success=False).

Primeros pasos con la interfaz de línea de comandos (CLI) ¶

Además de la API Python, Crawl4AI ofrece una utilidad de línea de comandos llamada crwl (se instala junto con la librería) para hacer crawling sin escribir código. Esta CLI es muy práctica para pruebas rápidas o para integrar en scripts shell. A continuación, algunos usos básicos:

Crawling simple: Ejecuta en tu terminal:
Esto realizará el crawling de https://ejemplo.com y mostrará por pantalla el resultado en formato por defecto (Markdown). Equivale a lo que hicimos con Python en la sección anterior, pero en un solo comando docs.crawl4ai.com.
Obtener Markdown explícitamente: Puedes especificar el formato de salida con la opción -o. Por ejemplo,
forzará la salida en Markdown legible (que es el comportamiento predeterminado). Existe también -o markdown-fit para obtener el Markdown filtrado (fit) enfocándose en el contenido principal, aunque en la mayoría de casos markdown ya aplica filtros heurísticos similares docs.crawl4ai.com docs.crawl4ai.com.
Salida JSON estructurada: Si configuras una extracción estructurada (veremos cómo), puedes pedir que la CLI devuelva JSON usando -o json. Por ejemplo, crwl https://ejemplo.com -o json -v retornaría un JSON con la información extraída (si has definido un esquema de extracción) y detalles verbosos (-v activa modo verbose) docs.crawl4ai.com.
Ver ejemplos y ayuda: Ejecutando crwl --example se mostrarán ejemplos de uso de la CLI con distintas opciones. Del mismo modo, crwl --help listará todas las opciones disponibles y su descripción.

La CLI acepta muchas opciones avanzadas: por ejemplo, -B para cargar una configuración de navegador desde un archivo YAML, -c / -C para parámetros de crawling (esperas, scroll, etc.), -e / -s para definir estrategias de extracción y esquemas, -f para filtros de contenido, -q para realizar preguntas a un LLM sobre la página, entre otras docs.crawl4ai.com docs.crawl4ai.com. En las siguientes secciones exploraremos varios de estos conceptos usando principalmente la API de Python, pero ten en cuenta que casi todo lo que se puede hacer por código también es posible vía CLI pasando las configuraciones adecuadas. La CLI es esencialmente un envoltorio conveniente alrededor de la biblioteca.

(Sugerencia: Si estás empezando y no te sientes cómodo con Python, la CLI te permite lograr muchas tareas de scraping de inmediato. Más adelante, cuando profundices, podrás combinar Python y la CLI según te convenga.)

Extracción estructurada con selectores CSS/XPath ¶

Muchas veces no solo queremos el texto completo de una página, sino extraer datos puntuales de forma estructurada, como por ejemplo una lista de productos con nombre y precio, los titulares y enlaces de noticias, tablas de datos, etc. Crawl4AI soporta esto mediante esquemas JSON de extracción basados en selectores CSS/XPath, sin necesidad de usar IA para parsear el contenido. Este enfoque “LLM-Free” permite obtener JSON de una página de manera determinista y rápida docs.crawl4ai.com.

¿Cómo funciona? Simplemente definimos un esquema (en forma de diccionario Python o archivo JSON/YAML) que describe qué elementos queremos extraer usando selectores CSS o XPath. Luego, le indicamos al crawler que use ese esquema; él se encargará de parsear el HTML y llenar el esquema con los datos correspondientes.

Veamos un ejemplo práctico. Supongamos que queremos extraer de una página de tienda una lista de productos, obteniendo el título y el precio de cada producto. Podemos definir un esquema de esta forma:

pythonimport asyncio, json
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
from crawl4ai.extraction_strategy import JsonCssExtractionStrategy

async def extraer_productos():
    # Definir el esquema de extracción usando selectores CSS
    schema = {
        "productos": {             # nombre del campo raíz
            "selector": "div.product-item",  # selector CSS para cada producto
            "type": "list",       # indica que habrá múltiples elementos
            "fields": {           # campos a extraer de cada producto
                "titulo": "h2",               # obtiene el texto del <h2> dentro del producto
                "precio": ".price"            # obtiene el texto del elemento con clase "price"
            }
        }
    }
    extractor = JsonCssExtractionStrategy(schema)
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(
            url="https://ejemplo.com/tienda",
            config=CrawlerRunConfig(extraction_strategy=extractor)
        )
        if result and result.success:
            data_json = json.loads(result.extracted_content)
            print(f"Extraídos {len(data_json['productos'])} productos:")
            print(json.dumps(data_json['productos'][0], indent=2, ensure_ascii=False))
        else:
            print("Error:", result.error_message)

asyncio.run(extraer_productos())

Explicación: En el esquema anterior, definimos un objeto productos que corresponde a una lista ("type": "list") de elementos encontrados con el selector CSS "div.product-item". Para cada elemento de esa lista, extraemos dos campos: "titulo" que corresponde al texto del h2 dentro del producto, y "precio" que corresponde al texto del elemento con clase .price. Este esquema es una forma declarativa de decir “de cada bloque de producto, dame el título y el precio” apidog.com apidog.com. Luego creamos una estrategia de extracción JsonCssExtractionStrategy pasándole este esquema.

Al ejecutar crawler.arun proporcionamos un CrawlerRunConfig especificando extraction_strategy=extractor. Esto le indica a Crawl4AI que, además de generar el Markdown de la página, aplique esta estrategia de extracción. El resultado (result) contendrá entonces result.extracted_content con un JSON (en formato texto) que encaja con nuestro esquema. En el código, hacemos json.loads(result.extracted_content) para convertir esa cadena JSON a un diccionario Python (data_json). Finalmente, imprimimos cuántos productos se extrajeron y mostramos el primer producto con json.dumps formateado.

Si todo sale bien, la salida podría ser algo así (suponiendo 10 productos en la página):

Crawl4AI rellenó automáticamente este JSON tomando el HTML de la página y aplicando nuestros selectores CSS, sin intervención manual. La gran ventaja es que obtenemos datos limpios y estructurados listos para usar (por ejemplo, en un DataFrame o en una base de datos). Y todo esto sin usar un LLM, por lo que es muy rápido y no implica coste adicional.

XPath: Si prefieres usar selectores XPath en lugar de CSS, Crawl4AI también lo soporta mediante JsonXPathExtractionStrategy de forma equivalente docs.crawl4ai.com. El esquema JSON tendría las mismas estructuras pero los selectores serían expresiones XPath. En general, los selectores CSS suelen ser más sencillos de leer, pero XPath puede ser útil para navegaciones más complejas en el árbol DOM.

Esquemas anidados y avanzados: El mecanismo de schema es muy poderoso. Puedes extraer listas anidadas, atributos de elementos (por ejemplo el href de un enlace, usando una sintaxis especial en el esquema), texto interno o HTML interno, etc. También existe una estrategia de extracción por expresiones regulares (RegexExtractionStrategy) para casos muy específicos de búsqueda de patrones en el texto docs.crawl4ai.com. Para mantener este tutorial enfocado, no entraremos en todos los detalles, pero la documentación oficial ofrece más ejemplos de extracción avanzada, incluyendo manejo de estructuras JSON complejas, utilidades para generar esquemas automáticamente, y mejores prácticas.

Extracción de información con LLMs (modelos de lenguaje) ¶

A veces nos encontramos con páginas cuyo contenido es muy desestructurado o complejo, donde definir selectores para cada dato es complicado. O quizá queremos extraer información de forma semántica (por ejemplo, un resumen, entidades mencionadas, conclusiones, etc.) en lugar de campos exactos. En estos casos, podemos aprovechar un LLM (modelo de lenguaje) como GPT-4 para que interprete el contenido y extraiga la información deseada. Crawl4AI facilita esta integración ofreciendo una estrategia de extracción con LLM.

¿Cómo funciona? Básicamente, le proporcionamos al crawler una instrucción en lenguaje natural que describa qué queremos extraer de la página, junto con un esquema o formato esperado para la respuesta. El crawler dividirá el contenido de la página si es muy grande (en chunks) y enviará esas partes al modelo de lenguaje (por ejemplo OpenAI GPT-4, Claude, etc.) para que extraiga los datos según la instrucción docs.crawl4ai.com docs.crawl4ai.com. Al final combinará las respuestas en un JSON unificado.

Para usar esta funcionalidad, necesitas una clave de API del proveedor de LLM que elijas (OpenAI, Anthropic, u otros soportados a través de la capa LiteLLM docs.crawl4ai.com). Crawl4AI no trae sus propios modelos, sino que se integra con servicios existentes. Veamos los pasos generales:

Configurar el proveedor de LLM: Por ejemplo, OpenAI GPT-4. Se indica típicamente mediante un identificador (ej. "openai/gpt-4") y proporcionando el api_token correspondiente en la configuración.
Definir la instrucción y esquema: Escribes una instrucción en inglés o español pidiendo la información. Por ejemplo: “Extrae todos los artículos con sus títulos y links”. Opcionalmente defines un esquema JSON para validar la respuesta del LLM (campos esperados y tipos).
Ejecutar el crawling con estrategia LLM: Indicas al crawler que use la estrategia LLM pasando esos parámetros. El crawler se encargará de enviar el texto de la página al modelo con la instrucción, recibir la respuesta y estructurarla como JSON según el esquema.

En la práctica, cuando usas la CLI, la primera vez que invocas una opción LLM (como -q para preguntas o -e llm para extracción con LLM) te pedirá que configures el proveedor y API key, guardando esa config en ~/.crawl4ai/global.yml para próximas veces docs.crawl4ai.com. En Python, tendrías que configurar el equivalente vía código (por ejemplo, usando LLMExtractionStrategy con sus parámetros).

Ejemplo conceptual: Supongamos que queremos extraer de un artículo web las citas bibliográficas que aparecen en el texto, pero no hay un formato HTML claro para seleccionarlas. Podemos recurrir a un LLM:

Instrucción: “Lee el artículo y extrae una lista de referencias bibliográficas, indicando el título del trabajo y el autor si está disponible”.
Esquema esperado: Un JSON con estructura, por ejemplo:
Configuración: Usar GPT-4 de OpenAI. En CLI podríamos tener un archivo YAML de extracción:
y un archivo de esquema JSON con la estructura anterior para validar la respuesta del modelo.

Al ejecutar crwl URL-del-articulo -e extraccion_llm.yml -s esquema_llm.json -o json, Crawl4AI enviará la instrucción y el texto del artículo al modelo GPT-4, obtendrá una respuesta (que intenta cumplir el esquema dado) y la presentará como JSON estructurado docs.crawl4ai.com docs.crawl4ai.com.

Consideraciones importantes: La extracción con LLM es poderosa pero:

Costo y velocidad: Llamar a un LLM (especialmente GPT-4) tiene coste monetario por token y añade latencia. Úsalo solo cuando la extracción por selectores no sea viable.
Calidad de instrucción: Debes redactar muy bien la instrucción para que el modelo devuelva lo pedido en el formato correcto. A veces se necesita afinar con ejemplos o ajustar la redacción (lo que se conoce como prompt engineering) docs.crawl4ai.com.
Chunking: Si la página es muy larga, Crawl4AI la dividirá en partes manejables antes de enviar al LLM para no pasar límites de contexto docs.crawl4ai.com. Esto suele ser automático, pero se puede ajustar parámetros como chunk_token_threshold (tamaño máximo de chunk en tokens) y overlap_rate (porcentaje de solapamiento entre chunks para no perder contexto) docs.crawl4ai.com.
Proveedores soportados: Gracias a LiteLLM, se soportan múltiples modelos y APIs (OpenAI, Anthropic, Ollama para modelos locales, etc.) docs.crawl4ai.com. Si usas la CLI, verás un menú de opciones de modelo. Para modelos locales como ollama no se requiere token.
Modo pregunta-respuesta: Crawl4AI también permite hacer Q&A directo sobre una página sin necesidad de definir un esquema JSON. Por ejemplo, crwl https://ejemplo.com -q "¿Cuál es el tema principal tratado?" hará que el LLM analice la página y devuelva una respuesta en texto docs.crawl4ai.com. Este modo es útil para consultas puntuales y debugging, aunque para integraciones RAG generalmente extraemos todo el contenido o datos clave en vez de una sola pregunta fija.

En resumen, la integración con LLMs te da flexibilidad para extraer informaciones complejas que de otro modo requerirían lógica de scraping complicada. Eso sí, debes tener en cuenta el costo y asegurarte de respetar los términos de servicio del sitio que estés rastreando y de la API del LLM que uses.

Filtros de contenido y generación de Markdown limpio ¶

Uno de los puntos fuertes de Crawl4AI es su capacidad de producir contenido en Markdown limpio, es decir, enfocado en la información relevante de la página y sin elementos superfluos. Ya vimos que result.markdown.fit_markdown nos da ese contenido filtrado. Vamos a profundizar en cómo funciona esto y cómo podemos afinarlo.

Cuando Crawl4AI convierte una página HTML a Markdown, por defecto aplica una heurística para eliminar secciones de bajo valor informativo. Elementos como menús de navegación, barras laterales repetitivas, pie de página, anuncios, etc., suelen detectarse y excluirse del Markdown resultante docs.crawl4ai.com apidog.com. El objetivo es quedarnos con el “núcleo” de texto de la página (por eso también se le llama fit markdown o Markdown “ajustado”).

Detrás de escena, existen algoritmos de filtrado de contenido que hacen posible esto. Crawl4AI incluye al menos dos estrategias principales de filtro:

PruningContentFilter (“poda”): Este filtro evalúa secciones del texto en función de su densidad o relevancia general, y recorta partes poco sustanciales. Es útil para quitar boilerplate común sin necesidad de saber de qué trata la página.
BM25ContentFilter: Este filtro utiliza el algoritmo BM25 (común en motores de búsqueda) para puntuar la relevancia de frases respecto a una consulta dada docs.crawl4ai.com. Si le proporcionamos una query (p. ej. “machine learning” o “receta de pasta”), puede identificar párrafos más relacionados con ese tema y descartar el resto, según un umbral configurado.

De forma predeterminada, Crawl4AI aplica un filtro genérico (similar a pruning) para generar fit_markdown automáticamente apidog.com. Pero podemos ajustar los filtros a nuestras necesidades:

En la CLI, podemos usar la opción -f para especificar un archivo YAML de filtro de contenido. Por ejemplo, un filter_bm25.yml con contenido:
y luego ejecutar crwl https://ejemplo.com -f filter_bm25.yml -o markdown-fit para obtener solo las partes de la página que sean relevantes a “inteligencia artificial” (según BM25) docs.crawl4ai.com docs.crawl4ai.com. Un valor de threshold más alto implica filtrar más agresivamente (requiere mayor relevancia para conservar texto).
En Python, podemos hacer algo equivalente pasando un objeto filtro en la configuración de ejecución. Por ejemplo:
Esto le dice al crawler que al generar el Markdown aplique el filtro BM25 con la query dada. El resultado fit_markdown entonces solo contendrá texto considerado relevante para “inteligencia artificial” docs.crawl4ai.com docs.crawl4ai.com.
También podríamos usar PruningContentFilter explícitamente de forma similar, aunque este no requiere una query, solo se basa en umbrales de densidad de información.

Además de los filtros, hay otros parámetros que influyen en la limpieza del contenido, como word_count_threshold (umbral mínimo de palabras para que un bloque de texto se considere relevante) docs.crawl4ai.com, exclusión de ciertas etiquetas (p. ej. <script>, <style> ya se excluyen por defecto), exclusión de enlaces externos, etc. La configuración por defecto suele ser suficiente para la mayoría de casos, pero es bueno saber que puedes tunear estos aspectos si lo necesitas.

En resumen, gracias a estos filtros, el Markdown que obtienes con Crawl4AI está listo para usarse en aplicaciones de NLP/IA sin requerir mucho procesamiento adicional. Por ejemplo, si planeas indexar páginas en un vector store para hacer preguntas con un LLM (típico flujo RAG), te conviene usar el fit_markdown filtrado para reducir ruido y almacenamiento, manteniendo solo la sustancia docs.crawl4ai.com. Y si buscas algo específico dentro de una página, un filtro de consulta con BM25 puede ahorrarte tener que analizar manualmente todo el texto.

(Puedes acceder tanto al Markdown bruto como al filtrado: result.markdown.raw_markdown vs result.markdown.fit_markdown. Así puedes comparar y ajustar filtros según necesites.)

Gestión de sesiones persistentes ¶

En escenarios de scraping más complejos, es útil poder mantener la sesión entre múltiples navegaciones. Por ejemplo, imagina que necesitas: (a) iniciar sesión en un sitio y luego (b) acceder a una página interna que requiere esas credenciales; o bien, quieres simular hacer clic en “Página 2” o “Cargar más” repetidamente para extraer contenido paginado. Todo esto se logra con la gestión de sesiones en Crawl4AI.

¿Qué es una sesión en este contexto? Es básicamente reutilizar la misma instancia de navegador (misma pestaña, mismas cookies, almacenamiento local, contexto JS) para varias operaciones sucesivas docs.crawl4ai.com. Normalmente, cada vez que llamamos crawler.arun sin especificar nada especial, el crawler abre una página nueva temporal, la carga y luego la cierra. Con las sesiones persistentes, podemos indicarle que reutilice la misma página para varios arun, evitando recargar cosas innecesariamente y manteniendo estado (por ejemplo, si en la primera página se hizo login, la segunda página aún estará logueada).

En Crawl4AI, habilitamos esto asignando un identificador de sesión (session_id) común a esas operaciones. Veamos un ejemplo simple:

Con session_id=session en ambos casos, Crawl4AI sabe que debe reutilizar la misma pestaña/browser para la segunda navegación docs.crawl4ai.com. Esto significa que cualquier efecto de la página1 (cookies de login, variables en localStorage, DOM modificado via JS, etc.) seguirá presente al cargar page2. Esta técnica es muy útil para crawling secuencial: por ejemplo, la página2 podría requerir que la página1 haya sido visitada (como en un asistente paso 1 -> paso 2), o podría ser la siguiente página de resultados en una lista paginada donde en vez de abrir una pestaña nueva, navegamos en la misma.

Un caso concreto: supongamos un sitio con un botón “Cargar más comentarios”. Podemos cargar la página, luego hacer clic en ese botón varias veces simulando scroll. Con sesiones, haríamos algo así (conceptualmente):

La primera llamada carga la página de comentarios. La segunda llamada, con el mismo session_id, no recarga la página desde cero sino que utiliza la existente y ejecuta el JavaScript que hace clic en el botón “load more”, esperando 2 segundos (wait_for_timeout) a que carguen más comentarios antes de extraer el contenido nuevamente. De este modo, result_more contendrá comentarios adicionales que no estaban en result_inicial. Podemos repetir este proceso varias veces para paginar. Todo ocurre en la misma pestaña, ahorrando tiempo y manteniendo el contexto docs.crawl4ai.com docs.crawl4ai.com.

Importante: Las sesiones persistentes están pensadas para operaciones secuenciales, no concurrentes. Dentro de una misma instancia de AsyncWebCrawler, solo una acción ocurre a la vez, y si varias comparten session_id, se ejecutarán en orden. No uses la misma sesión en múltiples asyncio.gather concurrentes, por ejemplo.

Cuando terminas, cierra la sesión para liberar recursos. Al salir del bloque async with AsyncWebCrawler normalmente se liberan, pero Crawl4AI también ofrece un método explícito:

que destruye la pestaña/contexto asociado a ese session_id docs.crawl4ai.com. Úsalo si mantienes el crawler abierto y quieres liberar una sesión en particular antes de cerrar todo.

En resumen, las sesiones persistentes te permiten manejar casos de uso complejos: login y navegación autenticada, pasos múltiples, scroll infinito manual, etc., de forma eficiente. Sin esta funcionalidad tendrías que implementar lógica de clicks manual con herramientas tipo Selenium, pero Crawl4AI ya lo incorpora de forma sencilla.

Uso de proxies en las peticiones ¶

En scraping real, a veces necesitamos usar servidores proxy por diversos motivos: evitar bloqueos o límites de tasa desde nuestra IP, geolocalizar las peticiones (ej. acceder a contenido disponible solo en ciertos países), anonimizar el origen, etc. Crawl4AI soporta proxies fácilmente a través de su configuración de navegador.

Para usar un proxy, basta con pasar la URL del proxy en la configuración BrowserConfig. Por ejemplo, si tienes un proxy HTTP en proxy.mired:8080:

En este ejemplo, la petición a ipinfo.io (un servicio que devuelve tu IP) saldría mediante el proxy especificado docs.crawl4ai.com, por lo que la IP reportada sería la del servidor proxy y no la tuya.

Proxies autenticados: Si tu proxy requiere usuario y contraseña, la configuración es ligeramente distinta. En lugar de proxy="http://host:puerto", debes proporcionar un diccionario con los datos:

Así se pasa credenciales para proxies HTTP con auth básica docs.crawl4ai.com. (Para proxies SOCKS5 con usuario/clave es similar, cambiando el esquema a "socks5://...").

Proxy SOCKS5 o otros: Puedes usar esquemas socks5:// o socks5h:// en la URL del proxy para proxies SOCKS. El soporte incluye HTTP, HTTPS, SOCKS5.

Rotación de proxies: Si necesitas cambiar de proxy por petición (por ejemplo, tienes una lista de proxies y quieres usarlos de forma rotativa para distribuir la carga), puedes hacerlo creando nuevos contextos de navegador o clonando la configuración de ejecución. Un enfoque es utilizar CrawlerRunConfig.clone() por cada URL, asignándole un proxy distinto docs.crawl4ai.com. Crawl4AI no trae un pool de proxies propio, pero puedes implementarlo fácilmente: por ejemplo, escribir una función get_next_proxy() que devuelva las credenciales del siguiente proxy a usar, e integrarla en tu bucle de crawling docs.crawl4ai.com docs.crawl4ai.com.

En la mayoría de casos, con solo especificar el proxy global en BrowserConfig todas las peticiones de esa sesión pasarán por él. Esto incluye las cargas de página, peticiones de recursos internos de la página, etc., ya que Playwright a nivel de navegador usará el proxy indicado.

(Nota: Si usas la CLI, también puedes indicar un proxy. La forma más sencilla es establecer la variable de entorno HTTPS_PROXY o http_proxy antes de ejecutar crwl, o usar un archivo YAML de config de navegador con la clave proxy: "http://proxy:puerto" y pasarlo con -B navegador.yml.)

Rastreo profundo y concurrente ¶

Hasta ahora hemos tratado principalmente el crawling de páginas individuales o unas pocas páginas manualmente. Sin embargo, Crawl4AI está capacitado para rastrear sitios completos siguiendo enlaces (lo que llamamos crawling profundo o crawling recursivo) y para manejar muchas URLs en paralelo de forma eficiente. Veamos ambos aspectos:

Rastreo profundo (navegación BFS/DFS) ¶

El deep crawling consiste en partir de una URL inicial y luego seguir los enlaces de esa página a otras páginas del mismo sitio, y así sucesivamente, para explorar gran parte (o la totalidad) de un sitio web automáticamente. Crawl4AI soporta estrategias de exploración clásica:

BFS (Breadth-First Search): búsqueda en anchura, explora nivel por nivel (primero todos los enlaces de la página inicial, luego los de las subsecuentes, etc.) docs.crawl4ai.com.
DFS (Depth-First Search): búsqueda en profundidad, sigue un camino lo más profundo posible antes de retroceder (útil para explorar en profundidad secciones particulares) docs.crawl4ai.com.
Best-First (por relevancia): una estrategia orientada a priorizar enlaces según algún puntaje o criterio (por ejemplo, relevancia por keywords). Esta estrategia usa scoring de URLs para decidir el orden óptimo de exploración, procesando primero las páginas “de mayor valor” según la métrica definida docs.crawl4ai.com docs.crawl4ai.com.

Por defecto, si no especificamos, Crawl4AI usa BFS (nivel por nivel) que suele ser lo más equilibrado para cobertura amplia medium.com.

Para realizar un deep crawl en Python, usamos el método adeep_crawl del crawler asíncrono. Este método devuelve un async generator, es decir, un iterador asíncrono que nos irá proporcionando resultados a medida que se van crawleando las páginas. Esto es útil porque en un sitio grande podría haber cientos de páginas y no queremos esperar a terminar toda la exploración para empezar a procesar resultados; en su lugar, vamos consumiendo resultados sobre la marcha.

Ejemplo de uso de adeep_crawl:

En este snippet, partimos de la URL de documentación de Crawl4AI y rastreamos hasta 2 niveles de enlaces internos, con un tope de 10 páginas en total para no excedernos apidog.com apidog.com. La estrategia es BFS, por lo que primero rastreará la página inicial (depth 0), luego sus enlaces (depth 1), luego enlaces de esos (depth 2). Vamos iterando sobre crawl_gen y por cada result imprimimos el nivel de profundidad y la URL, indicando si se crawleó con éxito. Cuando se alcanza max_depth o max_pages se detiene el proceso automáticamente apidog.com apidog.com.

Parámetros útiles en deep crawl:

max_depth: controla cuán profundo seguir enlaces (0 sería solo la inicial, 1 incluye enlaces de la inicial, etc.) docs.crawl4ai.com. Ten cuidado con valores altos (>3) porque el número de páginas crece exponencialmente en sitios densos.
max_pages: limita el número total de páginas a visitar, independientemente de la profundidad docs.crawl4ai.com docs.crawl4ai.com. Útil para acotar crawls muy grandes y evitar consumir demasiado tiempo o recursos.
include_external: por defecto False, significa que no seguirá enlaces a dominios externos distintos del dominio de start_url. Si lo pones True, el crawler podría salirse del sitio inicial y vagar por la web (normalmente no deseado salvo casos especiales) docs.crawl4ai.com.
include_patterns / exclude_patterns: listas de expresiones regulares para filtrar qué URLs se siguen o se ignoran durante el crawl apidog.com. Por ejemplo, podrías excluir URLs de logout o de imprimibles, o incluir solo ciertas secciones.
url_scorer y score_threshold: cuando usas bestfirst, puedes proveer una función de puntuación (por ejemplo basada en keywords que te interesan) para priorizar enlaces. score_threshold puede impedir que siga enlaces con score bajo cierto valor docs.crawl4ai.com.
stream=True/False: adeep_crawl por defecto hace streaming de resultados (similar a como mostramos, devuelve a medida que están listos). Si por algún motivo quisieras que devolviera una lista completa al final, podrías establecer stream=False para que espere a terminar y luego entregue todos los resultados juntos (menos eficiente en memoria generalmente) docs.crawl4ai.com.

La funcionalidad de deep crawling hace muy sencillo explorar sitios enteros. Por ejemplo, podrías extraer todos los artículos de un blog recorriendo automáticamente todas las páginas de archivo/categorías, o rastrear un sitio de documentación técnica. Siempre recuerda ser respetuoso: aunque Crawl4AI es rápido, considera poner pausas o límites razonables, y verifica si el sitio tiene un robots.txt que indique restricciones de crawling (Crawl4AI no lo respeta por defecto, está en el desarrollador usarlo con ética) docs.crawl4ai.com.

Crawling concurrente de múltiples URLs ¶

Otro caso común es que tengas muchas URLs independientes que quieres scrapear (por ejemplo, un listado de 100 enlaces a fichas de productos, o varias noticias individuales). En lugar de hacer un loop y llamar a await crawler.arun secuencialmente en cada URL (lo cual funcionaría pero no aprovecharía la concurrencia), puedes aprovechar que Crawl4AI maneja la paralelización interna.

La forma más sencilla es usar el método arun_many(), que toma una lista de URLs y las procesa concurrentemente utilizando un dispatcher interno optimizado docs.crawl4ai.com docs.crawl4ai.com. Ejemplo:

Aquí pasamos una lista de URLs a arun_many y este nos devuelve una lista de objetos CrawlResult correspondientes, una vez que se han completado todos (o a medida que completan, pero la función espera al final para retornar la lista). Internamente, Crawl4AI utiliza “dispatchers” que administran la concurrencia teniendo en cuenta la memoria disponible y haciendo rate limiting si es necesario para no sobrecargar el sistema ni el sitio objetivo docs.crawl4ai.com docs.crawl4ai.com. Es decir, no lanza 100 peticiones simultáneas de golpe sin control; va adaptándose. Esto es mucho más eficiente que un bucle secuencial: muchas páginas se cargarán en paralelo aprovechando tiempos muertos de I/O.

La librería ofrece diferentes estrategias de dispatch (por ejemplo, basada en número fijo de workers, o adaptativa basada en memoria). Por defecto arun_many elige una adaptativa que optimiza rendimiento y seguridad docs.crawl4ai.com, pero puedes profundizar en la documentación de Crawl Dispatcher si necesitas afinar este comportamiento.

Conclusión de esta sección: Crawl4AI permite escalar tanto en profundidad (navegando dentro de un sitio) como en amplitud (procesando muchas URLs independientes) de manera eficiente. Ya sea que necesites raspar 1 página o 1000 páginas, la herramienta ofrece las abstracciones para hacerlo de forma óptima y con mínimo esfuerzo de tu parte en cuanto a concurrencia. ¡Solo recuerda fijar límites razonables y ser considerado con los sitios que rastreas docs.crawl4ai.com

Despliegue en servidor con Docker ¶

Si planeas usar Crawl4AI como parte de una aplicación web, un servicio backend o simplemente quieres aislar tu entorno, Docker es tu amigo. La imagen oficial de Crawl4AI empaqueta todo lo necesario (Python, Playwright, etc.) y expone una API REST sencilla para realizar crawls remotamente.

Revisemos cómo desplegar y usar Crawl4AI vía Docker:

Obtener la imagen: Ya lo mencionamos en la sección de instalación, pero reiteramos el comando:
Esto descarga la última versión publicada de la imagen Docker apidog.com. (Nota: Puedes sustituir latest por una versión o tag específico si lo deseas, por ejemplo 0.6.0).
Ejecutar el contenedor:
Este comando inicia el contenedor en segundo plano (-d), mapeando el puerto 11235 tanto en el host como en el contenedor (puerto por defecto que usa la aplicación interna) apidog.com. Asignamos un nombre crawl4ai al contenedor y ajustamos --shm-size=1g para darle 1GB de shared memory (esto mejora la estabilidad de navegadores headless). Una vez ejecutado, el servicio Crawl4AI estará corriendo dentro del contenedor.
Acceder a la API/Playground: Crawl4AI en Docker utiliza FastAPI para exponer endpoints HTTP. Puedes abrir en tu navegador http://localhost:11235/playground para ver una interfaz web minimalista donde probar la API interactiva apidog.com. Desde allí, por ejemplo, puedes introducir una URL y hacer click en “Crawl” para obtener el resultado en JSON/Markdown. También hay documentación interactiva de la API en http://localhost:11235/docs gracias a Swagger UI.
Usar la API en tus aplicaciones: El servicio expone endpoints como /crawl donde puedes hacer un POST con un JSON que especifique la URL y opciones, y obtendrás de respuesta el resultado del crawl. Por ejemplo, vía curl:
Esto retornaría un JSON con campos similares a CrawlResult (incluyendo el markdown obtenido). Puedes así integrar Crawl4AI en cualquier lenguaje o entorno que pueda hacer peticiones HTTP. Piensa que podrías tener tu propio web scraping API montada en un servidor accesible a otros servicios.

Ventajas del despliegue Docker:

Aíslas el entorno de scraping del resto de tu aplicación, evitando conflictos de dependencias y facilitando la escalabilidad (puedes correr múltiples contenedores detrás de un balanceador si necesitas más throughput).
Viene con mejoras como browser pooling: el contenedor puede mantener instancias de navegador pre-iniciadas para manejar múltiples peticiones entrantes más rápidamente github.com.
Incluye la integración MCP (Machine Conversation Protocol) para conectar agentes de IA de terceros directamente. Por ejemplo, permite que herramientas como Anthropic Claude o otros agentes puedan utilizar el crawler a través de este protocolo de conversació**n github.com (esto es avanzado, pero muestra la visión orientada a IA de Crawl4AI).
La API es extensiva: además de /crawl, permite tomar screenshots, extraer PDFs, ejecutar scripts JS, etc., según las últimas actualizaciones. Puedes consultar la documentación específica de la API para ver todo lo que ofrece el modo servidor.

En definitiva, con Docker puedes convertir Crawl4AI en un servicio de crawling escalable. Por ejemplo, en un flujo de trabajo empresarial podrías desplegarlo en un servidor cloud y hacer que distintas aplicaciones le envíen URLs para extraer contenido en tiempo real. Dado que es stateless (cada petición es independiente, a menos que utilices sesiones deliberadamente), escala bien horizontalmente.

(Recuerda asegurar el acceso a este servicio si lo dejas expuesto en red, ya que potencialmente alguien podría abusar de él. Si es interno, mejor).

Integración con flujos RAG y agentes de IA ¶

Finalmente, hablemos de cómo encaja Crawl4AI en flujos de IA de más alto nivel, como Retrieval-Augmented Generation (RAG) y agentes autónomos tipo LangChain, AutoGPT, etc. Ya hemos ido mencionando piezas de esto, pero lo resumiremos en puntos claros:

Contenido “LLM-ready”: Una de las motivaciones centrales de Crawl4AI es servir contenido a modelos de lenguaje. La herramienta genera Markdown limpio, imágenes descargadas, metadatos estructurados, todo de forma que un modelo lo pueda consumir fácilmente docs.crawl4ai.com. Por ejemplo, en un pipeline RAG típico, primero se recopilan documentos relevantes, luego se indexan (p. ej. en un vector store) y finalmente un modelo los utiliza para responder preguntas. Crawl4AI facilita la etapa de recopilación y limpieza de documentos web, devolviéndolos en Markdown estructurado ideal para alimentar a la siguiente fase sin tener que limpiar HTML o eliminar boilerplate manualmente. Según la documentación, esta característica es “Perfecta para pipelines RAG o ingesta directa en LLMs” docs.crawl4ai.com.
Extracción estructurada para conocimiento: Si tu flujo RAG requiere datos muy específicos (ej. poblaciones, precios, eventos de un texto), puedes usar las estrategias de extracción (CSS/XPath o LLM) para obtener ya los datos en JSON y alimentar directamente tu base de conocimiento. Esto ahorra al modelo tener que “entender” todo el texto cada vez; en su lugar, le presentas info ya digerida. Por ejemplo, podrías crawllear un sitio de e-commerce extrayendo producto, precio, descripción en JSON y cargar esos datos en una base para que el modelo luego responda sobre ellos.
Agentes que navegan la web: En frameworks como LangChain existe el concepto de web browsing tool donde un agente de IA decide realizar búsquedas o leer páginas para obtener información actualizada. Crawl4AI puede ser el motor detrás de esa navegación. De hecho, gracias al despliegue en Docker con API, un agente puede simplemente llamar a la API de Crawl4AI con una URL y obtener el contenido medium.com. Alternativamente, dentro de un agente basado en Python, se podría invocar a Crawl4AI directamente (aunque habría que manejar el bucle de eventos async). Lo importante es que, a diferencia de soluciones de scraping tradicionales, Crawl4AI ya devuelve la página en un formato entendible por la IA (Markdown o JSON), evitando tener que convertir HTML o PDFs sobre la marcha.
Preguntas y sumarios on-the-fly: Crawl4AI integra la posibilidad de hacer Q&A o resúmenes con LLMs sobre las páginas (vía la opción -q en CLI o usando LLMExtractionStrategy con una instrucción tipo “resume el contenido”) docs.crawl4ai.com. Esto significa que en un flujo RAG, podrías incluso saltarte almacenar todo el documento y en su lugar preguntar algo específico al LLM mientras crawleas la página. Por ejemplo: un agente podría navegar a una página y directamente preguntar " ¿Cuál es la conclusión principal de esta página?". Crawl4AI internamente cargaría la página y usaría el LLM para responderte docs.crawl4ai.com. Este enfoque de “crawling dirigido por pregunta” es potente, aunque requiere confiar en la respuesta del LLM. En general, lo común es usar RAG para permitir al modelo buscar en los datos extraídos, pero es bueno saber que esta capacidad existe para ciertos casos dinámicos.
Ejemplo de flujo integrado: Imagina un asistente de investigación que dado un tema, busca artículos en la web, extrae su contenido, y luego permite al usuario hacer preguntas. Crawl4AI sería el componente que:
1. Realiza búsquedas (posiblemente integrando con una API de búsqueda o teniendo una lista de URLs relevantes).
2. Crawls cada URL obtenida generando Markdown limpio de cada artículo apidog.com.
3. Opcional: extrae datos estructurados (fechas, autores, etc.) si se requieren meta-datos.
4. Indexa el contenido en un vector store o base de conocimiento.
5. Luego, el usuario hace una pregunta y el sistema utiliza el contenido recolectado para componer una respuesta (este paso ya puede ser manejado por frameworks tipo LangChain o LlamaIndex con un modelo de lenguaje).
  Crawl4AI se encarga de la parte 2 de forma ejemplar: rápida, limpia y efectiva, permitiendo que el pipeline completo sea más robusto. Al compararlo con usar un scraper básico o API de navegador, la diferencia es que aquí ya tenemos contenido optimizado para IA (por ejemplo, formateado con títulos, listas, etc., en Markdown) y no necesitamos post-procesamiento complejo apidog.com apidog.com.
Integración con agentes de código/automatización: Mencionamos la integración MCP incluida en la versión Docker, que sugiere que herramientas como Claude pueden controlar el crawler. Esto apunta a futuros desarrollos donde un agente pueda decir “abre tal página, extrae esto, ve a este link, etc.” interactuando con Crawl4AI de manera conversacional. Aunque esto es avanzado, demuestra la intención de que Crawl4AI sea el brazo de exploración web de los agentes de IA. Al ser open source, también puedes integrarlo manualmente: por ejemplo, en AutoGPT podrías añadirlo como herramienta Python para obtener contenido web en vez del método de browsing por defecto.

En pocas palabras, Crawl4AI cierra la brecha entre el mundo web (HTML, navegadores) y el mundo IA (modelos de lenguaje, pipelines de datos). Su enfoque AI-centric lo hace ideal para cualquier aplicación donde necesites alimentar a un modelo con información fresca de la web. Proporciona la información de manera estructurada y depurada, lista para que el modelo la consuma sin distracciones apidog.com.

Esto habilita casos de uso como chatbots actualizados con la última información (crawlean noticias al momento), asistentes capaces de responder preguntas sobre documentación en línea, o agentes que realizan tareas en la web y resumen resultados. Gracias a su licencia abierta, puedes integrarlo sin costos ocultos, y adaptarlo a tus necesidades si fuera necesario.

Conclusiones y recursos adicionales ¶

En este tutorial hemos recorrido desde la instalación y primeros pasos hasta funcionalidades avanzadas de Crawl4AI. Recapitulando brevemente:

Aprendimos a instalar la librería con pip y a configurar Playwright apidog.com, además de la alternativa de usar Docker para desplegar un servicio de crawling apidog.com.
Vimos cómo hacer un crawling básico con apenas unas líneas de Python o un simple comando CLI, obteniendo contenido en Markdown listo para usar apidog.com.
Exploramos la extracción estructurada mediante selectores CSS/XPath, definiendo esquemas JSON para obtener datos específicos de las páginas apidog.com apidog.com.
Hablamos de la integración con LLMs, tanto para extracción avanzada como para hacer preguntas, incluyendo consideraciones de chunking y proveedores de modelos docs.crawl4ai.com docs.crawl4ai.com.
Profundizamos en los filtros de contenido que permiten generar Markdown enfocado en lo importante, y cómo ajustarlos (heurístico general vs. basado en consultas) docs.crawl4ai.com docs.crawl4ai.com.
Vimos cómo reutilizar sesiones para flujos de varios pasos o navegación autenticada, manteniendo estado entre solicitudes docs.crawl4ai.com docs.crawl4ai.com.
Configuramos el uso de proxies para anonimato o geolocalización de las peticiones, incluyendo proxies con autenticación y rotación docs.crawl4ai.com docs.crawl4ai.com.
Aprovechamos las capacidades de rastreo profundo (BFS/DFS) para explorar sitios automáticamente y concurrencia para paralelizar múltiples descargas, con control de límites para no sobrecargar nuestro entorno ni los sitios objetivo apidog.com docs.crawl4ai.com.
Finalmente, discutimos cómo integrar Crawl4AI en escenarios de IA, destacando su utilidad en pipelines de RAG (conocimiento aumentado) y su rol como herramienta en agentes inteligentes que necesitan leer y extraer información de la web apidog.com.

Como puedes ver, Crawl4AI es una herramienta muy completa que combina lo mejor de dos mundos: el web scraping de alto rendimiento y las necesidades de la IA moderna. Todo esto con una API sencilla y una comunidad activa detrás (no olvides que puedes visitar el repositorio en GitHub para encontrar ejemplos, reportar issues o contribuir).

Recursos adicionales recomendados:

Documentación oficial (en inglés): El sitio docs.crawl4ai.com docs.crawl4ai.com contiene guías y referencias detalladas, incluyendo secciones que no cubrimos a fondo, como interacción con páginas (relleno de formularios, clicks), manejo de contenido multimedia, estrategias de clustering de contenidos, etc.
Tutoriales y blogs: Existe una guía introductoria “Crawl4AI Tutorial: A Beginner’s Guide” de Mark Ponomarev apidog.com apidog.com y artículos en Medium que comparan Crawl4AI con otras herramientas. Estos recursos (en inglés) pueden darte otra perspectiva y trucos prácticos.
Discord/Comunidad: Crawl4AI fue tendencia en GitHub y tiene una comunidad creciente. Si tienes dudas o quieres estar al día de las novedades (por ejemplo, la versión 0.6.0 agregó características como geolocalización, pooling de navegadores y captura de tráfico de red), puedes unirte al Discord oficial o seguir el proyecto para enterarte de nuevas versiones github.com github.com.

Esperamos que este tutorial te haya sido útil para comenzar con Crawl4AI. ¡Ahora cuentas con una potente herramienta para rastrear la web y potenciar tus proyectos de inteligencia artificial con datos frescos y bien estructurados! Si no tienes experiencia previa con Python, no te preocupes: con los ejemplos suministrados y la CLI disponible, pronto te familiarizarás con el flujo de trabajo. ¡Feliz crawling! 🚀