Attivare la modalità JSON
In questa pagina
Aggiornato il 3 novembre 2026: Gli esempi TypeScript importavano precedentemente
Mistralcome esportazione predefinita (import Mistral from …), ma l’SDK fornisce solo un’esportazione nominata:import { Mistral } from "@mistralai/mistralai". Inoltre, passavano direttamente aJSON.parseun contenuto tipizzato comestring | ContentChunk[]e hardcodedavano la chiave API nel codice sorgente. Verificato tramite compilazione con SDK 3.5.0 e TypeScript 7.0.2. Fonte: Mistral TypeScript SDK.
Come funziona la modalità JSON
La modalità JSON è il meccanismo più semplice per ottenere un output strutturato da Mistral. Abilitando un singolo parametro, garantisci che la risposta del modello sia un JSON valido. Nessuno schema da definire, nessun modello di dati da scrivere: solo JSON sintatticamente corretto a ogni chiamata.
Abilitazione in Python
Abiliti questa funzionalità tramite il parametro response_format nel metodo client.chat.complete(). Nota che il prompt stesso deve descrivere la struttura attesa: spiegheremo a breve perché questo non è opzionale.
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": "Descrivi i 3 principali vantaggi del cloud computing. Restituisci il risultato come JSON con una chiave 'advantages' contenente una lista di oggetti con 'title' e 'description'."
}
],
response_format={"type": "json_object"}
)
print(response.choices[0].message.content)
L’output sarà un JSON valido, pronto all’uso così com’è:
{
"advantages": [
{
"title": "Scalabilità",
"description": "Adattamento dinamico delle risorse in base alla domanda."
},
{
"title": "Riduzione dei costi",
"description": "Nessun investimento richiesto in infrastrutture fisiche."
},
{
"title": "Accessibilità",
"description": "Accesso ai servizi da qualsiasi luogo."
}
]
}
Abilitazione in TypeScript
L’SDK TypeScript segue esattamente la stessa logica, con la nomenclatura camelCase: il parametro è responseFormat e l’analisi utilizza JSON.parse(). Si applica un’ulteriore precauzione: l’SDK tipizza content come string | ContentChunk[], quindi JSON.parse accetterà il valore solo dopo aver verificato che sia effettivamente una stringa.
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const response = await client.chat.complete({
model: "mistral-large-latest",
messages: [
{
role: "user",
content: "Elenca 3 framework JavaScript popolari in JSON con 'name' e 'useCase'."
}
],
responseFormat: { type: "json_object" },
});
const contenu = response.choices[0]?.message?.content;
if (typeof contenu !== "string") {
throw new Error("Response does not contain JSON text.");
}
const data = JSON.parse(contenu);
console.log(data);
Le istruzioni esplicite non sono opzionali
Ecco il punto che molti sviluppatori trascurano, e la ragione della maggior parte delle delusioni con la modalità JSON: abilitare il parametro non è sufficiente. La modalità garantisce la sintassi, non il contenuto. Devi istruire esplicitamente il modello, all’interno del prompt, riguardo al formato che ti aspetti.
Confronta le seguenti due chiamate. Nella prima, non viene fornita alcuna guida strutturale: il modello produrrà JSON, ma le chiavi, i loro nomi e la loro nidificazione varieranno da chiamata a chiamata, lasciando il tuo codice a valle senza punti di ancoraggio stabili.
# Cattiva pratica: nessuna istruzione JSON nel prompt
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "user", "content": "Quali sono i vantaggi del cloud?"}
],
response_format={"type": "json_object"}
)
# Il modello produrrà JSON, ma la struttura sarà imprevedibile
Nella seconda, uno scheletro strutturale viene inserito direttamente nel prompt. Il modello ha ora un obiettivo da imitare, rendendo l’output prevedibile tra le chiamate.
# Buona pratica: istruzione chiara nel prompt
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": """Quali sono i vantaggi del cloud computing?
Restituisci la tua risposta in JSON con la seguente struttura:
{
"topic": "string",
"advantages": [
{"title": "string", "description": "string"}
]
}"""
}
],
response_format={"type": "json_object"}
)
Includere un esempio di struttura nel tuo prompt guida il modello verso il formato desiderato. Non è una garanzia assoluta come gli Output Strutturati Personalizzati, ma è più che sufficiente per la maggior parte dei casi d’uso.
Spostare le istruzioni di formato nel prompt di sistema
Una volta che lo stesso elaborazione si ripete su centinaia di input, lasciare le istruzioni di formato nel messaggio dell’utente diventa ingestibile: le copi a ogni chiamata e si mescolano con il contenuto da elaborare. Spostale invece nel prompt di sistema.
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Sei un assistente per l'estrazione di dati. Restituisci SEMPRE le tue risposte in JSON con le chiavi 'entities', 'confidence' e 'source'."
},
{
"role": "user",
"content": "Estrai informazioni da questo testo: 'Acme Corp, fondata nel 2019 a Lione, impiega 250 persone.'"
}
],
response_format={"type": "json_object"}
)
Questa separazione—istruzioni di formato gestite dal ruolo system e contenuto da elaborare gestito dal ruolo user—rende il tuo codice significativamente più manutenibile: cambiare il formato avviene in un unico punto.
Analisi della risposta
Un’ultima abitudine da acquisire: la risposta della modalità JSON è sempre una stringa JSON all’interno di message.content, mai un oggetto. L’analisi è tua responsabilità, in entrambi i linguaggi.
import json
raw = response.choices[0].message.content
data = json.loads(raw)
# Accesso ai dati
for advantage in data["advantages"]:
print(f"- {advantage['title']}: {advantage['description']}")
const contenu = response.choices[0]?.message?.content;
if (typeof contenu !== "string") {
throw new Error("Response does not contain JSON text.");
}
const data = JSON.parse(contenu);
data.advantages.forEach((adv: any) => {
console.log(`- ${adv.title}: ${adv.description}`);
});
Punti chiave
- Abilita la modalità JSON con
response_format: {"type": "json_object"} - Usa
client.chat.complete()(nonparse()) - Istruisci sempre il modello nel prompt riguardo alla struttura JSON attesa
- La risposta è una stringa JSON: analizzala con
json.loads()oJSON.parse() - Inserisci le istruzioni di formato nel prompt di sistema per pipeline ripetitive