Formato di risposta manuale
In questa pagina
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:
- L’API restituisce il JSON come stringa in
response.choices[0].message.content - 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()
| Aspetto | parse() | response_format |
|---|---|---|
| Ritorno | (Response, ParsedModel) | Solo Response |
| Analisi | Automatica | Manuale |
| Accesso ai dati | parsed.field | json.loads() o model_validate_json() |
| Flessibilità | Standard | Massima |
| Gestione errori | Integrata | Tua 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_formatrestituisce una stringa JSON inresponse.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