הרצת קוד

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

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

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

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

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

‫Gemini 3.1 Flash-Lite תצוגה מקדימה
‫Gemini 3.1 Pro תצוגה מקדימה
‫Gemini 3 Flash תצוגה מקדימה
‫Gemini 3 Pro תצוגה מקדימה
‫Gemini 2.5 Pro
‫Gemini 2.5 Flash גרסת טרום-השקה
‫Gemini 2.5 Flash-Lite preview
‫Gemini 2.5 Flash
‫Gemini 2.5 Flash-Lite
‫Gemini 2.0 Flash עם Gemini Live API תצוגה מקדימה
‫Gemini 2.0 Flash

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

ההנחה היא שביצעתם את שלבי ההגדרה והקביעה שמופיעים במדריך למתחילים בנושא 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_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.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_VERTEXAI=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_VERTEXAI=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_VERTEXAI=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

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם 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

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

@'
{
  "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 שדומה לזו:

תשובה

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Okay, I understand. You want me to calculate the sum of the first 10 positive integers and to use code to do so. Here's my plan: I will use a loop to add the numbers from 1 to 10 and then return the final sum.\n\n"
          },
          {
            "executableCode": {
              "language": "PYTHON",
              "code": "\ntotal = 0\nfor i in range(1, 11):\n    total += i\nprint(f'{total=}')\n"
            }
          },
          {
            "codeExecutionResult": {
              "outcome": "OUTCOME_OK",
              "output": "total=55\n"
            }
          },
          {
            "text": "The sum of the first 10 positive numbers is 55.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.19436789,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.17441037
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.0685376,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.14903527
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.23231025,
          "severity": "HARM_SEVERITY_LOW",
          "severityScore": 0.2436427
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08269742,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.10818888
        }
      ],
      "score": -0.50845032930374146,
      "avgLogprobs": -0.0046222757209431042
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 34,
    "candidatesTokenCount": 110,
    "totalTokenCount": 144,
    "billablePromptUsage": {
      "textCount": 119
    },
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2024-12-09T23:33:47.842964Z",
  "responseId": "W35XZ9S5M6acmecP3vDFkQU"
}

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

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

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

(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 יוצר סיכום ומחזיר את הקוד שנוצר, את התוצאה של הקוד שהופעל ואת הסיכום הסופי. החיוב הוא על אסימוני פלט.
תגובת ה-API של Gemini כוללת ספירת אסימונים ביניים, כך שתוכלו לעקוב אחרי אסימוני קלט נוספים מעבר לאלה שהועברו בהנחיה הראשונית.

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

מגבלות

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

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

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

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

הפעלת הרצת קוד

Python

התקנה

Go

Node.js

התקנה

Java

REST

curl

PowerShell

תשובה

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

REST

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

Python

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

חיוב

מגבלות

הרצת קוד