Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Utilizzo di client.chat.parse()

Lezione 8 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Il metodo parse(): il cuore degli output strutturati personalizzati
  2. Una chiamata completa end-to-end
  3. Il prompt di sistema aggiunto automaticamente
  4. .parsed contro .content: due usi distinti
  5. Cosa può ancora fallire
  6. Punti chiave

Il metodo parse(): il cuore degli output strutturati personalizzati

client.chat.parse() è l’equivalente strutturato di client.chat.complete(). Invece di restituire testo libero o JSON grezzo che devi analizzare tu stesso, restituisce direttamente un oggetto tipizzato corrispondente al tuo modello Pydantic. La modifica potrebbe sembrare cosmetica, ma elimina effettivamente un intero livello di codice.

Il contrasto è più evidente mettendoli a confronto. Con complete(), recuperi una stringa e la trasformi manualmente. Con parse(), l’oggetto arriva pronto all’uso e il JSON grezzo rimane disponibile se ne hai bisogno.

# Modalità JSON — complete() restituisce testo JSON
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    response_format={"type": "json_object"}
)
raw_json: str = response.choices[0].message.content
data = json.loads(raw_json)  # Analisi manuale

# Personalizzato — parse() restituisce un oggetto tipizzato
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed  # Oggetto Pydantic
raw_json: str = response.choices[0].message.content   # Anche il JSON grezzo è disponibile

La differenza risiede nell’accesso a .parsed: un oggetto Pydantic direttamente utilizzabile con autocompletamento dell’IDE e validazione dei tipi.

Una chiamata completa end-to-end

L’esempio seguente illustra i cinque passaggi di un’estrazione reale: definire lo schema con descrizioni chiare, creare il client, chiamare parse(), utilizzare l’oggetto restituito e recuperare la rappresentazione JSON se necessario.

from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional

# 1. Definire lo schema
class BookInfo(BaseModel):
    title: str = Field(description="Book title")
    authors: list[str] = Field(description="List of authors")
    year: Optional[int] = Field(default=None, description="Publication year")
    genre: str = Field(description="Main literary genre")
    summary: str = Field(description="Summary in 2-3 sentences")

# 2. Creare il client
client = Mistral(api_key="your-api-key")

# 3. Chiamare parse()
response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            "content": "You are an expert librarian. Extract information about the mentioned book."
        },
        {
            "role": "user",
            "content": "I loved '1984' by George Orwell. It's a dystopian novel published in 1949 describing a totalitarian society under constant surveillance."
        }
    ],
    temperature=0
)

# 4. Utilizzare l'oggetto analizzato
book = response.choices[0].message.parsed
print(f"Title: {book.title}")
print(f"Authors: {', '.join(book.authors)}")
print(f"Year: {book.year}")
print(f"Genre: {book.genre}")
print(f"Summary: {book.summary}")

# 5. Il JSON grezzo è anche disponibile
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")

Nota cosa non contiene il prompt di sistema: nessuna descrizione del formato atteso.

Il prompt di sistema aggiunto automaticamente

L’SDK se ne occupa. Quando usi parse(), Mistral aggiunge automaticamente un prefisso al prompt di sistema:

Your output should be an instance of a JSON object following this schema: { ... }

Questo prefisso contiene lo schema JSON generato dal tuo modello Pydantic. Non hai bisogno di descrivere il formato nel tuo prompt: l’SDK lo fa per te. Questo libera il tuo messaggio di sistema affinché faccia ciò che sa fare meglio: fornire contesto aziendale e impostare requisiti di qualità, come la precisione per gli importi o come gestire i dati mancanti.

response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            # Non c'è bisogno di descrivere il formato JSON: è automatico
            # Concentrati su CONTESTO e QUALITÀ
            "content": """You are an expert financial analyst.
Be precise with amounts and percentages.
If data is not available in the text, use null."""
        },
        {"role": "user", "content": report_text}
    ],
    response_format=FinancialReport
)

.parsed contro .content: due usi distinti

L’oggetto tipizzato, accessibile tramite .parsed, è ciò che manipoli nella logica della tua applicazione. Espone attributi con i loro tipi, supporta l’iterazione, si converte in dizionario con model_dump() e si serializza con model_dump_json().

book = response.choices[0].message.parsed

# Accesso tipizzato con autocompletamento IDE
print(book.title)        # str
print(book.authors)      # list[str]
print(book.year)         # Optional[int]

# Iterare sulle liste
for author in book.authors:
    print(f"  - {author}")

# Convertire in dizionario
book_dict = book.model_dump()

# Serializzare in JSON
book_json = book.model_dump_json(indent=2)

Il JSON grezzo, d’altra parte, rimane utile ai confini del sistema: per il logging, l’archiviazione nel database o per passare la risposta così com’è a un’altra API.

raw = response.choices[0].message.content

# Questa è una stringa JSON, utile per:
# - Logging
# - Archiviazione nel database
# - Invio a un'altra API

import json
data = json.loads(raw)

Cosa può ancora fallire

Uno schema garantito non rende il tuo codice immune a tutto. L’API può restituire un errore di rete o di servizio e .parsed può essere None se la risposta è stata interrotta. Il modello seguente gestisce entrambi i casi separatamente: SDKError per l’API, ValidationError per lo schema, e ritenta solo un numero limitato di volte.

from mistralai.client import Mistral
from mistralai.client.errors import SDKError
from pydantic import ValidationError

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

def extract_structured(text: str, schema, max_retries: int = 2):
    """Estrazione strutturata con gestione degli errori."""
    for attempt in range(max_retries + 1):
        try:
            response = client.chat.parse(
                model="mistral-large-latest",
                messages=[
                    {"role": "system", "content": "Extract the requested information."},
                    {"role": "user", "content": text}
                ],
                response_format=schema,
                temperature=0,
                max_tokens=1024
            )

            parsed = response.choices[0].message.parsed
            if parsed is None:
                raise ValueError("Parsed is None—response may be truncated")

            return parsed

        except SDKError as e:
            print(f"API error (attempt {attempt + 1}): {e}")
            if attempt == max_retries:
                raise
        except ValidationError as e:
            print(f"Validation error (attempt {attempt + 1}): {e}")
            if attempt == max_retries:
                raise

# Utilizzo
try:
    book = extract_structured("'The Little Prince' by Saint-Exupéry, 1943", BookInfo)
    print(f"Extracted: {book.title} by {', '.join(book.authors)}")
except Exception as e:
    print(f"Final failure: {e}")

Il riflesso visto con la Modalità JSON si applica ancora qui: una risposta interrotta da max_tokens produce un oggetto incompleto o nullo, e finish_reason te lo indica prima che tu lo scopra più avanti nella pipeline.

response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    max_tokens=256
)

if response.choices[0].finish_reason != "stop":
    print(f"Warning: finish_reason = {response.choices[0].finish_reason}")
    # "length" = risposta troncata, aumentare max_tokens

Punti chiave

  • client.chat.parse() sostituisce client.chat.complete() per gli output strutturati personalizzati
  • .parsed restituisce un oggetto Pydantic tipizzato; .content restituisce JSON grezzo
  • Lo schema viene aggiunto automaticamente al prompt di sistema: non c’è bisogno di descrivere il formato
  • Controlla sempre finish_reason e gestisci gli errori SDKError e ValidationError
  • Usa model_dump() per convertire l’oggetto analizzato in un dizionario Python