Execução do código

O recurso de execução de código da API Gemini permite que o modelo gere e execute código Python e aprenda de forma iterativa com os resultados até chegar a uma saída final. É possível usar esse recurso de execução de código para criar aplicativos que se beneficiam do raciocínio baseado em código e que produzem saída de texto. Por exemplo, você pode usar a execução de código em um aplicativo que resolve equações ou processa texto.

A API Gemini fornece a execução de código como uma ferramenta, semelhante à chamada de função. Depois que você adiciona a execução de código como uma ferramenta, o modelo decide quando usá-la.

O ambiente de execução do código inclui as seguintes bibliotecas. Não é possível instalar suas próprias bibliotecas.

Modelos compatíveis

Os modelos a seguir oferecem suporte à execução de código:

Modelo Versões Estágio de inicialização da execução do código
Gemini 2.0 Flash Todas as versões Disponibilidade geral

Começar a usar a execução de código

Esta seção pressupõe que você tenha concluído as etapas de configuração mostradas no Guia de início rápido da API Gemini.

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

Você pode ativar a execução de código básica, conforme mostrado aqui:

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • GENERATE_RESPONSE_METHOD: o tipo de resposta que você quer que o modelo gere. Escolha um método que gere como você quer que a resposta do modelo seja retornada:
    • streamGenerateContent: a resposta é transmitida conforme é gerada para reduzir a percepção de latência para o público humano.
    • generateContent: a resposta será retornada depois de ser totalmente gerada.
  • LOCATION: a região para processar a solicitação. As opções disponíveis incluem:

    Clicar para abrir 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 ID do projeto.
  • MODEL_ID: o ID do modelo que você quer usar.
  • ROLE: o papel em uma conversa associada ao conteúdo. É necessário especificar um papel mesmo em casos de uso de turno único. Os valores aceitáveis são os seguintes:
    • USER: especifica o conteúdo que é enviado por você.
    • MODEL: especifica a resposta do modelo.
  • TEXT
     As instruções de texto a serem incluídas no comando.

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

Depois execute o comando a seguir para enviar a solicitação 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

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

Depois execute o comando a seguir para enviar a solicitação 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

Você receberá uma resposta JSON semelhante a seguinte.

SDK da Gen AI para Python

Saiba como instalar ou atualizar o SDK do Google Gen AI para Python.
Para mais informações, consulte a documentação de referência da API SDK do Gen AI para Python ou o python-genai repositório do GitHub.
Defina as variáveis de ambiente para usar o SDK da IA generativa com a 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,
    ),
)
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'

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

Também é possível usar a execução de código como parte de uma conversa.

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."
        }
      }
    ]
  }'

Execução do código versus chamada de função

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

  • A execução de código permite que o modelo execute código no back-end da API em um ambiente fixo e isolado.
  • A chamada de função permite executar as funções solicitadas pelo modelo em qualquer ambiente.

Em geral, é melhor usar a execução de código se ela puder lidar com seu caso de uso. A execução do código é mais simples de usar (basta ativá-la) e é resolvida em uma única solicitação GenerateContent. A chamada de função usa uma solicitação GenerateContent adicional para enviar a saída de cada chamada de função.

Na maioria dos casos, use a chamada de função se você tiver suas próprias funções que quer executar localmente. Use a execução de código se quiser que a API escreva e execute o código Python para você e retorne o resultado.

Faturamento

Não há cobrança extra para ativar a execução de código na API Gemini. A cobrança será feita com base na taxa atual de tokens de entrada e saída, de acordo com o modelo do Gemini que você está usando.

Confira algumas outras informações sobre o faturamento para execução de código:

  • Você só vai receber cobrança uma vez pelos tokens de entrada que transmitir ao modelo e pelos tokens de entrada intermediários gerados pelo uso da ferramenta de execução de código.
  • Você vai receber uma cobrança pelos tokens de saída finais retornados na resposta da API.

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

  • A cobrança é feita com base na taxa atual de tokens de entrada e saída com base no modelo do Gemini que você está usando.
  • Se o Gemini usar a execução de código ao gerar a resposta, a instrução original, o código gerado e o resultado do código executado serão marcados como tokens intermediários e cobrados como tokens de entrada.
  • O Gemini gera um resumo e retorna o código gerado, o resultado do código executado e o resumo final. Eles são cobrados como tokens de saída.
  • A API Gemini inclui uma contagem de tokens intermediários na resposta da API para que você possa acompanhar todos os tokens de entrada além daqueles transmitidos no comando inicial.

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

Limitações

  • O modelo só pode gerar e executar código. Ele não pode retornar outros artefatos, como arquivos de mídia.
  • O recurso não oferece suporte a E/S de arquivos ou casos de uso que envolvem saídas que não sejam de texto, como gráficos de dados ou um upload de arquivo CSV.
  • A execução do código pode durar no máximo 30 segundos antes do tempo limite.
  • Em alguns casos, a ativação da execução de código pode levar a regressões em outras áreas da saída do modelo (por exemplo, na escrita de uma história).