Execução de código

A funcionalidade de execução de código da API Gemini permite que o modelo gere e execute código Python e aprenda iterativamente com os resultados até chegar a um resultado final. Pode usar esta capacidade de execução de código para criar aplicações que beneficiam do raciocínio baseado em código e que produzem resultados de texto. Por exemplo, pode usar a execução de código numa aplicação que resolva equações ou processe texto.

A API Gemini oferece a execução de código como uma ferramenta, semelhante à chamada de funções. Depois de adicionar a execução de código como ferramenta, o modelo decide quando a usar.

O ambiente de execução de código inclui as seguintes bibliotecas. Não pode instalar as suas próprias bibliotecas.

Modelos suportados

Os seguintes modelos oferecem suporte para a execução de código:

Comece a usar a execução de código

Esta secção pressupõe que concluiu os passos de configuração mostrados no guia de início rápido da API Gemini.

Ative a execução de código no modelo

Pode ativar a execução de código básico, conforme mostrado aqui:

Python

Instalação

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o 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

Saiba como instalar ou atualizar o Go.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o 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: "user"}, 	} 	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

Instalação

npm install @google/genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o 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 generateContent(   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:       'What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50.',     config: {       tools: [{codeExecution: {}}],       temperature: 0,     },   });    console.debug(response.executableCode);   console.debug(response.codeExecutionResult);    return response.codeExecutionResult; }

Java

Saiba como instalar ou atualizar o Java.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o 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

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • GENERATE_RESPONSE_METHOD: o tipo de resposta que quer que o modelo gere. Escolha um método que gere a forma como quer que a resposta do modelo seja devolvida:
    • streamGenerateContent: a resposta é transmitida à medida que é gerada para reduzir a perceção de latência para um público humano.
    • generateContent: a resposta é devolvida depois de ser totalmente gerada.
  • LOCATION: a região para processar o pedido. As opções disponíveis incluem o seguinte:

    Clique para expandir uma lista parcial das regiões disponíveis

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: o seu ID do projeto.
  • MODEL_ID: o ID do modelo que quer usar.
  • ROLE: A função numa conversa associada ao conteúdo. É necessário especificar uma função, mesmo em exemplos de utilização de uma única interação. Os valores aceitáveis incluem o seguinte:
    • USER: especifica o conteúdo enviado por si.
    • MODEL: especifica a resposta do modelo.
  • TEXT
     As instruções de texto a incluir no comando.

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

Em seguida, execute o seguinte comando para enviar o seu pedido 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

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

Em seguida, execute o seguinte comando para enviar o seu pedido 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

Deve receber uma resposta JSON semelhante à seguinte.

Use a execução de código no chat

Também pode usar a execução de código como parte de um 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."         }       }     ]   }'

Execução de código versus chamadas de funções

A execução de código e a chamada de funções são funcionalidades semelhantes:

  • A execução de código permite que o modelo execute código no back-end da API num ambiente fixo e isolado.
  • A chamada de funções permite-lhe executar as funções que o modelo pede, no ambiente que quiser.

Em geral, deve preferir usar a execução de código se esta puder processar o seu exemplo de utilização. A execução de código é mais simples de usar (basta ativá-la) e é resolvida num único pedido GenerateContent. A chamada de funções requer um pedido GenerateContent adicional para enviar de volta o resultado de cada chamada de função.

Na maioria dos casos, deve usar a chamada de funções se tiver as suas próprias funções que quer executar localmente e deve usar a execução de código se quiser que a API escreva e execute código Python por si e devolva o resultado.

Faturação

Não existe qualquer custo adicional pela ativação da execução de código a partir da API Gemini. A faturação é feita à taxa atual de tokens de entrada e saída com base no modelo do Gemini que está a usar.

Seguem-se outros aspetos a ter em atenção sobre a faturação da execução de código:

  • A faturação é feita apenas uma vez pelos tokens de entrada que transmite ao modelo e pelos tokens de entrada intermédios usados pela ferramenta de execução de código.
  • A faturação é feita com base nos tokens de saída finais que lhe são devolvidos na resposta da API.

Diagrama do fluxo de faturação para a utilização da ferramenta de execução de código, conforme descrito no texto abaixo.

  • A faturação é feita à taxa atual de tokens de entrada e saída com base no modelo Gemini que está a usar.
  • Se o Gemini usar a execução de código ao gerar a sua resposta, o comando original, o código gerado e o resultado do código executado são etiquetados como tokens intermédios e são faturados como tokens de entrada.
  • Em seguida, o Gemini gera um resumo e devolve o código gerado, o resultado do código executado e o resumo final. Estes são faturados como tokens de saída.
  • A API Gemini inclui uma contagem de tokens intermédia na resposta da API, para que possa acompanhar os tokens de entrada adicionais além dos transmitidos no seu comando inicial.

O código gerado pode incluir texto e saídas multimodais, como imagens.

Limitações

  • O modelo só pode gerar e executar código. Não pode devolver outros artefactos, como ficheiros multimédia.
  • A ferramenta de execução de código não suporta URIs de ficheiros como entrada/saída. No entanto, a ferramenta de execução de código suporta a entrada de ficheiros e a saída de gráficos como bytes incorporados. Ao usar estas capacidades de entrada e saída, pode carregar ficheiros CSV e de texto, fazer perguntas sobre os ficheiros e gerar gráficos do Matplotlib como parte do resultado da execução do código. Os tipos MIME suportados para bytes incorporados são .cpp, .csv, .java, .jpeg, .js, .png, .py, .ts e .xml.
  • A execução do código pode durar um máximo de 30 segundos antes de atingir o limite de tempo.
  • Em alguns casos, a ativação da execução de código pode levar a regressões noutras áreas do resultado do modelo (por exemplo, escrever uma história).