コードの実行

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 リポジトリをご覧ください。
Vertex AI で Gen AI SDK を使用するように環境変数を設定します。

# 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 バックエンドのコードを実行できます。
  • 関数呼び出しを使用すると、モデルがリクエストする関数を任意の環境で実行できます。

一般に、ユースケースを処理できる場合は、コード実行を使用することをおすすめします。コード実行は使いやすく（有効にするだけ）、1 回の GenerateContent リクエストで解決されます。関数呼び出しでは、各関数呼び出しの出力を返すために追加の GenerateContent リクエストが必要です。

ほとんどの場合、ローカルで実行する独自の関数がある場合は関数呼び出しを使用し、API で Python コードを記述して実行し、結果を返す場合はコード実行を使用する必要があります。

課金

Gemini API からのコード実行を有効にしても、追加料金は発生しません。使用している Gemini モデルに基づいて、入力トークンと出力トークンの現在のレートで課金されます。

コード実行の課金について、その他の注意事項は次のとおりです。

  • モデルに渡す入力トークンと、コード実行ツールによって生成された中間入力トークンに対してのみ課金されます。
  • API レスポンスで返された最終出力トークンが課金対象となります。

以下のテキストで説明するように、コード実行ツールの使用に関する課金フローの図。

  • 使用している Gemini モデルに基づいて、入力トークンと出力トークンの現在のレートで課金されます。
  • Gemini がレスポンスの生成時にコード実行を使用する場合、元のプロンプト、生成されたコード、実行されたコードの結果には「中間トークン」というラベルが付けられ、入力トークンとして課金されます。
  • Gemini はサマリーを生成し、生成されたコード、実行されたコードの結果、最終的なサマリーを返します。これらは出力トークンとして課金されます。
  • Gemini API の API レスポンスには中間トークン数が含まれるため、最初のプロンプトで渡されたトークン以外の追加入力トークンを追跡できます。

生成されたコードには、テキストとマルチモーダル出力（画像など）の両方を含めることができます。

制限事項

  • モデルはコードの生成と実行のみを行います。メディア ファイルなどの他のアーティファクトを返すことはできません。
  • この機能は、ファイル I/O や、テキスト以外の出力（データプロットや CSV ファイルのアップロードなど）を伴うユースケースはサポートしていません。
  • コードの実行は、タイムアウトするまで最大 30 秒間実行できます。
  • コード実行を有効にすると、モデル出力の他の領域（ストーリーの作成など）で回帰が発生することがあります。