resiliparse Web Scraping: Extração Rápida de HTML para Texto

Resumo:

• resiliparse transforma HTML em texto limpo rapidamente, usando um núcleo de extração em C++ projetado para processar arquivos da web em escala de bilhões de páginas.
• main_content=True remove o conteúdo padrão. Ele retorna o texto do artigo sem a navegação, login e rodapé que uma exportação de texto ingênua mantém.
• O que o resiliparse não faz é buscar. Ele não possui cliente HTTP e não executa JavaScript; forneça a ele uma marcação e ele extrai.
• A diferença aparece em um script. Um simples GET em uma página de demonstração renderizada em JavaScript retorna 23 caracteres de texto; a mesma URL buscada através da API de Raspagem Universal Scrapeless com js_render fornece o conteúdo real.
• A extração é real neste guia. Uma execução ao vivo reduziu 10.968 caracteres de HTML renderizado para 1.469 caracteres de texto limpo do conteúdo principal.
• Gratuito para começar na parte de busca. Crie sua chave de API Scrapeless em app.scrapeless.com.

O que é o resiliparse e o que não é

resiliparse é a parte de análise e extração da ferramenta ChatNoir Resiliparse, construída pelo grupo de pesquisa do Arquivo da Web para processar o Common Crawl e corpora similares. Sua extração de HTML para texto roda em um núcleo C++, que é a razão pela qual permanece rápida quando a entrada é milhões de documentos em vez de um. A função que você mais usa é extract_plain_text, e seu modo main_content=True é a parte útil: remove a navegação, barras laterais e rodapés que tornam uma exportação de texto bruta barulhenta, deixando o conteúdo que o leitor realmente veio buscar.

É uma biblioteca de extração, não um raspador. resiliparse não possui cliente HTTP, não mantém sessão e não executa JavaScript. Dê-lhe uma string ou bytes e ele retornará texto; peça-lhe para buscar uma URL e não há método para isso. Portanto, toda configuração de "raspagem web do resiliparse" consiste em duas camadas: algo que retorna HTML fiel e resiliparse que extrai dele. Este guia usa a API de Raspagem Universal Scrapeless para a primeira camada, porque um simples cliente HTTP retorna a marcação pré-renderizada em qualquer página que constrói seu conteúdo com JavaScript — e a marcação vazia extrai texto vazio. Para campos estruturados em vez de texto legível, o tutorial de raspagem web em Python aborda a rota baseada em seletores.

Instalação

resiliparse e requests são toda a cadeia de ferramentas. A versão para a qual este guia foi escrito é resiliparse 1.0.9:

pip install "resiliparse==1.0.9" requests

Mantenha sua chave no ambiente, nunca na fonte:

export SCRAPELESS_API_KEY="sk_your_scrapeless_key"

Obtenha HTML que vale a pena extrair

A qualidade da extração é limitada pela fidelidade da busca, então comece por aí. Em uma página renderizada em JavaScript, a marcação que um cliente HTTP comum recebe não possui nenhum conteúdo — ele chega apenas após os scripts construírem o DOM, um ciclo de vida definido pela especificação de scripting HTML. Um script mostra o que o resiliparse obtém de cada um:

# fidelity.py — o que o resiliparse extrai: GET simples vs renderização do lado do servidor
import os

import requests
from resiliparse.extract.html2text import extract_plain_text

URL = "https://quotes.toscrape.com/js/"
MARKER = "O mundo como o criamos"

plain = requests.get(URL, timeout=60).text
plain_text = extract_plain_text(plain, main_content=True)
print("caracteres de texto simples:", len(plain_text), "| contém citação:", MARKER in plain_text)

resp = requests.post(
    "https://api.scrapeless.com/api/v2/unlocker/request",
    headers={"Content-Type": "application/json", "x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    json={"actor": "unlocker.webunlocker", "input": {"url": URL, "js_render": True}},
    timeout=120,
)
resp.raise_for_status()
rendered_text = extract_plain_text(resp.json().get("data", ""), main_content=True)
print("caracteres de texto renderizado:", len(rendered_text), "| contém citação:", MARKER in rendered_text)

A busca simples extrai quase nada; a renderizada carrega o conteúdo real:

caracteres de texto simples: 23 | contém citação: False
caracteres de texto renderizado: 1435 | contém citação: True

Renderização, desbloqueio e roteamento de proxy acontecem todos do lado do servidor naquele único POST — a API de Raspagem Universal é a camada de busca, e os bytes renderizados são o que o resiliparse deve extrair.

Extraia texto limpo

Com HTML real em mãos, o resiliparse faz a extração. Execute-o uma vez com os padrões e uma vez com main_content=True para ver o conteúdo padrão ser removido:

# extract.py — extração de texto completo vs de conteúdo principal
import os

import requests

from resiliparse.extract.html2text import extract_plain_text

resp = requests.post(
    "https://api.scrapeless.com/api/v2/unlocker/request",
    headers={"Content-Type": "application/json", "x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    json={"actor": "unlocker.webunlocker", "input": {"url": "https://quotes.toscrape.com/", "js_render": True}},
    timeout=120,
)
resp.raise_for_status()
html = resp.json().get("data", "")

full = extract_plain_text(html)
main = extract_plain_text(html, main_content=True)
print("caracteres html renderizados:", len(html))
print("caracteres de texto completo:", len(full))
print("caracteres de conteúdo principal:", len(main))
print("tem a primeira citação:", "O mundo como o criamos" in main)

A execução transforma 10.968 caracteres de HTML em texto legível, e `main_content` corta ainda mais o conteúdo:

```text
caracteres html renderizados: 10968
caracteres de texto completo: 1674
caracteres de conteúdo principal: 1469
tem a primeira citação: True

Esse é todo o pipeline: um POST para buscar e renderizar, uma chamada para extrair. main_content=True é o que faz a saída alimentar um modelo de linguagem ou um índice de busca de maneira limpa — a navegação e os prompts de login que sobrevivem a um despejo de texto completo estão ausentes, e o texto da citação permanece.

Obtenha sua chave de API no plano gratuito: app.scrapeless.com

Padrões avançados

• Passe bytes, não uma string decodificada, quando a codificação é incerta. resiliparse detecta a codificação a partir do documento; fornecer os bytes de resposta brutos evita uma dupla decodificação que desfigura o texto não ASCII.
• Use as flags alt_texts e links para manter ou eliminar detalhes. extract_plain_text aceita flags que preservam o texto alternativo de imagens ou alvos de links quando você precisa deles e os omitem quando não precisa.
• Recorra ao resiliparse.parse.html quando precisar da árvore. O kit de ferramentas também expõe uma árvore HTML e uma API de seletor, para que você possa extrair campos estruturados do mesmo núcleo rápido quando o texto simples não é suficiente.
• Mantenha os passos de busca e extração separados. Extrair é limitado por CPU e buscar é limitado por IO; obtenha as páginas primeiro e, em seguida, execute a extração sobre o lote, de modo que nenhuma espere pela outra.

Solução de problemas

• Quase nenhum texto de uma página que você pode ver em um navegador. O conteúdo é renderizado em JavaScript e sua busca retornou o HTML pré-renderizado. O resultado de 23 caracteres do primeiro script é exatamente esse caso; conserte isso na camada de busca com js_render.
• Texto de navegação e rodapé na saída. Você chamou extract_plain_text sem main_content=True. Ative-o para eliminar o conteúdo básico.
• Caracteres acentuados embaralhados. Você forneceu ao resiliparse uma string mal decodificada. Passe os bytes de resposta e deixe-o detectar a codificação.
• Conteúdo que você queria foi cortado. main_content é agressivo por design. Para páginas com estrutura incomum, compare com a saída de texto completo e volte a ela quando a passagem de conteúdo principal excluir demais.

Conclusão

resiliparse conquista seu lugar como a camada de extração que escala: um núcleo em C++ que transforma HTML em texto limpo rapidamente, com um modo main_content que remove o conteúdo desnecessário. A camada que decide se algum disso é possível é a busca — a divisão de 23 versus 1.435 caracteres do primeiro script resolve isso — e um POST renderizado no servidor fecha a lacuna. Conecte os dois e uma página renderizada se torna texto limpo, pronto para um índice ou um modelo.

Crie uma conta Scrapeless gratuita para obter uma chave de API, e a documentação do desenvolvedor cobre os parâmetros unlocker.webunlocker. Confira preços do Scrapeless quando planejar um trabalho recorrente.

FAQ

P: O resiliparse pode raspar sites por conta própria?

Não. O resiliparse extrai texto do HTML que você já possui; ele não tem cliente HTTP e não executa JavaScript. Combine-o com uma camada de busca — aqui, a API Universal Scraping do Scrapeless, que rende a página no lado do servidor — e o resiliparse lida com a extração de texto dos bytes retornados.

P: Como o resiliparse é diferente de um removedor de conteúdo básico como trafilatura?

Ambos removem conteúdo básico, mas o resiliparse vem do grupo de pesquisa da Web Archive e é construído em C++ para rendimento em escala de corpus, e faz parte de um kit de ferramentas mais amplo que também lê arquivos WARC e detecta codificação e língua. Use-o quando a velocidade em muitos documentos for a limitação.

P: O que main_content=True realmente faz?
Executa uma passagem de extração de conteúdo que mantém o texto do artigo principal e descarta navegação, barras laterais, cabeçalhos e rodapés. A comparação neste guia mostra a saída reduzida em relação à saída de texto completo para que você possa ver o que foi removido.

P: O resiliparse lida com páginas renderizadas em JavaScript?

Não por conta própria — ele nunca executa scripts. Se o conteúdo carregar após o HTML inicial, uma busca simples extrai quase nada, como mostra o resultado de 23 caracteres. Busque a página através da API Scrapeless com js_render primeiro, depois extraia.

P: É legal fazer scraping com o resiliparse?

A biblioteca de extração não altera as regras de coleta. Busque apenas páginas públicas, respeite os termos do site e as diretrizes de robots padronizadas pelo Protocolo de Exclusão de Robots, mantenha volumes limitados e lide com quaisquer dados pessoais de acordo com as leis que se aplicam a você.