Mistral OCR 3: guida completa con Mistral AI Studio e Python

L’ultimo modello OCR di Mistral, Mistral OCR 3, è in grado di estrarre testo e immagini incorporate da un’ampia gamma di documenti con un’accuratezza eccezionale.

In questo articolo, ti mostrerò come sfruttare al massimo Mistral OCR 3 sia con il loro AI Studio sia con la loro API in Python. Costruiremo una piccola applicazione che trasforma la foto di un menu in un sito web interattivo.

Se vuoi approfondire l’uso delle API per creare strumenti basati sull’IA, ti consiglio di dare un’occhiata al corso Working with the OpenAI API. 

Che cos’è Mistral OCR?

OCR sta per Optical Character Recognition e serve a convertire i documenti in testo. Per esempio, può trasformare la foto di un appunto scritto a mano in testo o una tabella in un PDF in una vera tabella di testo ricercabile e modificabile.

Mistral OCR 3 è l’ultimo modello di comprensione dei documenti di Mistral AI, che offre accuratezza ed efficienza all’avanguardia per documenti reali. Estrae testo e immagini incorporate con alta fedeltà e preserva la struttura tramite output in markdown con ricostruzione di tabelle basata su HTML, con JSON strutturato opzionale.

Mistral OCR 3 supera tutti i concorrenti in un’ampia gamma di benchmark:

Rispetto a Mistral OCR 2, ottiene un tasso di vittoria complessivo del 74% su moduli, documenti scansionati, tabelle complesse e scrittura a mano, con miglioramenti notevoli su scansioni di bassa qualità e layout densi.

Per saperne di più sull’OCR e sul modello precedente di Mistral, leggi questo articolo: Mistral OCR: guida con esempi pratici.

Usare Mistral OCR 3 su Mistral AI Studio

Vediamo come configurare Mistral OCR 3 con AI Studio. 

Configurazione dell’account

Mistral OCR 3 è disponibile su il loro AI Studio. È il modo più semplice per provarlo perché offre un’interfaccia intuitiva.

Dopo l’iscrizione, ci viene innanzitutto chiesto di creare un’organizzazione:

Inizialmente, Mistral OCR 3 sarà bloccato e dovremo selezionare un piano per sbloccarlo:

È possibile selezionare un piano gratuito, che consente di usare Mistral OCR 3 permettendo loro di raccogliere i dati d’uso per migliorare i servizi. In alternativa, possiamo inserire i dati della carta di credito e pagare a consumo.

Non c’è canone di abbonamento, ma si paga 2 $ o 1 $ ogni 1.000 pagine, a seconda che si usino o meno richieste batch.

Analisi del primo documento

Una volta configurato l’account, possiamo sperimentare Mistral OCR 3 accedendo alla scheda "Document AI" nell’AI Studio.

Per iniziare, carichiamo il documento o l’immagine su cui vogliamo eseguire l’OCR. Nel mio caso, ho scritto del testo e una tabella su un foglio di carta e l’ho caricata. La mia calligrafia è piuttosto pessima, quindi ero curioso di vedere se Mistral OCR 3 riuscisse a capirla.

Dopo aver selezionato il file, ci vengono presentate le opzioni su come elaborarlo. In questo primo esempio, ho lasciato le opzioni predefinite e ho semplicemente fatto clic sul pulsante "Run" in alto a destra.

Ecco il risultato:

Il risultato è piuttosto buono, ma non perfetto:

• La prima frase ha due errori: "homd" invece di "hand" e "tarnible" invece di "terrible".
• La tabella è complessivamente buona, ma non ha identificato correttamente i nomi delle colonne. Il nome della tabella "OCR Benchmark Multilingual Chinese" e la colonna "Result" sono stati fusi.
• Mi ha colpito il modo in cui ha gestito gli errori che ho cancellato manualmente. Tuttavia, se lo usassi per analizzare i miei appunti, preferirei che venissero identificati e omessi.
• Infine, ho scritto una frase in cinese tradizionale, e ne ha riconosciuto la maggior parte. Un carattere "好" è stato interpretato come due separati, "女" e "子"; le virgole sono state riconosciute come lettere "g" e c’è un errore anche alla fine.

Esplorare le opzioni di parsing

Una delle caratteristiche interessanti di Mistral OCR 3 è la possibilità di specificare una struttura JSON per analizzare i dati. È particolarmente utile per le tabelle, perché ci permette di indicare i nomi delle colonne e i relativi tipi di dato, così da ottenere le righe come dizionario JSON.

Proviamo a rianalizzare la tabella dell’esempio precedente specificando uno schema JSON.

Per fornire uno schema JSON, dobbiamo selezionare lo schema JSON invece della modalità testo prima di eseguire l’OCR.

Poi forniamo uno schema tramite codice o usando l’interfaccia "Visual Builder". Consiglio la seconda opzione, più semplice quando stiamo già usando il modello manualmente.

Quando aggiungiamo un campo, specifichiamo:

• Il nome
• La descrizione
• Il tipo di dato
• Se il campo è obbligatorio o meno

In questo caso, ho specificato due campi: uno per il nome del modello e un altro per il risultato del benchmark:

Ora possiamo fare clic su "Run" e vedere i risultati. Purtroppo, questo esempio non ha funzionato. Nei risultati, l’unica cosa restituita è stato lo schema che avevo fornito, non i dati reali.

Ho pensato di averlo usato male, quindi, per sicurezza, ho fatto uno screenshot di una tabella di esempio da Wikipedia) e ho riprovato.

Ho specificato quattro colonne, lasciando l’ultima come opzionale:

Questa volta ha funzionato bene. Sembra che, quando il parsing fallisce, il risultato JSON sia semplicemente lo schema fornito. Ciò significa anche che Mistral OCR 3 non è riuscito a interpretare la mia tabella scritta a mano come JSON, nonostante fosse in grado di renderla come testo.

Usare Mistral OCR 3 con Python

In questa sezione vedremo come usare Python per interagire con l’API di Mistral OCR 3. Questo offre molta più flessibilità, perché possiamo, per esempio, combinare l’output con altri modelli di IA per elaborare i dati estratti.

Quando carichiamo un file nell’AI Studio, c’è un pulsante "Code" accanto a "Run". Cliccandoci, possiamo vedere quale codice sarebbe necessario per eseguire la stessa operazione tramite API.

Ecco un esempio:

Tuttavia, il codice Python fornito non è del tutto accurato. Per esempio, definisce una funzione chiamata encode_file ma poi chiama una funzione chiamata encode. Sono piccole incongruenze, ma fanno sì che il codice non funzioni immediatamente.

Niente paura: spiegheremo nel dettaglio come usare l’API. Per saperne di più sull’API, consigliamo di consultare la documentazione ufficiale.

Configurazione dell’API

Per prima cosa dobbiamo creare una chiave API nella scheda "API Keys" e copiare tale chiave in un nuovo file chiamato .env situato nella stessa cartella dello script Python.

Poi installiamo le dipendenze richieste:

pip install mistralai python-dotenvOfferto da

Eseguire l’OCR su un’immagine

Ecco uno script Python che carica un’immagine JPEG locale, esegue l’OCR e salva il risultato in un file markdown:

import sys
import base64
import os
from mistralai import Mistral
from dotenv import load_dotenv

# Load the API key from the .env file
load_dotenv()

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

# Load a file as base 64
def encode_file(file_path):
    with open(file_path, "rb") as pdf_file:
        return base64.b64encode(pdf_file.read()).decode('utf-8')

# Perform OCR on and image
def process_image_ocr(file_path):
    base64_file = encode_file(file_path)
    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "image_url",
            "image_url": f"data:image/jpeg;base64,{base64_file}" 
        },
        include_image_base64=True
    )
    for index, page in enumerate(ocr_response.pages):
        with open(f"page{index}.md", "wt") as f:
            f.write(page.markdown)

if __name__ == "__main__":
    # Load the input file from the arguments
    file_path = sys.argv[1]
    process_image_ocr(file_path)Offerto da

Eseguire l’OCR su un PDF

Quando l’input è un PDF invece di un’immagine, cambia solo il valore fornito nel campo document. Per un’immagine JPEG, abbiamo usato:

document={
  "type": "image_url",
   "image_url": f"data:image/jpeg;base64,{base64_file}" 
},Offerto da

Per un PDF, invece, usiamo:

document={
  "type": "document_url",
  "document_url": f"data:application/pdf;base64,{base64_file}" 
},Offerto da

Ecco una funzione completa che possiamo usare per elaborare un PDF:

def process_pdf_ocr(file_path):
    base64_file = encode_file(file_path)
    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{base64_file}" 
        },
        include_image_base64=True
    )
    process_pages(ocr_response)Offerto da

Creare una versione generica

Avere due funzioni distinte per elaborare file PDF e JPEG è un po’ macchinoso e non è la pratica migliore, dato che condividono molto codice.

Per evitarlo, abbiamo scritto una nuova funzione migliorata che usa il pacchetto mimetypes per provare a identificare il tipo di file fornito e costruire la richiesta API di conseguenza. Abbiamo anche aggiornato il codice per salvare le immagini identificate nel documento.

Ecco la versione finale:

import sys
import os
import base64
import mimetypes
import datauri
from mistralai import Mistral
from dotenv import load_dotenv
# Load the API key from the .env file
load_dotenv()
# Initialize the Mistral client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# List the supported image types
SUPPORTED_IMAGE_TYPES = {
    "image/jpeg",
    "image/png",
    "image/webp",
    "image/tiff",
}
PDF_MIME = "application/pdf"
# Load a file as base 64
def encode_file(file_path: str) -> str:
    with open(file_path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")
# Build the document payload depending on the type of data contained in the file
def build_document_payload(file_path: str) -> dict:
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type:
        raise ValueError(f"Could not determine MIME type for {file_path}")
base64_file = encode_file(file_path)
if mime_type == PDF_MIME:
        return {
            "type": "document_url",
            "document_url": f"data:{mime_type};base64,{base64_file}",
        }
if mime_type in SUPPORTED_IMAGE_TYPES:
        return {
            "type": "image_url",
            "image_url": f"data:{mime_type};base64,{base64_file}",
        }
raise ValueError(f"Unsupported file type: {mime_type}")
# Generic function to process OCR on a file
def process_ocr(file_path: str, output_filename: str = "output.md"):
    document = build_document_payload(file_path)
    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document=document,
        include_image_base64=True,
    )
    process_pages(ocr_response, output_filename)
# Save an image to a local file
def save_image(image):
    parsed = datauri.parse(image.image_base64)
    with open(image.id, "wb") as f:
        f.write(parsed.data)
# Process all pages from the OCR response
def process_pages(ocr_response, output_filename: str):
    with open(output_filename, "wt") as f:
        for page in ocr_response.pages:
            f.write(page.markdown)
            for image in page.images:
                save_image(image)
if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python ocr.py <file>")
        sys.exit(1)
process_ocr(sys.argv[1])Offerto da

Questa versione richiede il pacchetto datauri per salvare l’immagine identificata da Mistral OCR 3, installabile con:

pip install datauriOfferto da

Fornire uno schema JSON

Abbiamo visto sopra che Mistral OCR 3 consente di fornire uno schema JSON per analizzare i dati. Questa funzionalità è disponibile anche tramite API.

Per farlo, dobbiamo fornire lo schema JSON nel parametro document_annotation_format quando effettuiamo la richiesta. Di seguito un esempio di schema JSON per le due colonne model e result, corrispondenti alla tabella scritta a mano dell’esempio.

document_annotation_format={
    "name": "response_schema",
    "schemaDefinition": {
        "properties": {
            "model": {
                "type": "string",
	         "description": "The name of the model"
             },
             "result": {
	         "type": "number",
	         "description": "The benchmark result"
	     }
         },
         "required": [
             "model"
         ]
    }
}Offerto da

La struttura è sempre la stessa. Dobbiamo aggiungere una voce per ogni colonna nel campo properties, includendo informazioni sul tipo di dato e una descrizione per aiutare il modello a identificare i dati.

Poi elenchiamo tutti i campi obbligatori nel campo required.

Per usarlo insieme al codice, il modo più semplice è archiviare lo schema in un file JSON e caricarlo con il pacchetto json.

Idee di progetti con Mistral OCR 3

Uno dei principali vantaggi di usare Mistral OCR 3 tramite API è la possibilità di costruirci sopra. In questa sezione ti proponiamo alcune idee di progetto su cui lavorare.

App per tracciare le spese

Abbiamo imparato a eseguire l’OCR su un’immagine. Possiamo usarlo per creare un’app che scatta la foto di uno scontrino, poi usa Mistral OCR 3 per elaborare i dati nell’immagine ed estrarre un dizionario JSON con gli articoli sullo scontrino e i relativi prezzi.

Queste spese possono quindi essere categorizzate automaticamente e aggiunte a un database, permettendo all’utente di tenere traccia dei propri consumi.

Lettore audio di documenti

Possiamo combinare Mistral OCR 3 con un’IA text-to-speech per creare un lettore audio di documenti. L’utente può selezionare un PDF di testo e inviarlo a Mistral OCR 3 per l’elaborazione. Quindi il testo risultante viene inviato a un modello text-to-speech come OpenAI Audio API o Eleven Labs.

Poiché Mistral OCR 3 funziona anche con le immagini, può essere usato con le foto, permettendo agli utenti di scattare la foto di un documento e ascoltarlo in mobilità.

Per saperne di più sul text-to-speech, ti consiglio uno dei seguenti contenuti:

• OpenAI's Audio API: guida con progetto demo
• Guida per principianti all’API di ElevenLabs: trasforma testo e voce in esperienze audio dinamiche

Conclusione

Mistral OCR 3 è uno strumento capace e pratico per trasformare documenti reali in testo utilizzabile e dati strutturati, sia che tu stia sperimentando nell’AI Studio sia che tu stia integrando via Python.

Dà il meglio su pagine scansionate, moduli e tabelle, preserva il layout con markdown e immagini e supporta schema JSON quando serve struttura. Come abbiamo visto, però, calligrafie disordinate e intestazioni ambigue possono ancora metterlo in difficoltà, e i parsing di schema falliti restituiscono semplicemente lo schema.

L’API è semplice, una volta risolte piccole incoerenze, e un gestore file generico, insieme al salvataggio delle immagini, rende facile l’integrazione in piccole app o pipeline. Se vuoi solo provarlo, lo Studio è la via più rapida. Per l’uso in produzione, valuta il modello di costo, usa il batch quando possibile e aggiungi validazioni per i casi limite.

Da lì puoi iterare: affina gli schemi, combina gli output con altri modelli e costruisci utility mirate come parser di scontrini o lettori audio, lasciando che il modello faccia il grosso del lavoro mentre tu ti occupi di affidabilità e UX.