Eksekusi kode

Fitur eksekusi kode Gemini API memungkinkan model membuat dan menjalankan kode Python serta belajar secara iteratif dari hasilnya hingga mencapai output akhir. Anda dapat menggunakan kemampuan eksekusi kode ini untuk mem-build aplikasi yang mendapatkan manfaat dari penalaran berbasis kode dan menghasilkan output teks. Misalnya, Anda dapat menggunakan eksekusi kode dalam aplikasi yang menyelesaikan persamaan atau memproses teks.

Eksekusi kode tersedia di Vertex AI Studio dan Gemini API. Di Vertex AI Studio, Anda dapat mengaktifkan eksekusi kode di bagian Setelan lanjutan. Gemini API menyediakan eksekusi kode sebagai alat, mirip dengan panggilan fungsi. Setelah Anda menambahkan eksekusi kode sebagai alat, model akan menentukan kapan harus menggunakannya.

Lingkungan eksekusi kode mencakup library berikut. Anda tidak dapat menginstal library Anda sendiri.

Model yang didukung

Eksekusi kode didukung oleh model gemini-2.0-flash-exp.

Mulai menggunakan eksekusi kode

Bagian ini mengasumsikan bahwa Anda telah menyelesaikan langkah-langkah penyiapan dan konfigurasi yang ditampilkan di panduan memulai Gemini API.

Mengaktifkan eksekusi kode pada model

Anda dapat mengaktifkan eksekusi kode dasar seperti yang ditunjukkan di sini:

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • GENERATE_RESPONSE_METHOD: Jenis respons yang ingin Anda hasilkan dari model. Pilih metode yang menghasilkan cara Anda ingin respons model ditampilkan:
    • streamGenerateContent: Respons di-streaming saat dibuat untuk mengurangi persepsi latensi bagi audiens manusia.
    • generateContent: Respons ditampilkan setelah sepenuhnya dibuat.
  • LOCATION: Region untuk memproses permintaan. Opsi yang tersedia mencakup hal berikut:

    Klik untuk meluaskan sebagian daftar region yang tersedia

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: Project ID Anda.
  • MODEL_ID: ID model dari model yang ingin Anda gunakan.
  • ROLE: Peran dalam percakapan yang terkait dengan konten. Menentukan peran diperlukan bahkan dalam kasus penggunaan satu giliran. Nilai yang dapat diterima mencakup hal berikut:
    • USER: Menentukan konten yang dikirim oleh Anda.
    • MODEL: Menentukan respons model.
  • TEXT
     Petunjuk teks yang akan disertakan dalam perintah.

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini: 

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

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda: 

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

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini: 

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

Kemudian, jalankan perintah berikut untuk mengirim permintaan REST Anda: 

$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

Anda akan menerima respons JSON yang mirip dengan berikut ini.

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
}

Menggunakan eksekusi kode di chat

Anda juga dapat menggunakan eksekusi kode sebagai bagian dari 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."
        }
      }
    ]
  }'

Eksekusi kode versus panggilan fungsi

Eksekusi kode dan panggilan fungsi adalah fitur yang serupa:

  • Eksekusi kode memungkinkan model menjalankan kode di backend API dalam lingkungan tetap dan terisolasi.
  • Panggilan fungsi memungkinkan Anda menjalankan fungsi yang diminta model, di lingkungan apa pun yang Anda inginkan.

Secara umum, sebaiknya gunakan eksekusi kode jika dapat menangani kasus penggunaan Anda. Eksekusi kode lebih mudah digunakan (Anda cukup mengaktifkannya) dan di-resolve dalam satu permintaan GenerateContent, sehingga menimbulkan satu tagihan. Pemanggilan fungsi memerlukan permintaan GenerateContent tambahan untuk mengirim kembali output dari setiap panggilan fungsi, sehingga menimbulkan beberapa tagihan.

Untuk sebagian besar kasus, Anda harus menggunakan panggilan fungsi jika memiliki fungsi sendiri yang ingin dijalankan secara lokal, dan Anda harus menggunakan eksekusi kode jika ingin API menulis dan menjalankan kode Python untuk Anda dan menampilkan hasilnya.

Penagihan

Tidak ada biaya tambahan untuk mengaktifkan eksekusi kode dari Gemini API. Anda akan ditagih dengan tarif karakter input dan output saat ini.

Berikut beberapa hal lain yang perlu diketahui tentang penagihan untuk eksekusi kode:

  • Anda hanya ditagih sekali untuk token input yang Anda teruskan ke model, dan ditagih untuk token output akhir yang ditampilkan kepada Anda oleh model.
  • Token yang mewakili kode yang dihasilkan dihitung sebagai token output.
  • Hasil eksekusi kode juga dihitung sebagai token output.

Batasan

  • Model ini hanya dapat membuat dan menjalankan kode. Metode ini tidak dapat menampilkan artefak lain seperti file media.
  • Fitur ini tidak mendukung I/O file atau kasus penggunaan yang melibatkan output non-teks (misalnya, plot data atau upload file CSV).
  • Eksekusi kode dapat berjalan selama maksimal 30 detik sebelum waktu habis.
  • Dalam beberapa kasus, mengaktifkan eksekusi kode dapat menyebabkan regresi di area lain output model (misalnya, menulis cerita).