结论先说
- 新版
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 条评论
还没有评论,来抢沙发~