結論先說
- 新版
google-genaiPython SDK 支持直接傳原生函數:只要給 Python 函數寫清類型註解(Type Hints)與文檔字符串(Docstring),放入tools=[fn]即可由 SDK 自動轉成 JSON Schema 並預設完成本地執行與結果回傳。 - 生產環境帶寫操作接口建議關閉自動執行改用手動閉環:傳入
AutomaticFunctionCallingConfig(disable=True)後,代碼可以從response.function_calls拿到參數先做權限校驗與人工審批,再用Part.from_function_response回傳。 - 用
FunctionCallingConfig的mode解決不調或亂調:AUTO讓模型自決,ANY強制必調工具(可配合allowed_function_names限定白名單),NONE臨時封禁調用,VALIDATED則強化 Schema 嚴格校驗。 - 並行調用只需遍歷
response.function_calls數組:當用戶一句話問兩個獨立城市的庫存或天氣時,模型會在同一輪返回多條調用請求,你只需並發執行後放在同一個user/tool消息的多個Part裏一次性回傳。 - 谷歌開發帳號與編程主力訂閱入口:登入 Google AI Studio 創建與管理 API Key 需具備個人谷歌帳號,缺號可查看本站 谷歌帳號購買說明(含即買即發的 谷歌電郵成品號),跨平台主力編程會員總覽見 AI 會員充值中心。

圖:本站根據 Google Gemini API 文檔:Function calling 整理的示意圖
本文根據 Google Gemini API 官方文檔《Function calling with the Gemini API》及google-genaiSDK 參考手冊整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Google 官方網站。
適用於誰
- 想讓 Gemini 模型連接內部訂單庫、天氣接口或業務系統,不再侷限於純文本回答的後端與全棧開發者;
- 遇到模型「明明傳了工具卻不調」或「不該調工具時亂調」,需要用
AUTO / ANY / NONE精確約束行為的人; - 需要在一輪提問裏同時觸發多個查詢(Parallel Function Calling)並安全回傳執行結果的工程團隊。
一、最快跑通:SDK 自動函數調用 vs 手動受控閉環
在開始前請確認已安裝最新官方包 pip install google-genai(不要再用已停止維護的舊版 google-generativeai,初始化教學見 Gemini API Python 調用教學,Node.js 版寫法見 Gemini API Node.js 調用教學)。
1. 自動執行模式(適合只讀查詢接口)
直接把帶類型註解和清晰英文/中文註釋的函數塞進 tools,SDK 會自動攔截模型的調用意圖、在本地跑完你的 Python 函數,再把返回值送回模型生成最終答覆:
python
from google import genai
from google.genai import types
client = genai.Client()
def get_order_status(order_id: str) -> dict:
"""根據訂單號查詢當前物流與支付狀態。
Args:
order_id: 訂單唯一編號,例如 ORD-20261118
"""
return {"order_id": order_id, "status": "已發貨", "carrier": "SF-Express"}
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="幫我查一下訂單 ORD-20261118 發什麼快遞了?",
config=types.GenerateContentConfig(tools=[get_order_status]),
)
print(response.text)
2. 手動受控模式 + 並行工具調用處理
涉及扣款、刪庫、發電郵或需要並發請求多個微服務的場景,應當關閉自動調用,自行遍歷 response.function_calls(同一輪可能包含 1 個或多個並行調用):
python
config = types.GenerateContentConfig(
tools=[get_order_status],
automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True),
)
contents = [types.Content(role="user", parts=[
types.Part.from_text(text="同時查一下 ORD-1001 和 ORD-1002 兩個訂單狀態")
])]
resp = client.models.generate_content(model="gemini-2.5-flash", contents=contents, config=config)
if resp.function_calls:
contents.append(resp.candidates[0].content) # 必須保留模型本輪返回的調用記錄
tool_parts = []
for call in resp.function_calls:
result = get_order_status(**call.args)
tool_parts.append(types.Part.from_function_response(name=call.name, response=result))
contents.append(types.Content(role="user", parts=tool_parts))
final_resp = client.models.generate_content(model="gemini-2.5-flash", contents=contents, config=config)
print(final_resp.text)
注意回傳前必須把 resp.candidates[0].content 原樣追加進 contents 歷史,尤其在使用帶思考鏈(Thinking)的 Gemini 模型時,原響應裏包含思考簽名(Thought Signatures),漏傳會導致下一輪校驗報錯。
二、AUTO / ANY / NONE / VALIDATED 四種模式怎麼控
如果遇到模型只用文字敷衍而不觸發函數,或者你想把函數調用當成 100% 穩定的意圖路由器,通過 tool_config 即可精準鎖定(對比 OpenAI 的 tool_choice 寫法見 OpenAI API 函數調用怎麼寫):
python
forced_config = types.GenerateContentConfig(
tools=[get_order_status],
automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True),
tool_config=types.ToolConfig(
function_calling_config=types.FunctionCallingConfig(
mode="ANY",
allowed_function_names=["get_order_status"],
)
),
)
AUTO(預設值):閒聊問題直接回文字,業務問題調函數;ANY(強制調用):強制模型本輪必須輸出函數調用,配合allowed_function_names可把可選範圍縮小到指定子集,非常適合多智能體網關分發;NONE(禁止調用):不刪tools定義(保留上下文理解),但本輪嚴禁再發起新調用,常用於「已重試兩次工具仍失敗,強制模型基於現有資訊給用戶總結道歉」;VALIDATED(嚴格模式):行為與AUTO相似,但在底層通過受約束解碼確保函數參數嚴格符合你聲明的 Schema 類型。若只是讓模型寫算術邏輯自己算結果,也可改開官方託管沙盒,見 Gemini API 代碼執行工具怎麼開。
谷歌開發帳號與 AI 編程工具提示:在 Google AI Studio 調試 Function Calling 或綁定結算卡前需登入合規個人谷歌帳號,缺可用帳號可在本站直接選購 谷歌電郵成品號(說明見 谷歌帳號購買頁);日常寫後端膠水代碼還可搭配 Claude Code 或 ChatGPT Plus 提效。

圖:本站根據 Google Gemini API 文檔:Function calling 整理的示意圖
三、提高工具命中率的三條 Schema 實戰建議
- 函數描述寫清「什麼時候調、什麼時候別調」:模型完全靠函數名與參數描述理解業務語義,避免用
func1、data這類模糊命名,枚舉值直接用Literal["pending", "paid"]或在 Schemaenum裏定死。 - 單次掛載函數數量控制在 10–20 個以內:官方工程建議指出,同一請求塞入幾十上百個複雜函數會同時拉高輸入 Token 成本與選錯工具的概率,工具過多時應先做一層意圖分類。
- 調低採樣隨機性或保持模型推薦預設溫度:對於 Gemini 2.5 及更新模型,盡量保持官方預設溫度(部分帶思考模型強改
temperature=0反而影響推理鏈),把確定性交給VALIDATED或ANY模式來保障。
常見問題
問:為什麼我傳了 Python 函數,調試時沒看到 response.function_calls,直接就打印出最終中文答案了?
答:因為 google-genai SDK 預設開啟了 Automatic Function Calling,它在底層已經悄悄替你調用了本地函數並完成了第二輪請求。想在中間攔截參數,務必按上文加上 AutomaticFunctionCallingConfig(disable=True)。
問:外部接口查詢報錯(比如訂單號不存在)時,應該直接拋異常中斷還是回傳給模型?
答:建議捕獲業務異常後,封裝成結構化字典(如 {"error": "訂單號不存在,請核對是否為 ORD 開頭"})通過 from_function_response 正常回傳給模型,這樣模型能禮貌引導用戶重輸正確單號,而不是讓整個對話接口直接崩成 500。
問:並行調用返回了 3 個函數請求,我可以只回傳其中 1 個的結果嗎?
答:不可以。模型在同一輪發出 N 個 function_call 時,下一輪迴傳的 user 消息裏必須包含對應數量的 function_response Part,漏傳會導致會話狀態不匹配報錯。
問:沒有可用的個人谷歌帳號申請 Gemini API,或者想開通其他 AI 會員怎麼買,能開發票嗎?
答:本站提供即買即發的 谷歌電郵成品號,同時在 AI 會員充值總覽 支持支付寶、微信支付與 AlipayHK 自助開通 Claude Code、ChatGPT Plus 等服務(支持免交密碼卡密兌換及企業增值稅發票開具);實時價格與售後保障(掉訂閱按剩餘天數折退,封號不在質保範圍)以各商品頁說明為準。
相關教學
- Gemini API Python 調用教學:安裝 google-genai SDK、流式輸出與多輪對話
- Gemini API Node.js / JavaScript 調用教學:@google/genai 安裝與函數調用
- OpenAI API 函數調用(function calling)怎麼寫:tools 定義與回傳
- Gemini API 代碼執行(Code Execution)工具怎麼開
參考資料
- Google Gemini API 官方文檔:Function calling with the Gemini API — https://ai.google.dev/gemini-api/docs/function-calling
- Google Gen AI Python SDK 官方參考手冊 — https://googleapis.github.io/python-genai/
0 條評論
還沒有評論,來搶沙發~