Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Estrarre metadati strutturati

Lezione 10 di 16 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Estrai esattamente ciò che ti serve
  2. Struttura invece di appiattimento
  3. Dati ripetuti
  4. Caselle di spunta e moduli
  5. Implementazione end-to-end
  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.

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_prompt con lo schema per il massimo contesto