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:

RESTSDK da Gen AI para Python

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:
    • 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:

curlPowerShell

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"

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.

{
  "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"
}

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