Ejecución de código

La función de ejecución de código de la API de Gemini permite que el modelo genere y ejecute código de Python, y aprenda de forma iterativa a partir de los resultados hasta llegar a un resultado final. Puedes usar esta función de ejecución de código para compilar aplicaciones que se beneficien del razonamiento basado en código y que produzcan resultados de texto. Por ejemplo, puedes usar la ejecución de código en una aplicación que resuelva ecuaciones o procese texto.

La API de Gemini proporciona la ejecución de código como una herramienta, similar a las llamadas a función. Después de agregar la ejecución de código como herramienta, el modelo decide cuándo usarla.

El entorno de ejecución de código incluye las siguientes bibliotecas. No puedes instalar tus propias bibliotecas.

Modelos compatibles

Los siguientes modelos proporcionan compatibilidad para la ejecución de código:

Modelo Versiones Etapa de lanzamiento de la ejecución de código
Gemini 2.0 Flash Todas las versiones Disponibilidad general

Comienza a usar la ejecución de código

En esta sección, se supone que completaste los pasos de configuración que se muestran en la guía de inicio rápido de la API de Gemini.

Habilita la ejecución de código en el modelo

Puedes habilitar la ejecución de código básica como se muestra a continuación:

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • GENERATE_RESPONSE_METHOD: El tipo de respuesta que quieres que genere el modelo. Elige un método que genere cómo quieres que se muestre la respuesta del modelo:
    • streamGenerateContent: La respuesta se transmite a medida que se genera para reducir la percepción de latencia para un público humano.
    • generateContent: La respuesta se muestra después de que se genera por completo.
  • LOCATION: La región para procesar la solicitud. Las opciones disponibles incluyen las siguientes:

    Haz clic para expandir una lista parcial de regiones disponibles

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: El ID del proyecto.
  • MODEL_ID: El ID del modelo que deseas usar.
  • ROLE: El rol en una conversación asociada con el contenido. Especificar un rol es obligatorio incluso en casos de uso de un solo turno. Los valores aceptables son los siguientes:
    • USER: especifica el contenido que envías.
    • MODEL: especifica la respuesta del modelo.
  • TEXT
     Las instrucciones de texto que se incluirán en el mensaje.

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual: 

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

Luego, ejecuta el siguiente comando para enviar tu solicitud de 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual: 

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

Luego, ejecuta el siguiente comando para enviar tu solicitud de 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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

SDK de Gen AI para Python

Obtén información para instalar o actualizar el SDK de Google Gen AI para Python.
Para obtener más información, consulta la documentación de referencia de la API del SDK de Gen AI para Python o el repositorio de GitHub de python-genai.
Establece variables de entorno para usar el SDK de IA generativa 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=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'

Usa la ejecución de código en el chat

También puedes usar la ejecución de código como parte de un 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."
        }
      }
    ]
  }'

Ejecución de código en comparación con la llamada a función

La ejecución de código y las llamadas a función son funciones similares:

  • La ejecución de código permite que el modelo ejecute código en el backend de la API en un entorno fijo y aislado.
  • Las llamadas a funciones te permiten ejecutar las funciones que solicita el modelo en cualquier entorno que desees.

En general, debes preferir usar la ejecución de código si puede controlar tu caso de uso. La ejecución de código es más fácil de usar (solo tienes que habilitarla) y se resuelve en una sola solicitud GenerateContent. Las llamadas a función requieren una solicitud GenerateContent adicional para enviar el resultado de cada llamada a función.

En la mayoría de los casos, debes usar llamadas a función si tienes tus propias funciones que deseas ejecutar de forma local y debes usar la ejecución de código si deseas que la API escriba y ejecute código Python por ti y muestre el resultado.

Facturación

No se cobra ningún cargo adicional por habilitar la ejecución de código desde la API de Gemini. Se te facturará a la tarifa actual de tokens de entrada y salida según el modelo de Gemini que uses.

A continuación, se incluyen otros aspectos que debes tener en cuenta sobre la facturación de la ejecución de código:

  • Solo se te factura una vez por los tokens de entrada que pasas al modelo y los tokens de entrada intermedios que genera la herramienta de ejecución de código.
  • Se te factura por los tokens de salida finales que se te muestran en la respuesta de la API.

Diagrama del flujo de facturación para el uso de la herramienta de ejecución de código, como se describe en el siguiente texto.

  • Se te factura a la tarifa actual de tokens de entrada y salida según el modelo de Gemini que uses.
  • Si Gemini usa la ejecución de código cuando genera tu respuesta, la instrucción original, el código generado y el resultado del código ejecutado se etiquetan como tokens intermedios y se facturan como tokens de entrada.
  • Luego, Gemini genera un resumen y muestra el código generado, el resultado del código ejecutado y el resumen final. Estos se facturan como tokens de salida.
  • La API de Gemini incluye un recuento de tokens intermedios en la respuesta de la API, por lo que puedes hacer un seguimiento de los tokens de entrada adicionales más allá de los que se pasan en la instrucción inicial.

El código generado puede incluir salidas multimodales y de texto, como imágenes.

Limitaciones

  • El modelo solo puede generar y ejecutar código. No puede mostrar otros artefactos, como archivos multimedia.
  • La función no admite E/S de archivos ni casos de uso que involucren resultados que no sean de texto (por ejemplo, gráficos de datos o una carga de archivo CSV).
  • La ejecución de código puede ejecutarse durante un máximo de 30 segundos antes de que se agote el tiempo de espera.
  • En algunos casos, habilitar la ejecución de código puede generar regresiones en otras áreas del resultado del modelo (por ejemplo, escribir una historia).