Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Pipeline di produzione

Lezione 16 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Dalla prova di concetto alla produzione
  2. I sei componenti di una pipeline completa
  3. Una classe che incapsula l’elaborazione
  4. Anticipare la fattura
  5. Monitorare la salute del servizio
  6. Dove andare adesso
  7. Riepilogo del corso
  8. Punti chiave
  9. Metti alla prova le tue conoscenze

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’alias mistral-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 tipo document_base64 presente negli esempi più vecchi non esiste né nella documentazione né nell’SDK mistralai, e quegli esempi avrebbero fallito. Fonti: OCR Processor · Document QnA. Corretto il 3 novembre 2026: il codice leggeva precedentemente page.document_annotation pagina per pagina; nell’SDK mistralai 3.7.0, l’annotazione del documento è un singolo campo nella risposta (response.document_annotation), e l’annotazione di un’immagine si legge da image.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

  1. Coda di ingestione: Riceve e priorizza i documenti.
  2. Pre-elaborazione: Convalida, converte i formati e migliora le immagini.
  3. OCR + Annotazioni: Estrae testo e dati strutturati.
  4. Post-elaborazione: Convalida, pulisce e arricchisce i dati.
  5. Archiviazione: Database, vector store e archiviazione a lungo termine.
  6. 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.

VoceBase di fatturazione
OCRPer pagina elaborata
AnnotazioniIncluse nella chiamata OCR (nessun costo extra)
QnAToken di input/output basati sul modello chat
EmbeddingToken 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.