Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Code Interpreter: esegui codice nell'API

Lezione 10 di 20 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Code Interpreter: esegui codice nell’API
  2. Abilita Code Interpreter
  3. Ispeziona il codice eseguito
  4. Fornisci file come input
  5. Recupera i file generati
  6. Container e ambiente
  7. Catena più esecuzioni
  8. Combina con altri strumenti
  9. Pattern: pipeline di analisi completa
  10. Punti chiave

Aggiornato il 2 novembre 2026 sulla base della guida ufficiale di Code Interpreter e dell’SDK openai: lo strumento richiede un parametro container (mancante in tutti gli esempi precedenti, che avrebbero fallito), i file generati appaiono nelle annotazioni container_file_citation e vengono scaricati tramite le API dei Container (non client.files.content), e gli output delle chiamate sono denominati outputs (non results). Le parti di testo in input usano il tipo input_text. I file allegati a un messaggio vengono caricati con lo scopo user_data, raccomandato da OpenAI per gli input del modello (File inputs). Fonti: Code Interpreter · File inputs.

Code Interpreter: esegui codice nell’API

Un modello linguistico prevede testo; non esegue calcoli. Chiedigli la radice quadrata di 1764 e produrrà il risultato più probabile basato sul suo addestramento: spesso corretto, a volte errato, senza modo di distinguere le due casistiche. Code Interpreter elimina questa incertezza fornendo al modello un interprete Python: scrive il calcolo, lo esegue e restituisce un risultato ottenuto, non un’ipotesi.

Il cambiamento è più profondo di quanto sembri. Il modello vede l’output del proprio codice, inclusi gli errori, quindi può correggersi e riprovare. Su un file dati di cui nessuno conosce la struttura esatta, questo ciclo batte qualsiasi istruzione pre-scritta.

Abilita Code Interpreter

Lo abiliti aggiungendo lo strumento all’array tools: nulla da installare, nessun ambiente da provisioningare. Il modello decide quando scrivere codice: risponde direttamente alle domande fattuali, ma passa all’esecuzione per calcoli o manipolazione dei dati.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Calcola la sequenza di Fibonacci fino al 20° termine",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

print(response.output_text)

Il modello scrive il codice Python, lo esegue in una sandbox e integra i risultati nella sua risposta.

Ispeziona il codice eseguito

Prendi l’abitudine di leggere questo codice, almeno durante lo sviluppo. È l’unico modo per distinguere un buon risultato da uno giusto per caso: una media calcolata ignorando silenziosamente i valori mancanti è numericamente corretta ma analiticamente falsa. La risposta non te lo dirà; il codice sì.

La risposta contiene il codice generato e i suoi risultati:

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Qual è la radice quadrata di 1764? Verifica elevando il risultato al quadrato.",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
    include=["code_interpreter_call.outputs"],  # per ricevere log e immagini prodotti
)

for item in response.output:
    if item.type == "code_interpreter_call":
        print("--- Codice Eseguito ---")
        print(item.code)
        print("--- Output ---")
        for output in item.outputs or []:
            print(output.logs if output.type == "logs" else output.url)

Fornisci file come input

Lo strumento offre il suo massimo valore quando lavora con i file. Carichi il file, lo riferisci nella chiamata e il modello lo apre effettivamente: legge le colonne reali, i tipi reali e gli outlier reali, invece di ragionare su una descrizione che potresti aver fornito.

# Carica il file
with open("sales_2025.csv", "rb") as f:
    file_obj = client.files.create(file=f, purpose="user_data")

# Usa Code Interpreter con il file
response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Analizza questo file di vendite. "
                 "Dammi il totale per categoria e il mese con le migliori prestazioni."},
                {"type": "input_file", "file_id": file_obj.id}
            ]
        }
    ],
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

print(response.output_text)

Recupera i file generati

Funziona anche il percorso inverso: il codice produce un CSV pulito, un grafico o una cartella di lavoro Excel, e questi file ti vengono restituiti. Rimangono nel container e il messaggio di risposta li cita nelle sue annotazioni di tipo container_file_citation, includendo l’ID del container, l’ID del file e il nome del file. Puoi quindi scaricarli tramite le API dei Container. Due piccole funzioni, riutilizzate nelle lezioni successive, incapsulano questo flusso:

def generated_files(response):
    """File creati da Code Interpreter, citati nelle annotazioni dei messaggi."""
    for item in response.output:
        if item.type == "message":
            for part in item.content:
                for ann in getattr(part, "annotations", None) or []:
                    if ann.type == "container_file_citation":
                        yield ann


def download(client, ann, path):
    """Scarica un file dal container e restituisce il suo percorso locale."""
    content = client.containers.files.content.retrieve(ann.file_id, container_id=ann.container_id)
    with open(path, "wb") as out:
        out.write(content.read())
    return path

I file che fornisci come input (input_file) vengono copiati automaticamente nel container: non devi caricare nient’altro.

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Crea un grafico delle vendite per mese "
                 "ed esporta i dati puliti come CSV."},
                {"type": "input_file", "file_id": file_obj.id}
            ]
        }
    ],
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

# Recupera i file generati
for ann in generated_files(response):
    print(f"File generato: {ann.filename}")
    download(client, ann, ann.filename)

Container e ambiente

Conoscere le regole del container ti fa risparmiare tempo nel debug di ciò che non può funzionare. Secondo la documentazione di OpenAI:

  • è una macchina virtuale completamente isolata (sandbox) in cui il modello esegue Python;
  • lo strumento richiede un parametro container: {"type": "auto"} crea un container (o ne riutilizza uno da una chiamata precedente presente nel contesto), mentre un ID ottenuto tramite client.containers.create(...) forza un container specifico;
  • la memoria è impostata con memory_limit: 1g (default), 4g, 16g o 64g, con livelli superiori fatturati alle tariffe degli strumenti integrati;
  • un container scade dopo 20 minuti di inattività; i suoi dati vengono quindi persi, quindi scarica eventuali file che vuoi conservare mentre è attivo.

Non contare sull’accesso alla rete dal codice: fornisci i dati come input o delega la ricerca allo strumento Web Search.

# Esempio: il modello può usare pandas direttamente
response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Carica questo CSV con pandas, "
                 "calcola le statistiche descrittive e identifica gli outlier."},
                {"type": "input_file", "file_id": file_obj.id}
            ]
        }
    ],
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

Catena più esecuzioni

Le esecuzioni successive condividono la stessa sessione: variabili, DataFrame e importazioni dal primo blocco rimangono disponibili nel successivo, esattamente come in un notebook. Il modello ne sfrutta naturalmente le potenzialità: carica, ispeziona, poi elabora, rendendo possibile un’analisi multi-step senza ricaricare tutto a ogni fase.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="1. Genera 1000 punti casuali da una distribuzione normale. "
          "2. Calcola media e deviazione standard. "
          "3. Crea un istogramma. "
          "4. Esegui un test di normalità di Shapiro-Wilk.",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

# Il modello esegue 4 blocchi di codice in sequenza
# Ogni blocco ha accesso alle variabili di quelli precedenti

Combina con altri strumenti

La combinazione più utile abbina una fonte dati alla capacità di elaborarla: File Search trova il passaggio rilevante nei tuoi documenti, Web Search porta dati di mercato e Code Interpreter confronta i due in una tabella o in un grafico. Nessuno di questi strumenti può svolgere il lavoro degli altri.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Cerca sul web i dati del PIL francese degli ultimi 10 anni, "
          "poi crea un grafico di tendenza con una regressione lineare.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter", "container": {"type": "auto"}}
    ]
)

Pattern: pipeline di analisi completa

L’esempio finale concatena tutto quanto sopra in un caso realistico: un file di input, un’analisi multi-step e deliverable in output. Concentrati soprattutto sul formato del prompt: numerato, esplicito sull’output atteso, perché è quello, ben più del codice Python che lo accompagna, a determinare la qualità del risultato.

def analyze_data(file_path: str, questions: list[str]) -> dict:
    """Pipeline di analisi dati con Code Interpreter."""
    # Caricamento
    with open(file_path, "rb") as f:
        file_obj = client.files.create(file=f, purpose="user_data")

    results = {}

    for question in questions:
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=[
                {
                    "role": "user",
                    "content": [
                        {"type": "input_text", "text": question},
                        {"type": "input_file", "file_id": file_obj.id}
                    ]
                }
            ],
            tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
            instructions="Scrivi codice Python pulito e commentato. "
                        "Mostra i risultati intermedi."
        )

        results[question] = response.output_text

    return results

# Utilizzo
results = analyze_data("sales.csv", [
    "Fornisci le statistiche descrittive per ogni colonna numerica",
    "Quali sono i 5 prodotti più venduti?",
    "C'è stagionalità nelle vendite?"
])

Punti chiave

  • Code Interpreter esegue Python in un container isolato; il parametro container è obbligatorio ({"type": "auto"} o un ID)
  • I file forniti come input_file vengono copiati automaticamente nel container
  • I file generati sono citati come container_file_citation e scaricati tramite client.containers.files.content.retrieve
  • Un container scade dopo 20 minuti di inattività: scarica ciò che vuoi conservare
  • Combinalo con Web Search e File Search per un’analisi arricchita