Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Best Practice per la Produzione

Lezione 16 di 16 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Dalla Prova di Concetto al Deploy
  2. Autenticazione e Versioning del Modello
  3. Un Client che Gestisce gli Incidenti
  4. Traccia i Costi in Tempo Reale
  5. Valida a Entrambe le Estremità
  6. Gestisci la Context Window
  7. Cosa Ti Porti a Casa da Questo Corso
  8. Punti chiave
  9. Metti alla Prova le Tue Conoscenze

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-embed e 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_prompt come 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.