有了 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 參考文件。
設定環境變數,以便透過 Vertex AI 使用 Google Gen AI SDK:
# 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 參考文件。
設定環境變數,透過 Vertex AI 使用 Google Gen AI SDK:
# 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 參考文件。
設定環境變數,透過 Vertex AI 使用 Google Gen AI SDK:
# 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 參考文件。
設定環境變數,透過 Vertex AI 使用 Google Gen AI SDK:
# 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:您的專案 ID。。MODEL_ID:要使用的模型 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)。 - 標準 I/O:編寫指令碼,接受來自指令列引數 (
sys.argv) 或標準輸入 (sys.stdin) 的輸入內容,然後直接將結果列印至標準輸出 (sys.stdout)。