Esecuzione del 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 del codice per creare applicazioni che sfruttano il ragionamento basato sul codice e che producono output di testo. Ad esempio, potresti utilizzare l'esecuzione del codice in un'applicazione che risolve equazioni o elabora testo.

L'API Gemini fornisce l'esecuzione del codice come strumento, in modo simile a chiamata di funzione. Dopo aver aggiunto l'esecuzione del codice come strumento, il modello decide 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:

Anteprima di Gemini 3.1 Flash-Lite
Gemini 3.1 Pro anteprima
Anteprima di Gemini 3 Flash
Anteprima di Gemini 3 Pro
Gemini 2.5 Pro
Anteprima di Gemini 2.5 Flash
Gemini 2.5 Flash-Lite Anteprima
Gemini 2.5 Flash
Gemini 2.5 Flash-Lite
Gemini 2.0 Flash con l'API Gemini Live anteprima

Inizia a utilizzare l'esecuzione del codice

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

Abilita l'esecuzione del codice

Puoi consentire al modello di utilizzare l'esecuzione del codice aggiungendolo all'elenco tools durante la configurazione del modello:

Python

Installa

pip install --upgrade google-genai

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

Imposta le variabili di ambiente per utilizzare l'SDK Gen AI 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=global
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.5-flash"

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

Go

Scopri come installare o aggiornare Go.

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

Imposta le variabili di ambiente per utilizzare l'SDK Gen AI 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=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithCodeExec shows how to generate text using the code execution tool.
func generateWithCodeExec(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	prompt := "Calculate 20th fibonacci number. Then find the nearest palindrome to it."
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: prompt},
		},
			Role: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{CodeExecution: &genai.ToolCodeExecution{}},
		},
		Temperature: genai.Ptr(float32(0.0)),
	}
	modelName := "gemini-2.5-flash"

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

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

	// Example response:
	// Gemini: Okay, I can do that. First, I'll calculate the 20th Fibonacci number. Then, I need ...
	//
	// Language: PYTHON
	//
	// def fibonacci(n):
	//    ...
	//
	// fib_20 = fibonacci(20)
	// print(f'{fib_20=}')
	//
	// Outcome: OUTCOME_OK
	// fib_20=6765
	//
	// Now that I have the 20th Fibonacci number (6765), I need to find the nearest palindrome. ...
	// ...

	return nil
}

Node.js

Installa

npm install @google/genai

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

Imposta le variabili di ambiente per utilizzare l'SDK Gen AI 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=global
export GOOGLE_GENAI_USE_VERTEXAI=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateAndExecuteCode(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents:
      'Calculate 20th fibonacci number. Then find the nearest palindrome to it.',
    config: {
      tools: [{codeExecution: {}}],
      temperature: 0,
    },
  });

  console.debug(response.executableCode);

  // Example response:
  // Code:
  // function fibonacci(n) {
  //   if (n <= 0) {
  //     return 0;
  //   } else if (n === 1) {
  //     return 1;
  //   } else {
  //     let a = 0, b = 1;
  //     for (let i = 2; i <= n; i++) {
  //       [a, b] = [b, a + b];
  //     }
  //     return b;
  //   }
  // }
  //
  // const fib20 = fibonacci(20);
  // console.log(`fib20=${fib20}`);

  console.debug(response.codeExecutionResult);

  // Outcome:
  // fib20=6765

  return response.codeExecutionResult;
}

Java

Scopri come installare o aggiornare Java.

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

Imposta le variabili di ambiente per utilizzare l'SDK Gen AI 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=global
export GOOGLE_GENAI_USE_VERTEXAI=True


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Tool;
import com.google.genai.types.ToolCodeExecution;

public class ToolsCodeExecWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates text using the Code Execution tool
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Create a GenerateContentConfig and set codeExecution tool
      GenerateContentConfig contentConfig =
          GenerateContentConfig.builder()
              .tools(Tool.builder().codeExecution(ToolCodeExecution.builder().build()).build())
              .temperature(0.0F)
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              modelId,
              "Calculate 20th fibonacci number. Then find the nearest palindrome to it.",
              contentConfig);

      System.out.println("Code: \n" + response.executableCode());
      System.out.println("Outcome: \n" + response.codeExecutionResult());
      // Example response
      // Code:
      // def fibonacci(n):
      //    if n <= 0:
      //        return 0
      //    elif n == 1:
      //        return 1
      //    else:
      //        a, b = 1, 1
      //        for _ in range(2, n):
      //            a, b = b, a + b
      //        return b
      //
      // fib_20 = fibonacci(20)
      // print(f'{fib_20=}')
      //
      // Outcome:
      // fib_20=6765
      return response.executableCode();
    }
  }
}

REST

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

GENERATE_RESPONSE_METHOD: il tipo di risposta che vuoi che il modello generi. Scegli un metodo che generi il modo in cui vuoi che venga restituita la risposta del modello:
- streamGenerateContent: la risposta viene trasmessa in streaming durante la generazione per ridurre la percezione della latenza per un pubblico umano.
- generateContent: la risposta viene restituita dopo essere stata generata completamente.
LOCATION: la regione in cui elaborare la richiesta. Le opzioni disponibili includono le seguenti:
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 modello del modello che vuoi utilizzare.
ROLE: Il ruolo in una conversazione associata ai contenuti. La specifica di un ruolo è obbligatoria anche nei casi d'uso a turno singolo. I valori accettabili includono i seguenti:
- 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 di queste opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui il seguente 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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui il seguente 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.

Risposta

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Okay, I understand. You want me to calculate the sum of the first 10 positive integers and to use code to do so. Here's my plan: I will use a loop to add the numbers from 1 to 10 and then return the final sum.\n\n"
          },
          {
            "executableCode": {
              "language": "PYTHON",
              "code": "\ntotal = 0\nfor i in range(1, 11):\n    total += i\nprint(f'{total=}')\n"
            }
          },
          {
            "codeExecutionResult": {
              "outcome": "OUTCOME_OK",
              "output": "total=55\n"
            }
          },
          {
            "text": "The sum of the first 10 positive numbers is 55.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.19436789,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.17441037
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.0685376,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.14903527
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.23231025,
          "severity": "HARM_SEVERITY_LOW",
          "severityScore": 0.2436427
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08269742,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.10818888
        }
      ],
      "score": -0.50845032930374146,
      "avgLogprobs": -0.0046222757209431042
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 34,
    "candidatesTokenCount": 110,
    "totalTokenCount": 144,
    "billablePromptUsage": {
      "textCount": 119
    },
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2024-12-09T23:33:47.842964Z",
  "responseId": "W35XZ9S5M6acmecP3vDFkQU"
}

Utilizza l'esecuzione del codice in chat

Puoi anche utilizzare l'esecuzione del codice come parte di una chat.

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/test-project/locations/global/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."
        }
      }
    ]
  }'

(Solo Gemini 3 Flash) Utilizza l'esecuzione del codice con le immagini

Gemini 3 Flash può scrivere ed eseguire codice Python per manipolare e ispezionare attivamente le immagini. Puoi utilizzare l'esecuzione del codice con le immagini per:

Ingrandire e ispezionare le immagini: rileva quando i dettagli sono troppo piccoli (ad esempio, la lettura di un indicatore lontano dalla fotocamera) e scrivi codice per ritagliare e riesaminare l'area a una risoluzione più alta.

Nota: il modello scrive automaticamente il codice per ingrandire i piccoli dettagli. Tuttavia, per altre attività devi chiedere esplicitamente al modello di scrivere il codice. Ad esempio, utilizza prompt come "scrivi codice per contare il numero di ingranaggi" o "ruota questa immagine per renderla verticale".
Matematica visiva: esegui calcoli in più passaggi utilizzando il codice (ad esempio, la somma delle voci di una ricevuta).
Annotazione delle immagini: annota le immagini per rispondere a domande, ad esempio disegnando frecce tra gli oggetti per mostrare le relazioni.

Per utilizzare l'esecuzione del codice con le immagini, abilita l'esecuzione del codice durante la configurazione del modello e invia un prompt con un'immagine da ispezionare al modello:

Python

# Example input image
image_path = "https://storage.googleapis.com/cloud-samples-data/generative-ai/image/chips.jpeg"
image_bytes = requests.get(image_path).content
image = types.Part.from_bytes(
  data=image_bytes, mime_type="image/jpeg"
)

response = client.models.generate_content(
    model=MODEL_ID,
    contents=[image, "Locate the ESMT chip. What are the numbers on the chip?"],
    config=types.GenerateContentConfig(
        tools=[types.Tool(code_execution=types.ToolCodeExecution)]
    ),
)

Esecuzione del codice rispetto alla chiamata di funzione

L'esecuzione del codice e la chiamata di funzione 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 tu voglia.

In generale, dovresti preferire l'utilizzo dell'esecuzione del codice se può gestire il tuo caso d'uso. L'esecuzione del codice è più semplice da utilizzare (basta abilitarla) e si risolve in una singola richiesta GenerateContent. La chiamata di funzione richiede una richiesta GenerateContent aggiuntiva per restituire l'output di ogni chiamata di funzione.

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

Fatturazione

Non sono previsti costi aggiuntivi per l'abilitazione dell'esecuzione del codice dall'API Gemini. Ti verrà addebitata la tariffa corrente dei token di input e output in base al modello Gemini che stai utilizzando.

Ecco alcuni altri aspetti da sapere sulla fatturazione per l'esecuzione del codice:

Ti viene addebitato un solo costo 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 restituiti nella risposta dell'API.

Diagramma del flusso di fatturazione per l'utilizzo dello strumento di esecuzione del codice, come descritto nel
testo seguente.

Ti verrà addebitata la tariffa corrente dei token di input e output in base al modello Gemini che stai utilizzando.
Se Gemini utilizza l'esecuzione del codice durante la generazione della risposta, il prompt originale, il codice generato e il risultato del codice eseguito vengono 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 dei token intermedi nella risposta dell'API, in modo che tu possa tenere traccia di eventuali token di input aggiuntivi oltre a quelli passati nel prompt iniziale.

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

Limitazioni

Il modello può solo generare ed eseguire codice. Non può restituire altri artefatti come i file multimediali.
Lo strumento di esecuzione del codice non supporta gli URI dei file come input/output. Tuttavia, lo strumento di esecuzione del codice supporta l'input dei file e l'output dei grafici come byte in linea. Utilizzando queste funzionalità di input e output, puoi caricare file CSV e di testo, porre domande sui file e generare grafici Matplotlib come parte del risultato dell'esecuzione del codice. I tipi MIME supportati per i byte in linea sono .cpp, .csv, .java, .jpeg, .js, .png, .py, .ts e .xml.
L'esecuzione del codice può durare al massimo 30 secondi prima del timeout.
In alcuni casi, l'abilitazione dell'esecuzione del codice può comportare regressioni in altre aree dell'output del modello (ad esempio, la scrittura di una storia).

Esecuzione del codice Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Modelli supportati

Inizia a utilizzare l'esecuzione del codice

Abilita l'esecuzione del codice

Python

Installa

Go

Node.js

Installa

Java

REST

curl

PowerShell

Risposta

Utilizza l'esecuzione del codice in chat

REST

(Solo Gemini 3 Flash) Utilizza l'esecuzione del codice con le immagini

Python

Esecuzione del codice rispetto alla chiamata di funzione

Fatturazione

Limitazioni

Esecuzione del codice