Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Attivare la modalità JSON

Lezione 4 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Come funziona la modalità JSON
  2. Abilitazione in Python
  3. Abilitazione in TypeScript
  4. Le istruzioni esplicite non sono opzionali
  5. Spostare le istruzioni di formato nel prompt di sistema
  6. Analisi della risposta
  7. Punti chiave

Aggiornato il 3 novembre 2026: Gli esempi TypeScript importavano precedentemente Mistral come esportazione predefinita (import Mistral from …), ma l’SDK fornisce solo un’esportazione nominata: import { Mistral } from "@mistralai/mistralai". Inoltre, passavano direttamente a JSON.parse un contenuto tipizzato come string | 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() (non parse())
  • Istruisci sempre il modello nel prompt riguardo alla struttura JSON attesa
  • La risposta è una stringa JSON: analizzala con json.loads() o JSON.parse()
  • Inserisci le istruzioni di formato nel prompt di sistema per pipeline ripetitive