Blog

Crawl4AI Tutorial: Guia Para Iniciantes

Audrey Lopez

Audrey Lopez

30 abril 2025

Crawl4AI Tutorial: Guia Para Iniciantes

Na era da IA, acessar e processar dados da web de forma eficiente é crucial. Crawl4AI surge como um poderoso crawler e scraper web de código aberto, meticulosamente projetado para desenvolvedores que trabalham com Large Language Models (LLMs), agentes de IA e pipelines de dados modernos. Este tutorial oferece um mergulho profundo no Crawl4AI, cobrindo tudo, desde a instalação até técnicas avançadas de crawling.

💡
Quer uma ótima ferramenta de Teste de API que gera Documentação de API linda?

Quer uma plataforma integrada, All-in-One para sua Equipe de Desenvolvedores trabalhar com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman a um preço muito mais acessível!
button

Por que Escolher o Crawl4AI para Seus Projetos?

O Crawl4AI é mais do que apenas um scraper web padrão. Ele foi projetado do zero para ser amigável a LLMs. Isso significa que ele foca em:

O Crawl4AI visa democratizar o acesso a dados, capacitando desenvolvedores a coletar e moldar dados da web com velocidade e eficiência.

Instalando e Configurando o Crawl4AI

Colocar o Crawl4AI para rodar é simples, oferecendo opções tanto via pip quanto via Docker.

Método 1: Instalação com Pip (Recomendado para Uso como Biblioteca)

Instale o Pacote: Abra seu terminal e execute:

# Instalar a versão estável mais recente
pip install -U crawl4ai

# Ou, instalar a última versão pré-lançamento (para recursos de ponta)
# pip install crawl4ai --pre

Execute a Configuração Pós-Instalação: Este passo crucial instala os binários de navegador Playwright necessários (Chromium por padrão):

crawl4ai-setup

Verifique: Verifique sua configuração usando a ferramenta de diagnóstico:

crawl4ai-doctor

Resolução de Problemas: Se crawl4ai-setup encontrar problemas, instale manualmente as dependências do navegador:

python -m playwright install --with-deps chromium

Método 2: Implantação com Docker (Ideal para Serviço de API)

Puxe a Imagem: Obtenha a imagem oficial do Docker (verifique o GitHub para a tag mais recente):

# Tag de exemplo, substitua se necessário
docker pull unclecode/crawl4ai:latest

Execute o Container: Inicie o serviço Crawl4AI, expondo sua API (porta padrão 11235):

docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g unclecode/crawl4ai:latest

Isso executa o Crawl4AI com um backend FastAPI, pronto para aceitar requisições de crawling via HTTP. Você pode acessar um playground de API interativo em http://localhost:11235/playground.

Como Executar Seu Primeiro Crawl com o Crawl4AI

O Crawl4AI torna o crawling básico incrivelmente simples usando o AsyncWebCrawler.

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode

async def run_basic_crawl():
    # --- Exemplo Básico ---
    print("--- Executando Crawl Básico ---")
    # Use 'async with' para inicialização e desligamento automático do navegador
    async with AsyncWebCrawler() as crawler:
        # O método arun() executa o crawl para uma única URL
        # Ele retorna um objeto CrawlResult
        result = await crawler.arun(url="https://example.com")

        if result and result.success:
            # Acesse o Markdown gerado (geralmente 'fit_markdown')
            print("Crawl Bem-sucedido!")
            # result.markdown fornece markdown bruto e filtrado
            print(f"Fit Markdown (primeiros 300 caracteres): {result.markdown.fit_markdown[:300]}...")
        else:
            print(f"Crawl Falhou: {result.error_message}")

    # --- Exemplo com Configuração Básica ---
    print("\n--- Executando Crawl com Configuração Básica ---")
    # Configurar o comportamento do navegador (por exemplo, rodar headful para depuração)
    browser_conf = BrowserConfig(headless=True) # Defina como False para ver a janela do navegador

    # Configurar definições específicas da execução (por exemplo, ignorar cache)
    # CacheMode.ENABLED (padrão), CacheMode.DISABLED, CacheMode.BYPASS
    run_conf = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)

    async with AsyncWebCrawler(config=browser_conf) as crawler:
        result = await crawler.arun(
            url="https://crawl4ai.com/", # Crawl do site oficial
            config=run_conf # Aplicar a configuração de execução
        )
        if result and result.success:
            print("Crawl Bem-sucedido!")
            print(f"Contagem de Palavras do Fit Markdown: {result.markdown.word_count}")
            print(f"URL Rastreada: {result.url}")
        else:
            print(f"Crawl Falhou: {result.error_message}")

if __name__ == "__main__":
    asyncio.run(run_basic_crawl())

Conceitos Chave do Crawl4AI:

Como Funciona o Objeto CrawlResult do Crawl4AI?

Cada chamada bem-sucedida de arun ou arun_many retorna um ou mais objetos CrawlResult, que encapsulam todas as informações coletadas durante o crawl.

O objeto CrawlResult contém vários atributos, incluindo:

Inspecionar este objeto é fundamental para acessar os dados específicos que você precisa de um crawl do Crawl4AI.

Como Gerar Markdown Pronto para IA com o Crawl4AI

Uma força central do Crawl4AI é sua capacidade de gerar Markdown limpo, adequado para LLMs.

O atributo result.markdown contém:

Você pode personalizar o processo de filtragem no Crawl4AI:

import asyncio
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, CacheMode
# Importar estratégias específicas para personalização
from crawl4ai.content_filter_strategy import PruningContentFilter
from crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerator

async def run_custom_markdown_crawl():
    print("\n--- Executando Crawl com Filtragem de Markdown Personalizada ---")

    # Configurar um gerador de Markdown com um filtro de conteúdo específico
    # PruningContentFilter remove elementos com base em limites de contagem de palavras
    markdown_generator_with_filter = DefaultMarkdownGenerator(
        content_filter=PruningContentFilter(
            threshold=0.48, # Ajustar limite (0 a 1) para rigidez
            threshold_type="fixed" # 'fixed' ou 'relative'
            )
    )

    # Aplicar este gerador na configuração de execução
    run_conf = CrawlerRunConfig(
        cache_mode=CacheMode.BYPASS,
        markdown_generator=markdown_generator_with_filter
    )

    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(
            url="https://www.nbcnews.com/business", # Um site de notícias geralmente tem lixo
            config=run_conf
        )
        if result and result.success:
            print("Crawl Bem-sucedido!")
            print(f"Comprimento do Raw Markdown: {len(result.markdown.raw_markdown)}")
            print(f"Comprimento do Fit Markdown: {len(result.markdown.fit_markdown)}") # Geralmente mais curto
            # Compare raw_markdown e fit_markdown para ver o efeito do filtro
        else:
            print(f"Crawl Falhou: {result.error_message}")

if __name__ == "__main__":
    asyncio.run(run_custom_markdown_crawl())

Ajustando o content_filter dentro do markdown_generator, você controla quão agressivamente o Crawl4AI limpa o conteúdo antes de produzir o fit_markdown.

Como Usar o Crawl Profundo do Crawl4AI

O Crawl4AI não se limita a páginas únicas. Ele pode realizar crawls profundos, navegando por um site seguindo links.

Use o método adeep_crawl (ou a flag --deep-crawl da CLI crwl):

import asyncio
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, CacheMode

async def run_deep_crawl():
    print("\n--- Executando Crawl Profundo ---")
    # A configuração pode ser aplicada globalmente ou por execução, como de costume
    run_conf = CrawlerRunConfig(cache_mode=CacheMode.ENABLED)

    async with AsyncWebCrawler() as crawler:
        # adeep_crawl retorna um gerador assíncrono, produzindo resultados conforme as páginas terminam
        crawl_generator = await crawler.adeep_crawl(
            start_url="https://docs.crawl4ai.com/", # Ponto de partida
            strategy="bfs", # 'bfs' (Busca em Largura), 'dfs' (Busca em Profundidade), 'bestfirst'
            max_depth=2,    # Limitar a profundidade dos links a seguir
            max_pages=10,   # Limitar o número total de páginas a rastrear
            config=run_conf
        )

        # Processar resultados conforme chegam
        pages_crawled = 0
        async for result in crawl_generator:
            if result.success:
                print(f"[OK] Rastreado: {result.url} (Profundidade: {result.depth}, Comprimento do Fit Markdown: {len(result.markdown.fit_markdown)})")
                pages_crawled += 1
            else:
                print(f"[FALHA] URL: {result.url}, Erro: {result.error_message}")

        print(f"\nCrawl profundo finalizado. Total de páginas rastreadas com sucesso: {pages_crawled}")

if __name__ == "__main__":
    asyncio.run(run_deep_crawl())

Parâmetros de Crawl Profundo do Crawl4AI:

Como Lidar com Conteúdo Dinâmico e Interações com o Crawl4AI

Sites modernos dependem muito de JavaScript para carregar conteúdo. O Crawl4AI lida com isso através das capacidades do Playwright.

Você pode executar JavaScript arbitrário ou esperar por condições específicas usando CrawlerRunConfig:

import asyncio
import json
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode
from crawl4ai.extraction_strategy import JsonCssExtractionStrategy # Por exemplo

async def crawl_dynamic_page():
    print("\n--- Rastreado Página Dinâmica com Interação JS ---")

    # Exemplo de esquema para extração CSS (adaptar ao site alvo)
    schema = { "items": { "selector": "div.product-item", "type": "list", "fields": { "title": "h2", "price": ".price" } } }
    css_extractor = JsonCssExtractionStrategy(schema)

    # JavaScript a ser executado na página (por exemplo, clicar em um botão 'Carregar Mais')
    # Nota: O seletor precisa corresponder ao site alvo
    js_to_run = """
    (async () => {
        const loadMoreButton = document.querySelector('button#load-more');
        if (loadMoreButton) {
            console.log('Clicando no botão carregar mais...');
            loadMoreButton.click();
            // Esperar um pouco para o conteúdo carregar potencialmente após o clique
            await new Promise(resolve => setTimeout(resolve, 2000));
            console.log('Esperou após o clique.');
        } else {
            console.log('Botão carregar mais não encontrado.');
        }
    })();
    """

    run_conf = CrawlerRunConfig(
        cache_mode=CacheMode.BYPASS,
        js_code=[js_to_run], # Lista de trechos de JS para executar
        wait_for_timeout=3000, # Esperar 3 segundos após o carregamento inicial E após a execução do JS
        # wait_for_selector="div.newly-loaded-content", # Ou esperar por um elemento específico
        extraction_strategy=css_extractor, # Extrair dados após a execução do JS
        output_formats=['markdown', 'extracted_content']
    )

    # Garantir que o JS esteja habilitado em BrowserConfig (É por padrão)
    browser_conf = BrowserConfig(headless=True, java_script_enabled=True)

    async with AsyncWebCrawler(config=browser_conf) as crawler:
        result = await crawler.arun(
            url="URL_OF_DYNAMIC_PAGE_HERE", # Substituir pela URL real
            config=run_conf
        )

        if result and result.success:
            print("Crawl de página dinâmica bem-sucedido!")
            print(f"Comprimento do Fit Markdown: {len(result.markdown.fit_markdown)}")
            if result.extracted_content:
                try:
                    extracted_data = json.loads(result.extracted_content)
                    print(f"Prévia do Conteúdo Extraído: {json.dumps(extracted_data, indent=2)[:500]}...")
                except json.JSONDecodeError:
                    print(f"Conteúdo Extraído (não JSON): {result.extracted_content[:500]}...")
        else:
            print(f"Crawl Falhou: {result.error_message}")


if __name__ == "__main__":
    # Por favor, substitua 'URL_OF_DYNAMIC_PAGE_HERE' e descomente a linha acima para executar o exemplo dinâmico.
    # asyncio.run(crawl_dynamic_page())
    print("Por favor, substitua 'URL_OF_DYNAMIC_PAGE_HERE' e descomente a linha acima para executar o exemplo dinâmico.")

Parâmetros Chave de Interação do Crawl4AI em CrawlerRunConfig:

Conclusão do Crawl4AI

O Crawl4AI oferece uma solução abrangente, Pythonica e centrada em IA para web crawling e scraping. Seu foco na geração de Markdown limpo, extração flexível de dados estruturados (baseada em CSS e LLM), manipulação robusta de conteúdo dinâmico e operação assíncrona eficiente o torna uma excelente escolha para projetos envolvendo RAG, fine-tuning de LLM, ou qualquer tarefa que exija informações estruturadas da web. Ao alavancar sua API clara, opções de configuração (BrowserConfig, CrawlerRunConfig) e objeto CrawlResult detalhado, desenvolvedores podem construir fluxos de trabalho de coleta de dados sofisticados e eficientes.

💡
Quer uma ótima ferramenta de Teste de API que gera Documentação de API linda?

Quer uma plataforma integrada, All-in-One para sua Equipe de Desenvolvedores trabalhar com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman a um preço muito mais acessível!
button

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar