Output strutturati ed esecuzione del codice
In questa pagina
Aggiornato il 2 novembre 2026. Basato sulla documentazione xAI: con
xai-sdk, gli output strutturati si combinano con gli strumenti creando la conversazione (client.chat.create(..., tools=[code_execution()])), per poi chiamarechat.parse(Schema), che restituisce la risposta e l’oggetto tipizzato; l’esempio precedente chiamavaclient.chat.parse(...)con argomenti Chat Completions, un metodo che non esiste in nessun SDK. Fonti: Structured Outputs · Code Execution.
Esegui codice e struttura i risultati
Combinare gli output strutturati con l’esecuzione del codice permette al modello di calcolare i risultati e restituirli in un formato strutturato. Il modello scrive il codice, lo esegue in un ambiente isolato (sandbox) e formatta l’output secondo il tuo schema.
Funzionalità da Grok 4 in poi
Come per la ricerca web, questa combinazione è riservata ai modelli Grok 4 e successivi, ovvero all’intera gamma attuale (Grok 4.5, Grok 4.3, varianti grok-4.20). I modelli precedenti non supportavano la combinazione di strumenti con output strutturati.
Caso d’uso tipico: calcoli precisi
Il vantaggio principale dell’esecuzione del codice con output strutturati è la precisione di calcolo. Gli LLM commettono regolarmente errori aritmetici. Eseguendo il codice, i risultati sono matematicamente esatti.
from pydantic import BaseModel
from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import code_execution
client = Client() # chiave letta da XAI_API_KEY
class FinancialAnalysis(BaseModel):
total_revenue: float
total_cost: float
gross_margin: float
margin_percentage: float
most_profitable_product: str
least_profitable_product: str
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[code_execution()],
)
chat.append(user("""Ecco le vendite trimestrali:
- Prodotto A: 150 unità a 45 €, costo unitario 28 €
- Prodotto B: 320 unità a 22 €, costo unitario 15 €
- Prodotto C: 85 unità a 120 €, costo unitario 78 €
Calcola l'analisi finanziaria completa."""))
response, parsed = chat.parse(FinancialAnalysis)
print(f"Margine lordo: €{parsed.gross_margin}")
print(f"Margine: {parsed.margin_percentage}%")
print(f"Miglior prodotto: {parsed.most_profitable_product}")
Il modello scriverà uno script Python per eseguire i calcoli, lo eseguirà e formatterà quindi i risultati nello schema FinancialAnalysis.
Esempio: analisi statistica
class DescriptiveStatistics(BaseModel):
mean: float
median: float
std_dev: float
minimum: float
maximum: float
quartile_1: float
quartile_3: float
value_count: int
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[code_execution()],
)
chat.append(user("""Calcola le statistiche descrittive per questi dati:
[23, 45, 12, 67, 34, 89, 56, 78, 41, 33, 61, 25,
72, 48, 55, 39, 64, 71, 28, 50]"""))
response, parsed = chat.parse(DescriptiveStatistics)
print(f"Media: {parsed.mean}")
print(f"Deviazione standard: {parsed.std_dev}")
Combina ricerca web ed esecuzione del codice
Puoi abilitare entrambi gli strumenti simultaneamente:
class MarketAnalysis(BaseModel):
company: str
current_price: float
change_30d: float
avg_volume: float
trend: str
recommendation: str
from xai_sdk.tools import web_search
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[web_search(), code_execution()],
)
chat.append(user("Analizza il titolo Apple negli ultimi 30 giorni"))
response, parsed = chat.parse(MarketAnalysis)
Il modello recupererà i dati recenti dal web, quindi utilizzerà l’esecuzione del codice per calcolare le variazioni e le medie.
Limiti dell’esecuzione del codice
- L’ambiente di esecuzione è isolato ed effimero
- I pacchetti Python comuni sono preinstallati (NumPy, Pandas, Matplotlib, SciPy)
- Il tempo di esecuzione e la memoria sono limitati
- Nessun accesso alla rete dal codice eseguito
- I file creati non persistono tra una chiamata e l’altra
Punti chiave
- L’esecuzione del codice + output strutturati richiede come minimo Grok 4: l’intera gamma attuale è compatibile
- Il modello scrive ed esegue codice per ottenere calcoli precisi
- Abilita lo strumento con
code_execution()nell’SDK xAI, o{"type": "code_interpreter"}nelle API Responses, quindi ottieni l’oggetto tipizzato conchat.parse(Schema) - Combinabile con
web_searchper cercare e poi calcolare - Ideale per analisi finanziarie, statistiche e matematiche
- I risultati calcolati sono esatti, a differenza delle stime degli LLM