התכונה 'הרצת קוד' ב-Gemini API מאפשרת למודל ליצור ולהריץ קוד Python, וללמוד מהתוצאות באופן איטרטיבי עד שהוא מגיע לפלט סופי. אתם יכולים להשתמש ביכולת הזו להרצת קוד כדי ליצור אפליקציות שמפיקות תועלת מהסקה שמבוססת על קוד ומייצרות פלט טקסטואלי. לדוגמה, אפשר להשתמש בהרצת קוד באפליקציה שפותרת משוואות או מעבדת טקסט.
Gemini API מספק כלי להרצת קוד, בדומה לבקשה להפעלת פונקציה. אחרי שמוסיפים את הפעלת הקוד ככלי, המודל מחליט מתי להשתמש בו.
סביבת ההפעלה של הקוד כוללת את הספריות הבאות. אי אפשר להתקין ספריות משלכם.
- Altair
- Chess
- Cv2
- Matplotlib
- Mpmath
- NumPy
- Pandas
- Pdfminer
- Reportlab
- Seaborn
- Sklearn
- Statsmodels
- Striprtf
- SymPy
- Tabulate
מודלים נתמכים
המודלים הבאים תומכים בהרצת קוד:
אפשר ללחוץ כדי להרחיב את רשימת המודלים הנתמכים
תחילת העבודה עם הפעלת קוד
ההנחה היא שסיימתם את שלבי ההגדרה והקביעה שמופיעים במדריך למתחילים בנושא 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
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
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
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
REST
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
-
GENERATE_RESPONSE_METHOD: סוג התגובה שרוצים שהמודל ייצור. בוחרים שיטה ליצירת התשובה של המודל:-
streamGenerateContent: התשובה מועברת בסטרימינג בזמן שהיא נוצרת, כדי לצמצם את תפיסת זמן האחזור בקרב קהל אנושי. -
generateContent: התשובה מוחזרת אחרי שהיא נוצרת במלואה.
-
-
LOCATION: האזור שבו הבקשה תעובד. האפשרויות הזמינות כוללות את האפשרויות הבאות:כאן אפשר ללחוץ כדי להרחיב את הרשימה החלקית של האזורים הזמינים
us-central1us-west4northamerica-northeast1us-east4us-west1asia-northeast3asia-southeast1asia-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 שניות לפני שפג הזמן הקצוב לתפוגה.
- במקרים מסוימים, הפעלת ביצוע קוד עלולה להוביל לרגרסיות בתחומים אחרים של פלט המודל (לדוגמה, כתיבת סיפור).