Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Ruoli e Messaggi

Lezione 2 di 16 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Il cuore del protocollo conversazionale
  2. I quattro ruoli
  3. Struttura completa di uno scambio multi-turno
  4. Contenuto strutturato
  5. Il flag prefix
  6. Punti chiave

Il cuore del protocollo conversazionale

L’API Chat Completions non accetta testo grezzo. Si aspetta un array di messaggi strutturati, ciascuno assegnato a un ruolo specifico. Questo sistema di ruoli permette al modello di distinguere chi sta parlando, qual è il contesto e come deve rispondere. Lo stesso testo — «Rispondi sempre in JSON» — ha un peso diverso a seconda che arrivi come istruzione dello sviluppatore o come input dell’utente. Padroneggiare questa struttura è ciò che separa un chatbot coerente da un sistema che devia dall’argomento dopo tre scambi.

I quattro ruoli

L’API di Mistral riconosce quattro ruoli distinti, ognuno con una funzione precisa nella conversazione.

Il ruolo system

Il messaggio di sistema definisce il comportamento globale del modello. Posizionato per primo, viene letto prima di qualsiasi scambio. È qui che imposti il tono, i vincoli e il contesto per la tua applicazione. Immagina un assistente progettato per uno studio legale: il messaggio di sistema equivale alla nota informativa che consegneresti a un nuovo associato prima del suo primo caso.

messages = [
    {
        "role": "system",
        "content": "You are a legal assistant specializing in French law. "
                   "Respond precisely and cite relevant legal articles. "
                   "If you are unsure, state it explicitly."
    }
]

Lo sviluppatore gestisce questo messaggio, mai l’utente finale, e non appare mai nell’interfaccia della tua applicazione.

Il ruolo user

Segue il messaggio dell’utente umano: la domanda, l’istruzione o il testo da elaborare. Questa è l’unica parte della conversazione che i tuoi utenti controllano direttamente.

messages.append({
    "role": "user",
    "content": "What are the statutes of limitations in civil law?"
})

Il ruolo assistant

Questo ruolo contiene le risposte precedenti del modello. Diventa essenziale una volta che la conversazione supera un singolo turno. Senza di esso, un utente che chiede «E per i debiti commerciali?» riceverebbe una risposta fuori tema perché il modello non saprebbe di cosa si sta discutendo.

messages.append({
    "role": "assistant",
    "content": "In French civil law, the standard statute of limitations is 5 years..."
})

Il ruolo tool

L’ultimo ruolo entra in gioco durante la chiamata di funzione. Quando il modello richiede l’esecuzione di una funzione esterna — ad esempio interrogare un’API meteo — esegui quella funzione dal tuo lato e restituisci il risultato sotto questo ruolo, facendo riferimento all’ID della chiamata specifica:

messages.append({
    "role": "tool",
    "content": '{"temperature": 22, "city": "Paris"}',
    "tool_call_id": "call_abc123"
})

Struttura completa di uno scambio multi-turno

Vediamo questi ruoli in azione durante una conversazione reale in cui l’utente affina la sua richiesta dopo una risposta iniziale:

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

conversation = [
    {
        "role": "system",
        "content": "You are a French chef. Propose simple and tasty recipes."
    },
    {
        "role": "user",
        "content": "I want to make a dessert with apples."
    }
]

# First turn
response = client.chat.complete(
    model="mistral-large-latest",
    messages=conversation
)

assistant_reply = response.choices[0].message.content
print(assistant_reply)

# Add response to history
conversation.append({"role": "assistant", "content": assistant_reply})

# Second turn
conversation.append({
    "role": "user",
    "content": "Can you adapt this recipe for 8 people?"
})

response = client.chat.complete(
    model="mistral-large-latest",
    messages=conversation
)

print(response.choices[0].message.content)

Nota cosa fa effettivamente questo codice: a ogni turno, invia indietro l’intera cronologia. Il modello non ha memoria persistente tra le richieste. «Questa ricetta» ha senso solo perché la risposta precedente è ancora nell’array. Sei interamente responsabile della gestione dello stato della conversazione.

Contenuto strutturato

Il campo content accetta due forme. La più comune è una semplice stringa. Ma non appena trasmetti qualcosa di diverso dal testo — un’immagine da descrivere, ad esempio — passi a una lista di blocchi tipizzati:

# Simple content (text)
{"role": "user", "content": "Describe this image."}

# Structured content (multimodal)
{"role": "user", "content": [
    {"type": "text", "text": "Describe this image."},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

Il flag prefix

Mistral offre una funzionalità unica: il flag prefix. Scrivi tu stesso l’inizio della risposta dell’assistente e il modello è costretto a continuare da lì. Questo è incredibilmente efficace quando devi analizzare l’output con zero margine di errore.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "system", "content": "You always respond in JSON."},
        {"role": "user", "content": "List 3 European capitals."},
        {"role": "assistant", "content": '{"capitals": [', "prefix": True}
    ]
)

Il modello riprende la generazione dopo {"capitals": [, eliminando immediatamente il rischio di vedere apparire «Certo, ecco il tuo JSON:» prima della parentesi graffa aperta. In produzione, questa garanzia di formato vale spesso più di un’istruzione ripetuta tre volte nel messaggio di sistema.

Adotta subito due abitudini. Mantieni il messaggio di sistema conciso: un paragrafo ben scritto produce risultati migliori di due pagine di regole, parte delle quali il modello finirà per ignorare. E non inventare mai risposte fittizie dell’assistente per guidare il modello, con un’eccezione: il few-shot learning, che affronteremo nella Lezione 10. Per conversazioni lunghe, invia l’intera cronologia, ma monitora la finestra di contesto e pota i turni più vecchi prima di superarla.

Punti chiave

  • Quattro ruoli: system (comportamento), user (richiesta), assistant (risposta), tool (risultato funzione)
  • Il messaggio di sistema va per primo e definisce il quadro dell’applicazione
  • Il modello non ha memoria: invia l’intera cronologia con ogni richiesta
  • Il flag prefix forza l’inizio della risposta per controllare il formato dell’output