Estrarre metadati strutturati
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.
Estrai esattamente ciò che ti serve
L’annotazione dei documenti non serve solo a recuperare testo grezzo. Produce dati strutturati, tipizzati e validati, pronti per l’uso immediato nei tuoi sistemi: una riga inserita in un database, un campo confrontato con un riferimento o un importo verificato prima del pagamento. La sfida si sposta interamente sulla progettazione dello schema, ed è su questo che si concentra questa lezione.
Struttura invece di appiattimento
Uno schema di estrazione dovrebbe riflettere la realtà del documento. Una fattura proviene da un’entità legale con una ragione sociale, un numero di partita IVA e un indirizzo. Invece di allineare otto campi come emetteur_rue, emetteur_ville, emetteur_siret, definisci un modello Address, poi un modello LegalEntity che lo contiene. Riutilizza questi mattoni sia per l’emittente che per il destinatario. L’enumerazione DocumentType svolge un ruolo simile: impedisce al modello di inventare una categoria e garantisce un valore utilizzabile in un’istruzione if o per il routing. I campi Optional dichiarano esplicitamente cosa può essere assente, mentre i valori predefiniti—come default="France" per il paese—evitano che il modello debba indovinare l’ovvio.
from pydantic import BaseModel, Field
from typing import Optional
from enum import Enum
class DocumentType(str, Enum):
INVOICE = "facture"
CONTRACT = "contrat"
REPORT = "rapport"
FORM = "formulaire"
OTHER = "autre"
class Address(BaseModel):
street: Optional[str] = Field(None, description="Numéro et street")
postal_code: Optional[str] = Field(None, description="Code postal")
city: Optional[str] = Field(None, description="Ville")
country: str = Field(default="France", description="Pays")
class LegalEntity(BaseModel):
name: str = Field(..., description="Raison sociale")
siret: Optional[str] = Field(None, description="Numéro SIRET")
address: Optional[Address] = Field(None, description="Address postale")
email: Optional[str] = Field(None, description="Address email")
class DocumentExtraction(BaseModel):
document_type: DocumentType = Field(
..., description="Type du document"
)
date: Optional[str] = Field(
None, description="Date principale (YYYY-MM-DD)"
)
emetteur: LegalEntity = Field(
..., description="Entité qui émet le document"
)
destinataire: Optional[LegalEntity] = Field(
None, description="Entité destinataire"
)
resume: str = Field(
..., description="Résumé en 2-3 phrases du contenu"
)
langue: str = Field(
..., description="Langue du document (code ISO 639-1)"
)
Dati ripetuti
Molti documenti contengono serie: righe di fatturazione, clausole o voci di spesa. Modellali come una list[...] di un sottomodello dedicato. Il modello scansiona quindi la tabella del documento e produce tanti oggetti InvoiceLine quante sono le righe trovate, includendo per ciascuna la descrizione, la quantità, il prezzo unitario e il totale. Questo ti fornisce dati sufficienti per ricalcolare tu stesso il subtotale e verificare la coerenza del documento prima di accettarlo.
from pydantic import BaseModel, Field
class InvoiceLine(BaseModel):
description: str = Field(..., description="Description du produit/service")
quantity: float = Field(..., description="Quantité")
unit_price: float = Field(..., description="Prix unitaire HT")
amount: float = Field(..., description="Montant total HT de la ligne")
class DetailedInvoice(BaseModel):
supplier: str = Field(..., description="Nom du supplier")
number: str = Field(..., description="Numéro de facture")
date: str = Field(..., description="Date (YYYY-MM-DD)")
lines: list[InvoiceLine] = Field(
..., description="Lignes de la facture"
)
subtotal_excl_tax: float = Field(..., description="Sous-total HT")
vat: float = Field(..., description="Montant TVA")
total_incl_tax: float = Field(..., description="Total TTC")
payment_terms: str = Field(
..., description="Conditions de paiement mentionnées"
)
Caselle di spunta e moduli
I moduli cartacei scannerizzati sono il terreno dove il modello eccelle. Un campo bool abbinato all’etichetta della domanda è sufficiente: il modello riconosce se una casella è spuntata, estrae la domanda corrispondente e—cruciale per usi medici o amministrativi—deduce che un campo manca invece di inventare un valore, come dimostrato dal team Mistral. La nota “null if not provided” nella descrizione del numero di telefono non è decorativa; autorizza esplicitamente un valore vuoto.
from pydantic import BaseModel, Field
class FormResponse(BaseModel):
question: str = Field(..., description="Intitulé de la question")
answer: bool = Field(..., description="True si coché, False sinon")
class MedicalForm(BaseModel):
patient_name: str = Field(..., description="Nom complet du patient")
age: Optional[int] = Field(None, description="Âge du patient")
sex: Optional[str] = Field(None, description="Sexe (M/F)")
patient_id: Optional[str] = Field(None, description="ID patient")
phone: Optional[str] = Field(
None, description="Numéro de téléphone (null si non fourni)"
)
responses: list[FormResponse] = Field(
..., description="Réponses aux questions du formulaire"
)
Implementazione end-to-end
Prendi l’esempio della fattura dettagliata e collegalo a un documento codificato in base64. Il prompt di annotazione completa lo schema specificando il tipo di file e sottolineando l’attenzione alle righe di fatturazione; la validazione Pydantic al ritorno converte la stringa JSON in un oggetto che puoi attraversare in sicurezza.
import os
import json
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
ocr_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(
DetailedInvoice
),
document_annotation_prompt=(
"Ce document est une invoice. Extrais toutes les lines "
"de facturation avec leurs montants."
)
)
# Extraction and validation
if ocr_response.document_annotation:
invoice = DetailedInvoice.model_validate_json(
ocr_response.document_annotation
)
print(f"Facture {invoice.numero} - {invoice.fournisseur}")
print(f"Date : {invoice.date}")
print(f"\nLignes :")
for line in invoice.lines:
print(f" - {line.description}: {line.quantite} x "
f"{line.prix_unitaire}€ = {line.montant}€")
print(f"\nTotal TTC : {invoice.total_incl_tax}€")
I risultati scarsi di estrazione derivano quasi sempre dallo schema, raramente dal modello. Rivedi le tue descrizioni una per una: devono essere precise e inequivocabili, poiché il modello si basa esclusivamente su di esse per comprendere le tue aspettative. Scrivile nella lingua dei tuoi documenti—il francese funziona perfettamente per le fatture francesi—e riserva le enum per i campi con valori limitati e i sottomodelli per le strutture che riutilizzerai tra gli schemi.
Punti chiave
- Gli schemi Pydantic abilitano l’estrazione di dati tipizzati e validati
- Usa tipi complessi (liste, enum, modelli nidificati) per estrazioni precise
- Il modello gestisce campi opzionali e caselle di spunta in modo affidabile
- Le descrizioni dei campi guidano l’estrazione: sii preciso ed esplicito
- Combina
document_annotation_promptcon lo schema per il massimo contesto