Como extrair tabelas de PDFs grandes e verificar os números
Um fluxo prático para extrair tabelas de documentos PDF extensos com a Gemini API: definição de esquemas que permitem valores nulos, escolha da Files API, solicitação de citações e números de página como pistas heurísticas e reconciliação dos dados extraídos com o documento visual original antes da exportação.
Conteúdo
Ao lidar com documentos PDF complexos — como relatórios de inspeção de equipamentos com várias páginas ou demonstrativos financeiros —, um texto limpo e uniforme é a exceção, e não a regra. Em documentos corporativos do mundo real, páginas digitais se misturam com folhas digitalizadas, tabelas não possuem bordas de grade nítidas e métricas críticas costumam estar ocultas em notas de rodapé densas.
Enviar esses arquivos diretamente para um modelo multimodal e gravar o resultado sem filtros em um banco de dados de produção é arriscado. Como os modelos de fundação continuam sendo sistemas probabilísticos, um pipeline de extração confiável não pode se basear em confiança cega. Em vez disso, ele deve ser construído em torno de um design de schema deliberado, da coleta de pistas contextuais de auditoria e de uma verificação rigorosa pós-extração em relação ao original visual.
1. Schema de dados: fixando campos e permitindo nulls
O mecanismo de Gemini Structured Outputs garante que as respostas do modelo sigam estritamente o schema declarado, gerando um JSON sintaticamente válido. Se uma propriedade for definida como numérica, nenhum texto conversacional indesejado contaminará o valor.
No entanto, a conformidade sintática com o schema protege apenas contra erros estruturais — ela não garante a veracidade semântica:
- O modelo pode misturar linhas adjacentes ou transpor colunas em tabelas densas e sem bordas;
- Em digitalizações degradadas, o dígito
8pode facilmente ser interpretado como3, e pontos decimais costumam se perder; - Quando uma métrica está ausente ou ilegível, um modelo que não tenha permissão explícita para omitir valores pode tentar inventar um número plausível.
Para mitigar o risco de alucinações, os schemas devem declarar os campos como anuláveis (Optional ou null), acompanhados de instruções explícitas no prompt para retornar null sempre que um número não puder ser decifrado com alto nível de confiança. Embora permitir valores nulos reduza significativamente a pressão para adivinhar, isso não oferece, por si só, uma garantia absoluta contra alucinações.
2. Ingestão de arquivos: quando escolher a Files API
De acordo com a documentação oficial de processamento de documentos do Gemini, os limites operacionais são de até 50 MB ou até 1.000 páginas por arquivo PDF (as restrições de tamanho de arquivo e contagem de páginas se aplicam simultaneamente, sem garantia de que ambos os limites máximos possam ser alcançados ao mesmo tempo — o processamento é interrompido no limite que for atingido primeiro).
O método de transmissão ideal depende do tamanho do documento e do padrão de operação:
- Envio de dados inline é mais adequado para documentos pequenos e chamadas de extração pontuais.
- A Files API (
client.files.upload) foi projetada para arquivos maiores e fluxos de trabalho com múltiplos turnos, em que o mesmo documento é consultado em operações consecutivas (por exemplo, uma classificação inicial de seções seguida pela extração direcionada de tabelas). O uso da Files API evita o reenvio de todo o payload do documento a cada chamada.
3. Consulta de dados: schema, pistas de citação e resposta hipotética
Para tornar os dados extraídos auditáveis, oriente o modelo no prompt a retornar metadados auxiliares junto aos valores de destino: um número de página aproximado (page_number) e um trecho de citação curto e textual (evidence_quote).
Distinção fundamental:
page_numbereevidence_quotenão são provas factuais; são estritamente pistas heurísticas de busca. Como o próprio modelo gera esses campos, os trechos de citação podem conter artefatos de OCR ou mesclar linhas adjacentes, e o número visual da página informado pode divergir do índice físico da folha no arquivo PDF.
Cenário hipotético do problema
Considere a modelagem de um problema hipotético (nenhum PDF real foi fornecido, enviado ou analisado, e nenhuma consulta real à API foi executada): simular a extração de métricas resumidas de um relatório hipotético de inspeção de bombas. Neste exemplo ilustrativo, examinamos uma tabela hipotética de duas linhas:
| Identificador | Pressão (MPa) | Vibração (mm/s) | Status | Observações |
|---|---|---|---|---|
| Н-101-А | 1.45 | 2.1 | Normal (В норме) | Inspeção agendada |
| Н-102-В | (ilegível) | 7.8 | Atenção (Внимание) | Folga excessiva |
Abaixo está um exemplo de schema definido com Pydantic acompanhado da sintaxe de chamada do 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)Resposta JSON ilustrativa do modelo
O JSON a seguir ilustra uma resposta hipotética do modelo para essa solicitação. Enfatizamos: este retorno atua como uma ilustração estrutural hipotética, e não como resultado de uma execução real da API ou medição física autêntica:
{
"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 Внимание"
}
]
}Nesta resposta hipotética, ambas as instâncias de page_number: 12 e ambos os valores de evidence_quote carregam o status de pistas não verificadas. Embora o modelo tenha emitido corretamente o valor null para o dado ilegível de pressão na segunda unidade, nenhum dos atributos extraídos é considerado um fato confirmado a priori.
4. Reconciliação com o original visual e regras de exportação
Os registros extraídos não podem ser gravados diretamente em bancos de dados de produção sem validação. É indispensável realizar uma auditoria ponta a ponta comparando cada campo com a renderização visual da página de origem no PDF.
Esclarecimento importante sobre o exemplo: A tabela de duas linhas, a página 12, o deslocamento físico para a 14ª folha, o setor de compressores e o fluxo de verificação visual representam uma ilustração exclusivamente hipotética do processo. Nenhum documento PDF real foi fornecido ou inspecionado, e as etapas descritas a seguir refletem o que um revisor checaria na prática, formulando decisões condicionais caso a renderização visual confirme os valores indicados.
Verificação passo a passo dos registros: o que um revisor checaria
-
Unidade
Н-101-А:- Página e localização: O modelo retornou a pista
page_number: 12. O revisor inspecionaria a renderização visual da página 12 (ou folha 14, se as páginas pré-textuais tiverem criado um deslocamento físico) e localizaria a tabela correspondente do setor de compressores. - Identificador: Na primeira coluna, o revisor confirmaria a correspondência exata do identificador
Н-101-А. - Pressão e unidades: Na coluna de pressão de entrada, o revisor verificaria se o valor
1.45está claramente legível e se as unidades de engenharia coincidem com o esperado pelo schema (МПа/MPa). - Vibração e unidades: Sob a vibração, o revisor verificaria o valor
2.1e a denominação da unidade (мм/с/mm/s). - Status: Na coluna de condição operacional, o revisor confirmaria a presença do status
В норме(Normal). - Decisão condicional: Se a página renderizada validar todos os campos, valores e unidades físicas, a linha seria aprovada para exportação (Export / Accepted).
- Página e localização: O modelo retornou a pista
-
Unidade
Н-102-В:- Página e localização: Na mesma tabela hipotética, o revisor passaria para a segunda linha.
- Identificador: O revisor confirmaria a presença do identificador
Н-102-В. - Vibração e status: O revisor cruzaria o valor de vibração
7.8e o statusВнимание(Atenção / Warning) com a camada visual. - Pressão: O modelo retornou
null. O revisor examinaria a célula correspondente na renderização da página: se uma mancha escura e borrada (um defeito de digitalização) for observada no lugar da leitura, isso valida a decisão do modelo de retornarnull; contudo, uma medição física essencial permanece ausente. - Decisão condicional: Como a confirmação visual atesta a ausência de uma leitura crítica de pressão, a linha seria bloqueada para exportação automatizada e encaminhada para revisão manual (Hold for manual review), demandando uma nova digitalização operacional ou o cruzamento de dados com registros de manutenção secundários.
Resultado verificado após auditoria (Checked Output)
A tabela de resumo detalha exatamente o que o revisor inspecionaria e qual decisão condicional de roteamento o pipeline de validação acionaria mediante confirmação visual:
| Unidade | Pressão (MPa) | Vibração (mm/s) | Status | O que o revisor checaria (Verificação hipotética) | Decisão condicional do pipeline (Se a renderização confirmar os valores) |
|---|---|---|---|---|---|
| Н-101-А | 1.45 | 2.1 | В норме (Normal) | Verificaria a correspondência do identificador, valores numéricos e unidades (MPa, mm/s) na renderização | Exportação aprovada (Pronto para ingestão) — condicionada à confirmação visual completa de todos os campos |
| Н-102-В | null (omitido) | 7.8 | Внимание (Atenção) | Confirmaria o defeito de digitalização (mancha) na célula de pressão e cruzaria o valor de vibração | Retido para revisão manual (Triagem por operador) — devido à ausência confirmada de uma métrica crítica |
Padrão arquitetural de validação
Um pipeline robusto de ingestão de documentos encaminha os registros processados para dois fluxos distintos:
- Corredor Verde (Exportação verificada): Reservado exclusivamente para linhas em que todos os campos obrigatórios foram corroborados visualmente com a renderização da página original e todas as unidades físicas foram normalizadas para os padrões do schema.
- Fila de Revisão (Quarentena): Quaisquer registros que contenham
nullem campos críticos, unidades de medida conflitantes ou citações ambíguas são colocados em quarentena para análise manual por um operador humano.
