Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Esempi pratici della modalità JSON

Lezione 5 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Mettere in pratica la modalità JSON
  2. Estrazione di entità da testo non strutturato
  3. Classificazione dei ticket di supporto
  4. Conversione di una descrizione in una scheda prodotto
  5. Elaborazione di più elementi in una singola chiamata
  6. Punti chiave

Aggiornato il 3 novembre 2026: L’esempio TypeScript importava precedentemente Mistral come esportazione predefinita, ma l’SDK fornisce solo un’esportazione nominata (import { Mistral } from "@mistralai/mistralai"). Inoltre, hardcodedava la chiave API e forzava il tipo di content con !, il che è insufficiente poiché il campo può anche essere una lista di chunk. Verificato tramite compilazione con SDK 3.5.0 e TypeScript 7.0.2. Fonte: Mistral TypeScript SDK.

Mettere in pratica la modalità JSON

Ora sai come abilitare la modalità JSON; vediamo degli esempi concreti. Tre scenari ricorrono costantemente nei progetti reali e ciascuno illustra un modo diverso di sfruttare questa modalità. Il codice è fornito in Python, con gli equivalenti in TypeScript laddove la traduzione non sia immediata.

Estrazione di entità da testo non strutturato

L’estrazione di entità è il caso d’uso più frequente ed economico: un’email commerciale contiene tutti i dettagli di contatto, ma sono sepolti nella firma e nelle formule di cortesia. L’istruzione chiave nell’esempio seguente è l’ultima riga del prompt di sistema: richiedere null per le informazioni mancanti impedisce al modello di inventare un numero di telefono solo per riempire il campo.

from mistralai.client import Mistral
import json

client = Mistral(api_key="your-api-key")

email_text = """
Hello,
I am Marie Dupont, Sales Director at TechVision SAS.
You can reach me at 06 12 34 56 78 or by email at [email protected].
Our headquarters are at 42 rue de la Paix, 75002 Paris.
Best regards,
Marie
"""

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": """Extract contact information from the provided text.
Return a JSON with keys: name, title, company, phone, email, address.
If information is missing, use null."""
        },
        {"role": "user", "content": email_text}
    ],
    response_format={"type": "json_object"},
    temperature=0
)

contact = json.loads(response.choices[0].message.content)
print(f"Name: {contact['name']}")
print(f"Company: {contact['company']}")
print(f"Phone: {contact['phone']}")

Output atteso:

{
  "name": "Marie Dupont",
  "title": "Sales Director",
  "company": "TechVision SAS",
  "phone": "06 12 34 56 78",
  "email": "[email protected]",
  "address": "42 rue de la Paix, 75002 Paris"
}

Classificazione dei ticket di supporto

La classificazione richiede un approccio diverso: invece di lasciare che il modello scelga i propri valori, elenchi i valori consentiti per ogni campo direttamente nel prompt. Questo rende i risultati confrontabili da un ticket all’altro e direttamente utilizzabili per il routing. Nota il passaggio a mistral-small-latest: il triage dei ticket non giustifica l’uso del modello più potente.

tickets = [
    "My payment was charged twice, I demand an immediate refund!",
    "How can I change my password?",
    "Your app crashes every time I open the settings tab.",
]

for ticket in tickets:
    response = client.chat.complete(
        model="mistral-small-latest",
        messages=[
            {
                "role": "system",
                "content": """Classify the support ticket.
Return a JSON with:
- category: "billing", "account", "technical", "feature_request", or "other"
- priority: "low", "medium", "high", or "critical"
- sentiment: "positive", "neutral", or "negative"
- summary: one-sentence summary"""
            },
            {"role": "user", "content": ticket}
        ],
        response_format={"type": "json_object"},
        temperature=0
    )

    result = json.loads(response.choices[0].message.content)
    print(f"Category: {result['category']} | Priority: {result['priority']} | Sentiment: {result['sentiment']}")

Ecco lo stesso classificatore in TypeScript. Il controllo prima di JSON.parse ci ricorda che l’SDK tipizza content come opzionale e come string | ContentChunk[]: solo una stringa può essere analizzata.

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const ticket = "My payment was charged twice!";

const response = await client.chat.complete({
  model: "mistral-small-latest",
  messages: [
    {
      role: "system",
      content: `Classify the support ticket.
Return a JSON with: category, priority, sentiment, summary.`,
    },
    { role: "user", content: ticket },
  ],
  responseFormat: { type: "json_object" },
  temperature: 0,
});

const contenu = response.choices[0]?.message?.content;
if (typeof contenu !== "string") {
  throw new Error("The response does not contain JSON text.");
}
const result = JSON.parse(contenu);
console.log(`Category: ${result.category}`);
console.log(`Priority: ${result.priority}`);

Conversione di una descrizione in una scheda prodotto

Terzo scenario: trasformare un testo marketing in un record pronto per un database. Questo esercizio è più delicato perché i tipi contano: un prezzo deve arrivare come numero, una durata di consegna come due interi e la spedizione gratuita come booleano. Da qui le annotazioni precise nel prompt.

product_text = """
The 16-inch MacBook Pro with M4 Pro chip is available starting at €2,799.
It features 24 GB of unified RAM, a 512 GB SSD, and a Liquid Retina XDR display.
Available in Space Black and Silver. Free delivery within 3-5 days.
"""

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": """Convert the product description into a structured sheet.
JSON with: name, brand, price_eur (number), specs (object with ram_gb, storage_gb, screen),
colors (list), delivery_days_min, delivery_days_max, free_shipping (boolean)."""
        },
        {"role": "user", "content": product_text}
    ],
    response_format={"type": "json_object"},
    temperature=0
)

product = json.loads(response.choices[0].message.content)
print(json.dumps(product, indent=2, ensure_ascii=False))

Risultato:

{
  "name": "MacBook Pro 16-inch",
  "brand": "Apple",
  "price_eur": 2799,
  "specs": {
    "ram_gb": 24,
    "storage_gb": 512,
    "screen": "Liquid Retina XDR"
  },
  "colors": ["Space Black", "Silver"],
  "delivery_days_min": 3,
  "delivery_days_max": 5,
  "free_shipping": true
}

Nota che il brand, Apple, non appare da nessuna parte nel testo sorgente: il modello lo ha dedotto dal nome del prodotto. Questo è un punto di forza per l’arricchimento, ma un rischio da monitorare se richiedi un’estrazione strettamente letterale.

Elaborazione di più elementi in una singola chiamata

Nulla ti obbliga a fare una chiamata per elemento. Chiedendo al modello una lista sotto un’unica chiave, riduci il numero di richieste e, di conseguenza, la latenza cumulativa per compiti brevi come l’analisi delle recensioni. Il punteggio richiesto qui varia da -1.0 a 1.0, una convenzione utile per aggregare i risultati in seguito.

texts = [
    "Excellent product, I recommend it!",
    "Late delivery, damaged product.",
    "Decent for the price, nothing exceptional."
]

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "system",
            "content": "Analyze the sentiment of each review. Return a JSON with a key 'reviews' containing a list of objects {text, sentiment, score}. The score ranges from -1.0 (very negative) to 1.0 (very positive)."
        },
        {"role": "user", "content": "\n---\n".join(texts)}
    ],
    response_format={"type": "json_object"},
    temperature=0
)

reviews = json.loads(response.choices[0].message.content)["reviews"]
for r in reviews:
    print(f"[{r['score']:+.1f}] {r['sentiment']} — {r['text'][:40]}...")

Un dettaglio comune a tutti questi esempi merita enfasi: temperature=0 è sistematico qui. Per i compiti di estrazione e classificazione, la creatività non aggiunge nulla e costa in termini di riproducibilità.

Punti chiave

  • La modalità JSON eccelle nell’estrazione dati, nella classificazione e nella conversione
  • Usa il prompt di sistema per definire la struttura e i tipi attesi
  • temperature=0 garantisce risultati riproducibili
  • L’elaborazione in batch in una singola richiesta è possibile richiedendo una lista JSON
  • Analizza sempre la risposta con json.loads() / JSON.parse() prima di accedere ai dati