Trafilatura Web Scraping: Extração Limpa de Texto para LLMs

TL;DR:

• Trafilatura transforma uma página HTML bruta em um texto limpo do conteúdo principal, eliminando navegação, barras laterais e rodapés para que um modelo de linguagem veja o conteúdo e não a interface.
• Na página de exemplo, 9.275 caracteres de HTML se tornam 1.324 caracteres de texto limpo, uma redução de 86% que vai direto para a janela de contexto de um LLM.
• Trafilatura não possui uma camada de busca que limpa blocos, então este guia combina Scrapeless para recuperação com trafilatura para extração.
• trafilatura.extract produz texto simples, e a mesma chamada com output_format="markdown" ou "json" dá o Markdown ou um registro de metadados com o título, autor e data.
• A divisão é limpa: Scrapeless obtém a página, trafilatura extrai o artigo dela.
• Comece no plano gratuito do Scrapeless e direcione o extrator para suas próprias páginas.

Uma página HTML raspada geralmente não é o que você quer. Navegação, banners de cookies, trilhos de artigos relacionados e rodapés podem compor a maior parte dos bytes, e alimentar tudo isso a um modelo de linguagem desperdiça tokens e dilui o sinal. Trafilatura resolve a segunda metade desse problema: dado um HTML, encontra o conteúdo principal e o retorna como texto limpo. Não resolve a primeira metade, porque não pode buscar uma página que resista.

Este guia combina as duas partes. A API Universal de Raspagem do Scrapeless recupera a página, e trafilatura extrai o artigo. Cada número abaixo vem de uma execução real contra uma página pública.

O que Trafilatura Faz

Trafilatura é uma biblioteca de extração de conteúdo principal: lê HTML e retorna o texto do artigo sem a estrutura ao redor. Ela analisa a estrutura da página para distinguir conteúdo da navegação, e sua qualidade de extração é avaliada em o artigo revisado por pares que a introduziu. Para qualquer pessoa construindo um pipeline de recuperação ou LLM, essa é a etapa entre "Eu tenho o HTML" e "Eu tenho texto que vale a pena embutir."

O que trafilatura não é, é um raspador. Ela não tem navegador, nem proxy, e nenhuma forma de passar por um desafio de acesso. Seu fetch_url embutido é um cliente HTTP simples, então em uma página protegida ela retorna uma página de bloqueio e extrai o bloco de forma diligente. É por isso que a recuperação pertence a uma ferramenta construída para isso.

Instalação

Trafilatura é uma instalação simples via pip.

pip install trafilatura

Defina sua chave Scrapeless no shell. Use a chave real em tempo de execução e mantenha o espaço reservado fora do seu código-fonte.

export SCRAPELESS_API_KEY="sk_your_key_here"

Extração Básica

Recupere a página com o Scrapeless e então entregue o HTML para trafilatura.extract. Isso retorna o conteúdo principal como texto limpo.

import json
import os
import urllib.request

import trafilatura

API_URL = "https://api.scrapeless.com/api/v2/unlocker/request"
TARGET = "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"


def fetch_html(url: str) -> str:
    payload = json.dumps(
        {"actor": "unlocker.webunlocker", "input": {"url": url, "js_render": False, "headless": False}}
    ).encode()
    request = urllib.request.Request(
        API_URL,
        data=payload,
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"], "Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=90) as response:
        return json.loads(response.read())["data"]


html = fetch_html(TARGET)
text = trafilatura.extract(html)
print(f"caracteres html brutos: {len(html)}")
print(f"caracteres texto limpo: {len(text)}")
print(f"boilerplate removido: {100 * (1 - len(text) / len(html)):.0f}%")

A saída mostra o quanto a página encolhe uma vez que a estrutura é removida.

caracteres html brutos: 9275
caracteres texto limpo: 1324
boilerplate removido: 86%

Os 1.324 caracteres que permanecem são o título, preço, disponibilidade e descrição do produto; a navegação, trilhas de navegação e rodapé foram removidos. Essa redução de 86% são tokens que você não paga mais a um modelo para ler.

Markdown e Metadados

Texto simples é o padrão, mas um pipeline de recuperação geralmente quer estrutura. A mesma chamada extract aceita um output_format, então Markdown mantém os cabeçalhos e listas que um modelo lê bem.

markdown = trafilatura.extract(html, output_format="markdown")
print(f"caracteres markdown: {len(markdown)}")

Para proveniência, solicite JSON com metadados. O registro carrega o título, autor, hostname, data e idioma junto com o texto, que é o que você armazena ao lado de uma incorporação para que um pedaço recuperado possa citar sua fonte.

record = json.loads(trafilatura.extract(html, output_format="json", with_metadata=True))
print(f"title: {record['title']}")

O Extrator Completo

Coloque a busca, o texto, o Markdown e os metadados juntos, e um script leva uma URL para tudo que um pipeline downstream precisa.

import json
import os
import urllib.request

import trafilatura

API_URL = "https://api.scrapeless.com/api/v2/unlocker/request"
TARGET = "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"


def fetch_html(url: str) -> str:
    payload = json.dumps(
        {"actor": "unlocker.webunlocker", "input": {"url": url, "js_render": False, "headless": False}}
    ).encode()
    request = urllib.request.Request(
        API_URL,
        data=payload,
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"], "Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=90) as response:
        return json.loads(response.read())["data"]


html = fetch_html(TARGET)
print(f"caracteres de html bruto: {len(html)}")

text = trafilatura.extract(html)
print(f"caracteres de texto limpo: {len(text)}")
print(f"boilerplate removido: {100 * (1 - len(text) / len(html)):.0f}%")

markdown = trafilatura.extract(html, output_format="markdown")
print(f"caracteres de markdown: {len(markdown)}")

record = json.loads(trafilatura.extract(html, output_format="json", with_metadata=True))
print(f"título: {record['title']}")

A execução relata cada saída que o pipeline consome.

caracteres de html bruto: 9275
caracteres de texto limpo: 1324
boilerplate removido: 86%
caracteres de markdown: 1474
título: A Light in the Attic

Onde Trafilatura Para

Trafilatura extrai; não recupera além de um bloco, e essa fronteira é a razão pela qual este guia usa duas ferramentas. Apontar a própria busca da trafilatura para uma página protegida resulta em um desafio ou uma shell vazia, e então não extrai nada útil dela. O Scrapeless lida com a recuperação, retornando o HTML renderizado, e a trafilatura assume a partir daí. Quando um alvo renderiza seu artigo com JavaScript, defina js_render como True na solicitação para que o HTML que a trafilatura recebe já contenha o conteúdo; mantenha como False, como aqui, quando a marcação é renderizada pelo servidor.

Antes de rodar isso em um site, leia seu robots.txt e termos. O Protocolo de Exclusão de Robôs declara quais caminhos um site pede a clientes automatizados para evitar, e respeitá-lo mantém um pipeline de extração sustentável. Para uma visão mais ampla da ingestão, o guia sobre como construir um pipeline de texto limpo para RAG mostra onde esse passo de extração se encaixa.

Pronto para tentar em suas próprias páginas? Crie uma conta gratuita no Scrapeless e mude a URL alvo.

Conclusão

Texto limpo é o que um modelo de linguagem realmente precisa, e chegar lá é feito em duas etapas: recuperar, depois extrair. O Scrapeless retorna a página, e a trafilatura transforma 9.275 caracteres de HTML em 1.324 caracteres de conteúdo, em texto, Markdown ou um registro de metadados. A documentação da trafilatura cobre os formatos de saída e opções de ajuste em detalhes. Comece com o script completo, troque pela sua própria URL e forneça o resultado para sua etapa de incorporação ou LLM.

Comece com o plano gratuito do Scrapeless para recuperar suas próprias páginas e consulte preços do Scrapeless quando dimensionar um trabalho recorrente.

FAQ

Q: A trafilatura busca páginas da web por conta própria?

Ela possui um fetch_url embutido, mas esse é um cliente HTTP simples sem desbloqueio, portanto falha em páginas atrás de um desafio de acesso. Combine-a com uma ferramenta de recuperação como o Scrapeless que retorna HTML renderizado, e deixe a trafilatura fazer o que sabe fazer, que é extrair o conteúdo principal desse HTML.

Q: Como a trafilatura é diferente do BeautifulSoup?

O BeautifulSoup é um analisador: você diz a ele quais elementos selecionar. A trafilatura é um extrator: ela decide qual parte da página é o conteúdo principal e o retorna, sem seletores para escrever. Use o BeautifulSoup quando você precisar de campos específicos, e a trafilatura quando quiser o corpo do artigo como texto limpo.

Q: Quais formatos de saída a trafilatura suporta?

A função extract aceita um output_format de txt (o padrão), markdown, json ou xml. O Markdown mantém cabeçalhos e listas para entrada LLM, e JSON com with_metadata=True adiciona o título, autor, data e idioma ao lado do texto.

Q: A trafilatura consegue manter o título e o autor?
Sim. Chame extract com output_format="json" e with_metadata=True, e o registro retornado inclui title, author, hostname, date e language. Armazenar esses metadados junto com uma incorporação permite que um bloco recuperado informe de onde veio.

Q: Por que extrair o conteúdo principal em vez de enviar a página inteira para um LLM?

A maior parte de uma página é navegação, anúncios e rodapés, que, no exemplo, correspondem a 86% dos caracteres. Enviar tudo isso custa tokens e esconde o sinal, então extrair primeiro o conteúdo principal reduz custos e melhora o foco do modelo no texto que realmente importa.