Inviare più immagini in un singolo messaggio
In questa pagina
Analizzare più immagini contemporaneamente
Le API Vision di Mistral non si limitano a un’immagine per messaggio. Puoi inviare più immagini in una singola chiamata per chiedere al modello di confrontarle, sintetizzarle o analizzarle insieme. La differenza rispetto a due chiamate separate è cruciale: in un’unica chiamata, il modello vede entrambe le immagini simultaneamente e può ragionare sulle loro relazioni, qualcosa che nessuna aggregazione di risposte individuali potrebbe ottenere.
Questa capacità sblocca casi d’uso in cui la domanda si concentra sul divario piuttosto che sul contenuto: confronti prima/dopo, analisi di serie documentali o verifiche di conformità visiva.
Struttura di un messaggio multi-immagine
Il principio è semplice: aggiungi più elementi image_url all’array content:
message = {
"role": "user",
"content": [
{"type": "text", "text": "Confronta queste due immagini e descrivi le differenze."},
{"type": "image_url", "image_url": "https://example.com/image1.jpg"},
{"type": "image_url", "image_url": "https://example.com/image2.jpg"}
]
}
L’omogeneità non è richiesta: puoi mescolare immagini tramite URL e Base64 nello stesso messaggio. Questo è comune quando devi confrontare un’immagine di riferimento ospitata con un file locale appena generato.
Esempio: confronto tra due immagini
Considera un’ispezione alla ricezione in magazzino. Confronti una foto di riferimento del prodotto conforme con una foto del campione ricevuto, utilizzando un prompt di sistema che stabilisce il ruolo dell’ispettore:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Sei un esperto di controllo qualità. Confronta le immagini fornite con precisione."
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Ecco due foto dello stesso prodotto. La prima è il riferimento, la seconda è il campione ricevuto. Identifica tutte le differenze."
},
{"type": "image_url", "image_url": "https://example.com/reference.jpg"},
{"type": "image_url", "image_url": "https://example.com/sample.jpg"}
]
}
]
)
print(response.choices[0].message.content)
Il testo dichiara esplicitamente l’ordine—“la prima è il riferimento”—perché il modello non può indovinarlo.
Alternare testo e immagini
Questo approccio all’ordinamento raggiunge rapidamente i suoi limiti oltre due immagini. Un metodo più robusto consiste nell’etichettare ogni immagine appena prima di fornirla, alternando elementi text e image_url:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Ecco il piano architettonico originale:"},
{"type": "image_url", "image_url": "https://example.com/plan-original.png"},
{"type": "text", "text": "Ed ecco la foto dell'edificio costruito:"},
{"type": "image_url", "image_url": "https://example.com/photo-batiment.jpg"},
{"type": "text", "text": "L'edificio corrisponde al piano? Elenca le discrepanze."}
]
}
]
)
Ogni immagine porta ora la propria etichetta e la domanda finale arriva solo dopo aver presentato tutto il materiale. Questo formato migliora significativamente la comprensione del modello: sa che il piano è lo standard e la foto è l’oggetto da valutare. Invertirli produrrebbe un rapporto di discrepanze invertito.
Elaborazione batch con Base64
Per una cartella di immagini locali, la costruzione del content diventa programmatica. Assembli la lista in un ciclo, codificando ogni file al volo:
import base64
import os
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
def encode_image(path):
with open(path, "rb") as f:
b64 = base64.standard_b64encode(f.read()).decode("utf-8")
ext = Path(path).suffix.lower()
mime = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"}.get(ext.lstrip("."), "jpeg")
return f"data:image/{mime};base64,{b64}"
# Carica tutte le immagini da una cartella
folder = Path("captures/")
images = sorted(folder.glob("*.png"))
# Costruisci il contenuto del messaggio
content = [{"type": "text", "text": f"Analizza questi {len(images)} screenshot e riassumi gli elementi comuni."}]
for img in images[:5]: # Limita a max 5 immagini
content.append({"type": "image_url", "image_url": encode_image(img)})
response = client.chat.complete(
model="mistral-small-latest",
messages=[{"role": "user", "content": content}]
)
print(response.choices[0].message.content)
Lo slice images[:5] è la salvaguardia dello script. Senza di esso, una cartella contenente duecento screenshot finirebbe interamente in un’unica chiamata, con le conseguenze descritte qui sotto.
Limiti delle chiamate multi-immagine
Non esiste un limite rigoroso documentato sul numero di immagini, ma oltre cinque-dieci si combinano due effetti: la qualità dell’analisi degrada poiché l’attenzione del modello si diluisce tra le immagini e i costi in token aumentano drasticamente. Ricorda l’ordine di grandezza dalla Lezione 2: ogni immagine consuma da 800 a 1.500 token, quindi cinque immagini rappresentano già da 5.000 a 7.500 token di prompt prima ancora che la tua domanda inizi. Il totale—immagini, testo e risposta—deve inoltre rientrare nella finestra di contesto del modello, un tetto che un batch di immagini raggiunge molto più velocemente di un documento testuale.
Questa funzione calcola il costo prima della chiamata piuttosto che dopo:
def estimate_multi_image_cost(num_images, tokens_per_image=1000, text_tokens=100, response_tokens=500):
"""Stima i token totali per una chiamata multi-immagine."""
total_input = (num_images * tokens_per_image) + text_tokens
total = total_input + response_tokens
print(f"Immagini: {num_images} x {tokens_per_image} = {num_images * tokens_per_image} token")
print(f"Testo del prompt: {text_tokens} token")
print(f"Risposta stimata: {response_tokens} token")
print(f"Totale stimato: {total} token")
return total
estimate_multi_image_cost(3)
# Immagini: 3 x 1000 = 3000 token
# Testo del prompt: 100 token
# Risposta stimata: 500 token
# Totale stimato: 3600 token
Strategia per grandi volumi
Oltre cinque immagini, cambia approccio invece di forzare la mano. Esistono tre percorsi, spesso combinati. L’analisi sequenziale elabora le immagini una per una e poi aggrega i risultati: il costo rimane lineare e la precisione per immagine è massima. Il raggruppamento batch invia pacchetti da tre a cinque immagini, preservando un certo confronto intra-batch. Il pre-filtraggio, infine, utilizza un modello più leggero come Small per scartare le immagini irrilevanti prima di passare i casi importanti a Large.
Il primo percorso appare così, con una sintesi finale che gestisce solo testo:
# Analisi sequenziale con aggregazione
results = []
for img_path in images:
response = client.chat.complete(
model="mistral-small-latest",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Descrivi brevemente il contenuto di questa immagine."},
{"type": "image_url", "image_url": encode_image(img_path)}
]
}]
)
results.append(response.choices[0].message.content)
# Sintesi finale (solo testo)
synthesis = client.chat.complete(
model="mistral-small-latest",
messages=[{
"role": "user",
"content": f"Ecco le descrizioni di {len(results)} immagini:\n\n" +
"\n---\n".join(results) +
"\n\nFornisci una sintesi globale."
}]
)
Il trucco risiede nella seconda chiamata: non contiene immagini, quindi nessun token visivo. Sintetizzi cinquanta immagini al prezzo di poche centinaia di token testuali.
Punti chiave
- Puoi inviare più immagini in un singolo messaggio aggiungendo più elementi
image_url - Alterna il testo tra le immagini per fornire contesto al modello
- Ogni immagine aggiunge 800-1500 token: stima i tuoi costi prima di chiamare
- Oltre 5 immagini, preferisci una strategia sequenziale o a batch
- URL e Base64 possono essere mescolati nello stesso messaggio