Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Casi d'uso delle annotazioni

Lezione 12 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Annotazioni per ogni ruolo
  2. Ordina prima di elaborare
  3. Leggi un contratto come un avvocato
  4. Verifica la conformità automaticamente
  5. Non perdere nulla prima dell’indicizzazione
  6. Punti chiave

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), generalmente disponibile 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), mentre l’annotazione dell’immagine si legge da image.image_annotation.

Annotazioni per ogni ruolo

Le annotazioni di Document AI trasformano documenti non strutturati in dati utilizzabili. Il meccanismo è sempre lo stesso—uno schema, un prompt, una chiamata—ma ciò che estrai cambia radicalmente a seconda del ruolo. Questa lezione esamina quattro implementazioni concrete: classificazione a monte in una pipeline, analisi delle clausole contrattuali, verifiche di conformità normativa e arricchimento di un indice RAG.

Ordina prima di elaborare

In un flusso di lavoro reale, i documenti arrivano mescolati: una fattura, un ordine d’acquisto, una carta d’identità, una lettera. Prima di applicare lo schema di estrazione appropriato, devi sapere con cosa hai a che fare. L’annotazione funge da prima fase di smistamento. L’enum TypeDocument blocca le categorie ammissibili, il punteggio di confidenza ti permette di instradare qualsiasi elemento al di sotto di una soglia per la revisione umana, e il riassunto in una frase fornisce agli operatori contesto sufficiente per prendere una decisione senza aprire il file.

import os
from enum import Enum
from pydantic import BaseModel, Field
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model

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

class TypeDocument(str, Enum):
    INVOICE = "facture"
    PURCHASE_ORDER = "bon_commande"
    CONTRACT = "contrat"
    REPORT = "rapport"
    LETTER = "courrier"
    FORM = "formulaire"
    ID_DOCUMENT = "piece_identite"
    OTHER = "autre"

class Classification(BaseModel):
    document_type: TypeDocument = Field(
        ..., description="Identified document type"
    )
    confidence: float = Field(
        ..., description="Confidence score between 0 and 1"
    )
    language: str = Field(
        ..., description="Primary language (ISO 639-1 code)"
    )
    summary: str = Field(
        ..., description="One-sentence summary of the content"
    )

def classify_document(document_base64: str) -> Classification:
    """Classifica automaticamente un documento."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            Classification
        ),
        document_annotation_prompt=(
            "Identify the type of this document and provide "
            "a summary of its content."
        )
    )

    if response.document_annotation:
        return Classification.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Leggi un contratto come un avvocato

L’analisi contrattuale è un caso d’uso majeure nel settore legale e finanziario, ed è qui che gli schemi annidati brillano davvero. Ogni Clause porta il proprio titolo, un riassunto del contenuto, la sua categoria—riservatezza, risoluzione, non concorrenza, responsabilità, pagamento—e una valutazione del rischio su tre livelli. Il contratto stesso aggrega queste clausole insieme alle parti, alla data di firma, alla durata, all’importo e alla giurisdizione applicabile. Su un portafoglio di duecento contratti con fornitori, ottieni in poche ore una mappatura che nessuno avrebbe avuto il tempo di produrre manualmente.

Il campo risk merita un avvertimento: è una valutazione prodotta da un modello, utile per prioritizzare la revisione di un avvocato, mai per sostituirla.

from pydantic import BaseModel, Field
from typing import Optional

class Clause(BaseModel):
    title: str = Field(..., description="Title or number of the clause")
    content: str = Field(..., description="Summary of the clause content")
    clause_type: str = Field(
        ..., description="Type: confidentiality, termination, "
        "non-compete, liability, payment, other"
    )
    risk: str = Field(
        ..., description="Risk level: low, medium, high"
    )

class ContractAnalysis(BaseModel):
    parts: list[str] = Field(
        ..., description="Names of the contracting parts"
    )
    signature_date: Optional[str] = Field(
        None, description="Signature date (YYYY-MM-DD)"
    )
    duration: Optional[str] = Field(
        None, description="Contract duration"
    )
    key_clauses: list[Clause] = Field(
        ..., description="Identified main clauses"
    )
    amount: Optional[float] = Field(
        None, description="Total amount if mentioned"
    )
    jurisdiction: Optional[str] = Field(
        None, description="Applicable jurisdiction"
    )

def analyze_contract(document_base64: str) -> ContractAnalysis:
    """Analizza un contratto ed estrae le clausole principali."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            ContractAnalysis
        ),
        document_annotation_prompt=(
            "Analyze this commercial contract. Identify the parts, "
            "the main clauses, and evaluate the risk level "
            "of each clause."
        )
    )

    if response.document_annotation:
        return ContractAnalysis.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Verifica la conformità automaticamente

Il controllo normativo è particolarmente adatto all’annotazione perché i criteri sono scritti nero su bianco nella legge. Per una fattura francese, il prompt elenca gli obblighi da verificare—menzioni obbligatorie (SIRET, IVA intracomunitaria, termini di pagamento, penali per ritardo), formattazione dell’importo, data di emissione—e lo schema impone, per ogni criterio, un verdetto booleano accompagnato dalla sua giustificazione. Ottieni un punteggio globale e raccomandazioni di miglioramento, sufficienti per bloccare una fattura non conforme prima che entri nel circuito dei pagamenti.

from pydantic import BaseModel, Field

class CompliancePoint(BaseModel):
    criterion: str = Field(..., description="Compliance criterion checked")
    compliant: bool = Field(..., description="True if compliant, False otherwise")
    justification: str = Field(
        ..., description="Explanation of compliance or non-compliance"
    )

class ComplianceAudit(BaseModel):
    document_type: str = Field(..., description="Type of document audited")
    compliance_points: list[CompliancePoint] = Field(
        ..., description="Compliance points checked"
    )
    global_score: float = Field(
        ..., description="Global compliance score (0-100)"
    )
    recommendations: list[str] = Field(
        ..., description="Improvement recommendations"
    )

def audit_invoice_compliance(document_base64: str) -> ComplianceAudit:
    """Verifica la conformità di una fattura secondo le regole francesi."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            ComplianceAudit
        ),
        document_annotation_prompt=(
            "Verify the compliance of this invoice according to "
            "French legal obligations: mandatory mentions "
            "(SIRET, intra-community VAT, payment terms, "
            "late payment penalties), amount formatting, issue date."
        )
    )

    if response.document_annotation:
        return ComplianceAudit.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Non perdere nulla prima dell’indicizzazione

Un ultimo caso d’uso, più discreto ma decisivo: preparare i contenuti per un indice RAG. Un indice costruito esclusivamente su Markdown perde tutto ciò che era visivo, e le tue ricerche non troveranno mai il grafico che conteneva la cifra chiave. La funzione sottostante ricompone, pagina per pagina, il testo e la descrizione di ogni immagine, aggiungendo poi i metadati estratti dal documento, in un unico blocco pronto per essere suddiviso in chunk.

def enrich_for_rag(ocr_response) -> str:
    """Arricchisce il contenuto OCR con annotazioni per RAG."""
    parts = []

    for page in ocr_response.pages:
        # Text content
        parts.append(page.markdown)

        # Image annotations (replace images with their description)
        for image in page.images:
            if image.image_annotation:
                parts.append(
                    f"[Description of {image.id}]: {image.image_annotation}"
                )

    # Document annotation: a single one, carried by the response
    if ocr_response.document_annotation:
        parts.append(
            f"[Extracted Metadata]: {ocr_response.document_annotation}"
        )

    return "\n\n".join(parts)

Aggiungendo le descrizioni delle immagini e i metadati estratti al contenuto indicizzato, non perdi alcuna informazione del documento originale. Noterai che questi quattro scenari condividono la stessa struttura portante: ciò che li distingue è lo schema e il prompt, non il codice di chiamata.

Punti chiave

  • La classificazione automatica instrada i documenti verso la pipeline di elaborazione corretta
  • L’estrazione delle clausole contrattuali identifica rischi e punti chiave
  • La verifica di conformità automatizza gli audit normativi
  • L’arricchimento tramite annotazioni migliora la qualità dell’indicizzazione RAG
  • Ogni caso d’uso si riduce a uno schema Pydantic ben progettato e a un prompt adattato