コードの実行

Gemini API のコード実行機能を使用すると、モデルは Python コードを生成して実行し、最終的な出力に到達するまで結果から反復的に学習できます。このコード実行機能を使用すると、コードベースの推論を活用し、テキスト出力を生成するアプリケーションを構築できます。たとえば、方程式を解くアプリやテキストを処理するアプリでコード実行を使用できます。

コード実行は、Vertex AI Studio と Gemini API の両方で使用できます。Vertex AI Studio では、[詳細設定] でコード実行を有効にできます。Gemini API は、関数呼び出しと同様に、コード実行をツールとして提供します。コード実行をツールとして追加すると、モデルがコード実行を使用するタイミングを決定します。

コード実行環境には、次のライブラリが含まれています。独自のライブラリをインストールすることはできません。

サポートされているモデル

コード実行は gemini-2.0-flash-exp モデルでサポートされています。

コード実行の開始

このセクションでは、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/v1beta1/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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

Python

from google import genai
from google.genai.types import Tool, ToolCodeExecution, GenerateContentConfig

client = genai.Client()
model_id = "gemini-2.0-flash-exp"

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'

Go

import (
  "bytes"
  "context"
  "flag"
  "fmt"
  "io"

  genai "google.golang.org/genai"
)

// codeExecution generates code for the given text prompt using Code Execution as a Tool.
func codeExecution(w io.Writer) error {
  modelName := "gemini-2.0-flash-exp"
  client, err := genai.NewClient(context.TODO(), &genai.ClientConfig{})
  if err != nil {
    return fmt.Errorf("NewClient: %w", err)
  }

  codeExecTool := genai.Tool{
    CodeExecution: &genai.ToolCodeExecution{},
  }
  config := &genai.GenerateContentConfig{
    Tools: []*genai.Tool{&codeExecTool},
  }

  textpart := genai.Text(`Calculate 20th fibonacci number. Then find the nearest palindrome to it.`)

  result, err := client.Models.GenerateContent(context.TODO(), modelName,
    &genai.ContentParts{textpart}, config)
  if err != nil {
    return fmt.Errorf("GenerateContent: %w", err)
  }

  for _, part := range result.Candidates[0].Content.Parts {
    if part.ExecutableCode != nil {
      fmt.Fprintf(w, "Code (%s):\n%s\n", part.ExecutableCode.Language, part.ExecutableCode.Code)
    }
    if part.CodeExecutionResult != nil {
      fmt.Fprintf(w, "Result (%s):\n %s\n", part.CodeExecutionResult.Outcome, part.CodeExecutionResult.Output)
    }
  }
  return nil
}

チャットでコード実行を使用する

コード実行をチャットの一部として使用することもできます。

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

コードの実行と関数呼び出し

コード実行と関数呼び出しは類似した機能です。

  • コード実行により、モデルは固定された分離された環境で API バックエンドのコードを実行できます。
  • 関数呼び出しを使用すると、モデルがリクエストする関数を任意の環境で実行できます。

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

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

課金

Gemini API からのコード実行を有効にしても、追加料金は発生しません。入力と出力の文字数の現在の料金が請求されます。

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

  • モデルに渡す入力トークンは 1 回だけ課金され、モデルから返された最終出力トークンは課金されます。
  • 生成されたコードを表すトークンは、出力トークンとしてカウントされます。
  • コード実行結果も出力トークンとしてカウントされます。

制限事項

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