תכונת הרצת הקוד של Gemini API מאפשרת למודל ליצור ולהריץ קוד Python, וללמוד באופן איטרטיבי מהתוצאות עד שהוא מגיע לפלט הסופי. אתם יכולים להשתמש ביכולת הזו של הרצת קוד כדי לפתח אפליקציות שמפיקות תועלת מהסקת מסקנות שמבוססת על קוד ומפיקות פלט טקסט. לדוגמה, אפשר להשתמש בהרצת קוד באפליקציה שפותרת משוואות או מעבדת טקסט.
Gemini API מספק הרצת קוד ככלי, בדומה לקריאה להפעלת פונקציות. אחרי שמוסיפים את הרצת הקוד ככלי, המודל מחליט מתי להשתמש בו.
סביבת ההפעלה של הקוד כוללת את הספריות הבאות. אי אפשר להתקין ספריות משלכם.
- Altair
- Chess
- Cv2
- Matplotlib
- Mpmath
- NumPy
- Pandas
- Pdfminer
- Reportlab
- Seaborn
- Sklearn
- Statsmodels
- Striprtf
- SymPy
- Tabulate
מודלים נתמכים
המודלים הבאים תומכים בהרצת קוד:
כדי להרחיב את רשימת המודלים הנתמכים, לוחצים כאן
איך מתחילים להשתמש בהרצת קוד
ההנחה היא שכבר ביצעתם את שלבי ההגדרה שמופיעים במאמר תחילת העבודה עם Gemini Enterprise Agent Platform.
הפעלת הרצת קוד
כדי להפעיל את המודל לשימוש בהרצת קוד, מוסיפים אותו לרשימה tools כשמגדירים את המודל:
Python
התקנה
pip install --upgrade google-genai
מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.
מגדירים משתני סביבה כדי להשתמש ב-Google 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.
מגדירים משתני סביבה כדי להשתמש ב-Google 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.
מגדירים משתני סביבה כדי להשתמש ב-Google 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.
מגדירים משתני סביבה כדי להשתמש ב-Google 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: האזור שבו הבקשה תעובד. -
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 כולל בתגובה מה-API את כמות טוקני הביניים, כדי שתוכלו לעקוב אחרי טוקני קלט נוספים מעבר לאלה שהועברו בהנחיה הראשונית.
הקוד שנוצר יכול לכלול גם טקסט וגם פלט מולטימודלי, כמו תמונות.
מגבלות
- המודל יכול רק ליצור ולהריץ קוד. הוא לא יכול להחזיר פריטים אחרים, כמו קובצי מדיה.
- כלי הרצת הקוד לא תומך בכתובות URI של קבצים כקלט או כפלט. עם זאת,
כלי הרצת הקוד תומך בקלט של קבצים ובפלט של גרפים כבייטים מוטבעים. באמצעות היכולות האלה של קלט ופלט, אתם יכולים להעלות קובצי CSV וקובצי טקסט, לשאול שאלות לגבי הקבצים ולקבל גרפים של Matplotlib שנוצרים כחלק מתוצאת הביצוע של הקוד.
סוגי ה-MIME שנתמכים לבייטים מוטבעים הם
.cpp,.csv,.java,.jpeg,.js,.png,.py,.tsו-.xml. - הפעלת הקוד יכולה להימשך עד 30 שניות לפני שהזמן הקצוב לתפוגה נגמר.
- במקרים מסוימים, הפעלת הרצת הקוד עלולה להוביל לרגרסיות בתחומים אחרים של הפלט מהמודל (לדוגמה, כתיבת סיפור).
שיטות מומלצות ואזהרות
ריכזנו כאן כמה שיטות מומלצות והנחיות לשימוש בהרצת קוד:
- הוראות ביצוע מפורשות: מודלים גדולים של שפה עשויים להשתמש כברירת מחדל בהסקה לשונית, אלא אם תורו להם אחרת. כשאתם נותנים הוראות להרצת קוד, השתמשו בהנחיות מפורשות (לדוגמה, "תמיד צריך להריץ את הסקריפט" או "אל תחשב ישירות").
- בידוד הרשת: לארגז החול להרצת הקוד אין גישה לאינטרנט הציבורי. סקריפטים לא יכולים לשלוח בקשות HTTP חיצוניות או להוריד משאבים חיצוניים.
- ביצוע ללא שמירת מצב: כל ביצוע פועל במאגר זמני. קבצים שנוצרו או שונו במהלך תור אחד לא נשמרים בתורים או בסשנים הבאים.
- יחסי תלות: אפשר להשתמש רק בספריות Python רגילות ובחבילות שמותקנות מראש לטיפול בנתונים (כמו
numpyאוpandas). הסביבה לא תומכת בהתקנות דינמיות של חבילות בזמן ריצה (כמוpip install). - קלט/פלט סטנדרטי: כותבים סקריפטים שמקבלים קלט מארגומנטים של שורת הפקודה (
sys.argv) או מקלט סטנדרטי (sys.stdin), ומדפיסים את התוצאה ישירות לפלט סטנדרטי (sys.stdout).