Pipeline di produzione
In questa pagina
Aggiornamento 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 ad esso dal 16 luglio. OCR 4.1 aggiunge punteggi di confidenza a livello di blocco. Addendum 3 novembre 2026: un PDF locale viene trasmesso in base64 come{"type": "document_url", "document_url": "data:application/pdf;base64,…"}; il tipodocument_base64presente negli esempi più vecchi non esiste né nella documentazione né nell’SDKmistralai, e quegli esempi avrebbero fallito. Fonti: OCR Processor · Document QnA. Corretto il 3 novembre 2026: il codice leggeva precedentementepage.document_annotationpagina per pagina; nell’SDKmistralai3.7.0, l’annotazione del documento è un singolo campo nella risposta (response.document_annotation), e l’annotazione di un’immagine si legge daimage.image_annotation.
Dalla prova di concetto alla produzione
Hai imparato a utilizzare OCR, annotazioni e Document AI QnA. Rimane un divario costoso: la distanza tra uno script che funziona sul tuo laptop e un servizio su cui i tuoi colleghi fanno affidamento ogni mattina. Questa lezione finale assembla i mattoni precedenti in una pipeline robusta, completa di recupero dagli errori, monitoraggio e controllo dei costi.
I sei componenti di una pipeline completa
- Coda di ingestione: Riceve e priorizza i documenti.
- Pre-elaborazione: Convalida, converte i formati e migliora le immagini.
- OCR + Annotazioni: Estrae testo e dati strutturati.
- Post-elaborazione: Convalida, pulisce e arricchisce i dati.
- Archiviazione: Database, vector store e archiviazione a lungo termine.
- Interfaccia di query: API QnA, dashboard e integrazioni.
Il codice in questa lezione copre il cuore della catena—i passaggi 3 e 4—perché è lì che si concentrano le difficoltà operative.
Una classe che incapsula l’elaborazione
La classe PipelineDocumentAI imposta una configurazione una volta per tutte—lo schema di annotazione, il formato delle tabelle e il numero di tentativi—per poi applicarla a ogni documento. Tre meccanismi meritano la tua attenzione. In primo luogo, il retry con backoff esponenziale (time.sleep(2 ** tentative) distanzia i tentativi di uno, poi due, poi quattro secondi. Questo dà tempo alla saturazione transitoria delle API di risolversi invece di aggravarla. In secondo luogo, il logging traccia ogni successo con il suo conteggio di pagine e durata, e ogni fallimento con il suo numero di tentativo; senza queste righe, scoprirai gli incidenti solo quando ti chiamerà il reparto contabilità. Infine, il dizionario stats alimenta il report di fine batch.
Nota che il metodo restituisce sempre un ResultatTraitement, anche dopo aver esaurito i tentativi: il chiamante non deve mai gestire un’eccezione, ma legge semplicemente il campo erreur.
import os
import time
import base64
import logging
from pathlib import Path
from dataclasses import dataclass, field
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field
from typing import Optional
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("document_ai_pipeline")
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
@dataclass
class ResultatTraitement:
fichier: str
pages: int = 0
texte: str = ""
annotations: Optional[dict] = None
duree_secondes: float = 0.0
erreur: Optional[str] = None
class PipelineDocumentAI:
def __init__(
self,
schema_annotation=None,
table_format: str = "markdown",
max_retries: int = 3,
):
self.schema_annotation = schema_annotation
self.table_format = table_format
self.max_retries = max_retries
self.stats = {"total": 0, "succes": 0, "erreurs": 0}
def traiter_document(self, chemin: str) -> ResultatTraitement:
"""Elabora un documento con retry e monitoraggio."""
debut = time.time()
self.stats["total"] += 1
for tentative in range(self.max_retries):
try:
# Lettura e codifica
with open(chemin, "rb") as f:
doc_b64 = base64.b64encode(f.read()).decode("utf-8")
# Parametri di chiamata
params = {
"model": "mistral-ocr-latest",
"document": {
"type": "document_url",
"document_url": f"data:application/pdf;base64,{doc_b64}"
},
"table_format": self.table_format,
}
if self.schema_annotation:
params["document_annotation_format"] = (
response_format_from_pydantic_model(
self.schema_annotation
)
)
# Chiamata OCR
response = client.ocr.process(**params)
# Estrazione testo
texte = "\n\n".join(
p.markdown for p in response.pages
)
# Estrazione annotazioni
annotations = None
if self.schema_annotation:
if response.document_annotation:
annotations = response.document_annotation
duree = time.time() - debut
self.stats["succes"] += 1
logger.info(
f"OK: {chemin} ({len(response.pages)} pagine, "
f"{duree:.1f}s)"
)
return ResultatTraitement(
fichier=chemin,
pages=len(response.pages),
texte=texte,
annotations=annotations,
duree_secondes=duree,
)
except Exception as e:
logger.warning(
f"Tentativo {tentative + 1}/{self.max_retries} "
f"fallito per {chemin}: {e}"
)
if tentative < self.max_retries - 1:
time.sleep(2 ** tentative) # Backoff esponenziale
# Tutti i tentativi falliti
self.stats["erreurs"] += 1
return ResultatTraitement(
fichier=chemin,
duree_secondes=time.time() - debut,
erreur="Fallimento dopo tutti i tentativi",
)
def traiter_dossier(self, dossier: str) -> list[ResultatTraitement]:
"""Elabora tutti i PDF in una cartella."""
chemin = Path(dossier)
fichiers = sorted(chemin.glob("*.pdf"))
resultats = []
for fichier in fichiers:
resultat = self.traiter_document(str(fichier))
resultats.append(resultat)
return resultats
def rapport(self) -> str:
"""Genera un report di elaborazione."""
return (
f"Documenti elaborati: {self.stats['total']}\n"
f"Successi: {self.stats['succes']}\n"
f"Errori: {self.stats['erreurs']}\n"
f"Tasso di successo: "
f"{self.stats['succes']/max(self.stats['total'],1)*100:.1f}%"
)
In pratica, la stessa classe copre entrambe le esigenze: istanziata senza schema, estrae semplicemente il testo; istanziata con un modello Pydantic, produce anche dati strutturati.
# Pipeline semplice (solo OCR)
pipeline = PipelineDocumentAI(table_format="markdown")
resultats = pipeline.traiter_dossier("./factures/")
print(pipeline.rapport())
# Pipeline con annotazioni
from pydantic import BaseModel, Field
class ExtractionFacture(BaseModel):
fournisseur: str = Field(..., description="Nome del fornitore")
montant_ttc: float = Field(..., description="Importo IVA inclusa")
date: str = Field(..., description="Data (AAAA-MM-GG)")
pipeline_annote = PipelineDocumentAI(
schema_annotation=ExtractionFacture,
table_format="markdown"
)
resultats = pipeline_annote.traiter_dossier("./factures/")
Anticipare la fattura
Il controllo dei costi è essenziale in produzione e inizia comprendendo per cosa ti viene addebitato.
| Voce | Base di fatturazione |
|---|---|
| OCR | Per pagina elaborata |
| Annotazioni | Incluse nella chiamata OCR (nessun costo extra) |
| QnA | Token di input/output basati sul modello chat |
| Embedding | Token di input |
Il fatto che le annotazioni non comportino costi extra cambia il design: estrai i metadati durante il passaggio OCR invece di eseguire una chiamata LLM separata successivamente. La funzione di stima sottostante ti permette di valutare il prezzo di un progetto prima di avviarlo; le sue tariffe sono cifre indicative da adattare, mentre la tabella di riferimento pubblicata da Mistral rimane l’autorità.
def estimer_cout(
nombre_pages: int,
avec_qna: bool = False,
modele_qna: str = "mistral-small-latest"
) -> dict:
"""Stima il costo di elaborazione."""
# Tariffe approssimative (verificare le tariffe attuali)
cout_ocr_par_page = 0.001 # Da adattare in base al livello
cout_qna_par_1k_tokens = {
"mistral-small-latest": 0.001,
"mistral-large-latest": 0.008,
}
cout_ocr = nombre_pages * cout_ocr_par_page
cout_qna = 0.0
if avec_qna:
# Stima: ~500 token per pagina in media
tokens_estimes = nombre_pages * 500
cout_qna = (
tokens_estimes / 1000
* cout_qna_par_1k_tokens.get(modele_qna, 0.001)
)
return {
"cout_ocr": round(cout_ocr, 4),
"cout_qna": round(cout_qna, 4),
"cout_total": round(cout_ocr + cout_qna, 4),
}
Monitorare la salute del servizio
Una pipeline si degrada lentamente e silenziosamente: un nuovo fornitore invia scansioni di scarsa qualità, il tasso di errore sale dal 2% al 15% e nessuno se ne accorge fino alla chiusura mensile. Quattro metriche sono sufficienti per rilevare la deriva—volume elaborato, durata media, tasso di errore e costo stimato—a patto di emetterle sistematicamente e inviarle al tuo strumento abituale, che sia Datadog, Prometheus o un altro.
import json
from datetime import datetime
def log_metrique(nom: str, valeur: float, tags: dict = None) -> None:
"""Registra una metrica di monitoraggio."""
metrique = {
"timestamp": datetime.utcnow().isoformat(),
"nom": nom,
"valeur": valeur,
"tags": tags or {}
}
# In produzione: inviare a Datadog, Prometheus, ecc.
logger.info(f"METRIQUE: {json.dumps(metrique)}")
# Esempio di metriche da tracciare
log_metrique("ocr.pages_traitees", 150, {"batch": "factures_mars"})
log_metrique("ocr.duree_moyenne_secondes", 2.3)
log_metrique("ocr.taux_erreur", 0.02)
log_metrique("ocr.cout_estime_usd", 0.15)
Dove andare adesso
Ora hai le basi per costruire un sistema Document AI completo e si aprono diverse estensioni a seconda dei tuoi vincoli. Volumi molto elevati giustificano un deployment on-premise del modello OCR su una GPU dedicata; documenti altamente specifici per il tuo business possono motivare il fine-tuning, un argomento da affrontare direttamente con Mistral. Sul lato dell’integrazione, la sfida consiste nel collegare la pipeline ai tuoi sistemi esistenti—ERP, CRM—e costruire una dashboard affinché i tuoi team possano interrogare i documenti da soli senza passare attraverso di te. Il passo finale è rimuovere l’attivazione manuale: la pipeline viene eseguita automaticamente quando arrivano nuovi documenti.
Riepilogo del corso
Queste sedici lezioni ti hanno guidato attraverso l’intero ciclo. Hai iniziato con i fondamenti—cos’è il Document AI, il modello OCR 4 e i casi d’uso—per poi passare all’OCR avanzato con l’API, l’estrazione di tabelle, intestazioni/piè di pagina e ottimizzazione. Le annotazioni ti hanno poi fornito l’estrazione strutturata, l’elaborazione in batch e il controllo della conformità, seguite dal Document QnA, che ha aperto alla query in linguaggio naturale, dai documenti isolati ai corpora indicizzati in RAG. Ora disponi dei mattoni necessari per dotare la gestione documentale della tua organizzazione con Mistral Document AI.
Punti chiave
- Una pipeline di produzione include retry, logging, monitoraggio e gestione dei costi.
- Il backoff esponenziale protegge dagli errori transitori delle API.
- Stima i tuoi costi prima di scalare (OCR per pagina, QnA per token).
- Il monitoraggio continuo permette di rilevare il degrado delle prestazioni.
- Il Document AI copre l’intero ciclo di vita del documento, dall’ingestione all’operatività.
Metti alla prova le tue conoscenze
OCR, annotazioni, QnA: valida la catena documentale completa.
1. Cosa produce l'API OCR di Mistral da un documento?
Risposta: Il contenuto strutturato del documento—testo, tabelle, layout—pronto per l’uso programmatico: OCR 4 legge il documento come una fonte di dati, non come un’immagine.
2. Qual è lo scopo dell'API Annotations?
Risposta: Estrarre metadati strutturati secondo il tuo schema (campi fattura, clausole contrattuali)—singolarmente o in batch per grandi volumi.
3. Cosa abilita il Document QnA?
Risposta: Porre domande in linguaggio naturale su uno o più documenti e ottenere risposte basate sul loro contenuto—il livello conversazionale sopra l’estrazione.
4. Come si ottimizza l'accuratezza dell'OCR?
Risposta: Attraverso la qualità dell’input (risoluzione, nitidezza, orientamento) e la gestione delle aree difficili—intestazioni, piè di pagina, impaginazione—che il corso ti insegna a gestire esplicitamente.
5. Perché combinare OCR e RAG?
Risposta: L’OCR trasforma i documenti scansionati in testo indicizzabile, mentre il RAG li rende interrogabili su larga scala: insieme, abilitano la ricerca semantica su interi archivi.
Estrazione, annotazione, domanda-e-risposta, indicizzazione: la pipeline di produzione sopra collega tutti e quattro—la tua carta diventa un database.