Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Estrazione di tabelle e strutture

Lezione 6 di 16 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Tabelle: la debolezza storica dell’OCR
  2. Il parametro table_format
  3. Recupero delle tabelle come dati
  4. Passaggio a pandas per l’analisi
  5. Quando le tabelle si complicano
  6. Punti chiave

Aggiornato il 2 novembre 2026 — OCR. OCR 4.0 (mistral-ocr-4-0) è stato ritirato il 30 settembre 2026. Utilizza OCR 4.1 (mistral-ocr-4-1), generalmente disponibile dal 31 agosto allo stesso prezzo, oppure l’alias mistral-ocr-latest, che punta a questa versione dal 16 luglio. OCR 4.1 aggiunge punteggi di confidenza a livello di blocco.

Tabelle: la debolezza storica dell’OCR

Chiedi a Tesseract di estrarre la tabella riassuntiva da un report finanziario e otterrai una sequenza di righe in cui i valori della colonna “Totale” si mescolano a quelli della colonna “Quantità”, senza alcun indizio che li colleghi alle rispettive righe originali. Il problema non è il riconoscimento dei caratteri, che funziona bene; è la totale mancanza di consapevolezza della struttura tabellare. Le soluzioni tradizionali leggono da sinistra a destra, dall’alto in basso, perdendo lungo il cammino le relazioni tra colonne e righe.

OCR 4 affronta la pagina in modo diverso: la vede. Questa comprensione visiva gli permette di ricostruire una tabella come tale, non come testo appiattito.

Il parametro table_format

Controlli il rendering delle tabelle con un singolo parametro passato alla chiamata OCR:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Formato Markdown (consigliato per la maggior parte dei casi)
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/financial-report.pdf"
    },
    table_format="markdown"
)

Sono possibili tre valori e la scelta non è cosmetica: determina cosa puoi fare con il risultato a valle.

Con null, il valore predefinito, le tabelle sono integrate nel flusso Markdown senza una formattazione tabellare specifica. Questa impostazione funziona quando non elabori documenti tabellari e vuoi solo indicizzare il testo.

Con "markdown", ogni tabella viene resa nel formato standard con pipe, producendo un output leggibile così com’è e facile da analizzare:

| Prodotto | Quantità | Prezzo Unitario | Totale |
|---------|----------|------------|-------|
| Widget A | 100 | €12,50 | €1.250 |
| Widget B | 50 | €25,00 | €1.250 |
| **Totale** | **150** | | **€2.500** |

Con "html", la tabella viene resa come HTML completo, preservando le unioni di celle e la formattazione avanzata che Markdown non può esprimere:

<table>
  <thead>
    <tr>
      <th>Prodotto</th>
      <th>Quantità</th>
      <th>Prezzo Unitario</th>
      <th>Totale</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Widget A</td>
      <td>100</td>
      <td>€12,50</td>
      <td>€1.250</td>
    </tr>
  </tbody>
</table>

In pratica, Markdown copre la maggior parte delle esigenze: indicizzazione RAG, ricerca o visualizzazione in un editor. Passa a HTML non appena le tue tabelle includono celle unite o il risultato deve essere incorporato in una pagina web. Mantieni null solo quando le tabelle non contano nel tuo flusso di lavoro, ad esempio in un report narrativo o nella corrispondenza.

Recupero delle tabelle come dati

Una tabella Markdown è ancora testo. Per trasformarla in dati manipolabili, devi individuarla nel flusso e suddividerla. La funzione seguente scorre le righe, identifica quelle appartenenti a una tabella, ignora la riga separatore e chiude la tabella corrente non appena appare una riga regolare:

import os
import re
import json
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

def extract_markdown_tables(markdown: str) -> list[list[list[str]]]:
    """Estrae le tabelle Markdown e le converte in liste."""
    tables = []
    lines = markdown.split("\n")
    current_table = []
    in_table = False

    for line in lines:
        if "|" in line and line.strip().startswith("|"):
            # Ignora la riga separatore (|---|---|)
            if re.match(r"^\|[\s\-:|]+\|$", line.strip()):
                continue
            cells = [
                c.strip() for c in line.strip().strip("|").split("|")
            ]
            current_table.append(cells)
            in_table = True
        else:
            if in_table and current_table:
                tables.append(current_table)
                current_table = []
            in_table = False

    if current_table:
        tables.append(current_table)

    return tables


# Estrazione OCR con tabelle Markdown
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/invoice.pdf"
    },
    table_format="markdown"
)

# Itera attraverso le pagine ed estrae le tabelle
for page in ocr_response.pages:
    tables = extract_markdown_tables(page.markdown)
    for i, table in enumerate(tables):
        print(f"Pagina {page.index + 1}, Tabella {i + 1}:")
        print(json.dumps(table, indent=2, ensure_ascii=False))

Il controllo finale fuori dal ciclo non è decorativo: senza di esso, una tabella alla fine di una pagina — un caso comune per il riepilogo di una fattura — non verrebbe mai aggiunta alla lista, poiché nessuna riga regolare arriva a chiuderla.

Passaggio a pandas per l’analisi

Una lista di liste è sufficiente per l’esportazione, non per il calcolo. Convertire in un DataFrame significa promuovere la prima riga a intestazioni:

import pandas as pd

def tables_to_dataframes(markdown: str) -> list[pd.DataFrame]:
    """Converte le tabelle Markdown in DataFrame pandas."""
    tables = extract_markdown_tables(markdown)
    dataframes = []

    for table in tables:
        if len(table) < 2:
            continue
        headers = table[0]
        data = table[1:]
        df = pd.DataFrame(data, columns=headers)
        dataframes.append(df)

    return dataframes

# Utilizzo
for page in ocr_response.pages:
    dfs = tables_to_dataframes(page.markdown)
    for df in dfs:
        print(df.to_string())
        print()

Il test len(table) < 2 filtra i falsi positivi: una riga isolata contenente una pipe, all’interno di un blocco di codice o di un indirizzo, non produrrà un DataFrame rotto o vuoto. Tieni presente che i valori rimangono stringhe; spetta ancora a te convertire “€1.250” in un numero.

Quando le tabelle si complicano

Celle unite, intestazioni su due livelli o layout irregolari spingono Markdown oltre i suoi limiti espressivi. Passa allora a HTML e lascia che BeautifulSoup e pandas gestiscano l’analisi:

from bs4 import BeautifulSoup
import pandas as pd

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/complex-report.pdf"
    },
    table_format="html"
)

for page in ocr_response.pages:
    soup = BeautifulSoup(page.markdown, "html.parser")
    tables = soup.find_all("table")

    for table in tables:
        df = pd.read_html(str(table))[0]
        print(df)

Questo approccio ti risparmia la scrittura di un parser: pd.read_html gestisce gli attributi rowspan e colspan che la tua suddivisione manuale mancherebbe. Il costo è una dipendenza extra e un output leggermente più verboso: un compromesso che vale la pena per report finanziari o tabelle normative.

Punti chiave

  • Il parametro table_format controlla il rendering delle tabelle (null, markdown, html)
  • Il formato Markdown è adatto alla maggior parte dei casi d’uso
  • Il formato HTML preserva le celle unite e la formattazione avanzata
  • Le tabelle estratte possono essere convertite in DataFrame pandas per l’analisi
  • OCR 4 ricostruisce fedelmente la struttura tabellare, anche su layout complessi