Migliori pratiche e riepilogo
In questa pagina
Riepilogo del corso
Hai esplorato l’intera gamma di meccanismi di output strutturato offerti dalle API Mistral. Questa lezione finale riunisce ciò che fa la differenza nel lavoro quotidiano: come scegliere tra i due approcci, le impostazioni non negoziabili, gli errori più comuni e cosa monitorare una volta in produzione.
Scegliere il tuo approccio
Quattro domande bastano per decidere, in questo ordine. Hai uno schema di output definito? Se la risposta è no, attieniti alla Modalità JSON: sei in fase di esplorazione o prototipazione e bloccare un modello di dati sarebbe prematuro. Se sì, passa alla domanda successiva.
Stai lavorando in Python o TypeScript? In tal caso, gli Output Strutturati Personalizzati sono pronti per te con Pydantic o Zod. Altrimenti, la Modalità JSON con validazione manuale rimane la tua strada.
Sei in produzione? Se sì, gli Output Strutturati Personalizzati sono obbligatori, sempre. Altrimenti, la Modalità JSON è più che sufficiente per la prototipazione.
Lo schema cambia frequentemente? Uno schema ancora in evoluzione rende la Modalità JSON più pratica all’inizio, finché i requisiti non si stabilizzano; uno schema fisso argomenta a favore degli Output Strutturati Personalizzati e dell’affidabilità che portano.
Le dieci regole d’oro
Le prime cinque riguardano il modo in cui scrivi le tue chiamate. Imposta sempre temperature=0 in produzione: la variabilità della temperatura è nemica dell’affidabilità e l’estrazione non ha bisogno di creatività.
# Produzione: deterministico
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
temperature=0 # Riproducibilità
)
Controlla sempre finish_reason. Questo è l’unico indicatore che ti avvisa di una risposta troncata prima di tentare di utilizzarla.
if response.choices[0].finish_reason != "stop":
# La risposta è troncata — aumenta max_tokens
raise ValueError(f"Risposta incompleta: {response.choices[0].finish_reason}")
In Modalità JSON, istruisci sempre il modello nel prompt. Il parametro garantisce la sintassi, non la struttura: spetta a te dichiarare le chiavi e i loro tipi.
# Modalità JSON — il prompt DEVE descrivere la struttura
messages = [
{
"role": "system",
"content": "Restituisci JSON con chiavi: name (string), age (number), city (string)."
},
{"role": "user", "content": text}
]
In modalità Personalizzata, documenta i tuoi campi. Una descrizione precisa vale più di un lungo prompt e viaggia con lo schema in entrambi i linguaggi.
class Product(BaseModel):
name: str = Field(description="Nome commerciale del prodotto")
price: float = Field(description="Prezzo in EUR escluso IVA, arrotondato a 2 decimali")
const ProductSchema = z.object({
name: z.string().describe("Nome commerciale del prodotto"),
price: z.number().describe("Prezzo in EUR escluso IVA, arrotondato a 2 decimali"),
});
Separa il contesto dal contenuto. Le istruzioni vivono nel messaggio di sistema, i dati da elaborare nel messaggio utente—mai il contrario, altrimenti il modello confonderà l’istruzione con il testo sorgente.
messages = [
{"role": "system", "content": "Sei un estrattore di dati. [Istruzioni sul formato]"},
{"role": "user", "content": "[Testo da elaborare — NESSUNA istruzione sul formato qui]"}
]
Le prossime due regole riguardano la tua rete di sicurezza. Implementa un meccanismo di retry: non fare mai una singola chiamata senza un backup; il retry con feedback è il pattern minimo in produzione. E valida oltre lo schema, poiché lo schema garantisce la struttura mentre la validazione semantica—limiti, coerenza, logica di business—rimane tua responsabilità.
Le ultime tre riguardano l’orchestrazione. Scegli il modello giusto per il caso d’uso giusto: mistral-large-latest per compiti complessi ed estrazione multi-campo, mistral-small-latest per classificazione semplice ed estrazione di base, ministral-8b-latest per alta frequenza e latenza minima. Registra ogni chiamata in produzione, annotando il modello utilizzato, la durata, finish_reason e l’esito: senza log, sei cieco. Infine, non ottimizzare il prompt troppo presto—inizia semplice, misura, itera; l’ottimizzazione prematura del prompt è una trappola comune, mentre lo schema e la validazione sono le vere leve.
Tre errori costosi
Il primo è un valore di max_tokens troppo basso. Il JSON verrà troncato su risposte lunghe e l’errore si manifesterà solo su documenti di grandi dimensioni, spesso dopo il go-live.
# Pericoloso — il JSON verrà troncato per risposte lunghe
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=128 # Troppo basso per uno schema complesso
)
Imposta max_tokens in base alla dimensione attesa del tuo output: una fattura con 20 righe richiede più token di una semplice classificazione.
Il secondo è una temperatura diversa da zero, che rende i tuoi risultati non riproducibili per zero guadagno in un compito di estrazione.
# Pericoloso in produzione — risultati non riproducibili
response = client.chat.parse(
...,
temperature=0.7 # Variazione inutile per l'estrazione
)
Il terzo è il riflesso di usare un singolo modello. Non usare mistral-large per tutto: una classificazione binaria non richiede il modello più potente e ministral-8b farà il lavoro 5 volte più velocemente a minor costo.
Cosa monitorare
Quattro metriche indicano la salute della tua pipeline. Il tasso di successo misura la percentuale di chiamate che restituiscono un oggetto valido al primo tentativo; il tasso di retry, la percentuale di chiamate che hanno avuto bisogno di un secondo tentativo. La latenza P50/P95 fornisce il tempo di risposta mediano e il 95° percentile, che è più rivelatore della media. Il costo per estrazione, espresso in token consumati per chiamata, tiene sotto controllo la fattura.
Su queste metriche, alcune soglie di allerta reggono bene: un tasso di successo inferiore al 95% giustifica un allerta gialla, inferiore all’85% un allerta rossa; una latenza P95 superiore a 10 s warrants un’indagine; e un circuit breaker aperto richiede un allerta immediato.
Andare oltre
Quattro direzioni estendono naturalmente questo corso. Il function calling utilizza output strutturati per alimentare chiamate di funzione in un agente. Lo streaming ti permette di ricevere l’output strutturato progressivamente, cosa importante per risposte lunghe. Il fine-tuning adatta un modello Mistral per migliorare la qualità dell’estrazione sui tuoi dati specifici. La valutazione, infine, consiste nel configurare un framework automatico basato su un dataset golden e metriche: è questo che ti dirà se una modifica al prompt migliora effettivamente le cose.
Una pipeline completa
Il codice seguente riunisce le pratiche del corso in un unico flusso: uno schema descritto campo per campo, un validatore che rifiuta punteggi fuori limite, un modello dimensionato al compito, temperature=0, un max_tokens esplicito, verifica di finish_reason e logging per entrambi i possibili esiti.
from mistralai.client import Mistral
from pydantic import BaseModel, Field, field_validator
import logging
import time
logger = logging.getLogger("pipeline")
class CustomerFeedback(BaseModel):
sentiment: str = Field(description="positive, negative, or neutral")
score: float = Field(description="Score between -1.0 and 1.0")
category: str = Field(description="product, service, delivery, price, or other")
action_required: bool = Field(description="True if action is required")
summary: str = Field(description="One-sentence summary")
@field_validator("score")
@classmethod
def score_in_range(cls, v):
if not -1.0 <= v <= 1.0:
raise ValueError(f"Score out of bounds: {v}")
return v
def analyze_feedback(client: Mistral, text: str) -> CustomerFeedback:
start = time.time()
try:
response = client.chat.parse(
model="mistral-small-latest",
messages=[
{"role": "system", "content": "Analyze customer feedback."},
{"role": "user", "content": text}
],
response_format=CustomerFeedback,
temperature=0,
max_tokens=256
)
assert response.choices[0].finish_reason == "stop"
result = response.choices[0].message.parsed
logger.info(f"OK in {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
return result
except Exception as e:
logger.error(f"ERROR in {time.time()-start:.2f}s — {e}")
raise
Una trentina di righe e hai un componente che può essere inserito in sicurezza nel mezzo di un sistema: è esattamente ciò che gli output strutturati rendono possibile.
Punti chiave
- Usa gli Output Strutturati Personalizzati in produzione, la Modalità JSON per la prototipazione
temperature=0, il controllo difinish_reasone il retry sono non negoziabili- Scegli il modello in base alla complessità del compito e al budget
- Monitora il tasso di successo, la latenza e il costo
- Inizia semplice, misura, poi ottimizza
Metti alla prova le tue conoscenze
Modalità JSON, schemi, retry: l’output strutturato sotto controllo?
1. Modalità JSON vs Output Strutturati Personalizzati: qual è la differenza?
Risposta: La Modalità JSON garantisce un JSON sintatticamente valido; gli Output Strutturati Personalizzati impongono inoltre il tuo schema esatto—campi, tipi, struttura: il contratto completo.
2. Cosa fornisce client.chat.parse() con Pydantic?
Risposta: Il ciclo completo: lo schema Pydantic dichiara la struttura, l’API vincola la generazione e la risposta arriva già validata e tipizzata come oggetto Python—zero parsing manuale.
3. E lato TypeScript?
Risposta: Lo stesso comfort con Zod: lo schema Zod definisce e valida la struttura—un’unica fonte di verità per generazione e tipizzazione.
4. Cosa fare quando l'output non rispetta lo schema?
Risposta: Validare sistematicamente e pianificare una strategia di retry: richiedere nuovamente con l’errore nel contesto, o degradare con grazia—mai fidarsi ciecamente dell’output.
5. Quando l'output strutturato è indispensabile?
Risposta: Non appena un programma consuma la risposta senza revisione umana: estrazione, integrazioni, pipeline—il formato cessa di essere una cortesia, diventa un’interfaccia.
Schema dichiarato, generazione vincolata, validazione dell’output: la triade che rende l’IA inseribile nel software reale.