Esecuzione di codice

La funzionalità di esecuzione del codice dell'API Gemini consente al modello di generare ed eseguire codice Python e di apprendere in modo iterativo dai risultati fino a ottenere un output finale. Puoi utilizzare questa funzionalità di esecuzione di codice per creare applicazioni che beneficiano del ragionamento basato su codice e che producono output di testo. Ad esempio, potresti utilizzare l'esecuzione di codice in un'applicazione che risolve equazioni o elabora il testo.

L'API Gemini fornisce l'esecuzione di codice come strumento, in modo simile alla chiamata di funzioni. Dopo aver aggiunto l'esecuzione di codice come strumento, è il modello a decidere quando utilizzarlo.

L'ambiente di esecuzione del codice include le seguenti librerie. Non puoi installare le tue librerie.

Modelli supportati

I seguenti modelli forniscono supporto per l'esecuzione del codice:

Iniziare a utilizzare l'esecuzione di codice

In questa sezione si presuppone che tu abbia completato i passaggi di configurazione e impostazione illustrati nella guida rapida dell'API Gemini.

Attiva l'esecuzione del codice sul modello

Puoi attivare l'esecuzione di codice di base come mostrato di seguito:

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • GENERATE_RESPONSE_METHOD: il tipo di risposta che vuoi che il modello generi. Scegli un metodo che generi la modalità di restituzione della risposta del modello:
    • streamGenerateContent: la risposta viene trasmessa in streaming durante la generazione per ridurre la percezione della latenza da parte di un pubblico di persone.
    • generateContent: la risposta viene restituita dopo essere stata completamente generata.
  • LOCATION: la regione in cui elaborare la richiesta. Le opzioni disponibili includono:

    Fai clic per espandere un elenco parziale delle regioni disponibili

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: il tuo ID progetto.
  • MODEL_ID: l'ID del modello che vuoi utilizzare.
  • ROLE: Il ruolo in una conversazione associato ai contenuti. La specifica di un ruolo è obbligatoria anche nei casi d'uso con un solo turno. I valori accettabili sono:
    • USER: specifica i contenuti inviati da te.
    • MODEL: specifica la risposta del modello.
  • TEXT
     Le istruzioni di testo da includere nel prompt.

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

cat > request.json << 'EOF'
{
  "tools": [{'codeExecution': {}}],
  "contents": {
    "role": "ROLE",
    "parts": { "text": "TEXT" }
  },
}
EOF

Quindi, esegui il seguente comando per inviare la richiesta REST: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"

PowerShell

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente: 

@'
{
  "tools": [{'codeExecution': {}}],
  "contents": {
    "role": "ROLE",
    "parts": { "text": "TEXT" }
  },
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi, esegui il seguente comando per inviare la richiesta REST: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Gen AI SDK for Python

Scopri come installare o aggiornare Gen AI SDK for Python.

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK di IA generativa con Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import (
    HttpOptions,
    Tool,
    ToolCodeExecution,
    GenerateContentConfig,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.0-flash-001"

code_execution_tool = Tool(code_execution=ToolCodeExecution())
response = client.models.generate_content(
    model=model_id,
    contents="Calculate 20th fibonacci number. Then find the nearest palindrome to it.",
    config=GenerateContentConfig(
        tools=[code_execution_tool],
        temperature=0,
    ),
)
print("# Code:")
print(response.executable_code)
print("# Outcome:")
print(response.code_execution_result)

# Example response:
# # Code:
# def fibonacci(n):
#     if n <= 0:
#         return 0
#     elif n == 1:
#         return 1
#     else:
#         a, b = 0, 1
#         for _ in range(2, n + 1):
#             a, b = b, a + b
#         return b
#
# fib_20 = fibonacci(20)
# print(f'{fib_20=}')
#
# # Outcome:
# fib_20=6765

Utilizzare l'esecuzione di codice in chat

Puoi anche utilizzare l'esecuzione di codice all'interno di una chat.

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/test-project/locations/us-central1/publishers/google/models/gemini-2.0-flash-001:generateContent -d \
$'{
    "tools": [{'code_execution': {}}],
    "contents": [
      {
        "role": "user",
        "parts": {
          "text": "Can you print \"Hello world!\"?"
        }
      },
      {
        "role": "model",
        "parts": [
          {
            "text": ""
          },
          {
            "executable_code": {
              "language": "PYTHON",
              "code": "\nprint(\"hello world!\")\n"
            }
          },
          {
            "code_execution_result": {
              "outcome": "OUTCOME_OK",
              "output": "hello world!\n"
            }
          },
          {
            "text": "I have printed \"hello world!\" using the provided python code block. \n"
          }
        ],
      },
      {
        "role": "user",
        "parts": {
          "text": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50."
        }
      }
    ]
  }'

Esecuzione del codice e chiamata di funzione

L'esecuzione del codice e la chiamata di funzioni sono funzionalità simili:

  • L'esecuzione del codice consente al modello di eseguire il codice nel backend dell'API in un ambiente fisso e isolato.
  • La chiamata di funzione ti consente di eseguire le funzioni richieste dal modello in qualsiasi ambiente desideri.

In generale, ti consigliamo di utilizzare l'esecuzione di codice se può gestire il tuo caso d'uso. L'esecuzione di codice è più semplice da utilizzare (basta attivarla) e si risolve in una singola richiesta GenerateContent. La chiamata di funzioni richiede un'altra richiestaGenerateContent per inviare il risultato di ogni chiamata di funzione.

Nella maggior parte dei casi, devi utilizzare la chiamata di funzione se hai funzioni proprie che vuoi eseguire localmente e devi utilizzare l'esecuzione di codice se vuoi che l'API scriva ed esegua il codice Python per te e restituisca il risultato.

Fatturazione

Non sono previsti costi aggiuntivi per l'abilitazione dell'esecuzione di codice dall'API Gemini. Ti verrà addebitato il prezzo corrente dei token di input e di output in base al modello Gemini che utilizzi.

Ecco alcune altre informazioni da conoscere sulla fatturazione per l'esecuzione di codice:

  • Ti viene addebitato un solo importo per i token di input che passi al modello e per i token di input intermedi generati dall'utilizzo dello strumento di esecuzione del codice.
  • Ti vengono addebitati i token di output finali che ti vengono restituiti nella risposta dell'API.

Diagramma del flusso di fatturazione per l&#39;utilizzo dello strumento di esecuzione del codice, come descritto nel testo di seguito.

  • La fatturazione avviene in base alla tariffa corrente dei token di input e di output in base al modello Gemini in uso.
  • Se Gemini utilizza l'esecuzione di codice per generare la risposta, il prompt originale, il codice generato e il risultato del codice eseguito sono etichettati come token intermedi e vengono fatturati come token di input.
  • Gemini genera quindi un riepilogo e restituisce il codice generato, il risultato del codice eseguito e il riepilogo finale. Questi vengono fatturati come token di output.
  • L'API Gemini include un conteggio intermedio dei token nella risposta dell'API, in modo da poter tenere traccia di eventuali token di input aggiuntivi oltre a quelli passati nel prompt iniziale.

Il codice generato può includere output sia di testo che multimodali, come le immagini.

Limitazioni

  • Il modello può solo generare ed eseguire codice. Non può restituire altri elementi come i file multimediali.
  • La funzionalità non supporta l'I/O dei file o i casi d'uso che prevedono output non di testo (ad esempio, grafici di dati o caricamento di un file CSV).
  • L'esecuzione del codice può durare al massimo 30 secondi prima del timeout.
  • In alcuni casi, l'attivazione dell'esecuzione di codice può portare a regressioni in altre aree dell'output del modello (ad esempio, la scrittura di una storia).