Prossimi passi: Document AI, Function Calling e pipeline multimodali
In questa pagina
Aggiornato il 3 novembre 2026 sulla base della pagina Document QnA di Mistral e dell’SDK
mistralai3.7.0: l’esempio interroga un documento utilizzando un modello di chat (mistral-small-latest), non il modello OCR, edocument_image_limitnon è un parametro perchat.complete(la chiamata fallirebbe); i limiti di pagina si impostano inclient.ocr.process. Fonte: Document QnA.
Oltre la Vision API
Ora hai padroneggiato i fondamenti della Mistral Vision API: invio di immagini tramite URL e Base64, analisi di grafici, esecuzione di OCR, estrazione di dati strutturati e confronto di immagini. Questa base ha un confine naturale: finora il modello ha sempre osservato un’immagine e restituito testo, senza mai compiere azioni. Questa lezione finale supera quel confine in tre fasi: il servizio specializzato per i documenti, il function calling che trasforma l’analisi in azione e le pipeline che li concatenano.
Mistral Document AI (OCR 4)
Per esigenze OCR avanzate, Mistral offre Document AI, un servizio specializzato nell’elaborazione di documenti. Mentre la Vision API gestisce singole immagini, Document AI ragiona alla scala del documento: gestisce PDF multipagina e analizza file lunghi in un’unica passata. Gestisce layout complessi—colonne, intestazioni e piè di pagina, tabelle nidificate—e preserva la struttura, con un output che mantiene la gerarchia del documento di titoli, paragrafi ed elenchi. Infine, la sua accuratezza OCR è ottimizzata sia per il testo stampato che per quello manoscritto.
Esempio di chiamata a Document AI
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Analizza un PDF con Document AI
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Extract the full content of this document while preserving the structure."
},
{
"type": "document_url",
"document_url": "https://example.com/annual-report.pdf"
}
]
}
]
)
print(response.choices[0].message.content)
La differenza rispetto a tutto ciò che hai scritto finora risiede nel tipo di elemento: document_url invece di image_url, letto da un modello di chat standard (mistral-small-latest nella documentazione di Mistral). Il documento non deve superare i 50 MB e contenere al massimo 1.000 pagine. Per elaborare solo una parte di un rapporto annuale di 300 pagine, usa invece l’endpoint OCR (client.ocr.process), dove i parametri pages e image_limit delimitano il lavoro.
Quando usare Document AI rispetto alla Vision API
| Necessità | Vision API | Document AI |
|---|---|---|
| Foto di una fattura | Sufficiente | Eccessivo |
| PDF di 50 pagine | Non supportato | Ideale |
| Tabella nidificata complessa | Approssimativa | Precisa |
| Screenshot di interfaccia | Ideale | Non adatto |
| Documento manoscritto | Base | Ottimizzato |
Ricorda la regola pratica: usa la Vision API per ciò che è nato come immagine e Document AI per ciò che è nato come documento.
Vision + Function Calling
Fino ad ora, il tuo codice riceveva una risposta e decideva cosa farne. Il function calling inverte questo rapporto: fornisci al modello un elenco di azioni disponibili ed esso sceglie quale chiamare in base all’immagine. Questa è la chiave per costruire agenti visivi autonomi.
Il ciclo prevede quattro passaggi:
- Invii un’immagine + definizioni delle funzioni
- Il modello analizza l’immagine e decide quale funzione chiamare
- Esegui la funzione e restituisci il risultato
- Il modello formula una risposta finale
Esempio: Agente per l’elaborazione delle fatture
Considera un reparto contabile che riceve fatture per posta. Sono possibili due esiti: la fattura è valida e deve essere registrata, oppure presenta un’anomalia e deve essere segnalata. Definiamo quindi due strumenti, con i loro parametri e campi obbligatori.
import json
# Definisci gli strumenti disponibili
outils = [
{
"type": "function",
"function": {
"name": "enregistrer_facture",
"description": "Enregistre une facture dans le système comptable",
"parameters": {
"type": "object",
"properties": {
"emetteur": {"type": "string", "description": "Nom de l'émetteur"},
"numero": {"type": "string", "description": "Numéro de facture"},
"date": {"type": "string", "description": "Date d'émission (YYYY-MM-DD)"},
"montant_ttc": {"type": "number", "description": "Montant TTC en euros"},
"tva": {"type": "number", "description": "Montant de la TVA"}
},
"required": ["emetteur", "numero", "date", "montant_ttc"]
}
}
},
{
"type": "function",
"function": {
"name": "signaler_anomalie",
"description": "Signale une anomalie sur une facture (doublons, montants incohérents)",
"parameters": {
"type": "object",
"properties": {
"type_anomalie": {"type": "string"},
"description": {"type": "string"}
},
"required": ["type_anomalie", "description"]
}
}
}
]
# Invia l'immagine con gli strumenti
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Vous êtes un assistant comptable. Analysez les factures et utilisez les outils appropriés."
},
{
"role": "user",
"content": [
{"type": "text", "text": "Traitez cette facture."},
{"type": "image_url", "image_url": encoder_image("factures/facture-2024-0042.jpg")}
]
}
],
tools=outils,
tool_choice="auto"
)
# Gestisci la chiamata alla funzione
if response.choices[0].message.tool_calls:
appel = response.choices[0].message.tool_calls[0]
nom_fonction = appel.function.name
arguments = json.loads(appel.function.arguments)
print(f"Fonction appelée : {nom_fonction}")
print(f"Arguments : {json.dumps(arguments, indent=2, ensure_ascii=False)}")
Cura attentamente il campo description per ogni funzione: il modello basa la sua scelta su questo, non sul nome. Una descrizione vaga produce un agente che chiama la funzione sbagliata.
Pipeline multimodali
Una pipeline multimodale concatena più passaggi di elaborazione combinando visione, testo e strumenti. Il suo valore è sia economico che organizzativo: ogni passaggio impiega strettamente il modello necessario.
Esempio: Pipeline di elaborazione della posta
La posta in arrivo per una PMI mescola fatture, preventivi, contratti e pubblicità. Classificarli costa poco; analizzarli nel dettaglio costa di più. La pipeline inizia quindi con uno smistamento usando un modello leggero, e impegna Large solo sui documenti che lo giustificano.
def mail_pipeline(image_path):
"""Pipeline complet : classification -> extraction -> action."""
# Étape 1 : Classification (modèle léger)
classification = client.chat.complete(
model="mistral-small-latest",
response_format={"type": "json_object"},
messages=[{
"role": "user",
"content": [
{"type": "text", "text": 'Classifiez ce document : {"type": "facture|devis|contrat|courrier|autre", "urgence": "haute|moyenne|basse"}'},
{"type": "image_url", "image_url": encoder_image(image_path)}
]
}]
)
info = json.loads(classification.choices[0].message.content)
print(f"Type : {info['type']} | Urgence : {info['urgence']}")
# Étape 2 : Extraction détaillée (modèle puissant, seulement si nécessaire)
if info["type"] == "facture":
extraction = client.chat.complete(
model="mistral-large-latest",
response_format={"type": "json_object"},
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Extrayez toutes les données de cette facture en JSON : emetteur, numero, date, lignes, total_ht, tva, total_ttc."},
{"type": "image_url", "image_url": encoder_image(image_path)}
]
}]
)
data = json.loads(extraction.choices[0].message.content)
return {"classification": info, "données": data}
# Étape 3 : Résumé pour les autres types
summary = client.chat.complete(
model="mistral-small-latest",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Résumez le contenu de ce document en 3 phrases maximum."},
{"type": "image_url", "image_url": encoder_image(image_path)}
]
}]
)
return {"classification": info, "summary": summary.choices[0].message.content}
# Traiter un lot de courrier
from pathlib import Path
for file in sorted(Path("courrier/").glob("*.jpg")):
print(f"\n--- {file.name} ---")
result = mail_pipeline(file)
print(json.dumps(result, indent=2, ensure_ascii=False))
In un lotto in cui un elemento su cinque è una fattura, quattro documenti su cinque non vedono mai il modello costoso, a parità di qualità finale.
Riepilogo del corso
In queste 12 lezioni, sei passato dal meccanismo all’applicazione. Hai prima compreso l’architettura multimodale e cosa accade realmente quando un’immagine entra nel modello, poi hai imparato a scegliere la variante adatta al tuo carico di lavoro—Large, Small o Ministral. Successivamente, hai appreso come inviare immagini tramite URL e Base64, singolarmente o in batch. Su questa base, hai affrontato gli usi che costituiscono la maggior parte del lavoro reale: analisi di grafici, lettura di testo tramite OCR, estrazione di dati strutturati, confronto di immagini per il controllo qualità e il monitoraggio dell’evoluzione. Infine, hai imparato a ottimizzare le tue chiamate per costi, latenza e affidabilità, e a integrare la visione in pipeline più grandi grazie al function calling.
Prossimi passi
Quattro direzioni estendono naturalmente questo percorso. Innanzitutto, Document AI, il cui OCR 4 gestisce documenti che la Vision API non può supportare. Poi, gli agenti, che combinano visione e function calling per costruire sistemi che decidono e agiscono. Quindi il fine-tuning, se le tue immagini hanno specificità che nessun modello generalista conosce—un catalogo di parti industriali, un modulo interno. Infine, la Batch API, progettata per elaborare migliaia di immagini a costi ridotti quando il tempo di risposta non è critico. Nel lungo termine, capacità multimodali avanzate apriranno la strada a video e audio quando disponibili.
Punti chiave
- Document AI (OCR 4) è il complemento naturale alla Vision API per documenti complessi e PDF
- Il function calling trasforma la visione in un agente autonomo capace di agire sui dati estratti
- Una pipeline multimodale combina classificazione (Small) ed estrazione (Large) per ottimizzare qualità e costi
- La Mistral Vision API è un mattone fondamentale per costruire applicazioni AI moderne
Metti alla prova le tue conoscenze
Visione tramite API: cinque domande per consolidare la pipeline.
1. Come si invia un'immagine alle API di Mistral?
Risposta: Tramite URL o codificata in Base64, in un messaggio con contenuto misto testo + immagine—e più immagini possono viaggiare nello stesso messaggio per il confronto.
2. Cosa abilita la visione oltre la descrizione?
Risposta: Analisi di grafici, OCR (trascrizione di testo da immagini) ed estrazione di dati strutturati—l’immagine diventa una fonte di dati, non un’illustrazione.
3. Come rendere affidabile l'estrazione strutturata da un'immagine?
Risposta: Specifica precisamente lo schema atteso (campi, formato), richiedi completezza o l’ammissione dell’assenza e verifica i valori critici—la visione viene promptata come il testo.
4. Quali limiti devi tenere a mente?
Risposta: La qualità dell’immagine condiziona tutto (risoluzione, nitidezza); testi molto piccoli e layout complessi affaticano il modello—ottimizza l’input prima di incolpare l’output.
5. Quali sono i naturali seguiti di questo corso?
Risposta: Document AI per documenti completi, function calling per collegare l’estrazione ai tuoi sistemi e pipeline multimodali che combinano il tutto.
URL o Base64, prompt precisi, input curati: la pipeline di visione è pronta—i prossimi passi la integrano nelle tue applicazioni.