Mistral OCR: una guida con esempi pratici

La settimana scorsa, Mistral ha rilasciato Mistral OCR, un'innovativa API di riconoscimento ottico dei caratteri (OCR). La loro API stabilisce un nuovo standard per le capacità dell'IA di comprendere documenti e immagini. È in grado di elaborare e analizzare documenti con immagini, formule, tabelle e altro ancora con un alto grado di accuratezza.

In questo articolo ti spiegherò passo dopo passo come usare Mistral OCR con Python. Ti mostrerò come utilizzarlo con documenti, immagini e come combinarlo con la chat per unire prompt e documenti.

Che cos'è Mistral OCR?

Il riconoscimento ottico dei caratteri, o OCR, è una tecnologia che converte diversi tipi di documenti — come documenti cartacei scansionati, file PDF o immagini catturate con una fotocamera digitale — in dati modificabili e ricercabili.

L'OCR funziona identificando i caratteri di testo nelle immagini, analizzandone i pattern e traducendo questi elementi visivi in testo codificato a macchina. Questa tecnologia ha trasformato il modo in cui interagiamo con i materiali stampati, abilitando di tutto, dalla digitalizzazione di archivi storici all'automazione dell'inserimento dati da moduli aziendali.

L'API OCR di Mistral rappresenta un progresso significativo in questo campo, offrendo agli sviluppatori uno strumento potente per estrarre testo da immagini e documenti con notevole precisione.

Fonte: Mistral

A differenza delle soluzioni OCR tradizionali che si limitano a identificare il testo, l'API di Mistral usa modelli di IA avanzati per comprendere il contesto e la struttura dei documenti, mantenendo la formattazione mentre estrae i contenuti. Questo significa che può riconoscere layout complessi, distinguere tra intestazioni e corpo del testo e interpretare correttamente tabelle e formati a più colonne.

Ciò che rende l'API OCR di Mistral particolarmente speciale è la sua integrazione con le capacità di comprensione del linguaggio di Mistral. Il sistema non si limita a estrarre il testo: lo comprende.

Questo consente flussi di elaborazione dei documenti più sofisticati, in cui l'API non solo riconosce il testo ma può anche rispondere a domande sul contenuto, riassumere informazioni o estrarre punti dati specifici.

Inoltre, l'API OCR di Mistral è progettata per funzionare con più lingue e set di caratteri, rendendola versatile per applicazioni globali. Questa combinazione di riconoscimento del testo preciso e profonda comprensione linguistica posiziona l'offerta di Mistral come una soluzione di document intelligence di nuova generazione, non un semplice strumento OCR.

Prezzi e limiti di Mistral OCR

L'API Mistral OCR non è gratuita, ma costa solo 1 $ ogni 1.000 pagine (ovvero 0,001 $ a pagina). A mio avviso è un prezzo molto competitivo e accessibile.

I file dei documenti non devono superare i 50 MB di dimensione e non devono essere più lunghi di 1.000 pagine.

Puoi trovare maggiori informazioni nella loro pagina dei prezzi.

Configurazione dell'API Mistral OCR

Vai alla pagina delle chiavi API di Mistral e clicca sul pulsante "Create new key".

Nel modulo di creazione della chiave, possiamo assegnarle un nome e una data di scadenza.

• Il nome è utile a fini organizzativi se abbiamo più progetti, ognuno con una chiave diversa. Per questo tutorial possiamo lasciarlo vuoto.
• La data di scadenza è utile per assicurarsi che, se la condividiamo accidentalmente, le persone non abbiano accesso alla nostra chiave per sempre.

Dopo aver creato la chiave, copiala e crea un file chiamato .env nella stessa cartella in cui scriveremo lo script. 

Incolla la chiave nel file usando il seguente formato:

MISTRAL_API_KEY=<paste_api_key_here>

Se usi GitHub, assicurati di aggiungere questo file al .gitignore per evitare di caricare la chiave API su GitHub.

Configurazione dell'ambiente Python

Per usare l'API OCR di Mistral con Python, installa i seguenti pacchetti:

• mistralai: il pacchetto fornito da Mistral per interagire con la loro API.
• python-dotenv: un pacchetto che semplifica il caricamento della chiave API dal file .env.
• datauri: questo pacchetto serve per elaborare i dati delle immagini e salvarli in file.

Possiamo installarli con il comando:

pip install mistralai python-dotenv datauri

Ti consiglio di creare un ambiente per assicurarti che l'installazione non entri in conflitto con la tua installazione Python predefinita. Un modo per farlo è usare Anaconda:

conda create -n mistral -y python=3.9
conda activate mistral
pip install mistralai python-dotenv datauri

Il primo comando crea un ambiente chiamato mistral che usa Python 3.9. Poi attiviamo quell'ambiente e installiamo i pacchetti menzionati sopra.

Creare lo script Python per interagire con Mistral OCR

Vediamo come effettuare la nostra prima richiesta all'API OCR di Mistral.

Importare le dipendenze necessarie

Nella stessa cartella del file .env, crea un nuovo script Python chiamato ocr.py e importa i pacchetti necessari:

from mistralai import Mistral
from dotenv import load_dotenv
import datauri
import os

Nota che importiamo anche os, che usiamo per caricare la chiave API dall'ambiente in una variabile. Non serve installarlo perché è un pacchetto integrato.

Caricare la chiave API e inizializzare il client Mistral

Aggiungiamo quindi le seguenti righe per caricare la chiave API e inizializzare il client Mistral:

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

Effettuare una richiesta all'API Mistral OCR

Il modo più semplice per usare l'API OCR è con l'URL di un PDF ospitato online. Per questo esempio, usiamo questo paper su Mistral 7B ospitato su arXiv (una piattaforma che ospita versioni pre-sottomissione di articoli di ricerca):

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

Possiamo poi eseguire lo script con il comando python ocr.py. Questo genererà la seguente risposta:

pages=[OCRPageObject(index=0, markdown='# Mistral 7B \n\nAlbert Q. Jiang,
...

Struttura della risposta

La risposta contiene diversi campi. I dettagli completi sono disponibili nella documentazione API di Mistral. Ci interessa in particolare il campo pages, che contiene, per ogni pagina, il testo in markdown della pagina.

Possiamo stampare il numero di pagine per verificare che corrisponda al file PDF:

print(len(ocr_response.pages))

Risultato:

9

Ogni pagina ha diversi campi. I più importanti sono:

• markdown: il contenuto markdown della pagina.
• images: le immagini nella pagina.

Per esempio, possiamo stampare il contenuto markdown della prima pagina con:

print(ocr_response.pages[0].markdown)

# Mistral 7B 

Albert Q. Jiang, Alexandre Sablayrolles, Arthur Mensch, Chris Bamford, Devendra Singh Chaplot, Diego de las Casas, Florian Bressand, Gianna Lengyel, Guillaume Lample, Lucile Saulnier, Lélio Renard Lavaud, Marie-Anne Lachaux, Pierre Stock, Teven Le Scao, Thibaut Lavril, Thomas Wang, Timothée Lacroix, William El Sayed

![img-0.jpeg](img-0.jpeg)

#### Abstract

We introduce Mistral 7B, a 7-billion-parameter language
...

Convertire un file PDF in Markdown

Per convertire un PDF in Markdown, cicliamo su tutte le pagine e scriviamo il contenuto Markdown di ciascuna in un file. Ecco una funzione per farlo.

def create_markdown_file(ocr_response, output_filename = "output.md"):
  with open(output_filename, "wt") as f:
    for page in ocr_response.pages:
      f.write(page.markdown)

Ecco un confronto affiancato tra il file PDF originale e il file Markdown che abbiamo generato:

Elaborare le immagini

Nell'esempio precedente, abbiamo visto che il file Markdown non conteneva le immagini del PDF. Questo perché non abbiamo creato i file immagine, ma solo il testo Markdown.

Se guardiamo l'output markdown, vediamo che contiene un riferimento all'immagine:

...
![img-0.jpeg](img-0.jpeg)
...

Tuttavia, quell'immagine non viene renderizzata. Le immagini di ogni pagina sono memorizzate nell'attributo images.

for page in ocr_response.pages:
  print(page.images)

Output:

[OCRImageObject(id='img-0.jpeg', top_left_x=425, top_left_y=600, bottom_right_x=1283, bottom_right_y=893, image_base64=None)]
[OCRImageObject(id='img-1.jpeg', top_left_x=294, top_left_y=638, bottom_right_x=1405, bottom_right_y=1064, image_base64=None)]
[OCRImageObject(id='img-2.jpeg', top_left_x=294, top_left_y=191, bottom_right_x=1405, bottom_right_y=380, image_base64=None)]
[OCRImageObject(id='img-3.jpeg', top_left_x=292, top_left_y=204, bottom_right_x=1390, bottom_right_y=552, image_base64=None)]
[OCRImageObject(id='img-4.jpeg', top_left_x=464, top_left_y=202, bottom_right_x=1232, bottom_right_y=734, image_base64=None)]
[]
[OCRImageObject(id='img-5.jpeg', top_left_x=727, top_left_y=794, bottom_right_x=975, bottom_right_y=1047, image_base64=None)]
[]
[]

Nell'output sopra, vediamo che abbiamo effettivamente un riferimento a img-0.jpeg. Tuttavia, i dati non sono presenti: image_base64=None.

Per ottenere i dati dell'immagine, dobbiamo modificare la richiesta OCR per includere i dati dell'immagine aggiungendo il parametro include_image_base64=True.

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

Se stampiamo di nuovo le immagini, vedremo che i campi image_base_64 sono ora popolati. Come indica il nome del campo, i dati dell'immagine sono memorizzati in base 64. Non entreremo nei dettagli di come funziona la rappresentazione delle immagini in base 64. Al contrario, forniamo una funzione che usa il pacchetto datauri installato in precedenza per scrivere un'immagine su file:

def save_image(image):
    parsed = datauri.parse(image.image_base64)
    with open(image.id, "wb") as file:
      file.write(parsed.data)

Ora possiamo aggiornare la funzione create_markdown_file() per scrivere anche tutte le immagini su file:

def create_markdown_file(ocr_response, output_filename = "output.md"):
  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)

Se eseguiamo il codice aggiornato e riapriamo l'anteprima Markdown, vediamo le immagini.

Usare un file locale

Nell'esempio sopra, abbiamo usato un file già ospitato online. Per lavorare con un file PDF dal nostro computer, l'API Mistral ci permette di caricare un file usando la funzione client.files.upload(). Supponendo che il file PDF, myfile.pdf, sia nella stessa cartella dello script, ecco come fare:

filename = "myfile.pdf"
uploaded_pdf = client.files.upload(
  file={
    "file_name": filename,
    "content": open(filename, "rb"),
  },
  purpose="ocr"
)

Ogni file caricato in questo modo ha un ID univoco associato, necessario per fare riferimento a quel file. Possiamo accedervi usando l'attributo id del risultato, così:

print(uploaded_pdf.id)

Per eseguire l'OCR su quel file, dobbiamo fornirne l'URL. Possiamo ottenerlo usando la funzione client.files.get_signed_url() fornendo l'ID del file:

signed_url = client.files.get_signed_url(file_id=uploaded_pdf.id)

Mettendo insieme i passaggi, possiamo implementare una funzione che carica un file tramite l'API Mistral e ne recupera l'URL:

def upload_pdf(filename):
  uploaded_pdf = client.files.upload(
    file={
      "file_name": filename,
      "content": open(filename, "rb"),
    },
    purpose="ocr"
  )
  signed_url = client.files.get_signed_url(file_id=uploaded_pdf.id)
  return signed_url.url

Ecco un esempio di richiesta OCR con un file locale:

ocr_response = client.ocr.process(
  model="mistral-ocr-latest",
  document={
    "type": "document_url",
    "document_url": upload_pdf("myfile.pdf"),
  },
  include_image_base64=True,
)
Per usare un altro file, sostituiamo myfile.pdf con il nome del file che vogliamo utilizzare.
OCR su un'immagine
L'API OCR funziona anche con input di immagini. Per usare un'immagine, usiamo il tipo image_url invece di document_url:
ocr_response = client.ocr.process(
  model="mistral-ocr-latest",
  document={
    "type": "image_url",
    "image_url": <url of the image>,
  },
)
Nell'esempio sopra, dovremmo sostituire <url of the image> con l'URL dell'immagine. 
Per usare un'immagine locale, possiamo utilizzare la seguente funzione per caricarla:
def load_image(image_path):
  import base64
  mime_type, _ = mimetypes.guess_type(image_path)
  with open(image_path, "rb") as image_file:
    image_data = image_file.read()
  base64_encoded = base64.b64encode(image_data).decode('utf-8')
  base64_url = f"data:{mime_type};base64,{base64_encoded}"
  return base64_url
Questa funzione usa il pacchetto base64, che è integrato, quindi non serve installarlo.
Proviamo a eseguire l'OCR su questa ricevuta che abbiamo salvato in un file chiamato receipt.jpeg:

Possiamo fare la richiesta OCR usando la funzione load_image() per caricare l'immagine dal nostro computer:
ocr_response = client.ocr.process(
  model="mistral-ocr-latest",
  document={
    "type": "image_url",
    "image_url": load_image("receipt.jpeg"),
  },
)
Ecco il risultato:

È lontano dall'essere perfetto, ma il risultato non è poi così distante.
Combinare Mistral OCR con la chat
L'OCR offre un modo efficiente per convertire i dati in un formato testuale pronto per l'uso da parte degli LLM. L'API Mistral permette di combinare documenti e prompt nelle richieste all'LLM. Dietro le quinte, l'API OCR viene utilizzata per elaborare i documenti per il consumo da parte dell'LLM.
Proviamo a usarlo per riassumere l'articolo a cui abbiamo fatto riferimento nel corso di questo tutorial.
Se è la tua prima volta con l'API di chat di Mistral, potresti voler leggere questa guida completa a Mistral perché non entreremo nei dettagli del suo funzionamento.
Ecco un esempio completo in Python per chiedere una spiegazione dell'articolo semplice da capire:
from mistralai import Mistral
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.environ["MISTRAL_API_KEY"]
client = Mistral(api_key=api_key)
messages = [
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "Explain this article in detail to someone who doesn't have a technical background",
      },
      {
        "type": "document_url",
        "document_url": "https://arxiv.org/pdf/2310.06825",
      },
    ],
  }
]
chat_response = client.chat.complete(
  model="mistral-small-latest",
  messages=messages,
)
print(chat_response.choices[0].message.content)
Nota che il file viene fornito usando lo stesso formato visto sopra:
{
  "type": "document_url",
  "document_url": "https://arxiv.org/pdf/2310.06825",
}
Applicazioni reali di Mistral OCR
Ora che hai imparato come implementare Mistral OCR nei tuoi progetti Python, esploriamo alcune applicazioni pratiche in cui potresti applicare ciò che abbiamo imparato.
Analisi di articoli di ricerca
Puoi estrarre testo, equazioni, tabelle e figure da articoli scientifici per costruire un assistente alla ricerca personalizzato. Potresti creare un sistema che riassume i risultati chiave, estrae dettagli di metodologia o costruisce un database ricercabile di paper nel tuo campo.
Progetti di digitalizzazione dei documenti
Puoi trasformare archivi fisici o documenti scansionati in collezioni digitali ricercabili. Questo è particolarmente prezioso per documenti storici, registri di famiglia o archivi organizzativi che necessitano di conservazione e accesso semplice.
Elaborazione multilingue dei documenti
Puoi usare le capacità multilingue di Mistral OCR per elaborare documenti in varie lingue. Potrebbe essere utile per aziende internazionali, servizi di traduzione o progetti di ricerca globali che devono estrarre informazioni da documenti in alfabeti diversi.
Gestione di contenuti didattici
Puoi convertire libri di testo, slide di lezione e appunti manoscritti in formati digitali. Crea un sistema che estragga concetti chiave, formule e diagrammi per costruire materiali di studio personalizzati o raccolte di domande.
Elaborazione di documenti finanziari
Puoi automatizzare l'estrazione di dati da fatture, ricevute, rendiconti finanziari o documenti fiscali. Questo potrebbe semplificare i processi contabili o aiutare nella gestione delle spese e nell'analisi finanziaria.
Conclusione
L'API OCR di Mistral offre uno strumento potente per estrarre e comprendere testo da documenti e immagini. In questo tutorial, abbiamo visto come configurare e usare questa funzionalità per varie attività di elaborazione dei documenti.
Seguendo i passaggi descritti, puoi integrare l'OCR di Mistral nelle tue applicazioni, che tu stia digitalizzando archivi, automatizzando l'inserimento dati o costruendo sistemi intelligenti di gestione documentale. Con il continuo evolversi della tecnologia, possiamo aspettarci capacità di elaborazione dei documenti sempre più accurate e consapevoli del contesto, che colmino ulteriormente il divario tra documenti fisici e flussi di lavoro digitali.