Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Formato di risposta manuale

Lezione 5 di 12 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Maggiore controllo con response_format
  2. Flusso di lavoro
  3. Esempio completo
  4. Differenze rispetto a parse()
  5. Analisi senza Pydantic
  6. Quando scegliere response_format
  7. Gestione degli errori
  8. Punti chiave

Maggiore controllo con response_format

Il metodo manuale tramite response_format ti offre il pieno controllo sull’analisi dei dati. A differenza di parse(), che restituisce un oggetto tipizzato, questo approccio restituisce una stringa JSON che devi analizzare tu stesso: il modello Pydantic fornisce solo lo schema (model_json_schema()) ed esegue la validazione successivamente. Scegli questo metodo quando hai bisogno di flessibilità o quando lavori in un ambiente privo di Pydantic.

Flusso di lavoro

Con response_format, il processo si svolge in due fasi:

  1. L’API restituisce il JSON come stringa in response.choices[0].message.content
  2. Analizzi questa stringa utilizzando il metodo di tua scelta

Esempio completo

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI(
    api_key="your-xai-key",
    base_url="https://api.x.ai/v1"
)

class MovieReview(BaseModel):
    title: str
    rating: float
    summary: str
    recommend: bool

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Review the movie Inception"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "movie_review",
            "schema": MovieReview.model_json_schema()
        }
    }
)

# Il contenuto è una stringa JSON
json_string = response.choices[0].message.content
print(type(json_string))  # <class 'str'>
print(json_string)
# {"title": "Inception", "rating": 9.2, "summary": "...", "recommend": true}

# Analisi manuale con Pydantic
parsed = MovieReview.model_validate_json(json_string)
print(parsed.title)  # "Inception"

Differenze rispetto a parse()

Aspettoparse()response_format
Ritorno(Response, ParsedModel)Solo Response
AnalisiAutomaticaManuale
Accesso ai datiparsed.fieldjson.loads() o model_validate_json()
FlessibilitàStandardMassima
Gestione erroriIntegrataTua responsabilità

Analisi senza Pydantic

Non sei obbligato a usare Pydantic per analizzare il risultato. Funziona anche il modulo standard json:

import json

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Analyze this text and extract entities"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "entities",
            "schema": {
                "type": "object",
                "properties": {
                    "people": {
                        "type": "array",
                        "items": { "type": "string" }
                    },
                    "places": {
                        "type": "array",
                        "items": { "type": "string" }
                    }
                }
            }
        }
    }
)

data = json.loads(response.choices[0].message.content)
print(data["people"])  # ["Marie Curie", "Pierre Curie"]
print(data["places"])      # ["Paris", "Warsaw"]

Quando scegliere response_format

response_format è ideale ogni volta che devi visualizzare o ispezionare il JSON prima che diventi un oggetto. Il caso più comune è il logging: in produzione, conservare il JSON grezzo prima della trasformazione è spesso un requisito di audit o di debug, e parse() non ti offre questo punto di intercettazione. Viene poi la questione dello schema: se il contratto della tua interfaccia è uno schema JSON grezzo – condiviso con altri team, generato da uno strumento, versionato indipendentemente dal codice Python – imporlo direttamente è più fedele che ricostruirlo come modello Pydantic. Infine, non tutti i progetti operano nell’ecosistema Pydantic: se la tua validazione passa attraverso un altro framework o attraverso un passaggio di elaborazione intermedio specifico per la tua pipeline, response_format ti consegna il JSON così com’è e ti lascia il controllo su ciò che segue.

Gestione degli errori

Con il metodo manuale, devi gestire tu stesso gli errori di analisi:

import json

try:
    data = json.loads(response.choices[0].message.content)
except json.JSONDecodeError as e:
    print(f"Parsing error: {e}")

In pratica, questo errore non dovrebbe mai verificarsi poiché l’API garantisce un JSON valido. Tuttavia, una gestione difensiva rimane una best practice in produzione.

Punti chiave

  • response_format restituisce una stringa JSON in response.choices[0].message.content
  • L’analisi è tua responsabilità: json.loads(), model_validate_json() o un altro metodo
  • Puoi usare uno schema JSON grezzo invece di un modello Pydantic
  • Maggiore flessibilità rispetto a parse(), ma più codice da scrivere
  • Il JSON restituito è garantito valido: gli errori di analisi non dovrebbero verificarsi