Gemini Web Scraping: Extração Baseada em Esquema em Python

Resumo:

• O nível de flash barato do Gemini é feito exatamente para esse trabalho. Alimente-o com uma página renderizada e um esquema rígido e ele retornará registros validados — uma execução ao vivo deste guia coletou todos os 20 produtos de uma página de catálogo de 50.449 caracteres por 12.904 tokens em um modelo de flash-lite.
• Schema primeiro, prompt segundo. A API atual do Gemini aceita um esquema JSON derivado do Pydantic na própria solicitação, portanto, os nomes e tipos dos campos são impostos pela API em vez de serem solicitados em prosa.
• O que o Gemini não resolve é obter a página. O modelo não pode renderizar JavaScript, manter sessões ou superar desafios de acesso no volume que você escolher — uma camada de fetch faz isso, e o fetch deste guia é um POST por página através da Scrapeless Universal Scraping API.
• O custo dos tokens acompanha o tamanho da página, então a qualidade do fetch é controle de custos. Enviar conteúdo renderizado e ajustado em vez de fetches quebrados ou inchados faz a diferença entre centavos e dinheiro real em grande escala.
• Sem chave do Google ainda? A mesma extração é feita através do OpenRouter. Este guia executou ao vivo em google/gemini-2.5-flash-lite e mostra a saída capturada.
• Gratuito para começar no lado do fetch. Crie sua chave da Scrapeless API em app.scrapeless.com.

O Gemini pode extrair dados de websites?

O Gemini extrai; ele não coleta. Dê ao modelo o texto da página e um esquema e ele retorna registros limpos — essa parte é realmente excelente e barata no nível de flash. Mas um pipeline de scraping também precisa buscar páginas específicas, renderizar seu JavaScript e fazer isso em um volume e cadência que você controla, e nada disso reside dentro de uma API de modelo de linguagem.

O Google oferece ferramentas de contexto de URL que permitem que a API leia um link que você insere, e vale uma formulação honesta: conveniente para leituras únicas, mas você herda seu fetch — sem controle sobre o comportamento de renderização, geografia ou o que acontece quando uma página desafia o acesso automatizado. A extração em produção mantém as camadas separadas: uma camada de fetch que você controla, depois o Gemini como o parser.

Uma desambiguação, porque a palavra-chave corta dos dois lados: este guia aponta o Gemini para a web como um motor de extração. Capturar as próprias respostas do Gemini como dados é o trabalho inverso — esse é o guia da API de Scrape do Gemini, e a explicação do scraper LLM cobre essa categoria.

Instalação

Dois clientes: o SDK do Google para o caminho nativo e requests para a camada de fetch. As execuções deste guia usaram Python 3.12:

pip install google-genai requests

Configuração

Ambas as chaves vêm do ambiente:

export GEMINI_API_KEY="sua_chave_google_ai_studio"
export SCRAPELESS_API_KEY="sk_sua_chave_scrapeless"

Buscar uma página que vale a pena extrair

O alvo da demonstração é uma página de catálogo de livraria pública construída para prática de scraping — 20 produtos, cada um com um título, preço, indicador de estoque e classificação em estrelas enterrados em HTML de apresentação. Um POST para a Universal Scraping API retorna a página com renderização, desbloqueio e roteamento de proxy tratados no lado do servidor:

# fetch_catalogue.py — um POST retorna a página de catálogo renderizada
import os

import requests

resp = requests.post(
    "https://api.scrapeless.com/api/v1/unlocker/request",
    headers={
        "Content-Type": "application/json",
        "x-api-token": os.environ["SCRAPELESS_API_KEY"],
    },
    json={
        "actor": "unlocker.webunlocker",
        "input": {"url": "https://books.toscrape.com/catalogue/page-1.html", "method": "GET"},
    },
    timeout=120,
)
resp.raise_for_status()
html = resp.json().get("data", "")
print(f"buscado {len(html):,} caracteres")
print("cartões de produtos no HTML:", html.count('<article class="product_pod">'))

with open("page.html", "w", encoding="utf-8") as f:
    f.write(html)

A execução imprime 50.449 caracteres e 20 cartões de produto. Esse número de 50k importa mais tarde: é o que o Gemini irá ler, e pelo que você pagará em tokens.

Implementação básica: extração primeiro utilizando esquema

A API atual do Gemini aceita um esquema JSON na solicitação, e a forma mais limpa de produzir um é um modelo Pydantic — a linguagem do esquema em si é a que é definida pela especificação JSON Schema. As classificações nessa página estão em uma classe CSS em vez de texto, portanto, o esquema e a regra do sistema especificam como lê-las.

Nota: Este bloco precisa de uma GEMINI_API_KEY — a única pré-condição que este guia não assume. A próxima seção executa a extração idêntica ao vivo através do OpenRouter, com a saída capturada. A interface exata da solicitação está documentada em o guia de saída estruturada do Gemini.

# extract_gemini.py — extração nativa do Gemini (requer GEMINI_API_KEY)
from google import genai
from pydantic import BaseModel


class Book(BaseModel):
    title: str
    price_gbp: float
    in_stock: bool
    rating: int


class Catalogue(BaseModel):
    books: list[Book]


client = genai.Client()  # lê GEMINI_API_KEY do ambiente
page_html = open("page.html", encoding="utf-8").read()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Extraia todos os livros. A classificação é de 1 a 5, leia a partir do nome da classe de classificação por estrelas.\n\n" + page_html,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Catalogue.model_json_schema(),
    },
)
print(interaction)

O esquema faz a aplicação: price_gbp retorna como um número, in_stock como um booleano, rating como um inteiro — sem limpeza de string pós-hoc.

Sem chave do Google? Execute através do OpenRouter

A extração também é executada em uma interface compatível com o OpenAI, com um modelo Gemini por trás, que é como este guia a executou de ponta a ponta — busca e extração em um único script autocontido:

# extract_openrouter.py — a mesma extração, executada via OpenRouter
import json
import os

import requests
from openai import OpenAI

resp = requests.post(
    "https://api.scrapeless.com/api/v1/unlocker/request",
    headers={
        "Content-Type": "application/json",
        "x-api-token": os.environ["SCRAPELESS_API_KEY"],
    },
    json={
        "actor": "unlocker.webunlocker",
        "input": {"url": "https://books.toscrape.com/catalogue/page-1.html", "method": "GET"},
    },
    timeout=120,
)
resp.raise_for_status()
page_html = resp.json().get("data", "")

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

completion = client.chat.completions.create(
    model="google/gemini-2.5-flash-lite",
    temperature=0,
    max_tokens=4000,
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "system",
            "content": 'Extraia todos os livros. Responda SOMENTE com JSON: '
            '{"books":[{"title":str,"price_gbp":number,"in_stock":bool,"rating":int}]}. '
            "A classificação é de 1 a 5, leia a partir do nome da classe de classificação por estrelas.",
        },
        {"role": "user", "content": page_html},
    ],
)

data = json.loads(completion.choices[0].message.content)
print(f"extraídos {len(data['books'])} livros")
print(json.dumps(data["books"][0], ensure_ascii=False))

A execução ao vivo retornou todos os 20 produtos, primeiro registro:

extraídos 20 livros
{"title": "A Light in the Attic", "price_gbp": 51.77, "in_stock": true, "rating": 3}

Preço analisado como um float, estoque como um booleano, e a classificação de três estrelas lida corretamente a partir do nome da classe — a partir de 50 mil caracteres de HTML do catálogo, em uma chamada, por 12.904 tokens em um modelo que custa frações de dólar por milhão.

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

Padrões avançados: economia de tokens

O custo da extração é dominado pela entrada, então a camada de busca também é a camada de orçamento.

• Meça os tokens por página cedo. A execução acima custou 12.904 tokens para uma página de catálogo. Multiplique pelo seu número de páginas antes de se comprometer com um nível de modelo, não depois da fatura.
• Corte antes de enviar. O chrome da página é um imposto. Isolar o contêiner do produto, ou buscar páginas como markdown em vez de HTML bruto, reduz o tamanho da entrada — muitas vezes em mais da metade — sem perda de conteúdo extraível.
• Mantenha-se na camada flash para trabalho de esquema. Um esquema rígido mais temperature=0 torna a extração uma tarefa restringida; a execução acima não precisou de nada maior. Aumente o tamanho do modelo apenas quando os campos retornarem incorretos com entrada limpa.
• Não armazene nada no prompt. O esquema vive na mensagem do sistema uma vez por chamada; não cole exemplos de páginas anteriores em novas chamadas — isso infla a entrada e ensina o modelo a repetir registros desatualizados.

Resolução de problemas

• Campos retornam como strings. Seu esquema não está alcançando a API — verifique se a chamada nativa passa schema (ou se a chamada do OpenRouter passa o contrato JSON na mensagem do sistema) em vez de descrever os campos de forma vaga em prosa.
• Zero ou três produtos de uma página de 20 produtos. Inspecione o HTML buscado primeiro: conte os cartões de produtos da maneira que o script de busca faz. Uma busca quase vazia é um problema de renderização ou acesso — um conserto da camada de busca, não um conserto do prompt.
• As classificações sempre retornam como 5. O valor está codificado em marcação, não em texto. Diga onde ele está ("leia-o do nome da classe de classificação por estrelas"), como ambos os blocos de extração aqui fazem.
• Os custos variam entre execuções. Compare os tamanhos de entrada; um redesign que duplica o peso da página duplica sua conta de tokens. O corte e a recuperação de markdown são as alavancas.

Conclusão

O nível flash do Gemini mais um esquema rigoroso transforma uma página de catálogo de 50 mil caracteres em 20 registros digitados por trocados — essa é a metade da extração, e agora é a metade fácil. A metade que decide se os registros existem ou não é a recuperação: renderizada, controlada, uma POST por página. Mantenha as camadas separadas, meça os tokens por página, e as mesmas quarenta linhas escalam de uma livraria de demonstração para um catálogo real.

Pronto para Alimentar o Gemini com Páginas Reais?

A camada de recuperação aqui é a API Universal Scraping — planos e volumes de requisição estão na página de preços, e a documentação do desenvolvedor cobre todos os parâmetros de unlocker.webunlocker. Crie uma chave no plano gratuito em app.scrapeless.com e a recuperação de catálogo acima roda como escrito.

FAQ

Q: O Gemini pode acessar sites diretamente?

Apenas através das ferramentas de contexto de URL do Google, que recuperam um link do lado do servidor para leituras únicas. Isso não oferece controle de renderização, saída geográfica ou volume — as propriedades nas quais um pipeline de scraping é construído — que é por isso que implementações de produção emparelham o Gemini com uma camada de recuperação dedicada e passam o texto da página limpa do modelo.

Q: Qual modelo do Gemini devo usar para extração?

O menor modelo de nível flash que mantém seu esquema. A extração contra um esquema rigoroso é uma tarefa restrita, não um benchmark de raciocínio — a execução ao vivo neste guia usou um modelo flash-lite e digitou corretamente os 20 registros. Suba um nível apenas quando a entrada limpa ainda produzir campos errados.

Q: Quanto custa scraping com o Gemini em grande escala?

Tokens de entrada dominam, então o custo é aproximadamente páginas × tokens por página × taxa do modelo. A execução medida aqui foi de 12.904 tokens para uma página de 50.449 caracteres; cortar o chrome ou recuperar markdown reduz isso substancialmente. Meça uma página real antes de extrapolar — médias inventadas são como orçamentos morrem.

Q: Como isso é diferente de um scraper do Gemini?

Direção. Este guia usa o Gemini como o parser direcionado à web. Um scraper do Gemini direciona um scraper ao Gemini — capturando suas respostas, citações e fontes como dados. O Scrapeless embarca isso como um ator; o guia da API do Scraper do Gemini, vinculado na introdução, cobre isso.

Q: É legal fazer scraping com o Gemini?

A camada de extração não muda nada sobre as regras de coleta. Recupere apenas páginas públicas, respeite os termos do site e as diretrizes de robots padronizadas por o Protocolo de Exclusão de Robots, mantenha os volumes limitados e trate qualquer dado pessoal de maneira legal — além dos termos da API do Google no lado do modelo.