La tua prima chiamata OCR in Python
In questa pagina
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’aliasmistral-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 tipodocument_base64presente nei vecchi esempi non esiste né nella documentazione né nell’SDKmistralai, 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 , 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""
data_uri = f""
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