Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Migliori pratiche e produzione

Lezione 14 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Dalla prova di concetto alla produzione
  2. Checklist di deployment
  3. Scrivere descrizioni che fanno lavorare il modello
  4. Scegliere il modello giusto
  5. Strutturare il messaggio di sistema
  6. Gestire i costi in produzione
  7. Testare il Function Calling
  8. Monitoraggio in produzione
  9. Prossimi passi
  10. Punti chiave
  11. Metti alla prova le tue conoscenze

Dalla prova di concetto alla produzione

Ora hai tutti i mattoni per costruire sistemi di function calling con Mistral. Ciò che separa il tuo prototipo da un servizio pronto per la produzione non sono funzionalità mancanti, ma una serie di controlli e passaggi di ottimizzazione che scopri solitamente durante un incidente. Questa lezione finale riunisce migliori pratiche, errori comuni e una checklist per passare in produzione con fiducia.

Checklist di deployment

Questo è l’unico punto del corso in cui un elenco è obbligatorio: prima di andare online, devi spuntare delle caselle. Quattro domini devono essere coperti, ognuno rispondendo a una domanda diversa.

Architettura garantisce che la meccanica tenga. Restituire stringhe JSON nella catena e avere un dizionario di dispatch completo sono le due cause più frequenti di crash alla prima chiamata reale.

  • Tutte le funzioni restituiscono stringhe JSON (mai oggetti Python grezzi)
  • Il dizionario di dispatch è completo e aggiornato
  • Le funzioni gestiscono i casi di errore e restituiscono messaggi utilizzabili
  • Il messaggio di sistema è chiaro, preciso e testato
  • Il ciclo di conversazione gestisce chiamate sequenziali e parallele

Sicurezza presuppone che gli argomenti provengano da un utente, mai dalla tua applicazione.

  • Gli argomenti sono validati prima dell’esecuzione (formato, tipo, valori)
  • Le query SQL usano parametri (nessuna concatenazione)
  • Una whitelist limita le funzioni disponibili
  • Le azioni distruttive richiedono conferma
  • Il rate limiting è attivo per funzione e per utente
  • I risultati sono sanificati (nessun dato sensibile restituito al modello)

Affidabilità gestisce ciò che fallisce senza che nessuno abbia colpe.

  • Gli errori sono restituiti al modello in un formato strutturato
  • Il retry con backoff è implementato per errori transitori
  • I timeout sono configurati per ogni funzione esterna
  • La dimensione della cronologia è limitata per evitare superamenti di token

Monitoraggio, infine, è ciò che ti permette di diagnosticare senza indovinare.

  • Ogni chiamata di funzione è registrata (nome, argomenti, risultato, durata)
  • Gli errori attivano alert (Slack, PagerDuty, ecc.)
  • Le metriche sono raccolte (tasso di successo, latenza, costo API)

Scrivere descrizioni che fanno lavorare il modello

La qualità della descrizione ha un impatto diretto sulla precisione ed è spesso la leva più economica da tirare. Tre schemi ricorrono tra i team con alti tassi di chiamate corrette. Il primo ancora la descrizione nel contesto aziendale: invece di parafrasare il nome della funzione, elenca i possibili valori di ritorno e dichiara esplicitamente quando chiamarla. Il secondo inserisce esempi di formato nella descrizione del parametro, il che risolve la maggior parte degli errori di estrazione degli ID. Il terzo sostituisce un’istruzione in linguaggio naturale con un enum, l’unico modo per vietare davvero un valore fuori lista.

# Schema 1: Descrizione con contesto aziendale
{
    "description": "Recupera lo stato del pagamento. "
                   "Stati possibili: paid, pending, failed, refunded. "
                   "Usa questa funzione quando l'utente chiede "
                   "lo stato di un pagamento o se è stato ricevuto."
}

# Schema 2: Parametri con esempi
{
    "transaction_id": {
        "type": "string",
        "description": "ID univoco nel formato T seguito da 4 cifre (es. T1001, T2345)"
    }
}

# Schema 3: Enum per valori limitati
{
    "status": {
        "type": "string",
        "enum": ["paid", "pending", "failed", "refunded"],
        "description": "Filtra per stato del pagamento"
    }
}

Scegliere il modello giusto

La scelta del modello bilancia precisione e costo, e non esiste una risposta universale: dipende dal numero di funzioni esposte e dalla complessità dei loro schemi. Un caso complesso con molte funzioni e parametri nidificati giustifica Mistral Large 3, più affidabile nella selezione delle funzioni ma più costoso. Un caso standard con poche funzioni semplici in produzione ad alto throughput gira molto bene su Mistral Small 4, veloce ed economico. Per prototipazione e test, Mistral Medium 3.5 offre un buon compromesso.

# Casi complessi: molte funzioni, parametri nidificati
# -> Mistral Large 3 (più affidabile, più costoso)
model = "mistral-large-latest"

# Casi standard: poche funzioni semplici, produzione ad alto throughput
# -> Mistral Small 4 (veloce, economico)
model = "mistral-small-latest"

# Casi di sviluppo: prototipazione, test
# -> Mistral Medium 3.5 (buon compromesso)
model = "mistral-medium-latest"

Il metodo conta quanto il risultato: in produzione, inizia con il modello più capace, misura il tuo tasso di chiamate corrette, poi scendi gradualmente per trovare il miglior rapporto costo/prestazioni. Il contrario—iniziare dal modello più economico—ti priva della baseline necessaria per sapere se il degrado viene dal modello o dalle tue descrizioni.

Strutturare il messaggio di sistema

Un buon messaggio di sistema fa la differenza tra un assistente mediocre e uno eccellente. Questo illustra una struttura collaudata: una dichiarazione di ruolo, un blocco di regole imperative, poi un promemoria degli strumenti disponibili. Le due regole più efficaci in termini di costo qui sono “Se l’utente non fornisce un ID richiesto, chiedi gentilmente” e “Non indovinare mai un ID transazione”: insieme, eliminano il comportamento più dannoso in assoluto, ovvero chiamare una funzione con un ID inventato.

system_message = {
    "role": "system",
    "content": """Sei un assistente per la gestione dei pagamenti per Acme Corporation.

Regole:
- Rispondi sempre in inglese
- Formatta gli importi in euro con il simbolo e 2 decimali
- Se l'utente non fornisce un ID richiesto, chiedi gentilmente
- Non indovinare mai un ID transazione
- Quando una transazione fallisce, offriti di controllare i dettagli

Strumenti disponibili:
- retrieve_payment_status: per controllare lo stato di un pagamento
- retrieve_payment_date: per controllare la data di un pagamento
- retrieve_payment_details: per ottenere tutti i dettagli di una transazione
- list_customer_transactions: per visualizzare tutte le transazioni di un cliente"""
}

Gestire i costi in produzione

Ogni chiamata di function calling consuma token e la fattura sale attraverso due canali sottovalutati: le definizioni degli strumenti sono inviate con ogni richiesta e la cronologia cresce a ogni turno. Filtrare le funzioni per contesto risolve il primo punto: non serve inviare tutti e dodici gli strumenti quando la domanda riguarda chiaramente i pagamenti. Troncare la cronologia oltre una soglia risolve il secondo. E quando tutti i dati necessari sono già nel contesto, tool_choice="none" evita un round trip extra.

# 1. Limita il numero di funzioni per richiesta
# Passa solo le funzioni rilevanti per il contesto
def get_relevant_tools(user_input: str, all_tools: list) -> list:
    """Filtra gli strumenti in base al contesto."""
    if "payment" in user_input.lower() or "transaction" in user_input.lower():
        return [t for t in all_tools if "payment" in t["function"]["name"]]
    if "contact" in user_input.lower() or "customer" in user_input.lower():
        return [t for t in all_tools if "contact" in t["function"]["name"]]
    return all_tools

# 2. Limita la dimensione della cronologia
MAX_HISTORY = 20  # messaggi

# 3. Usa tool_choice="none" quando i dati sono già disponibili

Testare il Function Calling

I test sono essenziali per evitare regressioni e qui prendono di mira un oggetto insolito: non stai controllando il valore di ritorno della tua funzione, ma la decisione del modello. Due famiglie di test coprono l’essenziale. La prima verifica che una domanda aziendale attivi la funzione giusta con gli argomenti estratti corretti. La seconda, altrettanto importante e spesso dimenticata, verifica che un saluto non attivi alcuna chiamata: questo test intercetta descrizioni troppo ampie che spingono il modello a chiamare una funzione in ogni circostanza.

def test_payment_status():
    """Verifica che il modello chiami la funzione corretta."""
    messages = [{"role": "user", "content": "Stato del pagamento T1001?"}]

    response = client.chat.complete(
        model=model, messages=messages, tools=tools
    )

    message = response.choices[0].message
    assert message.tool_calls is not None
    assert len(message.tool_calls) == 1
    assert message.tool_calls[0].function.name == "retrieve_payment_status"

    args = json.loads(message.tool_calls[0].function.arguments)
    assert args["transaction_id"] == "T1001"


def test_no_function_for_greeting():
    """Verifica che il modello non chiami una funzione per un saluto."""
    messages = [{"role": "user", "content": "Ciao!"}]

    response = client.chat.complete(
        model=model, messages=messages, tools=tools
    )

    message = response.choices[0].message
    assert message.tool_calls is None or len(message.tool_calls) == 0
    assert message.content is not None

Monitoraggio in produzione

Ora devi sapere cosa fa il tuo sistema una volta rilasciato nel mondo reale. La classe sottostante aggrega tre segnali che, insieme, raccontano quasi tutta la storia: tasso di successo globale, latenza media e ripartizione per funzione. Quest’ultima è la più rivelatrice nella pratica: una funzione il cui contatore di errori deriva in isolamento indica un problema specifico, mentre un tasso globale degradato non ti dice dove guardare.

import time
import logging

logger = logging.getLogger("fc_monitor")

class FunctionCallingMonitor:
    def __init__(self):
        self.metrics = {
            "total_calls": 0,
            "successful_calls": 0,
            "failed_calls": 0,
            "total_latency_ms": 0,
            "calls_by_function": {}
        }

    def record(self, function_name: str, success: bool, latency_ms: float):
        self.metrics["total_calls"] += 1
        self.metrics["total_latency_ms"] += latency_ms

        if success:
            self.metrics["successful_calls"] += 1
        else:
            self.metrics["failed_calls"] += 1

        if function_name not in self.metrics["calls_by_function"]:
            self.metrics["calls_by_function"][function_name] = {
                "count": 0, "errors": 0
            }
        self.metrics["calls_by_function"][function_name]["count"] += 1
        if not success:
            self.metrics["calls_by_function"][function_name]["errors"] += 1

    def get_success_rate(self) -> float:
        if self.metrics["total_calls"] == 0:
            return 0.0
        return self.metrics["successful_calls"] / self.metrics["total_calls"]

    def get_avg_latency(self) -> float:
        if self.metrics["total_calls"] == 0:
            return 0.0
        return self.metrics["total_latency_ms"] / self.metrics["total_calls"]

monitor = FunctionCallingMonitor()

Prossimi passi

Ora che hai padroneggiato il function calling con Mistral, si aprono diverse direzioni. La più naturale è costruire agenti autonomi, combinando il function calling con un loop di agente che pianifica ed esegue compiti complessi; le Mistral Agents API e il loro client.beta.agents.create() vanno oltre offrendo agenti persistenti con stato. Un altro asse combina RAG e function calling: il modello decide da sé quando interrogare un database vettoriale, invece che la ricerca venga attivata sistematicamente a monte. Sul lato dell’esperienza utente, lo streaming ti permette di visualizzare le risposte in tempo reale mentre le funzioni vengono eseguite, cambiando la percezione della latenza su catene di chiamate lunghe. Infine, il multimodale apre il function calling alla visione per l’analisi dei documenti.

Punti chiave

  • La checklist di deployment copre architettura, sicurezza, affidabilità e monitoraggio
  • Descrizioni precise con esempi ed enum migliorano la precisione del modello
  • Scegli il modello giusto in base alla complessità e al budget (Large per l’affidabilità, Small per il throughput)
  • Il messaggio di sistema è una leva potente per guidare il comportamento
  • Testa sistematicamente le chiamate di funzione e i comportamenti senza funzione
  • Monitora tasso di successo, latenza e costi in produzione

Metti alla prova le tue conoscenze

Function calling end-to-end: cinque controlli.

1. Quali sono i cinque passaggi del function calling?

Risposta: Definire le funzioni (schemi), fornirle all’API, il modello richiede una chiamata con i suoi argomenti, il tuo codice esegue e restituisce il risultato, il modello produce la risposta finale.

2. Cosa rende buono uno schema di funzione?

Risposta: Tipi rigorosi e descrizioni operative: nome chiaro, quando usarlo, formato di ogni parametro: questo è il testo che il modello legge per decidere e compilare.

3. Cosa abilitano le chiamate parallele?

Risposta: Il modello richiede più funzioni in una singola risposta quando sono indipendenti: meno round trip, a patto di abbinare ogni risultato alla sua chiamata.

4. A cosa serve tool_choice?

Risposta: A impostare la libertà del modello: auto (decide lui), any (deve usare uno strumento) o uno strumento forzato: quest’ultimo è chiave per un’estrazione strutturata affidabile.

5. Quali regole di sicurezza per le funzioni esposte?

Risposta: Valida gli argomenti ricevuti, limita lo scope di ogni funzione, registra le chiamate e mantieni la validazione umana per le azioni di commit: il modello propone, il tuo codice dispone.

I due esempi pratici in questo corso (tracker pagamenti, CRM) applicano esattamente queste regole: le tue integrazioni seguiranno lo stesso stampo.