Interprete codice

Utilizzare l'interprete di codice per consentire al modello di scrivere ed eseguire codice Python in un contenitore sicuro e isolato. Questo strumento è utile per i calcoli, l'analisi dei dati, l'elaborazione dei file e altre attività complesse di calcolo.

Nota

Lo strumento di interprete del codice OCI utilizza lo stesso formato dello strumento di interprete del codice OpenAI utilizzato con l'API Responses con l'endpoint compatibile con OCI OpenAI. Per i dettagli di sintassi e richiesta, vedere l'argomento Interprete codice nella documentazione OpenAI.

Suggerimento

Nei prompt, fare riferimento all'interprete di codice come strumento python. Ad esempio: Use the python tool to solve the problem.

Poiché il codice viene eseguito in un ambiente isolato senza accesso alla rete esterna, Code Interpreter è una buona opzione quando il flusso di lavoro richiede il calcolo o l'elaborazione dei file in un'impostazione controllata.

Utilizzo di Code Intepreter

Se stai usando questo per la prima volta, pensa a Code Interpreter come a un'area di lavoro Python temporanea per il modello.

È possibile utilizzarlo per task quali:

Risolvere i problemi di matematica
Analisi dei file caricati
Pulizia o trasformazione dei dati
Creazione di grafici o tabelle
Generazione di file di output quali log o set di dati elaborati

Ambiente esecuzione

L'ambiente Python include più di 420 librerie preinstallate, tra cui Pandas, Matplotlib e SciPy, quindi molte attività comuni funzionano senza alcuna configurazione aggiuntiva.

Il codice viene eseguito all'interno di un contenitore sandbox. Questo contenitore è l'ambiente di lavoro in cui viene eseguito Python e in cui i file caricati, i file generati e i dati di lavoro temporanei vengono memorizzati durante la sessione.

Limiti memoria contenitore

I contenitori dell'interprete di codice utilizzano un pool di memoria condivisa di 64 GB per tenancy.

Le dimensioni del contenitore supportate sono:

1 GB
4 GB
16 GB
64 GB

Questo limite condiviso può essere diviso tra più container. Ad esempio, può supportare:

Sessantaquattro contenitori da 1 GB
Sedici contenitori da 4 GB
Quattro contenitori da 16 GB
Un contenitore da 64 GB

Se è necessaria maggiore capacità, è possibile sottomettere una richiesta di servizio.

Scadenza container

Un contenitore scade dopo 20 minuti di inattività.

Questo è importante sapere quando si creano flussi in più fasi:

Impossibile riutilizzare un contenitore scaduto
Creare un nuovo contenitore
Se necessario, è necessario caricare di nuovo i file
Lo stato in memoria, come le variabili Python e gli oggetti Python, viene perso

Per questo motivo, è meglio trattare i container come ambienti di lavoro temporanei.

Esempio

Per utilizzare Code Interpreter, aggiungere una definizione di strumento nella proprietà tools con "type": "code_interpreter".

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    tools=[
        {
            "type": "code_interpreter",
            "container": {"type": "auto"}
        }
    ],
    instructions="Use the python tool to solve the problem and explain the result.",
    input="Find the value of (18 / 3) + 7 * 2."
)

print(response.output_text)

In questo esempio, lo strumento python è Code Interpreter.

Container per interprete codice

Lo strumento Interprete codice richiede un oggetto contenitore. Il contenitore è l'ambiente isolato in cui il modello esegue il codice Python.

Un contenitore può contenere:

File caricati
File creati dal modello
Dati di lavoro temporanei durante l'esecuzione

Quando si utilizza Code Interpreter, è possibile utilizzare una delle due modalità contenitore riportate di seguito.

auto: OCI Generative AI esegue il provisioning o riutilizza un contenitore nel contesto corrente.
OCID contenitore: si crea il contenitore personalmente, si definisce la dimensione della memoria e si fornisce l'OCID.

Per entrambe le opzioni, i container vengono creati e gestiti in OCI Generative AI. Il codice che viene eseguito in tali contenitori viene eseguito anche nella tenancy OCI Generative AI.

Nota

Lo strumento di interprete del codice OCI utilizza lo stesso formato dello strumento di interprete del codice OpenAI utilizzato con l'API Responses con l'endpoint compatibile con OCI OpenAI. Per i dettagli sulla sintassi e sulle richieste, consulta Containers for Code Intepreters e la documentazione dell'API OpenAI Containers.

Modalità automatica

In modalità automatica, il servizio esegue il provisioning o riutilizza automaticamente il contenitore. Questa è l'opzione più semplice e un buon punto di partenza per la maggior parte degli utenti.

Utilizza la modalità automatica quando:

Si desidera che OCI Generative AI gestisca il contenitore
Non hai bisogno di un controllo diretto sull'ambiente
Vuoi un setup più semplice

Se si desidera, è possibile specificare memory_limit. Se non viene specificato, il valore predefinito è 1 GB.

response = client.responses.create(
    model="xai.grok-code-fast-1",
    tools=[{
        "type": "code_interpreter",
        "container": {
            "type": "auto",
            "memory_limit": "1g"
        }
    }],
    input="Use the python tool to calculate the mean, median, and standard deviation of 12, 18, 24, 30, and 42."
)

Modalità esplicita

In modalità esplicita, si crea prima il contenitore e si imposta la dimensione. Passare quindi l'ID contenitore nella richiesta.

Utilizzare la modalità esplicita quando si desidera un maggiore controllo sulle impostazioni del contenitore, ad esempio le dimensioni della memoria, o quando si desidera mantenere una sessione dedicata.

container = client.containers.create(name="test-container", memory_limit="4g")

response = client.responses.create(
    model="xai.grok-code-fast-1",
    tools=[{
        "type": "code_interpreter",
        "container": container.id
    }],
    tool_choice="required",
    input="Use the python tool to calculate the mean, median, and standard deviation of 12, 18, 24, 30, and 42."
)

print(response.output_text)

File nell'interprete di codice

Code Interpreter supporta l'interazione dinamica dei file durante la durata del contenitore. Il modello può leggere i file forniti e può anche creare nuovi file.

Ciò è utile per flussi di lavoro quali:

Lettura di un file CSV o PDF
Generazione di un grafico
Salvataggio dell'output elaborato
Creazione di log o report

Riferimento API: documentazione API OpenAI Container Files e API Container Files.

Persistenza file

I file creati o aggiornati dallo strumento python persistono tra i cicli di esecuzione del codice nello stesso contenitore, purché il contenitore non sia scaduto.

Ciò significa che il modello può basarsi su lavori precedenti nella stessa sessione. Ad esempio, può:

Leggi file
Analizzalo
Salva un grafico
Utilizzare il grafico più tardi nello stesso contenitore

Alla scadenza del contenitore, lo stato non è più disponibile.

Caricamento e gestione dei file

È possibile gestire i file contenitore tramite le API Container Files.

Le operazioni comuni includono:

Crea file contenitore: consente di aggiungere un file al contenitore mediante caricamento multiparte o facendo riferimento a un ID /v1/files esistente.
Elenca file contenitore: consente di visualizzare i file nel contenitore
Elimina file contenitore: rimuovere un file
Recupera contenuto file contenitore: scaricare un file dal contenitore.

Ciò consente di utilizzare il contenitore come area di lavoro temporanea per l'esecuzione del codice basata su modelli.

File di output e citazioni

Quando il modello crea i file, tali file vengono memorizzati nel contenitore e possono essere restituiti come annotazioni nella risposta.

Queste annotazioni possono includere:

container_id
file_id
filename

È possibile utilizzare questi valori per recuperare il contenuto del file generato.

La risposta può includere un oggetto container_file_citation che identifica il file generato. Utilizzare l'operazione Recupera contenuto file contenitore per scaricare il file.

L'API OCI Responses supporta endpoint compatibili con OpenAI per funzioni quali Risposte, File, Container e File contenitore. È possibile utilizzare la documentazione OpenAI correlata come riferimento per la struttura delle richieste, i formati di risposta e i flussi di lavoro generali. Quando si utilizzano queste API con OCI, inviare richieste agli endpoint di inferenza dell'AI generativa OCI, utilizzare l'autenticazione OCI e notare che le risorse e l'esecuzione rimangono nell'AI generativa OCI, non in una tenancy OpenAI.

Nota

L'API File OCI utilizza lo stesso formato dell'API File OpenAI con l'endpoint compatibile con OCI OpenAI. Per i dettagli di sintassi e richiesta, consulta la documentazione API OpenAI Files.