Best Practice per la Produzione
In questa pagina
Dalla Prova di Concetto al Deploy
Ora conosci ogni parametro delle API Chat Completions. La parte più delicata rimane colmare il divario tra un notebook funzionante e un servizio utilizzato da altri senza il tuo intervento. Questa lezione finale consolida l’intero corso in una checklist operativa per la produzione, indicando poi la strada per i corsi di approfondimento.
Autenticazione e Versioning del Modello
Due decisioni precedono la prima riga di logica di business. La prima riguarda la chiave API: deve risiedere in una variabile d’ambiente, mai nel codice, e un’asserzione all’avvio vale più di un None che si propaga per tre livelli fino a generare un messaggio di errore incomprensibile. Pianifica anche la rotazione: crea la nuova chiave, effettua il deploy, poi revoca quella vecchia, in questo ordine, se vuoi evitare di mettere offline il servizio.
import os
# SEMPRE: chiave API in variabile d'ambiente
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY non definita"
# MAI: chiave hardcoded nel codice
# api_key = "sk-abc123..." # VIETATO in produzione
# SEMPRE: rotazione regolare delle chiavi
# Crea una nuova chiave, fai il deploy, poi revoca quella vecchia
La seconda decisione riguarda l’identificativo del modello. In sviluppo, -latest ti offre miglioramenti senza sforzo. In produzione, quello stesso alias significa che un cambio di versione lato provider può alterare il comportamento della tua applicazione senza preavviso, un martedì mattina, senza alcuna traccia di commit per spiegarlo. Fissa la versione.
# SVILUPPO — ultima versione
model = "mistral-large-latest"
# PRODUZIONE — versione fissa per riproducibilità
model = "mistral-large-2512"
# Perché? Un cambio "latest" può alterare il comportamento
# della tua applicazione senza preavviso.
Un Client che Gestisce gli Incidenti
Il cuore di un’integrazione production non è la chiamata API, ma tutto ciò che la circonda. La classe seguente raggruppa tre responsabilità in un unico punto di controllo: retry con backoff esponenziale sui 429, una breve pausa sugli errori server e l’escalation immediata degli errori client che nessun retry può risolvere. Normalizza inoltre la risposta in un dizionario stabile—contenuto, finish_reason, usage, modello, ID—così il resto del tuo codice non dipende più dalla forma esatta dell’oggetto restituito dall’SDK. Il solo logger.warning sulle troncature giustifica l’incapsulamento: è l’unico modo per scoprire che un’impostazione max_tokens è troppo stretta prima che gli utenti se ne lamentino.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging
logger = logging.getLogger(__name__)
class MistralClient:
"""Client production con retry, timeout e logging."""
def __init__(self, api_key: str, max_retries: int = 3):
self.client = Mistral(api_key=api_key)
self.max_retries = max_retries
def complete(self, messages: list, **kwargs) -> dict:
for attempt in range(self.max_retries):
try:
response = self.client.chat.complete(
messages=messages,
**kwargs
)
result = {
"content": response.choices[0].message.content,
"finish_reason": response.choices[0].finish_reason,
"usage": {
"prompt": response.usage.prompt_tokens,
"completion": response.usage.completion_tokens,
"total": response.usage.total_tokens,
},
"model": response.model,
"id": response.id,
}
# Alert se la risposta è troncata
if result["finish_reason"] == "length":
logger.warning(f"Risposta troncata — req_id={response.id}")
return result
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
logger.warning(f"Limite rate raggiunto, retry {attempt+1}/{self.max_retries} tra {wait}s")
time.sleep(wait)
elif e.status_code >= 500:
logger.error(f"Errore server {e.status_code}, retry {attempt+1}")
time.sleep(1)
else:
logger.error(f"Errore client {e.status_code}: {e.message}")
raise
raise Exception(f"Fallito dopo {self.max_retries} tentativi")
Traccia i Costi in Tempo Reale
Scoprire i tuoi consumi sulla fattura mensile è un lusso che poche squadre possono permettersi. Il tracker seguente scrive una riga JSONL per chiamata—timestamp, modello, token in input e output, finish_reason, ID richiesta—e mantiene un totale di sessione interrogabile in qualsiasi momento. Il formato JSONL non è un dettaglio: si aggrega con qualsiasi strumento di analytics senza step di parsing, e la presenza dell’ID richiesta ti permette di legare un’anomalia di costo a una chiamata specifica.
import json
from datetime import datetime, timezone
class CostTracker:
"""Tracciamento costi API in tempo reale."""
def __init__(self, log_path: str = "api_costs.jsonl"):
self.log_path = log_path
self.session_tokens = {"prompt": 0, "completion": 0}
def log(self, response_data: dict):
usage = response_data["usage"]
self.session_tokens["prompt"] += usage["prompt"]
self.session_tokens["completion"] += usage["completion"]
entry = {
"ts": datetime.now(timezone.utc).isoformat(),
"model": response_data["model"],
"prompt_tokens": usage["prompt"],
"completion_tokens": usage["completion"],
"finish_reason": response_data["finish_reason"],
"id": response_data["id"],
}
with open(self.log_path, "a") as f:
f.write(json.dumps(entry) + "\n")
def report(self) -> str:
total = self.session_tokens["prompt"] + self.session_tokens["completion"]
return (
f"Sessione — Prompt: {self.session_tokens['prompt']:,} | "
f"Completion: {self.session_tokens['completion']:,} | "
f"Totale: {total:,} token"
)
Valida a Entrambe le Estremità
Un’applicazione robusta non si fida né di ciò che entra né di ciò che esce. In input, rifiuta messaggi vuoti, limita la lunghezza a 10.000 caratteri per evitare che un copia-incolla sfortunato faccia esplodere la tua fattura, e rimuovi i caratteri di controllo che disturbano la tokenizzazione. In output, non rifiutare nulla ma genera avvisi: risposta potenzialmente troncata, risposta anormalmente breve sotto i cinque caratteri, risposta anormalmente lunga oltre i 50.000. Questi tre segnali catturano la stragrande maggioranza dei fallimenti silenziosi.
def validate_input(user_message: str) -> str:
"""Valida e pulisce l'input utente."""
if not user_message or not user_message.strip():
raise ValueError("Messaggio vuoto")
if len(user_message) > 10_000:
raise ValueError("Messaggio troppo lungo (max 10.000 caratteri)")
# Pulisci caratteri di controllo
cleaned = "".join(c for c in user_message if c.isprintable() or c in "\n\t")
return cleaned.strip()
def validate_output(content: str, finish_reason: str) -> dict:
"""Valida l'output API."""
warnings = []
if finish_reason == "length":
warnings.append("Risposta potenzialmente troncata")
if not content or len(content.strip()) < 5:
warnings.append("Risposta anormalmente breve")
if len(content) > 50_000:
warnings.append("Risposta anormalmente lunga")
return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}
Gestisci la Context Window
Un’ultima questione: la lenta deriva delle conversazioni lunghe. La funzione seguente stima il volume a un token ogni quattro caratteri in francese—un’approssimazione grezza ma sufficiente come guardrail—e lascia passare le richieste finché restano sotto l’80% del limite. Oltre quella soglia, preserva il prompt di sistema e rimuove i messaggi più vecchi fino a scendere sotto il 70%. Questo divario tra le due soglie è deliberato: tagliare solo alla soglia di innesco spingerebbe la funzione di nuovo nella zona rossa al messaggio successivo.
def manage_context(messages: list, max_tokens: int = 100_000) -> list:
"""Mantiene i messaggi entro il limite di token del modello."""
# Stima: 1 token ~ 4 caratteri in francese
total_chars = sum(len(m["content"]) for m in messages)
estimated_tokens = total_chars // 4
if estimated_tokens < max_tokens * 0.8:
return messages # Tutto entra
# Mantieni system + primo e ultimo messaggio
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
# Rimuovi i messaggi più vecchi
while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
removed = history.pop(0)
estimated_tokens -= len(removed["content"]) // 4
return system + history
Cosa Ti Porti a Casa da Questo Corso
Il percorso ha seguito quattro passi. Primo, i fondamentali: endpoint, ruoli, parametri base e struttura della risposta. Poi, lo streaming, con il protocollo SSE, la sua implementazione Python, le sequenze di stop e il rafforzamento tramite safe_prompt e guardrail. Il prompting ha occupato la terza fase: prompt di sistema per la produzione, few-shot, strutturazione XML e Markdown, anti-pattern. I parametri avanzati hanno chiuso il cerchio: temperatura e Top P nel dettaglio, penalità di presenza e frequenza, N completamenti, e questa checklist per la produzione.
La configurazione seguente distilla queste scelte in un punto di partenza difendibile per un primo deploy in produzione: versione fissa, tetto di token adatto al caso d’uso, bassa temperatura per coerenza fattuale, top_p intatto poiché la temperatura è regolata, penalità neutre salvo necessità specifica, e safe_prompt abilitato.
# Configurazione tipica per un'applicazione production
PRODUCTION_CONFIG = {
"model": "mistral-large-2512", # Versione fissa
"max_tokens": 2000, # Adatto al caso d'uso
"temperature": 0.3, # Coerente e fattuale
"top_p": 1.0, # Intatto se la temperatura è regolata
"presence_penalty": 0.0, # Default salvo necessità specifica
"frequency_penalty": 0.0, # Default salvo necessità specifica
"safe_prompt": True, # Sicurezza abilitata
}
Per andare oltre con le API Mistral, quattro corsi complementari seguono su Corsen Academy:
- Embeddings e RAG — Ricerca semantica con
mistral-embede database vettoriali - Function Calling — Connetti il modello ai tuoi tool e API esterne
- Fine-tuning — Adatta un modello al tuo dominio specifico
- Produzione e Valutazione — Metriche, eval automatizzati, ottimizzazione dei costi
Punti chiave
- Usa modelli versionati in produzione, mai
-latest - Implementa retry + backoff + logging fin dal primo deploy
- Valida sia gli input CHE gli output di ogni chiamata API
- Traccia i costi in tempo reale con un token tracker
- Gestisci la context window per le conversazioni lunghe
- Abilita
safe_promptcome rete di sicurezza minima - Testa i tuoi prompt con casi limite prima di ogni release in produzione
Metti alla Prova le Tue Conoscenze
Nessun più segreto nell’endpoint chat/completions? Verifichiamo.
1. Quali ruoli strutturano la lista dei messaggi?
Risposta: system (la cornice), user (richieste), assistant (risposte del modello)—l’intera storia riparte a ogni chiamata, poiché l’API è stateless.
2. Cosa trovi nel campo usage della risposta?
Risposta: Token consumati in input e output—la base per la fatturazione e la metrica da monitorare per dimensionamento e costi.
3. Come funziona lo streaming SSE?
Risposta: La risposta arriva come Server-Sent Events, frammento per frammento: visualizzi man mano che arriva e concatena per ottenere il messaggio finale.
4. A cosa servono le sequenze di stop?
Risposta: A interrompere la generazione non appena appare una data stringa: controllo della lunghezza, stop a un delimitatore, garanzia di formati puliti.
5. Temperatura, Top P, penalità: quale uso in produzione?
Risposta: Temperatura/Top P impostano il determinismo per task; le penalità di presenza/frequenza limitano la ripetizione—impostazioni da fissare per caso d’uso e documentare alongside i tuoi prompt.
Ruoli, usage, streaming, stop, tuning: i fondamentali tengono—le best practice per la produzione sopra esposte li mettono in ordine.