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 条评论

登录 后参与评论

还没有评论,来抢沙发~