Casi d'uso delle annotazioni
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), generalmente disponibile 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), mentre l’annotazione dell’immagine si legge daimage.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