הרצת קוד

התכונה 'הרצת קוד' ב-Gemini API מאפשרת למודל ליצור ולהריץ קוד Python, וללמוד מהתוצאות באופן איטרטיבי עד שהוא מגיע לפלט סופי. אתם יכולים להשתמש ביכולת הזו להרצת קוד כדי ליצור אפליקציות שמפיקות תועלת מהסקה שמבוססת על קוד ומייצרות פלט טקסטואלי. לדוגמה, אפשר להשתמש בהרצת קוד באפליקציה שפותרת משוואות או מעבדת טקסט.

‫Gemini API מספק כלי להרצת קוד, בדומה לבקשה להפעלת פונקציה. אחרי שמוסיפים את הפעלת הקוד ככלי, המודל מחליט מתי להשתמש בו.

סביבת ההפעלה של הקוד כוללת את הספריות הבאות. אי אפשר להתקין ספריות משלכם.

מודלים נתמכים

המודלים הבאים תומכים בהרצת קוד:

אפשר ללחוץ כדי להרחיב את רשימת המודלים הנתמכים

תחילת העבודה עם הפעלת קוד

ההנחה היא שסיימתם את שלבי ההגדרה והקביעה שמופיעים במדריך למתחילים בנושא Gemini API.

הפעלת ביצוע קוד

כדי להפעיל את המודל לשימוש בהרצת קוד, מוסיפים אותו לרשימה tools כשמגדירים את המודל:

Python

התקנה

pip install --upgrade google-genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-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=global
export GOOGLE_GENAI_USE_ENTERPRISE=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.5-flash"

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,
    ),
)
print("# Code:")
print(response.executable_code)
print("# Outcome:")
print(response.code_execution_result)

# Example response:
# # Code:
# def fibonacci(n):
#     if n <= 0:
#         return 0
#     elif n == 1:
#         return 1
#     else:
#         a, b = 0, 1
#         for _ in range(2, n + 1):
#             a, b = b, a + b
#         return b
#
# fib_20 = fibonacci(20)
# print(f'{fib_20=}')
#
# # Outcome:
# fib_20=6765

Go

כך מתקינים או מעדכנים את Go.

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-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=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithCodeExec shows how to generate text using the code execution tool.
func generateWithCodeExec(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	prompt := "Calculate 20th fibonacci number. Then find the nearest palindrome to it."
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: prompt},
		},
			Role: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{CodeExecution: &genai.ToolCodeExecution{}},
		},
		Temperature: genai.Ptr(float32(0.0)),
	}
	modelName := "gemini-2.5-flash"

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

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

	// Example response:
	// Gemini: Okay, I can do that. First, I'll calculate the 20th Fibonacci number. Then, I need ...
	//
	// Language: PYTHON
	//
	// def fibonacci(n):
	//    ...
	//
	// fib_20 = fibonacci(20)
	// print(f'{fib_20=}')
	//
	// Outcome: OUTCOME_OK
	// fib_20=6765
	//
	// Now that I have the 20th Fibonacci number (6765), I need to find the nearest palindrome. ...
	// ...

	return nil
}

Node.js

התקנה

npm install @google/genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-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=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateAndExecuteCode(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents:
      'Calculate 20th fibonacci number. Then find the nearest palindrome to it.',
    config: {
      tools: [{codeExecution: {}}],
      temperature: 0,
    },
  });

  console.debug(response.executableCode);

  // Example response:
  // Code:
  // function fibonacci(n) {
  //   if (n <= 0) {
  //     return 0;
  //   } else if (n === 1) {
  //     return 1;
  //   } else {
  //     let a = 0, b = 1;
  //     for (let i = 2; i <= n; i++) {
  //       [a, b] = [b, a + b];
  //     }
  //     return b;
  //   }
  // }
  //
  // const fib20 = fibonacci(20);
  // console.log(`fib20=${fib20}`);

  console.debug(response.codeExecutionResult);

  // Outcome:
  // fib20=6765

  return response.codeExecutionResult;
}

Java

כך מתקינים או מעדכנים את Java.

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-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=global
export GOOGLE_GENAI_USE_ENTERPRISE=True


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Tool;
import com.google.genai.types.ToolCodeExecution;

public class ToolsCodeExecWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates text using the Code Execution tool
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Create a GenerateContentConfig and set codeExecution tool
      GenerateContentConfig contentConfig =
          GenerateContentConfig.builder()
              .tools(Tool.builder().codeExecution(ToolCodeExecution.builder().build()).build())
              .temperature(0.0F)
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              modelId,
              "Calculate 20th fibonacci number. Then find the nearest palindrome to it.",
              contentConfig);

      System.out.println("Code: \n" + response.executableCode());
      System.out.println("Outcome: \n" + response.codeExecutionResult());
      // Example response
      // Code:
      // def fibonacci(n):
      //    if n <= 0:
      //        return 0
      //    elif n == 1:
      //        return 1
      //    else:
      //        a, b = 1, 1
      //        for _ in range(2, n):
      //            a, b = b, a + b
      //        return b
      //
      // fib_20 = fibonacci(20)
      // print(f'{fib_20=}')
      //
      // Outcome:
      // fib_20=6765
      return response.executableCode();
    }
  }
}

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: מזהה הפרויקט.
  • MODEL_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 שדומה לזו:

איך משתמשים בהרצת קוד בצ'אט

אפשר גם להשתמש בהרצת קוד כחלק משיחה.

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/test-project/locations/global/publishers/google/models/gemini-3.5-flash: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."
        }
      }
    ]
  }'

(‫Gemini 3 Flash בלבד) שימוש בהרצת קוד עם תמונות

‫Gemini 3 Flash יכול לכתוב ולהריץ קוד Python כדי לבצע מניפולציות פעילות בתמונות ולבדוק אותן. אתם יכולים להשתמש בהרצת קוד עם תמונות כדי:

  • הגדלה ובדיקה של תמונות: זיהוי מצבים שבהם הפרטים קטנים מדי (לדוגמה, קריאת מד שנמצא רחוק מהמצלמה) וכתיבת קוד לחיתוך ולבדיקה מחדש של האזור ברזולוציה גבוהה יותר.

  • מתמטיקה ויזואלית: ביצוע חישובים מרובי שלבים באמצעות קוד (למשל, חישוב סכום הפריטים בקבלה).

  • הערות לתמונות: הוספת הערות לתמונות כדי לענות על שאלות, למשל ציור של חצים בין אובייקטים כדי להראות את הקשרים ביניהם.

כדי להשתמש בהרצת קוד עם תמונות, מפעילים את הרצת הקוד כשמגדירים את המודל ושולחים הנחיה עם תמונה כדי שהמודל יבדוק אותה:

Python

# Example input image
image_path = "https://storage.googleapis.com/cloud-samples-data/generative-ai/image/chips.jpeg"
image_bytes = requests.get(image_path).content
image = types.Part.from_bytes(
  data=image_bytes, mime_type="image/jpeg"
)

response = client.models.generate_content(
    model=MODEL_ID,
    contents=[image, "Locate the ESMT chip. What are the numbers on the chip?"],
    config=types.GenerateContentConfig(
        tools=[types.Tool(code_execution=types.ToolCodeExecution)]
    ),
)
      

הרצת קוד לעומת בקשה להפעלת פונקציה

הפעלת קוד וקריאה לפונקציה הן תכונות דומות:

  • הפעלת קוד מאפשרת למודל להריץ קוד בקצה העורפי של ה-API בסביבה קבועה ומבודדת.
  • הבקשה להפעלת פונקציה מאפשרת להריץ את הפונקציות שהמודל מבקש, בכל סביבה שרוצים.

באופן כללי, מומלץ להשתמש בהרצת קוד אם היא יכולה לטפל בתרחיש השימוש שלכם. השימוש בהרצת קוד פשוט יותר (רק מפעילים אותה), והיא מסתיימת בבקשה אחת GenerateContent. בקשה להפעלת פונקציה דורשת עוד בקשה אחת, GenerateContent, כדי לשלוח בחזרה את הפלט מכל קריאה לפונקציה.

ברוב המקרים, כדאי להשתמש בהפעלת פונקציות אם יש לכם פונקציות משלכם שאתם רוצים להריץ באופן מקומי, וכדאי להשתמש בהרצת קוד אם אתם רוצים שה-API יכתוב ויריץ קוד Python בשבילכם ויחזיר את התוצאה.

חיוב

אין עלות נוספת להפעלת ביצוע קוד מ-Gemini API. החיוב יתבצע לפי התעריף הנוכחי של טוקנים של קלט ופלט, על סמך מודל Gemini שבו אתם משתמשים.

ריכזנו כאן כמה דברים נוספים שכדאי לדעת על חיוב על הפעלת קוד:

  • תחויבו רק פעם אחת על טוקני הקלט שמועברים למודל ועל טוקני הקלט הביניים שנוצרים על ידי כלי ההרצה של הקוד.
  • החיוב הוא על הטוקנים של הפלט הסופי שמוחזרים בתגובת ה-API.

תרשים של תהליך החיוב על שימוש בכלי להרצת קוד, כפי שמתואר בטקסט שלמטה.

  • החיוב מתבצע לפי התעריף הנוכחי של טוקנים של קלט ופלט, בהתאם למודל Gemini שבו אתם משתמשים.
  • אם Gemini משתמש בהרצת קוד כדי ליצור את התשובה, ההנחיה המקורית, הקוד שנוצר והתוצאה של הקוד שהורץ מסומנים כטוקנים ביניים והחיוב עליהם הוא כטוקנים של קלט.
  • ‫Gemini ייצור סיכום ויחזיר את הקוד שנוצר, את התוצאה של הקוד שהופעל ואת הסיכום הסופי. החיוב על הטוקנים האלה הוא על טוקנים של פלט.
  • תגובת ה-Gemini API כוללת ספירה של אסימוני ביניים, כך שאפשר לעקוב אחרי אסימוני קלט נוספים מעבר לאלה שהועברו בהנחיה הראשונית.

קוד שנוצר יכול לכלול פלט טקסט ופלט מולטימודאלי, כמו תמונות.

מגבלות

  • המודל יכול רק ליצור ולהריץ קוד. הוא לא יכול להחזיר פריטים אחרים, כמו קובצי מדיה.
  • הכלי להרצת קוד לא תומך בכתובות URI של קבצים כקלט או כפלט. עם זאת, כלי הרצת הקוד תומך בקלט של קבצים ובפלט של גרפים כבייטים מוטבעים. באמצעות היכולות האלה של קלט ופלט, אתם יכולים להעלות קובצי CSV וקובצי טקסט, לשאול שאלות לגבי הקבצים ולקבל גרפים של Matplotlib שנוצרים כחלק מתוצאת הביצוע של הקוד. סוגי ה-MIME הנתמכים עבור בייטים מוטבעים הם .cpp,‏ .csv,‏ .java, .jpeg,‏ .js,‏ .png,‏ .py,‏ .ts ו-.xml.
  • הביצוע של הקוד יכול להימשך עד 30 שניות לפני שפג הזמן הקצוב לתפוגה.
  • במקרים מסוימים, הפעלת ביצוע קוד עלולה להוביל לרגרסיות בתחומים אחרים של פלט המודל (לדוגמה, כתיבת סיפור).