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'esecuzione di codice è disponibile sia in Vertex AI Studio sia nell'API Gemini. In Vertex AI Studio, puoi attivare l'esecuzione del codice in Impostazioni avanzate. L'API Gemini fornisce l'esecuzione di codice come strumento, in modo simile alla chiamata di funzione. 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

L'esecuzione del codice è supportata dal modello gemini-2.0-flash-exp.

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 accettati 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/v1beta1/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/v1beta1/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.

Python

from google import genai
from google.genai.types import Tool, ToolCodeExecution, GenerateContentConfig

client = genai.Client()
model_id = "gemini-2.0-flash-exp"

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,
    ),
)
for part in response.candidates[0].content.parts:
    if part.executable_code:
        print(part.executable_code)
    if part.code_execution_result:
        print(part.code_execution_result)
# Example response:
# code='...' language='PYTHON'
# outcome='OUTCOME_OK' output='The 20th Fibonacci number is: 6765\n'
# code='...' language='PYTHON'
# outcome='OUTCOME_OK' output='Lower Palindrome: 6666\nHigher Palindrome: 6776\nNearest Palindrome to 6765: 6776\n'

Vai

import (
  "bytes"
  "context"
  "flag"
  "fmt"
  "io"

  genai "google.golang.org/genai"
)

// codeExecution generates code for the given text prompt using Code Execution as a Tool.
func codeExecution(w io.Writer) error {
  modelName := "gemini-2.0-flash-exp"
  client, err := genai.NewClient(context.TODO(), &genai.ClientConfig{})
  if err != nil {
    return fmt.Errorf("NewClient: %w", err)
  }

  codeExecTool := genai.Tool{
    CodeExecution: &genai.ToolCodeExecution{},
  }
  config := &genai.GenerateContentConfig{
    Tools: []*genai.Tool{&codeExecTool},
  }

  textpart := genai.Text(`Calculate 20th fibonacci number. Then find the nearest palindrome to it.`)

  result, err := client.Models.GenerateContent(context.TODO(), modelName,
    &genai.ContentParts{textpart}, config)
  if err != nil {
    return fmt.Errorf("GenerateContent: %w", err)
  }

  for _, part := range result.Candidates[0].Content.Parts {
    if part.ExecutableCode != nil {
      fmt.Fprintf(w, "Code (%s):\n%s\n", part.ExecutableCode.Language, part.ExecutableCode.Code)
    }
    if part.CodeExecutionResult != nil {
      fmt.Fprintf(w, "Result (%s):\n %s\n", part.CodeExecutionResult.Outcome, part.CodeExecutionResult.Output)
    }
  }
  return nil
}

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/v1beta1/projects/test-project/locations/us-central1/publishers/google/models/gemini-2.0-flash-exp: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, con un solo addebito. La chiamata di funzione richiede un'ulteriore richiesta GenerateContent per inviare nuovamente l'output di ogni chiamata di funzione, con conseguente addebito di più importi.

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 costo alla tariffa corrente dei caratteri di input e output.

Di seguito sono riportate altre informazioni sulla fatturazione per l'esecuzione di codice:

  • Ti viene addebitato un solo importo per i token di input che passi al modello e un altro per i token di output finali che ti vengono restituiti dal modello.
  • I token che rappresentano il codice generato vengono conteggiati come token di output.
  • Anche i risultati dell'esecuzione del codice vengono conteggiati come token di output.

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 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).