Gemini API 函數調用(Function Calling)怎麼寫:AUTO / ANY / NONE 模式控制、並行工具調用與代碼示例

用新一代 google-genai SDK 怎麼讓 Gemini 穩定調用外部接口?本文按官方文檔詳解自動與手動函數調用寫法、AUTO / ANY / NONE / VALIDATED 四種控制模式,以及並行工具調用代碼模板。

NNathaniel bigo··原創首發·AI 輔助撰寫
11 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 其他 帳號

結論先說

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

Gemini 函數調用控制模式對照表

圖:本站根據 Google Gemini API 文檔:Function calling 整理的示意圖

本文根據 Google Gemini API 官方文檔《Function calling with the Gemini API》及 google-genai SDK 參考手冊整理,資料核對於 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 提效。

Gemini 函數調用四步執行閉環

圖:本站根據 Google Gemini API 文檔:Function calling 整理的示意圖

三、提高工具命中率的三條 Schema 實戰建議

  1. 函數描述寫清「什麼時候調、什麼時候別調」:模型完全靠函數名與參數描述理解業務語義,避免用 func1、data 這類模糊命名,枚舉值直接用 Literal["pending", "paid"] 或在 Schema enum 裏定死。
  2. 單次掛載函數數量控制在 10–20 個以內:官方工程建議指出,同一請求塞入幾十上百個複雜函數會同時拉高輸入 Token 成本與選錯工具的概率,工具過多時應先做一層意圖分類。
  3. 調低採樣隨機性或保持模型推薦預設溫度:對於 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 等服務(支持免交密碼卡密兌換及企業增值稅發票開具);實時價格與售後保障(掉訂閱按剩餘天數折退,封號不在質保範圍)以各商品頁說明為準。

相關教學

參考資料

  • 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/

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同模型

  1. 01

    用 Google Takeout 單獨備份導出 NotebookLM 筆記本與 Gemini 記錄:只勾選指定服務不下載整個雲端硬碟的步驟

    想把 NotebookLM 裏的幾十個研究筆記本、來源副本與音頻概覽,連同 Gemini 聊天記錄一起備份到本地,又怕 Google Takeout 把整個雲端硬碟和相冊全打包?本文講清先取消全選、精準勾選兩項服務、解壓目錄查看與跨號遷移的做法。

    Gemini0
  2. 02

    Google Workspace 企業/教育版管理員怎麼在後台給成員開啟 Gemini 應用、NotebookLM 與設定年齡訪問權限

    團隊成員或學校師生登入 Google Workspace 帳號時提示無權使用 Gemini 或打不開 NotebookLM?本文按 Google 管理控制檯官方文檔整理服務開關路徑、組織部門(OU)與群組放行、18 歲年齡訪問權限設定及對話保留合規配置。

    Gemini0
  3. 03

    安卓手機預設助手換成 Gemini 後設鬧鐘、發短訊或控制智能家居失靈怎麼辦:Workspace 與實用程序擴展開啟步驟

    安卓手機把預設語音助手從 Google Assistant 換成 Gemini 後,喊它定鬧鐘、開手電筒、發短訊或開關智能燈全都沒反應?本文按官方幫助中心整理實用程序(Utilities)、Google Home 與 Workspace 關聯應用開啟步驟及鎖屏放行設定。

    Gemini0
  4. 04

    Gemini 寫長代碼或長文檔到一半突然停住、格式截斷怎麼無縫續寫:錨點接續指令與 Canvas 分塊修改技巧

    讓 Gemini 寫幾百行代碼或萬字長文時經常寫到一半突然停住、Markdown 代碼塊沒閉合,直接回「繼續」又重頭抄一遍?本文整理字面錨點續寫指令、代碼塊防亂碼補齊法與 Canvas 局部圈選修改工作流。

    Gemini0
  5. 05

    NotebookLM 中文音頻播客(Audio Overview)高階玩法:用自定義引導詞控制對談深度、受眾水平與重點章節(附模板)

    NotebookLM 生成的中文音頻播客總是泛泛而談、漏掉核心章節或夾雜生僻英文縮寫?本文按官方幫助中心整理來源勾選過濾、四種播客格式搭配與三維自定義引導詞寫法,附 4 套可直接複製的中文控場模板。

    Gemini0
  6. 06

    NotebookLM 添加 YouTube 影片、網頁或掃描版 PDF 提示「無法導入來源」怎麼辦:無字幕、反爬與純圖 PDF 逐項解決

    往 NotebookLM(Gemini Notebook)塞 YouTube 連結、外文網頁或掃描教材時總是亮紅歎號提示無法導入來源?本文按官方幫助中心逐項排查無字幕影片、反爬動態頁與加密純圖 PDF 的替代導入步驟。

    Gemini0

同產品的其他教學

  1. 01

    iPhone 操作按鈕(Action Button)或鎖屏小組件一鍵開啟 ChatGPT / Gemini 實時語音對話配置教學

    每次在 iPhone 上練口語或語音提問都要解鎖、找圖標、再點耳機按鈕太繁瑣?本文整理利用 iPhone 操作按鈕(Action Button)、iOS 18 鎖屏底部控制項、控制中心與背面輕點一鍵直達 ChatGPT 實時語音或 Gemini Live 的完整步驟。

    ChatGPTGemini0
  2. 02

    Firebase Studio(原 Project IDX)是什麼、怎麼用:瀏覽器雲端全棧開發環境搭配 Gemini 智能體實戰

    以前收藏的 Project IDX 網址為什麼跳到了 Firebase Studio?本文按 Google 官方文檔講清它的全棧雲端定位、App Prototyping 原型智能體、Code 視圖切換、.idx/dev.nix 環境定製與免費工作區上限。

    Gemini其他 AI 工具0
  3. 03

    Google Colab 內置 Gemini 編程助手怎麼用:免費雲端 GPU 筆記本自動生成數據分析代碼、修報錯與限額說明

    不用配本地 Python 環境,怎麼在 Google Colab 雲端筆記本里免費用 Gemini 自動寫數據分析代碼、一鍵修復紅字報錯並跑 Data Science Agent?本文整理四大入口用法、Secrets 密鑰管理與免費版限額。

    Gemini其他 AI 工具0
  4. 04

    Gemini API Token 計數(count_tokens)與多模態計費規則:圖片解像度、音頻秒數與影片幀率怎麼折算 Token

    傳一張高清截圖或一段 10 分鐘影片給 Gemini API 到底扣多少 Token?本文按官方文檔拆解 258 圖片切片、每秒 32 音頻與每秒 263 影片折算公式,附 count_tokens 免費預估與降本代碼。

    Gemini0
  5. 05

    Gemini API 回答被安全策略攔截(SAFETY / PROHIBITED_CONTENT)怎麼辦:閾值調節邊界與合規提示詞排查

    調用 Gemini API 翻譯文檔或分析安全日誌時返回空白、報 finish_reason: SAFETY 或 PROHIBITED_CONTENT 怎麼辦?本文詳解四類可調安全閾值代碼寫法、不可關閉的硬性紅線區別與誤報排查步驟。

    Gemini0
  6. 06

    Gemini API 圖像生成與多輪改圖怎麼調:用 google-genai SDK 出圖、局部修改與寬高比控制參數

    怎麼用 Python 代碼調用 Gemini API 生成高清配圖並像聊天一樣連續局部改圖?本文詳解 google-genai SDK 原生生圖代碼、多輪對話改圖、參考圖融合與 aspect_ratio 寬高比配置。

    Gemini0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~