Anti-modelli delle API
In questa pagina
- Errori che costano cari in produzione
- Considerare una risposta troncata come completa
- Lasciare crescere la cronologia delle conversazioni senza limiti
- Presupporre che la rete risponda sempre
- Chiedere al modello di fare ciò che non può fare
- Distribuire senza lasciare tracce
- Una routine di debug
- Punti chiave
Errori che costano cari in produzione
Dopo aver esaminato le migliori pratiche, è il momento di guardare l’altra faccia della medaglia. Gli anti-modelli seguenti rappresentano le insidie più comuni quando si utilizza l’API Chat Completions e condividono una caratteristica sgradevole: non emergono durante lo sviluppo. Su dieci richieste di test, tutto funziona perfettamente. È in produzione che esplodono, causando costi imprevisti, risposte incoerenti, alta latenza o, peggio ancora, fughe di dati sensibili.
Considerare una risposta troncata come completa
L’errore più comune è ignorare finish_reason. Chiedi un contratto, ricevi del testo, lo salvi nel database: peccato che max_tokens=100 abbia interrotto la generazione nel mezzo di una clausola e nessuno se ne accorga fino alla firma del cliente. La correzione richiede tre righe di codice e dovrebbe diventare un riflesso automatico.
# SBAGLIATO — nessuna verifica
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=100 # Troppo corto per un contratto!
)
contract = response.choices[0].message.content # Potenzialmente troncato!
# CORRETTO — verifica sistematica
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=4000
)
if response.choices[0].finish_reason == "length":
print("WARNING: Response truncated, increase max_tokens")
else:
contract = response.choices[0].message.content
Lasciare crescere la cronologia delle conversazioni senza limiti
La seconda trappola si innesca lentamente. Un ciclo di chat che invia l’intera cronologia della conversazione a ogni turno funziona perfettamente per i primi dieci scambi, raddoppia i costi al ventesimo e alla fine supera la finestra di contesto al centesimo, con la fattura che segue la stessa curva. La soluzione consiste nel mantenere il prompt di sistema (non negoziabile) e conservare solo gli ultimi N messaggi.
# SBAGLIATO — la cronologia cresce all'infinito
conversation = []
while True:
user_input = input("You: ")
conversation.append({"role": "user", "content": user_input})
response = client.chat.complete(
model="mistral-large-latest",
messages=conversation # 100 turni = migliaia di token!
)
reply = response.choices[0].message.content
conversation.append({"role": "assistant", "content": reply})
# CORRETTO — finestra scorrevole con taglio
MAX_MESSAGES = 20
def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
"""Mantiene il prompt di sistema + gli ultimi N messaggi."""
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
if len(history) > max_messages:
history = history[-max_messages:]
return system + history
Presupporre che la rete risponda sempre
Una chiamata API nuda presuppone che nulla vada storto: nessun timeout, nessun errore 429, nessun 500. In produzione, tutti e tre accadono, e il terzo si verifica nel momento peggiore. Nota la distinzione nel codice: un 429 giustifica un backoff esponenziale, un errore del server merita un secondo di pazienza, ma un errore del client come un 400 o un 401 non deve mai essere ritentato: la tua chiave non diventerà valida al terzo tentativo; ritarderai solo la diagnosi.
# SBAGLIATO — nessuna gestione degli errori
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
# Si blocca su timeout, 429, 500...
# CORRETTO — ritento con backoff
from mistralai.client.errors import SDKError
import time
def safe_complete(client, messages, max_retries=3, **kwargs):
"""Chiamata API con ritento e backoff esponenziale."""
for attempt in range(max_retries):
try:
return client.chat.complete(messages=messages, **kwargs)
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
print(f"Rate limit hit, waiting {wait}s...")
time.sleep(wait)
elif e.status_code >= 500:
time.sleep(1)
else:
raise # Errore client (400, 401) — non ritentare
raise Exception("Failed after 3 attempts")
Chiedere al modello di fare ciò che non può fare
Qui convergono tre anti-modelli. Il primo è il linguaggio soggettivo: “breve”, “molti”, “interessante” non si riferiscono a nulla di verificabile e il modello deciderà in modo diverso da una chiamata all’altra. Sostituisci ogni aggettivo con un numero o un criterio osservabile.
# SBAGLIATO — soggettivo, non misurabile
"Write a short summary." # Breve = 1 frase? 1 paragrafo?
"Give many examples." # Molti = 3? 10? 50?
"Answer in an interesting way." # Interessante secondo quali criteri?
# CORRETTO — criteri oggettivi
"Write a summary of 50 to 80 words."
"Give exactly 5 examples, one per line."
"Start every response with a relevant statistic."
Il secondo è lasciare che il modello conti. Gli LLM sono notoriamente scarsi nel contare parole, caratteri e elementi: chiedere “esattamente 280 caratteri” produrrà un testo di 240 o 310 caratteri. Il conteggio spetta alla tua applicazione, non al modello.
# SBAGLIATO — il modello non può contare con precisione
"Write exactly 280 characters for a tweet."
# CORRETTO — conta lato applicazione
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a tweet about AI in France."}],
max_tokens=100
)
tweet = response.choices[0].message.content
if len(tweet) > 280:
tweet = tweet[:277] + "..."
print(f"Tweet ({len(tweet)} chars): {tweet}")
Il terzo rientra nella stessa famiglia: le scale numeriche. “Valuta da 1 a 5” presuppone che il modello abbia una rappresentazione stabile del divario tra 3 e 4, cosa che non ha. Una scala verbale in cui ogni passo è definito da un criterio produce valutazioni molto più riproducibili.
# SBAGLIATO — i modelli interpretano male le scale numeriche
"Rate the quality of this text from 1 to 5."
# CORRETTO — scala verbale con definizioni
"""Rate the quality of this text according to the following scale:
- EXCELLENT: Clear, well-structured, no errors
- GOOD: Generally correct, minor improvements possible
- AVERAGE: Understandable but lacks structure or contains errors
- POOR: Difficult to understand, significant errors
- VERY POOR: Incomprehensible or off-topic
Respond only with the label in uppercase."""
Distribuire senza lasciare tracce
L’ultimo anti-modello è il più discreto: chiamare l’API, restituire il contenuto e non conservare nulla. Il giorno in cui un utente segnala una risposta aberrante, non hai né l’ID della richiesta, né il modello effettivamente servito, né il consumo di token. Il logging strutturato per chiamata costa pochi millisecondi e rende possibile l’indagine.
# SBAGLIATO — nessuna traccia
response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
return response.choices[0].message.content
# CORRETTO — logging strutturato
import logging
import json
logger = logging.getLogger("mistral_api")
def logged_complete(client, messages, **kwargs):
"""Chiamata API con logging strutturato."""
response = client.chat.complete(messages=messages, **kwargs)
logger.info(json.dumps({
"request_id": response.id,
"model": response.model,
"prompt_tokens": response.usage.prompt_tokens,
"completion_tokens": response.usage.completion_tokens,
"finish_reason": response.choices[0].finish_reason
}))
return response
Una routine di debug
Quando una risposta non soddisfa le tue aspettative, la tentazione è riscrivere il prompt. Invece, inizia con cinque controlli meccanici, in ordine: la risposta è completa? Ha risposto il modello corretto? Quanti token sono stati consumati? La risposta è vuota? Il rapporto output/input è plausibile? Un rapporto inferiore all’1% su un prompt ampio segnala quasi sempre che il modello ha rifiutato di elaborare la richiesta piuttosto che gestirla male.
def debug_response(response):
"""Checklist di debug per risposte inaspettate."""
choice = response.choices[0]
# 1. La risposta è completa?
if choice.finish_reason == "length":
print("ISSUE: Response truncated — increase max_tokens")
# 2. È stato usato il modello corretto?
print(f"Model: {response.model}")
# 3. Quanti token sono stati consumati?
print(f"Input tokens: {response.usage.prompt_tokens}")
print(f"Output tokens: {response.usage.completion_tokens}")
# 4. La risposta è vuota?
if not choice.message.content or not choice.message.content.strip():
print("ISSUE: Empty response")
# 5. Rapporto input/output sospetto?
ratio = response.usage.completion_tokens / max(response.usage.prompt_tokens, 1)
if ratio < 0.01:
print(f"WARNING: Very low output/input ratio ({ratio:.4f})")
Punti chiave
- Controlla sempre
finish_reasonper rilevare i troncamenti - Limita la cronologia delle conversazioni con una finestra scorrevole
- Implementa un ritento con backoff esponenziale per gli errori di rete
- Usa criteri oggettivi e misurabili nei tuoi prompt
- Non lasciare mai che sia il modello a contare: valida lato applicazione
- Registra ogni chiamata API in produzione per il debug e il monitoraggio dei costi