结论先说
- 开启只需在
tools里声明google_search工具:Interactions API 传tools=[{"type": "google_search"}],模型会自动判断是否需要检索并自行生成一条或多条搜索词。 - 返回结果自带字符级精确引用坐标:在 Interactions API 中读取文本块的
annotations(类型为url_citation,含start_index、end_index、title与url);在generateContent中则读取grounding_metadata。 - 付费层每月提供 5,000 次免费搜索请求(跨 Gemini 3 及更新模型共享),超出后按每 1,000 次请求
14 美元计费,默认每日上限为1,500次请求。 - 只有模型实际发起了检索才会产生搜索工具调用记录;普通逻辑推理或无需联网的提问虽然挂着工具,但未触发搜索时不扣搜索配额。
- 谷歌账号准备与多工具订阅入口:使用 Gemini、Google AI Studio 与 Antigravity 需具备符合地区与年龄要求的个人谷歌账号,缺号可查看本站 谷歌账号购买说明(含带 2FA 的 谷歌邮箱成品号),跨平台付费订阅总览见 AI 会员充值中心。

图:本站根据 Google Gemini API 文档:Grounding with Google Search 整理的示意图
本文根据 Google Gemini API 官方文档《Grounding with Google Search》《Gemini Developer API Pricing》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 想让基于 Gemini API 开发的应用回答最新新闻、赛事比分、股价动态或新发布技术文档,减少模型幻觉的开发者;
- 调通了联网回答,却不知道怎么从返回 JSON 里提取来源链接做前端角标高亮的人;
- 需要核算生产环境成本,想弄清每月免费搜索次数、每千次单价与每日配额上限的团队。
一、开启参数:Interactions API 与 generateContent 写法
如果你先在网页沙盒测试联网效果,操作入口见 Google AI Studio 系统指令与运行设置。迁移到代码调用时,官方 SDK(安装见 Gemini API Python 调用教程)支持以下两种主流接口:
1. Interactions API(推荐新一代接口)
python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="2026 年最新发布的 TypeScript 主版本有哪些核心改动?",
tools=[{"type": "google_search"}],
)
print(interaction.output_text)
2. generateContent 接口写法
如果现有工程基于 models.generate_content 构建,则在配置对象中挂载 google_search:
python
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="查询本周美联储议息会议的最新利率决议结果",
config=types.GenerateContentConfig(
tools=[types.Tool(google_search=types.GoogleSearch())]
),
)
print(response.text)
需要注册 Google 账号前往 AI Studio 创建 API Key 时,也可在本站查看 谷歌账号说明。
二、解析引用来源元数据与展示搜索入口
开启联网后,把出处链接渲染到界面上不仅方便用户核验真伪,也是合规展示的重要一环。按接口不同,返回结构对应关系如下:
| 元数据内容 | Interactions API 字段位置 | generateContent 字段位置 |
|---|---|---|
| 模型实际搜了什么词 | google_search_call 步骤的 arguments.queries | grounding_metadata.web_search_queries |
| 网页标题与目标 URL | 文本块 annotations 里的 title 与 url | grounding_metadata.grounding_chunks |
| 正文对应字符起止位置 | url_citation 的 start_index / end_index | grounding_metadata.grounding_supports |
| 搜索建议挂件 HTML | google_search_result 的 search_suggestions | grounding_metadata.search_entry_point |
以 Interactions API 为例,提取每句话对应引用来源的 Python 代码如下:
python
for step in interaction.steps:
if step.type == "model_output":
for block in step.content:
if block.type == "text" and block.annotations:
for ann in block.annotations:
if ann.type == "url_citation":
snippet = block.text[ann.start_index:ann.end_index]
print(f"原文片段: {snippet} -> 来源: {ann.title} ({ann.url})")
注意按 Google 服务条款关于 Grounding with Google Search 的展示要求,商业应用面向外部用户展示联网回答时,还应将返回的 search_suggestions(或 search_entry_point)HTML 搜索建议组件按规范渲染在界面中。横向对比 OpenAI 与 Claude 的联网接口写法,可查阅 OpenAI API 联网搜索工具怎么用 与 Claude API 联网搜索工具怎么用。

图:本站根据 Google Gemini API 文档:Gemini Developer API Pricing 整理的示意图
谷歌开发账号与主力编程订阅提示:若当前账号卡在地区不支持、手机核验或工作空间限制,可在本站选购已配置两步验证的 谷歌账号成品号(即时发货,质保首登,到手请按指引先登后改密);日常搭配主力模型开发,也可同步了解免境外卡自助兑换的 ChatGPT Plus 与 Claude Pro。
三、计费规则、免费额度与每日配额上限
除常规的模型输入输出 token 费用外,联网搜索工具在付费层(Paid Tier)按请求独立核算:
- 每月免费赠送额度:付费层项目每月包含 5,000 次免费搜索请求,该额度在项目下所有受支持的 Gemini 3 及更新代际模型之间共享;
- 超额按量单价:当月超过 5,000 次后,按 每 1,000 次请求 14 美元 计收工具费;
- 每日保护上限(Daily Cap):为防代码死循环刷爆账单,官方默认设置每个项目每天最多 1,500 次搜索请求(1,500 RPD),业务量增大时可在 Google AI Studio 配额页面申请调高。完整模型 token 费率见 Gemini API 价格。
常见问题
问:我已经传了 google_search,为什么返回结果里没有 annotations 引用?
答:挂载工具代表「允许模型联网」,不代表强制搜索。如果问的是常识性编程语法(如冒泡排序怎么写),模型认为自身知识足够解答就不会触发 google_search_call,自然也不会返回网页引用。需要查实时信息时可在提示词里明确写「请联网检索最新官方公告并附上来源」。
问:能不能同时指定某几个特定网页让它读,又允许它全网搜索?
答:可以。官方文档说明 Grounding with Google Search 支持与 URL Context 工具组合传入,让模型既能精读你给出的指定 URL 正文,又能补充检索公开网页信息。
问:一次对话里模型自动拆了 3 个搜索词,怎么判断触发了联网?
答:查看返回的 steps 中是否包含 "type": "google_search_call"(或检查 web_search_queries 是否非空),里面会完整列出本轮模型实际下发的查询词数组。
问:没有可用的个人谷歌账号,或者同时想开其他主流 AI 会员怎么办?
答:本站提供即买即发的 谷歌邮箱成品号(登录方法见 谷歌账号购买页),同时支持支付宝、微信支付与 AlipayHK 自助充值 ChatGPT Plus、Claude Code 等主流服务,实时价格与质保细则以各商品页说明为准。
相关教程
- Gemini API 价格:各模型每百万 tokens 多少钱、免费层和付费层差在哪
- Google AI Studio 系统指令怎么写:System instructions 与运行设置(思考等级、温度、联网搜索)
- OpenAI API 联网搜索工具(web search)怎么用
- Claude API 联网搜索工具(web search tool)怎么用
参考资料
- Google Gemini API 官方文档:Grounding with Google Search(Interactions API) — https://ai.google.dev/gemini-api/docs/google-search
- Google Gemini API 官方文档:Grounding with Google Search(generateContent) — https://ai.google.dev/gemini-api/docs/generate-content/google-search
- Google Gemini API 官方文档:Gemini Developer API Pricing — https://ai.google.dev/gemini-api/docs/pricing
0 条评论
还没有评论,来抢沙发~