Vai al contenuto principale
Italiano— Scegli una lingua
Menu

La tua prima chiamata OCR in Python

Lezione 5 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Dalla teoria al codice
  2. Lo script minimale
  3. Elaborazione di un file dal tuo computer
  4. Salvataggio dell’estrazione
  5. Il caso di un’immagine isolata
  6. Ricostruzione di un documento illustrato
  7. 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), disponibile in versione generale 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. Addendum del 3 novembre 2026: un PDF locale viene trasmesso in base64 come {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; il tipo document_base64 presente nei vecchi esempi non esiste né nella documentazione né nell’SDK mistralai, e quegli esempi avrebbero fallito. Fonti: OCR Processor · Document QnA.

Dalla teoria al codice

Ora conosci l’endpoint e i suoi parametri. È il momento di scrivere uno script completo che estragga il testo da un PDF, dalla prima riga di importazione fino al file Markdown salvato sul tuo disco. Inizieremo con il caso più semplice—un documento pubblico—per poi passare a ciò che incontrerai nella pratica: file locali, immagini isolate e documenti illustrati che necessitano di ricostruzione.

Due prerequisiti, già trattati ma che vale la pena verificare prima di perdere dieci minuti su un errore di autenticazione:

pip install mistralai
export MISTRAL_API_KEY="your-api-key"

Lo script minimale

Ecco l’estrazione completa di un PDF accessibile online. Tre righe utili: istanzia il client, chiama process e itera attraverso le pagine.

import os
from mistralai.client import Mistral

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

# Chiamata OCR su un PDF pubblico
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://arxiv.org/pdf/2201.04234"
    }
)

# Visualizza il numero di pagine
print(f"Number of pages: {len(ocr_response.pages)}")

# Visualizza il contenuto di ogni pagina
for page in ocr_response.pages:
    print(f"\n--- Page {page.index + 1} ---")
    print(page.markdown)

Nota il page.index + 1: l’indice restituito dall’API inizia da zero, mentre i tuoi utenti contano da uno. È un offset minore finché lo tieni a mente, ma una fonte di confusione duratura quando lo scopri in un report consegnato a un cliente.

Elaborazione di un file dal tuo computer

Nella vita reale, i documenti arrivano raramente tramite un URL pubblico. Li hai sul disco, sono confidenziali, quindi li codifichi in base64. Lo script seguente elabora una fattura di un fornitore e concatena tutte le pagine in un unico blocco di testo:

import os
import base64
from mistralai.client import Mistral

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

# Leggi e codifica il file locale
file_path = "supplier_invoice.pdf"

with open(file_path, "rb") as f:
    document_base64 = base64.b64encode(f.read()).decode("utf-8")

# Chiamata OCR
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": f"data:application/pdf;base64,{document_base64}"
    }
)

# Concatena tutto il testo
full_text = "\n\n".join(
    page.markdown for page in ocr_response.pages
)

print(full_text)

La concatenazione tramite "\n\n".join(...) funziona bene per la visualizzazione o la ricerca full-text. Tuttavia, cancella il confine tra le pagine: se in seguito hai bisogno di citare una fonte o indirizzare un utente alla pagina corretta di un contratto, conserva la struttura pagina per pagina piuttosto che questo unico blocco.

Salvataggio dell’estrazione

Ogni chiamata OCR costa denaro e richiede tempo. Rieseguire l’estrazione dello stesso report di duecento pagine perché hai dimenticato di salvare il risultato è un errore che fai una volta sola. La funzione sottostante scrive il Markdown su un file, segnando le interruzioni di pagina con un commento e un separatore:

import os
import base64
from mistralai.client import Mistral

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

def extract_pdf(pdf_path: str, output_path: str) -> None:
    """Estrae il testo da un PDF e lo salva come Markdown."""

    with open(pdf_path, "rb") as f:
        document_base64 = base64.b64encode(f.read()).decode("utf-8")

    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        }
    )

    with open(output_path, "w", encoding="utf-8") as f:
        for page in ocr_response.pages:
            f.write(f"<!-- Page {page.index + 1} -->\n\n")
            f.write(page.markdown)
            f.write("\n\n---\n\n")

    print(f"Extraction complete: {len(ocr_response.pages)} pages")
    print(f"Result saved to: {output_path}")


# Utilizzo
extract_pdf("annual_report.pdf", "annual_report.md")

Il commento HTML <!-- Page N --> è invisibile nella visualizzazione renderizzata ma rimane presente nel file: puoi trovarlo tramite espressione regolare per ricostruire l’impaginazione durante l’indicizzazione.

Il caso di un’immagine isolata

OCR 4 non si limita ai PDF. Una foto di una fattura scattata con il telefono, una ricevuta scannerizzata, uno screenshot: tutto viene inviato allo stesso modo, utilizzando il tipo image_base64:

import os
import base64
from mistralai.client import Mistral

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

# Codifica un'immagine
with open("scanned_invoice.png", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

# Chiamata OCR su un'immagine
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "image_base64",
        "image_base64": image_base64
    }
)

# Una singola "pagina" per un'immagine
print(ocr_response.pages[0].markdown)

La risposta mantiene la stessa forma: una lista di pagine, che in questo caso ne contiene solo una. Il tuo codice di elaborazione rimane quindi identico indipendentemente dal tipo di file di input, il che semplifica notevolmente le pipeline miste.

Ricostruzione di un documento illustrato

Il Markdown restituito fa riferimento alle immagini come ![imageN.jpg](imageN.jpg), senza incorporarle. Se desideri un file autonomo—un report leggibile offline, un’anteprima da inviare via email—richiedi le immagini in base64 e sostituisci ogni riferimento con un data URI:

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

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

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://arxiv.org/pdf/2201.04234"
    },
    include_image_base64=True
)

for page in ocr_response.pages:
    markdown = page.markdown

    # Sostituisci i riferimenti alle immagini con base64
    for image in page.images:
        placeholder = f"![{image.id}]({image.id})"
        data_uri = f"![{image.id}](data:image/jpeg;base64,{image.image_base64})"
        markdown = markdown.replace(placeholder, data_uri)

    print(markdown[:500])

Il file risultante cresce rapidamente, poiché il base64 pesa circa un terzo in più rispetto al binario originale. Riserva questa ricostruzione per i documenti che devi rendere autonomi e mantieni le immagini come file separati nelle tue pipeline di indicizzazione.

Prima di procedere, prendi un documento di tua proprietà—una fattura, un contratto, una pagina scannerizzata—ed eseguilo attraverso lo script di estrazione locale. Confronta il Markdown risultante con l’originale riga per riga: le discrepanze che trovi, una tabella mal ricostruita o un’intestazione assorbita nel corpo del testo, sono esattamente i problemi che le prossime tre lezioni ti insegneranno a gestire.

Punti chiave

  • La chiamata OCR richiede 3 righe: client, process, leggi pagine
  • Usa base64 per i file locali, URL per i documenti pubblici
  • Il risultato è Markdown strutturato, pronto all’uso
  • Le immagini estratte possono essere ricombinate con il testo
  • Salva sempre le tue estrazioni per evitare chiamate API ripetute