代码执行

Gemini API 代码执行功能可让模型生成和运行 Python 代码，并从结果中迭代学习，直到生成最终输出。您可以使用此代码执行功能来构建可从基于代码的推理中受益并生成文本输出的应用。例如，您可以在解方程或处理文本的应用中使用代码执行。

Gemini API 提供代码执行作为工具，类似于函数调用。将代码执行添加为工具后，模型会决定何时使用它。

代码执行环境包含以下库。您无法安装自己的库。

支持的模型

以下模型支持代码执行：

型号 版本 代码执行发布阶段
Gemini 2.0 Flash 所有版本 正式发布

代码执行使用入门

本部分假定您已完成 Gemini API 快速入门中显示的设置和配置步骤。

在模型上启用代码执行

您可以启用基本代码执行，如下所示：

REST

在使用任何请求数据之前，请先进行以下替换：

  • GENERATE_RESPONSE_METHOD：您希望模型生成的回答类型。选择一种方法来生成您希望返回模型回答的方式：
    • streamGenerateContent：在生成回答时进行流式传输，以降低真人受众群体对于延迟的感知度。
    • generateContent：回答在完全生成后返回。
  • LOCATION：处理请求的区域。可用的选项包括：

    点击即可展开可用区域的部分列表

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID：您的项目 ID。
  • MODEL_ID：您要使用的模型的模型 ID。
  • ROLE：与内容关联的对话中的角色。即使在单轮应用场景中，也需要指定角色。 可接受的值包括：
    • USER：指定由您发送的内容。
    • MODEL：指定模型的响应。
  • TEXT
     要包含在提示中的文本指令。

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

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

然后，执行以下命令以发送 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

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

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

然后，执行以下命令以发送 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

您应该收到类似以下内容的 JSON 响应。

Gen AI SDK for Python

了解如何安装或更新 Google Gen AI SDK for Python。
如需了解详情，请参阅 Gen AI SDK for Python API 参考文档或 python-genai GitHub 代码库。
设置环境变量以将 Gen AI SDK 与 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'

在聊天中使用代码执行

您还可以将代码执行作为聊天内容的一部分。

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

代码执行与函数调用

代码执行和函数调用是类似的功能：

  • 代码执行可让模型在固定的隔离环境中运行 API 后端中的代码。
  • 通过函数调用，您可以在任何所需的环境中运行模型请求的函数。

通常，如果代码执行可以处理您的使用场景，您应优先使用代码执行。代码执行的使用更简单（只需启用即可），并且会在单个 GenerateContent 请求中解析。函数调用需要额外的 GenerateContent 请求来发回每个函数调用的输出。

在大多数情况下，如果您具有要在本地运行的自己的函数，则应使用函数调用；如果您希望 API 为您编写和运行 Python 代码并返回结果，则应使用代码执行。

结算

通过 Gemini API 启用代码执行不会产生额外费用。系统会根据您使用的 Gemini 模型，按当前的输入和输出令牌费率向您收费。

以下是关于代码执行结算的其他注意事项：

  • 您只需为您传递给模型的输入令牌以及代码执行工具使用的中间输入令牌支付一次费用。
  • 您需要为 API 响应中返回给您的最终输出令牌付费。

代码执行工具使用情况的结算流程图，如以下文本所述。

  • 系统会根据您使用的 Gemini 模型，按当前的输入和输出令牌费率向您收费。
  • 如果 Gemini 在生成响应时使用代码执行，则原始提示、生成的代码以及执行的代码的结果会被标记为中间令牌，并按输入令牌计费。
  • 然后，Gemini 会生成摘要并返回生成的代码、执行的代码的结果以及最终摘要。这些数据按输出令牌计费。
  • Gemini API 在 API 响应中包含中间令牌数，因此您可以跟踪除初始提示中传递的令牌之外的任何其他输入令牌。

生成的代码可以包含文本和多模态输出（例如图片）。

限制

  • 该模型只能生成和执行代码。它无法返回其他工件，例如媒体文件。
  • 此功能不支持文件 I/O 或涉及非文本输出（例如数据图表或 CSV 文件上传）的应用场景。
  • 代码执行最多可运行 30 秒，超出即会超时。
  • 在某些情况下，启用代码执行可能会导致模型输出的其他方面（例如，撰写故事）出现回归问题。