اجرای کد

رابط برنامه‌نویسی نرم‌افزار Gemini یک ابزار اجرای کد ارائه می‌دهد که مدل را قادر می‌سازد کد پایتون را تولید و اجرا کند. سپس مدل می‌تواند به صورت تکراری از نتایج اجرای کد یاد بگیرد تا زمانی که به خروجی نهایی برسد. می‌توانید از اجرای کد برای ساخت برنامه‌هایی استفاده کنید که از استدلال مبتنی بر کد بهره می‌برند. به عنوان مثال، می‌توانید از اجرای کد برای حل معادلات یا پردازش متن استفاده کنید. همچنین می‌توانید از کتابخانه‌های موجود در محیط اجرای کد برای انجام وظایف تخصصی‌تر استفاده کنید.

Gemini فقط قادر به اجرای کد در پایتون است. شما هنوز می‌توانید از Gemini بخواهید که کد را به زبان دیگری تولید کند، اما مدل نمی‌تواند از ابزار اجرای کد برای اجرای آن استفاده کند.

فعال کردن اجرای کد

برای فعال کردن اجرای کد، ابزار اجرای کد را روی مدل پیکربندی کنید. این به مدل اجازه می‌دهد تا کد را تولید و اجرا کند.

پایتون

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What is the sum of the first 50 prime numbers? "
    "Generate and run code for the calculation, and make sure you get all 50.",
    config=types.GenerateContentConfig(
        tools=[types.Tool(code_execution=types.ToolCodeExecution)]
    ),
)

for part in response.candidates[0].content.parts:
    if part.text is not None:
        print(part.text)
    if part.executable_code is not None:
        print(part.executable_code.code)
    if part.code_execution_result is not None:
        print(part.code_execution_result.output)

جاوا اسکریپت

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

let response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: [
    "What is the sum of the first 50 prime numbers? " +
      "Generate and run code for the calculation, and make sure you get all 50.",
  ],
  config: {
    tools: [{ codeExecution: {} }],
  },
});

const parts = response?.candidates?.[0]?.content?.parts || [];
parts.forEach((part) => {
  if (part.text) {
    console.log(part.text);
  }

  if (part.executableCode && part.executableCode.code) {
    console.log(part.executableCode.code);
  }

  if (part.codeExecutionResult && part.codeExecutionResult.output) {
    console.log(part.codeExecutionResult.output);
  }
});

برو

package main

import (
    "context"
    "fmt"
    "os"
    "google.golang.org/genai"
)

func main() {

    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

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

    result, _ := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash",
        genai.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."),
        config,
    )

    fmt.Println(result.Text())
    fmt.Println(result.ExecutableCode())
    fmt.Println(result.CodeExecutionResult())
}

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d ' {"tools": [{"code_execution": {}}],
    "contents": {
      "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."
        }
    },
}'

خروجی ممکن است چیزی شبیه به زیر باشد که برای خوانایی بیشتر قالب‌بندی شده است:

Okay, I need to calculate the sum of the first 50 prime numbers. Here's how I'll
approach this:

1.  **Generate Prime Numbers:** I'll use an iterative method to find prime
    numbers. I'll start with 2 and check if each subsequent number is divisible
    by any number between 2 and its square root. If not, it's a prime.
2.  **Store Primes:** I'll store the prime numbers in a list until I have 50 of
    them.
3.  **Calculate the Sum:**  Finally, I'll sum the prime numbers in the list.

Here's the Python code to do this:

def is_prime(n):
  """Efficiently checks if a number is prime."""
  if n <= 1:
    return False
  if n <= 3:
    return True
  if n % 2 == 0 or n % 3 == 0:
    return False
  i = 5
  while i * i <= n:
    if n % i == 0 or n % (i + 2) == 0:
      return False
    i += 6
  return True

primes = []
num = 2
while len(primes) < 50:
  if is_prime(num):
    primes.append(num)
  num += 1

sum_of_primes = sum(primes)
print(f'{primes=}')
print(f'{sum_of_primes=}')

primes=[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67,
71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151,
157, 163, 167, 173, 179, 181, 191, 193, 197, 199, 211, 223, 227, 229]
sum_of_primes=5117

The sum of the first 50 prime numbers is 5117.

این خروجی چندین بخش محتوا را که مدل هنگام استفاده از اجرای کد برمی‌گرداند، ترکیب می‌کند:

  • text : متن درون‌خطی تولید شده توسط مدل
  • executableCode : کدی که توسط مدل تولید می‌شود و قرار است اجرا شود
  • codeExecutionResult : نتیجه کد اجرایی

قراردادهای نامگذاری برای این بخش‌ها بسته به زبان برنامه‌نویسی متفاوت است.

استفاده از اجرای کد در چت

همچنین می‌توانید از اجرای کد به عنوان بخشی از چت استفاده کنید.

پایتون

from google import genai
from google.genai import types

client = genai.Client()

chat = client.chats.create(
    model="gemini-2.5-flash",
    config=types.GenerateContentConfig(
        tools=[types.Tool(code_execution=types.ToolCodeExecution)]
    ),
)

response = chat.send_message("I have a math question for you.")
print(response.text)

response = chat.send_message(
    "What is the sum of the first 50 prime numbers? "
    "Generate and run code for the calculation, and make sure you get all 50."
)

for part in response.candidates[0].content.parts:
    if part.text is not None:
        print(part.text)
    if part.executable_code is not None:
        print(part.executable_code.code)
    if part.code_execution_result is not None:
        print(part.code_execution_result.output)

جاوا اسکریپت

import {GoogleGenAI} from "@google/genai";

const ai = new GoogleGenAI({});

const chat = ai.chats.create({
  model: "gemini-2.5-flash",
  history: [
    {
      role: "user",
      parts: [{ text: "I have a math question for you:" }],
    },
    {
      role: "model",
      parts: [{ text: "Great! I'm ready for your math question. Please ask away." }],
    },
  ],
  config: {
    tools: [{codeExecution:{}}],
  }
});

const response = await chat.sendMessage({
  message: "What is the sum of the first 50 prime numbers? " +
            "Generate and run code for the calculation, and make sure you get all 50."
});
console.log("Chat response:", response.text);

برو

package main

import (
    "context"
    "fmt"
    "os"
    "google.golang.org/genai"
)

func main() {

    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

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

    chat, _ := client.Chats.Create(
        ctx,
        "gemini-2.5-flash",
        config,
        nil,
    )

    result, _ := chat.SendMessage(
                    ctx,
                    genai.Part{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.",
                              },
                )

    fmt.Println(result.Text())
    fmt.Println(result.ExecutableCode())
    fmt.Println(result.CodeExecutionResult())
}

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-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."
            }]
        }
    ]
}'

ورودی/خروجی (I/O)

با شروع از Gemini 2.0 Flash ، اجرای کد از ورودی فایل و خروجی نمودار پشتیبانی می‌کند. با استفاده از این قابلیت‌های ورودی و خروجی، می‌توانید فایل‌های CSV و متنی را آپلود کنید، در مورد فایل‌ها سؤال بپرسید و نمودارهای Matplotlib را به عنوان بخشی از پاسخ تولید کنید. فایل‌های خروجی به عنوان تصاویر درون‌خطی در پاسخ بازگردانده می‌شوند.

قیمت‌گذاری ورودی/خروجی

هنگام استفاده از ورودی/خروجی اجرای کد، برای توکن‌های ورودی و توکن‌های خروجی هزینه دریافت می‌شود:

توکن‌های ورودی:

  • درخواست کاربر

توکن‌های خروجی:

  • کد تولید شده توسط مدل
  • خروجی اجرای کد در محیط کد
  • توکن‌های تفکر
  • خلاصه تولید شده توسط مدل

جزئیات ورودی/خروجی

هنگام کار با ورودی/خروجی اجرای کد، از جزئیات فنی زیر آگاه باشید:

  • حداکثر زمان اجرای محیط کد 30 ثانیه است.
  • اگر محیط کد خطایی ایجاد کند، مدل ممکن است تصمیم بگیرد خروجی کد را دوباره تولید کند. این اتفاق می‌تواند تا ۵ بار رخ دهد.
  • حداکثر اندازه فایل ورودی توسط پنجره توکن مدل محدود می‌شود. در AI Studio، با استفاده از Gemini Flash 2.0، حداکثر اندازه فایل ورودی ۱ میلیون توکن است (تقریباً ۲ مگابایت برای فایل‌های متنی از انواع ورودی پشتیبانی شده). اگر فایلی را آپلود کنید که خیلی بزرگ باشد، AI Studio به شما اجازه ارسال آن را نمی‌دهد.
  • اجرای کد با فایل‌های متنی و CSV بهترین عملکرد را دارد.
  • فایل ورودی می‌تواند به صورت part.inlineData یا part.fileData (که از طریق Files API آپلود می‌شود) ارسال شود و فایل خروجی همیشه به صورت part.inlineData بازگردانده می‌شود.
نوبت تکی دو طرفه (API زنده چندوجهی)
مدل‌های پشتیبانی‌شده تمام مدل‌های Gemini 2.0 و 2.5 فقط مدل‌های آزمایشی فلش
انواع ورودی فایل پشتیبانی می‌شوند ‎.png، .jpeg، .csv، .xml، .cpp، .java، .py، .js، .ts ‎.png، .jpeg، .csv، .xml، .cpp، .java، .py، .js، .ts
کتابخانه‌های ترسیم نقشه پشتیبانی می‌شوند کتابخانه Matplotlib، سی‌بورن کتابخانه Matplotlib، سی‌بورن
استفاده چند ابزاری بله (فقط اجرای کد + اتصال زمین) بله

صورتحساب

هیچ هزینه اضافی برای فعال کردن اجرای کد از API Gemini وجود ندارد. هزینه شما بر اساس نرخ فعلی توکن‌های ورودی و خروجی و بر اساس مدل Gemini که استفاده می‌کنید، محاسبه خواهد شد.

در اینجا چند نکته دیگر وجود دارد که باید در مورد صدور صورتحساب برای اجرای کد بدانید:

  • شما فقط یک بار برای توکن‌های ورودی که به مدل می‌دهید، صورتحساب دریافت می‌کنید و برای توکن‌های خروجی نهایی که توسط مدل به شما بازگردانده می‌شود، صورتحساب دریافت خواهید کرد.
  • توکن‌هایی که نشان‌دهنده‌ی کد تولید شده هستند، به عنوان توکن‌های خروجی محسوب می‌شوند. کد تولید شده می‌تواند شامل متن و خروجی چندوجهی مانند تصاویر باشد.
  • نتایج اجرای کد نیز به عنوان توکن‌های خروجی شمارش می‌شوند.

مدل محاسبه‌ی هزینه‌ها در نمودار زیر نشان داده شده است:

مدل صدور صورتحساب اجرای کد

  • بر اساس مدل Gemini که استفاده می‌کنید، هزینه شما با نرخ فعلی توکن‌های ورودی و خروجی محاسبه می‌شود.
  • اگر Gemini هنگام تولید پاسخ شما از اجرای کد استفاده کند، اعلان اصلی، کد تولید شده و نتیجه کد اجرا شده، توکن‌های میانی نامیده می‌شوند و به عنوان توکن‌های ورودی ثبت می‌شوند.
  • سپس Gemini خلاصه‌ای تولید می‌کند و کد تولید شده، نتیجه کد اجرا شده و خلاصه نهایی را برمی‌گرداند. این‌ها به عنوان توکن‌های خروجی ثبت می‌شوند.
  • رابط برنامه‌نویسی Gemini شامل تعداد توکن‌های میانی در پاسخ API است، بنابراین می‌دانید که چرا توکن‌های ورودی اضافی فراتر از درخواست اولیه خود دریافت می‌کنید.

محدودیت‌ها

  • این مدل فقط می‌تواند کد تولید و اجرا کند. نمی‌تواند مصنوعات دیگری مانند فایل‌های رسانه‌ای را برگرداند.
  • در برخی موارد، فعال کردن اجرای کد می‌تواند منجر به رگرسیون در سایر حوزه‌های خروجی مدل شود (برای مثال، نوشتن یک داستان).
  • در توانایی مدل‌های مختلف برای استفاده موفقیت‌آمیز از اجرای کد، تفاوت‌هایی وجود دارد.

ترکیب ابزارهای پشتیبانی شده

ابزار اجرای کد را می‌توان با Grounding با جستجوی گوگل ترکیب کرد تا موارد استفاده پیچیده‌تری را پشتیبانی کند.

کتابخانه‌های پشتیبانی‌شده

محیط اجرای کد شامل کتابخانه‌های زیر است:

  • جذابیت‌ها
  • شطرنج
  • کانتورپی
  • اف پی دی اف
  • ژئوپانداها
  • ایمیجیو
  • جینجا۲
  • شغل‌محور
  • جی‌سون‌اسکِما
  • مشخصات jsonschema
  • lxml
  • مت‌پلات‌لیب
  • ام پی مت
  • نامپی
  • opencv-python
  • اوپن‌پایکسل
  • بسته بندی
  • پانداها
  • بالش
  • پروتوباف
  • پیلاتکس
  • پی‌پارسینگ
  • پای‌PDF2
  • پایتون-dateutil
  • پایتون-docx
  • پایتون-pptx
  • گزارش آزمایشگاه
  • سایکیت-لرن
  • اسکیپی
  • دریازاده
  • شش
  • استریپ‌آر‌تی‌اف
  • سمپی
  • جدول بندی کردن
  • تنسورفلو
  • ابزار
  • ایکس ال آر دی

شما نمی‌توانید کتابخانه‌های خودتان را نصب کنید.

قدم بعدی چیست؟