BroadRouter

Extraer datos de facturas, recibos y formularios a JSON con visión

Por el equipo de BroadNet Inference · 4 min de lectura · Publicado

Convierta cada página en una imagen, envíela a un modelo de visión con un prompt que nombre cada campo y su formato, y pida solo JSON. Después valide en código: analícelo, compruebe su esquema, verifique que las líneas suman el total y reintente una vez con el error. Envíe los fallos repetidos a una persona.

A paper invoice headed "فاتورة" (invoice) with tabs labelled Vendor, Date and Total, and the text "Turn documents into useful data."
Illustrative example.

Las facturas, los recibos y los formularios comparten el mismo problema: los datos están en una imagen y usted los necesita en una base de datos. El OCR basado en plantillas se rompe con cada nuevo diseño de proveedor. Un modelo de visión y lenguaje lee la página y devuelve los campos directamente. El inconveniente es que puede equivocarse con total seguridad, así que el trabajo está en el flujo que lo rodea. Este artículo cubre el flujo general para cualquier idioma. Para documentos en árabe, consulte leer facturas en árabe con visión para la configuración y OCR árabe frente a LLM de visión para saber cuándo el OCR clásico es la mejor herramienta.

¿Cómo es el flujo?

  1. Prepare cada página: convierta los PDF en imágenes, corrija la rotación y redimensione.
  2. Extraiga: una solicitud por documento con un prompt campo por campo, solo JSON.
  3. Valide: analice, compruebe el esquema, compruebe la aritmética.
  4. Reintente una vez con el mensaje de error si la validación falla.
  5. Revise: lo que siga fallando pasa a una persona, con la imagen y el borrador.
  6. Mida la precisión por campo en una muestra etiquetada y repita la medición cada vez que cambie de modelo o de prompt.

¿Cómo se preparan las imágenes de los documentos?

Convierta los PDF en imágenes con PyMuPDF y mantenga nítido el texto más pequeño sin enviar más píxeles de los necesarios:

# pip install pymupdf pillow
import base64, io
import pymupdf  # older code imports it as fitz
from PIL import Image

def pdf_pages_as_data_urls(path, long_edge=1800):
    urls = []
    for page in pymupdf.open(path):
        pix = page.get_pixmap(dpi=200)
        img = Image.open(io.BytesIO(pix.tobytes("png"))).convert("RGB")
        img.thumbnail((long_edge, long_edge))
        buf = io.BytesIO()
        img.save(buf, format="JPEG", quality=90)
        urls.append("data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode())
    return urls

En BroadNet Inference, las imágenes van en el mensaje como URL data: con un tipo MIME correcto, y con pago por uso se facturan como tokens de entrada; las imágenes más grandes consumen más. Mida una vez los tokens por página con el bloque usage y dimensione sus lotes a partir de ahí; contar tokens antes de enviar explica cómo, y costo por imagen de los LLM de visión convierte tokens en costo por página. Para estimar los tokens por página antes de enviar nada, cargue un escaneo de muestra en la calculadora de tokens de imagen.

¿Cómo se escribe el prompt de extracción?

Sea exacto con las claves, los tipos, los formatos y los valores ausentes. Si además quiere un JSON Schema para validar o para proveedores que lo imponen, el generador de esquemas JSON gratuito lo crea a partir de una factura de ejemplo:

PROMPT = """Extract this invoice. Reply with one JSON object only, no prose.
Keys:
- vendor_name: string, as printed
- vendor_tax_id: string or null
- invoice_number: string
- invoice_date: string, YYYY-MM-DD
- currency: ISO 4217 code, e.g. USD, EUR, SAR
- line_items: list of {description: string, quantity: number, unit_price: number, line_total: number}
- subtotal: number
- tax: number or null
- total: number
Rules: numbers without currency symbols or thousands separators. If a field is not on the page, use null. Never guess."""

Lo que más importa es “Never guess” (Traducción: nunca suponga) junto con un null explícito. Sin eso, los modelos rellenan los huecos con valores verosímiles, lo que es peor que un campo vacío porque supera un control ingenuo.

¿Cómo se obtiene y se valida la salida estructurada?

Hay dos niveles de salida estructurada. El modo JSON garantiza un JSON válido. La salida restringida por esquema garantiza además la forma. La guía de OpenAI lo dice claramente: ambos producen JSON válido, pero solo Structured Outputs garantiza la adherencia al esquema. La compatibilidad con cada uno varía según el proveedor y el modelo, así que valide en código, prometa lo que prometa la API:

import json, os
from decimal import Decimal
from pydantic import BaseModel, ValidationError, model_validator
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Line(BaseModel):
    description: str
    quantity: Decimal
    unit_price: Decimal
    line_total: Decimal

class Invoice(BaseModel):
    vendor_name: str
    vendor_tax_id: str | None = None
    invoice_number: str
    invoice_date: str
    currency: str
    line_items: list[Line]
    subtotal: Decimal
    tax: Decimal | None = None
    total: Decimal

    @model_validator(mode="after")
    def sums(self):
        tol = Decimal("0.02")
        if abs(sum(l.line_total for l in self.line_items) - self.subtotal) > tol:
            raise ValueError("line_totals do not sum to subtotal")
        if abs(self.subtotal + (self.tax or 0) - self.total) > tol:
            raise ValueError("subtotal + tax != total")
        return self

def extract(image_urls, model="broadnet/qwen3.8-27b"):
    content = [{"type": "text", "text": PROMPT}] + [
        {"type": "image_url", "image_url": {"url": u}} for u in image_urls]
    messages = [{"role": "user", "content": content}]
    for attempt in range(2):
        r = client.chat.completions.create(model=model, messages=messages, max_tokens=4000, temperature=0)
        raw = (r.choices[0].message.content or "").strip().removeprefix("```json").removesuffix("```")
        try:
            return Invoice.model_validate(json.loads(raw)), r.usage
        except (json.JSONDecodeError, ValidationError, ValueError) as e:
            messages += [{"role": "assistant", "content": raw},
                         {"role": "user", "content": f"That failed validation: {e}. Re-read the image and reply with corrected JSON only."}]
    return None, r.usage  # send to human review

Use Decimal, no float, para importes. Mantenga max_tokens generoso: Qwen3.8 27B razona antes de responder, y el razonamiento cuenta para el límite; un tope pequeño devuelve una cadena vacía. Consulte por qué los modelos de razonamiento devuelven respuestas vacías.

¿Qué controles detectan más errores?

Control Detecta Costo
El JSON se analiza Texto alrededor del JSON, truncamiento Gratis
El esquema valida Claves ausentes, tipos incorrectos Gratis
Las líneas suman el subtotal Dígitos mal leídos, líneas omitidas Gratis
Subtotal + impuesto = total Total o impuesto mal leídos Gratis
La fecha se analiza y no es futura Día y mes invertidos, ruido de OCR Gratis
El ID fiscal del proveedor coincide con su lista de proveedores Proveedor equivocado, fraude Una búsqueda
Número de factura duplicado por proveedor Pago doble Una consulta

Los controles aritméticos son los más rentables: un solo dígito mal leído casi siempre rompe una suma. Los recibos a menudo carecen de detalle por línea, así que compruebe lo que haya y acepte menos controles en ellos.

¿Cómo se mide la precisión antes de salir a producción?

Etiquete a mano entre 50 y 100 documentos reales, ejecute el flujo y puntúe por campo, no por documento. Los totales y las fechas merecen un listón más alto que las descripciones. Haga seguimiento de tres cifras: la precisión por campo, la proporción de documentos que pasan la validación sin reintento y la proporción que va a revisión. Cómo diseñar ese paso de revisión, incluidas auditorías aleatorias de documentos que pasaron, se explica en cómo integrar la revisión humana en su flujo de IA para documentos. Cuando pruebe otro modelo, ejecute el mismo conjunto; evaluar un LLM antes de cambiar cubre el método.

¿Qué modelos de visión ofrece BroadNet Inference?

Modelo Imágenes Contexto Notas
Qwen3.8 27B Sí 262,144 Herramientas, salida estructurada y razonamiento listados; probado en árabe por BroadNet
Gemma 4 VL 26B Sí 32,768 El precio más bajo de BroadNet; funciona con el crédito gratuito y la clave por hora
DeepSeek V4.1 Flash Sí 1,048,576 Imágenes incluidas en los planes ilimitados

Los precios por 1M de tokens están en la página de precios; multiplique sus tokens medidos por página por el volumen mensual en la calculadora de costo de API de LLM.

Dónde encaja BroadNet Inference

BroadNet Inference acepta imágenes en tres modelos de chat mediante el formato de mensajes estándar de OpenAI, y no conserva prompts, imágenes ni respuestas después de la solicitud, lo que importa en facturas llenas de nombres, ID fiscales y datos bancarios (cero retención de datos). Su documentación lista la salida estructurada para Qwen3.8 27B, pero no documenta parámetros de esquema, así que confíe en la capa de validación anterior y no en la API para imponer su esquema. BroadNet no publica un límite de tamaño de imagen ni un producto específico de IA para documentos, y su documentación describe la entrada de imágenes, no la subida de PDF, así que convierta primero las páginas en imágenes. Para ejecuciones de gran volumen con un presupuesto fijo, un plan ilimitado de DeepSeek V4.1 Flash incluye imágenes.

Preguntas frecuentes

¿Puede un LLM de visión sustituir al OCR en las facturas?

En muchos diseños, sí. Un modelo de visión lee la imagen y asigna el texto a los campos en un solo paso, sin plantillas por proveedor. Aun así, a veces lee mal los dígitos, así que mantenga la validación y una cola de revisión.

¿Cómo obtengo JSON fiable de un modelo de visión?

Enumere en el prompt las claves, los tipos y los formatos exactos, pida solo JSON y analícelo en código. Si el modelo admite salida restringida por esquema, úsela. En cualquier caso, valide con una biblioteca de esquemas y reintente una vez con el error.

¿Cómo extraigo datos de una factura PDF de varias páginas?

Convierta cada página en una imagen y envíe todas las páginas de una factura en una sola solicitud si caben en el contexto del modelo, para que los totales de la última página puedan cotejarse con las líneas de la primera.

¿Qué resolución deben tener las imágenes de facturas?

La suficiente para que los dígitos más pequeños se vean nítidos, y no más. Las imágenes más grandes consumen más tokens de entrada. Un lado largo de unos 1,500 a 2,000 píxeles es un punto de partida razonable para una página A4; pruebe con sus propios documentos.

¿Cómo mido la precisión de la extracción?

Etiquete a mano entre 50 y 100 documentos reales y puntúe campo por campo. Haga seguimiento de los totales y las fechas por separado de los campos de texto libre, como los nombres de proveedor, porque el costo de sus errores es distinto.

Leer en MarkdownPreguntar a ChatGPTPreguntar a ClaudePreguntar a Perplexity