Gemini Web Scraping: Extracción Primero de Esquema en Python

Resumen:

• El nivel de flash económico de Gemini está diseñado precisamente para este trabajo. Aliméntalo con una página renderizada y un esquema estricto y devuelve registros validados: una ejecución en vivo de esta guía extrajo 20 productos de una página de catálogo de 50,449 caracteres por 12,904 tokens en un modelo flash-lite.
• Esquema primero, prompt segundo. La API actual de Gemini toma un esquema JSON derivado de Pydantic en la propia solicitud, por lo que los nombres y tipos de campo son impuestos por la API en lugar de solicitados en prosa.
• Lo que Gemini no resuelve es obtener la página. El modelo no puede renderizar JavaScript, mantener sesiones o superar desafíos de acceso en el volumen que elijas: una capa de obtención hace eso, y la obtención de esta guía es una POST por página a través de la API de Scraping Universal de Scrapeless.
• El costo de tokens rastrea el tamaño de la página, por lo que la calidad de la obtención es control de costos. Enviar contenido renderizado y recortado en lugar de descargas rotas o infladas es la diferencia entre centavos y dinero real a gran escala.
• ¿Sin clave de Google aún? La misma extracción se ejecuta a través de OpenRouter. Esta guía lo ejecutó en vivo en google/gemini-2.5-flash-lite y muestra la salida capturada.
• Gratis para comenzar del lado de la obtención. Crea tu clave de API de Scrapeless en app.scrapeless.com.

¿Puede Gemini raspar sitios web?

Gemini extrae; no colecciona. Entrega al modelo texto de página y un esquema y devuelve registros limpios; esa parte es genuinamente excelente y económica en el nivel de flash. Pero un pipeline de raspado también debe obtener páginas específicas, renderizar su JavaScript y hacerlo a un volumen y ritmo que controlas, y nada de eso vive dentro de una API de modelo de lenguaje.

Google ofrece herramientas de contexto de URL que permiten a la API leer un enlace que pasas, y vale la pena un marco honesto: conveniente para lecturas únicas, pero heredas su obtención: sin control sobre el comportamiento de renderizado, geografía o lo que sucede cuando una página desafía el acceso automatizado. La extracción en producción mantiene las capas separadas: una capa de obtención que controlas, luego Gemini como el analizador.

Una disambiguación, porque la palabra clave corta en ambos sentidos: esta guía apunta a Gemini hacia la web como un motor de extracción. Capturar las propias respuestas de Gemini como datos es el trabajo inverso: esa es la guía de la API de Gemini Scraper, y el explicador de raspar LLM cubre esa categoría.

Instalación

Dos clientes: el SDK de Google para la ruta nativa y requests para la capa de obtención. Las ejecuciones en esta guía usaron Python 3.12:

pip install google-genai requests

Configuración

Ambas claves provienen del entorno:

export GEMINI_API_KEY="tu_clave_google_ai_studio"
export SCRAPELESS_API_KEY="sk_tu_clave_scrapeless"

Obtener una página que valga la pena extraer

El objetivo de demostración es una página de catálogo de una librería pública creada para la práctica de raspado: 20 productos, cada uno con un título, precio, bandera de stock y calificación estelar enterrados en HTML de presentación. Una POST a la API de Scraping Universal devuelve la página con renderizado, desbloqueo y apuntamiento de proxy manejados del lado del servidor:

# fetch_catalogue.py — una POST devuelve la 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"obtenidos {len(html):,} caracteres")
print("tarjetas de producto en el HTML:", html.count('<article class="product_pod">'))

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

La ejecución imprime 50,449 caracteres y 20 tarjetas de productos. Esa cifra de 50k es importante más adelante: es lo que Gemini leerá y por lo que pagarás tokens.

Implementación básica: extracción primero del esquema

La API actual de Gemini acepta un esquema JSON en la solicitud, y la forma más limpia de producir uno es un modelo de Pydantic: el lenguaje del esquema es el definido por la especificación del esquema JSON. Las calificaciones en esta página viven en una clase CSS en lugar de en texto, por lo que el esquema y las reglas del sistema explican cómo leerlas.
Nota: Este bloque necesita un GEMINI_API_KEY — el único requisito que esta guía no asume. La siguiente sección ejecuta la extracción idéntica en vivo a través de OpenRouter, con la salida capturada. La superficie exacta de la solicitud está documentada en la guía de salida estructurada de Gemini.

# extract_gemini.py — extracción nativa de Gemini (requiere 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()  # lee GEMINI_API_KEY del entorno
page_html = open("page.html", encoding="utf-8").read()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Extrae cada libro. la calificación es de 1 a 5, léela del nombre de la clase de calificación por estrellas.\n\n" + page_html,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Catalogue.model_json_schema(),
    },
)
print(interaction)

El esquema hace la imposición: price_gbp regresa como un número, in_stock como un booleano, rating como un entero — sin limpieza de cadena post-hoc.

¿No tienes clave de Google? Ejecuta a través de OpenRouter

La extracción también se ejecuta sobre una superficie compatible con OpenAI con un modelo de Gemini detrás de ella, que es cómo esta guía lo ejecutó de principio a fin — obtención y extracción en un solo script autónomo:

# extract_openrouter.py — la misma extracción, ejecutada a través de 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": 'Extrae cada libro. Responde SOLO con JSON: '
            '{"books":[{"title":str,"price_gbp":number,"in_stock":bool,"rating":int}]}. '
            "la calificación es de 1 a 5, léela del nombre de la clase de calificación por estrellas.",
        },
        {"role": "user", "content": page_html},
    ],
)

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

La ejecución en vivo devolvió todos los 20 productos, primer registro:

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

Precio analizado como un flotante, inventario como un booleano, y la calificación de tres estrellas leída correctamente desde un nombre de clase — de 50k caracteres de HTML de catálogo, en una sola llamada, por 12,904 tokens en un modelo cuyo precio es fracciones de dólar por millón.

Obtén tu clave API en el plan gratuito: app.scrapeless.com

Patrones avanzados: economía de tokens

El costo de extracción está dominado por la entrada, por lo que la capa de obtención también es la capa presupuestaria.

• Mide tokens por página temprano. La ejecución anterior costó 12,904 tokens por una página de catálogo. Multiplica por tu cantidad de páginas antes de comprometerte a una categoría de modelo, no después de la factura.
• Recorta antes de enviar. El chrome de la página es un impuesto. Aislar el contenedor del producto, o obtener páginas como markdown en lugar de HTML sin procesar, reduce el tamaño de entrada — a menudo en más de la mitad — sin pérdida de contenido extraíble.
• Permanece en el nivel flash para trabajo de esquema. Un esquema estricto más temperature=0 convierte la extracción en una tarea restringida; la ejecución anterior no necesitó nada más grande. Escala el tamaño del modelo solo cuando los campos regresen incorrectos en la entrada limpia.
• No caches nada en el aviso. El esquema vive en el mensaje del sistema una vez por llamada; no pegues ejemplos de páginas anteriores en nuevas llamadas — infla la entrada y enseña al modelo a repetir registros desactualizados.

Solución de problemas

• Los campos regresan como cadenas. Tu esquema no está alcanzando la API — verifica que la llamada nativa pase schema (o que la llamada de OpenRouter pase el contrato JSON en el mensaje del sistema) en lugar de describir campos de manera suelta en prosa.
• Cero o tres productos de una página de 20 productos. Inspecciona primero el HTML obtenido: cuenta las tarjetas de productos de la manera en que lo hace el script de obtención. Una obtención casi vacía es un problema de renderizado o acceso — un arreglo de capa de obtención, no un arreglo de aviso.
• Las calificaciones siempre regresan como 5. El valor está codificado en marcas, no en texto. Di dónde se encuentra ("léelo desde el nombre de la clase de calificación estelar"), como hacen ambos bloques de extracción aquí.
• Los costos varían entre ejecuciones. Compara tamaños de entrada; un rediseño que duplica el peso de la página duplica tu factura de tokens. El recorte y la obtención de markdown son las palancas.

Conclusión

El nivel flash de Gemini más un esquema estricto convierte una página de catálogo de 50k caracteres en 20 registros tipados por monedas de bolsillo — esa es la mitad de extracción, y es la mitad fácil ahora. La mitad que decide si los registros existen en absoluto es la obtención: renderizada, controlada, un POST por página. Mantén las capas separadas, mide tokens por página, y las mismas cuarenta líneas escalan de una librería de demostración a un catálogo real.

¿Listo para alimentarlo con páginas reales?

La capa de obtención aquí es la API de Raspado Universal — los planes y volúmenes de solicitudes están en la página de precios, y la documentación para desarrolladores cubre cada parámetro de unlocker.webunlocker. Crea una clave en el plan gratuito en app.scrapeless.com y la obtención de catálogo anterior se ejecuta como está escrito.

Preguntas frecuentes

P: ¿Puede Gemini acceder a sitios web directamente?

Solo a través de la herramienta de contexto de URL de Google, que obtiene un enlace del lado del servidor para lecturas únicas. No te da control de renderizado, salida geográfica o volumen — las propiedades sobre las que se construye un pipeline de raspado — que es por lo que las configuraciones de producción emparejan a Gemini con una capa de obtención dedicada y pasan el texto limpio de la página al modelo.

P: ¿Qué modelo de Gemini debería usar para la extracción?

El modelo más pequeño de nivel flash que mantenga tu esquema. La extracción contra un esquema estricto es una tarea limitada, no un banco de referencia de razonamiento — la ejecución en vivo de esta guía utilizó un modelo flash-lite y tipó correctamente los 20 registros. Sube de nivel solo cuando la entrada limpia aún produzca campos incorrectos.

P: ¿Cuánto cuesta el raspado web de Gemini a gran escala?

Los tokens de entrada dominan, por lo que el costo es aproximadamente páginas × tokens por página × tarifa del modelo. La ejecución medida aquí fue de 12,904 tokens para una página de 50,449 caracteres; recortar chrome u obtener markdown reduce eso sustancialmente. Mide una página real antes de extrapolar — los promedios inventados son cómo mueren los presupuestos.

P: ¿Cómo se diferencia esto de un raspador de Gemini?

Dirección. Esta guía utiliza a Gemini como el analizador apuntado a la web. Un raspador de Gemini apunta un raspador a Gemini — capturando sus respuestas, citas y fuentes como datos. Scrapeless lo envía como un actor; la guía de la API del Raspador de Gemini vinculada en la introducción lo cubre.

P: ¿Es legal raspar con Gemini?

La capa de extracción no cambia nada sobre las reglas de recolección. Obtén solo páginas públicas, respeta los términos del sitio y las directivas de robots estandarizadas por el Protocolo de Exclusión de Robots, mantén los volúmenes limitados, y maneja cualquier dato personal de manera legal — además de los términos de la API de Google en el lado del modelo.