Cómo extraer tablas de PDF grandes y verificar los números

Al procesar documentos PDF complejos —como informes de inspección de equipos de varias páginas o estados financieros—, el texto uniforme y limpio suele ser la excepción y no la regla. En los documentos empresariales reales, las páginas digitales se mezclan con hojas escaneadas, las tablas carecen de bordes de cuadrícula definidos y las métricas críticas a menudo quedan ocultas en notas al pie densas.

Enviar estos archivos directamente a un modelo multimodal y registrar la salida sin intermediarios en una base de datos de producción entraña un alto riesgo. Dado que los modelos fundacionales siguen siendo sistemas probabilísticos, una canalización de extracción confiable no puede basarse en la confianza ciega. Por el contrario, debe diseñarse en torno a una definición deliberada del esquema, la recopilación de pistas contextuales para auditoría y una verificación posterior rigurosa frente al original visual.

---

1. Esquema de datos: fijar campos y permitir nulls

El mecanismo de Gemini Structured Outputs garantiza que las respuestas del modelo se ajusten estrictamente a un esquema declarado, generando un JSON sintácticamente válido. Si una propiedad se define como numérica, ningún texto conversacional adicional contaminará dicho valor.

Sin embargo, la conformidad sintáctica con el esquema solo previene errores estructurales; no asegura la veracidad semántica:

• El modelo puede confundir filas adyacentes o trasponer columnas en tablas densas y sin bordes;
• En escaneos degradados, el dígito 8 puede confundirse fácilmente con un 3, y los puntos decimales suelen perderse;
• Cuando una métrica falta o está borrosa, un modelo al que no se le permita omitir valores de forma explícita puede intentar inventar un número plausible.

Para mitigar el riesgo de alucinaciones, los esquemas deben definir los campos como anulables (Optional o null), junto con instrucciones explícitas en el prompt para devolver null siempre que un número no pueda descifrarse con un alto nivel de confianza. Si bien permitir valores null reduce notablemente la presión del modelo por adivinar, esto no constituye por sí solo una garantía absoluta contra las alucinaciones.

---

2. Ingesta de archivos: cuándo elegir la Files API

Según la documentación oficial sobre procesamiento de documentos de Gemini, los límites operativos se sitúan en hasta 50 MB o hasta 1,000 páginas por archivo PDF (se aplican simultáneamente las restricciones de tamaño de archivo y de número de páginas, sin garantía de que ambos máximos puedan alcanzarse a la vez; el procesamiento se detiene ante el límite que se alcance primero).

El método de transmisión óptimo depende del tamaño del documento y del patrón operativo:

• El envío de datos en línea (inline) resulta más adecuado para documentos pequeños y llamadas de extracción puntuales.
• La Files API (client.files.upload) está diseñada para archivos de mayor tamaño y flujos de trabajo de varios pasos en los que el mismo documento se consulta en operaciones consecutivas (por ejemplo, una clasificación inicial de secciones seguida de la extracción específica de tablas). El uso de la Files API evita tener que volver a subir la carga útil completa del documento en cada llamada.

---

3. Consulta de datos: esquema, pistas de citas y respuesta hipotética

Para que los datos extraídos sean auditables, solicite al modelo que devuelva metadatos auxiliares junto con los valores objetivo: un número de página aproximado (page_number) y un fragmento de cita textual breve (evidence_quote).

Distinción fundamental: page_number y evidence_quote no constituyen pruebas fácticas; son estrictamente pistas heurísticas de búsqueda. Dado que el modelo genera estos campos por sí mismo, los fragmentos de citas pueden contener artefactos de OCR o fusionar líneas adyacentes, y el número de página visual reportado puede diferir del índice de la hoja física dentro del contenedor PDF.

Configuración hipotética del problema

Considere una configuración de problema hipotética (no se proporcionó, cargó ni analizó ningún PDF real, y no se ejecutó ninguna consulta real a la API): modelar la extracción de métricas de resumen a partir de un informe hipotético de inspección de bombas. En este ejemplo ilustrativo, examinamos una tabla hipotética de dos filas:

Identificador	Presión (MPa)	Vibración (mm/s)	Estado	Notas
Н-101-А	1.45	2.1	Normal (В норме)	Inspección programada
Н-102-В	(ilegible)	7.8	Atención (Внимание)	Holgura incrementada

A continuación se muestra un esquema de ejemplo definido con Pydantic junto con la sintaxis de invocación del SDK oficial:

from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional

class PumpRecord(BaseModel):
    unit_id: str = Field(
        description="Идентификатор агрегата точно как в таблице"
    )
    inlet_pressure_mpa: Optional[float] = Field(
        default=None,
        description="Давление в МПа. Если значение неразборчиво или отсутствует — null"
    )
    vibration_mms: Optional[float] = Field(
        default=None,
        description="Уровень вибрации в мм/с. При отсутствии данных — null"
    )
    status: str = Field(
        description="Статус узла (например, 'В норме', 'Внимание')"
    )
    page_number: Optional[int] = Field(
        default=None,
        description="Оценочный номер страницы документа (подсказка для аудитора, не подтверждена)"
    )
    evidence_quote: Optional[str] = Field(
        default=None,
        description="Короткий фрагмент строки (до 10 слов), откуда взяты числа (подсказка, не подтверждена)"
    )

class InspectionPayload(BaseModel):
    records: List[PumpRecord]

client = genai.Client()

uploaded_file = client.files.upload(file="hypothetical_inspection.pdf")

response = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "document",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type,
        },
        {
            "type": "text",
            "text": (
                "Извлеки показатели агрегатов в соответствии со схемой. "
                "Если число неразборчиво или отсутствует, возвращай null. "
                "Для каждой записи заполни номер страницы и короткую цитату-подтверждение."
            ),
        },
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": InspectionPayload.model_json_schema(),
    },
)

payload = InspectionPayload.model_validate_json(response.output_text)

Respuesta JSON ilustrativa del modelo

El siguiente JSON ilustra una respuesta hipotética del modelo ante esta solicitud. Enfatizamos: esta salida sirve como una ilustración estructural hipotética, no como el resultado de una ejecución real de la API ni de una medición física verídica:

{
  "records": [
    {
      "unit_id": "Н-101-А",
      "inlet_pressure_mpa": 1.45,
      "vibration_mms": 2.1,
      "status": "В норме",
      "page_number": 12,
      "evidence_quote": "Н-101-А 1.45 2.1 В норме"
    },
    {
      "unit_id": "Н-102-В",
      "inlet_pressure_mpa": null,
      "vibration_mms": 7.8,
      "status": "Внимание",
      "page_number": 12,
      "evidence_quote": "Н-102-В [пятно] 7.8 Внимание"
    }
  ]
}

En esta respuesta hipotética, ambas instancias de page_number: 12 y ambos valores de evidence_quote tienen el estado de pistas no verificadas. Aunque el modelo generó correctamente null para la cifra de presión ilegible en la segunda unidad, ninguno de los atributos extraídos se considera a priori un hecho confirmado.

---

4. Cotejo con el original visual y reglas de exportación

Los registros extraídos no pueden escribirse directamente en las bases de datos de producción sin una validación previa. Se requiere una auditoría integral que compare cada campo con el renderizado visual de la página del PDF de origen.

Aclaración importante sobre el ejemplo: La tabla de dos filas, la página 12, el desfase físico a la 14.ª hoja, el departamento de compresores y el flujo de verificación visual representan una ilustración exclusivamente hipotética del proceso. No se proporcionó ni inspeccionó ningún documento PDF real, y los pasos descritos a continuación reflejan lo que un revisor comprobaría en la práctica, formulando decisiones condicionales en caso de que el renderizado visual confirme los valores indicados.

Verificación de registros paso a paso: lo que comprobaría un revisor

1. Unidad Н-101-А:

   • Página y localización: El modelo devolvió la pista page_number: 12. El revisor inspeccionaría el renderizado visual de la página 12 (o la hoja 14 si las páginas preliminares generaron un desfase físico) y localizaría la tabla correspondiente al departamento de compresores.
   • Identificador: En la primera columna, el revisor verificaría la coincidencia exacta del identificador Н-101-А.
   • Presión y unidades: En la columna de presión de entrada, el revisor comprobaría que el valor 1.45 sea claramente legible y que las unidades de ingeniería coincidan con las expectativas del esquema (МПа / MPa).
   • Vibración y unidades: En la columna de vibración, el revisor verificaría la presencia de 2.1 y la denominación de la unidad (мм/с / mm/s).
   • Estado: En la condición operativa, el revisor confirmaría la presencia del estado В норме (Normal).
   • Decisión condicional: Si la página renderizada valida todos los campos, valores y unidades físicas, la fila se aprobaría para su exportación (Export / Accepted).

2. Unidad Н-102-В:

   • Página y localización: En la misma tabla hipotética, el revisor pasaría a la segunda fila.
   • Identificador: El revisor confirmaría la presencia del identificador Н-102-В.
   • Vibración y estado: El revisor cotejaría el valor de vibración 7.8 y el estado Внимание (Warning / Atención) con la capa visual.
   • Presión: El modelo devolvió null. El revisor examinaría la celda correspondiente en el renderizado de la página: si observa una mancha oscura y corrida (un defecto de escaneo) en lugar de una lectura, esto valida la decisión del modelo de devolver null, aunque sigue faltando una medición física esencial.
   • Decisión condicional: Dado que la confirmación visual determina la ausencia de una lectura de presión crítica, la fila se bloquearía para la exportación automatizada y se enviaría a revisión manual (Hold for manual review), lo que requeriría un reescaneo operativo o el cotejo con registros de mantenimiento de respaldo.

Salida comprobada tras la verificación

La tabla resumen detalla exactamente qué inspeccionaría el revisor y qué decisión de enrutamiento condicional activaría la canalización de validación tras la confirmación visual:

Unidad	Presión (MPa)	Vibración (mm/s)	Estado	Qué comprobaría el revisor (verificación hipotética)	Decisión condicional de la canalización (si el renderizado confirma los valores)
Н-101-А	1.45	2.1	В норме (Normal)	Verificaría la coincidencia del identificador, los valores numéricos y las unidades (MPa, mm/s) frente al renderizado	Exportación aprobada (Ready for ingestion): condicionada a la confirmación visual completa de todos los campos
Н-102-В	null (omitido)	7.8	Внимание (Warning)	Confirmaría el defecto de escaneo (mancha) en la celda de presión y cotejaría el valor de vibración	Retenido para revisión manual (Operator triage): debido a la ausencia confirmada de una métrica crítica

Patrón arquitectónico de validación

Una canalización sólida de ingesta de documentos distribuye los registros procesados en dos flujos independientes:

• Corredor verde (Verified Export): Reservado exclusivamente para aquellas filas donde cada campo obligatorio se corrobora visualmente con el renderizado de la página de origen y todas las unidades físicas se normalizan según los estándares del esquema.
• Cola de revisión (Quarantine): Cualquier registro que contenga null en campos críticos, discrepancias en las unidades de medida o citas ambiguas se pone en cuarentena para su revisión manual por parte de un operador humano.

---

Documentación oficial y guías

• Procesamiento de documentos con la API de Gemini (límites y formatos admitidos)
• Salidas estructuradas (aplicación de esquemas y validación)