Limiti e ottimizzazione della Vision API
In questa pagina
Conosci i limiti per aggirarli
Le dieci lezioni precedenti hanno illustrato i punti di forza della Vision API. Questa si concentra sulle sue debolezze. Non si tratta di un esercizio di umiltà: la differenza tra un prototipo dimostrativo che stupisce e un’applicazione solida in produzione risiede esattamente qui. Imparerai a gestire i vincoli tecnici, le trappole più comuni – in primis le allucinazioni visive – e le strategie per ottimizzare costi e latenza.
Limiti tecnici
Abbiamo già accennato ai vincoli di formato, ma raggruppiamoli. Ogni immagine ha un limite di circa 20 MB e verrà comunque ridimensionata internamente, tipicamente a 768x768 o equivalente: un’immagine 4K non migliorerà i risultati. I formati accettati sono JPEG, PNG, GIF (solo il primo fotogramma) e WebP. La Vision API non supporta direttamente i PDF: devi ricorrere a Document AI, come discusso nella Lezione 8.
Il vincolo più strutturale rimane il consumo di token. Ogni immagine ne consuma un numero significativo e questa funzione traduce quella stima in dollari piuttosto che in unità astratte:
# Estimate the cost of a vision call
def estimate_cost(num_images=1, text_tokens=100, response_tokens=500,
tokens_per_image=1000, input_price=0.10, output_price=0.30):
"""Estimates the cost in dollars for a vision call (Small 3.2)."""
input_tokens = (num_images * tokens_per_image) + text_tokens
output_tokens = response_tokens
input_cost = (input_tokens / 1_000_000) * input_price
output_cost = (output_tokens / 1_000_000) * output_price
total_cost = input_cost + output_cost
print(f"Input tokens: {input_tokens} (${input_cost:.4f})")
print(f"Output tokens: {output_tokens} (${output_cost:.4f})")
print(f"Total cost: ${total_cost:.4f}")
return total_cost
# 1 image with Small 3.2
estimate_cost(num_images=1)
# 5 images with Large 3
estimate_cost(num_images=5, input_price=2.00, output_price=6.00)
Confronta le due chiamate alla fine dello script: la seconda costa decine di volte più della prima. Moltiplica questo valore per il tuo volume giornaliero prima di prendere una decisione. A ciò si aggiunge il limite della finestra di contesto, che la somma di immagini + prompt + risposta non deve superare: un tetto che più immagini raggiungono molto più velocemente di un lungo testo.
Allucinazioni visive
Il modello può “inventare” dettagli assenti nell’immagine. Questo è il problema più critico in produzione perché è silenzioso: la risposta è ben formata, plausibile e sbagliata.
Quattro schemi ricorrenti. Testo inventato, dove il modello legge una parola che non esiste nell’immagine. Numeri approssimativi, dove i valori letti da un grafico possono discostarsi del 5–15% dalla realtà. Dettagli aggiunti, dove il modello riempie ciò che non vede chiaramente con informazioni plausibili: un numero SIRET sfocato diventa un SIRET perfettamente formattato ma falso. Infine, confusione di elementi, dove due oggetti vicini vengono fusi in uno solo.
Esistono tre contromisure; combinale in base alla criticità. Primo, costringi il modello a qualificare la propria certezza. Secondo, fagli rileggere l’immagine dopo la trascrizione. Terzo, metti due modelli a confronto sulla stessa domanda e mantieni solo ciò su cui concordano.
# 1. Ask for a confidence level
prompt_confiance = """Analyze this image. For each piece of extracted information, indicate your confidence level:
- [CERTAIN]: clearly visible
- [PROBABLE]: partially visible or inferred
- [INCERTAIN]: barely legible, estimated
If an element is illegible, mark it [ILLISIBLE] rather than guessing."""
# 2. Ask for cross-verification
prompt_verification = """Read the text in this document. After transcribing, reread the image and verify every number and proper noun. Correct any detected errors."""
# 3. Double reading with two models
def double_verification(image_uri, question):
"""Sends the same image to two models and compares results."""
resultats = {}
for modele in ["mistral-small-latest", "mistral-large-latest"]:
response = client.chat.complete(
model=modele,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": question},
{"type": "image_url", "image_url": image_uri}
]
}]
)
resultats[modele] = response.choices[0].message.content
return resultats
La doppia lettura raddoppia il costo: riservala a importi, identificativi e qualsiasi cosa inneschi un’azione irreversibile.
Ottimizzare i costi
L’ottimizzazione più efficace in termini di costi è stata trattata nella Lezione 5 ed è la più semplice: riduci le dimensioni dell’immagine prima dell’invio. Una foto da 6 MB ridimensionata a 1024 pixel non perde nulla ai fini dell’analisi e alleggerisce l’intera catena.
from PIL import Image
from io import BytesIO
import base64
def optimiser_image(chemin, taille_max=1024, qualite=80):
"""Resizes and compresses an image for the Vision API."""
img = Image.open(chemin)
taille_originale = img.size
# Resize
if max(img.size) > taille_max:
img.thumbnail((taille_max, taille_max))
# Compress as JPEG
buffer = BytesIO()
img.convert("RGB").save(buffer, format="JPEG", quality=qualite)
taille_fichier = buffer.tell()
b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")
print(f"Original: {taille_originale} | Optimized: {img.size} | Size: {taille_fichier/1024:.0f} KB")
return f"data:image/jpeg;base64,{b64}"
Segue il routing per complessità: non ogni compito merita il modello più costoso. Una funzione di tre righe è sufficiente per decidere, a patto di aver classificato i tuoi compiti a monte.
def choose_model(task):
"""Selects the optimal model based on the task."""
simple_tasks = ["classification", "ocr_simple", "description", "triage"]
complex_tasks = ["extraction_json", "comparaison", "analyse_graphique", "raisonnement"]
if task in simple_tasks:
return "mistral-small-latest" # ~$0.10/M tokens
else:
return "mistral-large-latest" # ~$2.00/M tokens
La terza leva è la più spesso dimenticata: non pagare due volte per la stessa analisi. In produzione, la stessa immagine ritorna più spesso di quanto pensi: riavvio di un processo, invii duplicati o nuovi tentativi dopo un incidente. Una cache su disco indicizzata sull’hash del file e sul prompt elimina queste chiamate ridondanti.
import hashlib
import json
from pathlib import Path
CACHE_DIR = Path("cache_vision/")
CACHE_DIR.mkdir(exist_ok=True)
def analyser_avec_cache(image_path, prompt, modele="mistral-small-latest"):
"""Analyzes an image with disk caching."""
# Generate a cache key
with open(image_path, "rb") as f:
image_hash = hashlib.md5(f.read()).hexdigest()
cache_key = hashlib.md5(f"{image_hash}{prompt}{modele}".encode()).hexdigest()
cache_file = CACHE_DIR / f"{cache_key}.json"
# Check cache
if cache_file.exists():
return json.loads(cache_file.read_text())
# API call
response = client.chat.complete(
model=modele,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": prompt},
{"type": "image_url", "image_url": encoder_image(image_path)}
]
}]
)
resultat = response.choices[0].message.content
# Save to cache
cache_file.write_text(json.dumps(resultat, ensure_ascii=False))
return resultat
La chiave include il prompt e il modello, non solo l’immagine: cambiare la domanda sulla stessa foto deve infatti innescare una nuova chiamata.
Ottimizzare la latenza
Per un’applicazione interattiva, quattro impostazioni influenzano il tempo di risposta percepito. Ridimensiona le immagini lato client a un massimo di 1024 pixel, riducendo il tempo di caricamento. Scegli Small o Ministral, poiché la loro generazione è significativamente più veloce. Passa le immagini tramite URL quando sono già ospitate per evitare di inviare un corpo richiesta Base64 voluminoso. Infine, abilita lo streaming, che non riduce il tempo totale ma visualizza la risposta man mano che viene costruita:
# Streaming for a progressive response
stream = client.chat.stream(
model="mistral-small-latest",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Describe this image."},
{"type": "image_url", "image_url": image_url}
]
}]
)
for chunk in stream:
if chunk.data.choices[0].delta.content:
print(chunk.data.choices[0].delta.content, end="", flush=True)
Si tratta di chat.stream che sostituisce chat.complete; il resto del messaggio è esattamente lo stesso.
Checklist per la produzione
Prima di distribuire un’applicazione Vision in produzione, verifica ciascuno di questi punti:
- Ridimensionamento automatico delle immagini (max 1024px)
- Validazione di formato e dimensioni prima dell’invio
- Gestione degli errori API (nuovo tentativo, timeout, fallback)
- Cache dei risultati per immagini identiche
- Routing intelligente (Small per compiti semplici, Large per complessi)
- Monitoraggio di costi e latenza
- Test con immagini di scarsa qualità (sfocate, bassa risoluzione, ruotate)
- Strategia anti-allucinazione (livelli di confidenza, doppia verifica)
Il penultimo punto è quello più spesso saltato, e quello che causa i danni maggiori: costruisci un dataset di immagini deliberatamente scadenti ed eseguilo prima di ogni distribuzione.
Punti chiave
- Le immagini vengono ridimensionate internamente: non serve inviare risoluzioni molto elevate
- Le allucinazioni visive sono il rischio principale: richiedi livelli di confidenza
- Il ridimensionamento lato client è l’ottimizzazione più efficace in termini di costi
- Il routing per complessità (Small vs Large) riduce i costi del 90% sui compiti semplici
- La cache su disco evita chiamate API ridondanti sulle stesse immagini