Gemini API Google Search Grounding 怎么验收：查询链、引用标注与失败边界

AI 客服回答“今天的活动规则是什么”时，最危险的不是回答速度慢，而是模型把旧信息说得像刚查过。Gemini API 的 Google Search Grounding 可以让模型自动检索实时网页，并在响应中返回搜索步骤和 URL 引用，但“打开工具”不等于“每句话都有可用证据”。验收时要同时看检索是否发生、引用是否落到正文和来源是否真的支持结论。

先把 Grounding 链路拆成四个可验收节点

Google 的官方说明把这条链路拆得很清楚：应用提交问题和 google_search 工具，模型分析是否需要搜索，随后自动生成一个或多个查询并处理结果，最后返回带 URL 引用的回答。工程上可以把它落成四个节点：请求配置、搜索调用、结果处理、文本引用。

这四个节点不能只看最后一段回答。用户问一个明确的实时问题时，如果响应里没有搜索调用，说明模型判断当前请求不需要检索；如果有搜索调用但最终文本没有 URL 引用，就不能把回答当成已核验内容展示。

用当前工具配置发出最小请求

下面示例只保留最小配置，先验证工具链路是否通，再往业务提示里加入输出格式和风险策略。

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="请查找本周公开发布的一个 AI 开发者活动，并给出官方来源。",
    tools=[{"type": "google_search"}],
)

print(interaction.output_text)
for step in interaction.steps:
    print(step.type)

不同 SDK 对响应对象的字段封装会变化，调试阶段建议保留原始 JSON。至少要能找到搜索调用的查询数组、搜索结果步骤，以及模型文本块上的 url_citation 标注。不要只打印 output_text 后再尝试从文字里猜来源。

引用标注才是可交付的证据

一个可用的引用通常包含 URL、标题以及在回答文本中的起止位置。起止位置让前端知道哪句话对应哪个来源；如果只把所有链接堆在回答底部，用户无法判断哪条事实由哪篇页面支持。

建议把每次响应转换成自己的审计结构：answer_text 保存最终文本，citations 保存 URL、标题、start_index 和 end_index，search_queries 保存模型实际发出的查询。展示层只渲染通过边界检查的引用，越界或找不到对应文本的标注直接降级为“待复核”。

高频故障不在模型，而在验收边界

把搜索建议当成引用

搜索结果步骤可能包含建议展示内容，但它不是正文事实的来源映射。前端应优先使用文本块里的 URL 引用，并把建议当作可选的搜索体验信息。

只检查“有搜索调用”

有搜索调用只能说明检索动作发生，不能证明最终答案里的日期、价格或规则都被来源覆盖。对于敏感事实，必须逐条检查引用范围和来源页面。

继续沿用旧工具名

当前模型使用 google_search。旧模型曾使用另一套搜索工具名称，迁移时如果只改模型、不改工具配置，最容易得到兼容性或能力判断错误。

把搜索失败当作空答案

网络、配额或来源质量都可能让搜索链失败。应用应保留错误类型和原始请求摘要，向用户明确提示“暂未完成来源核对”，而不是返回一段没有证据的确定语气。

上线前用两组请求做回归

第一组使用近期事实问题，检查是否出现搜索调用和 URL 引用；第二组使用不需要实时资料的常识问题，确认系统不会把所有回答都强行标成已检索。两组都记录模型名、工具配置、查询数组、引用数量、无效引用数量和总耗时。

• 引用起止位置按 SDK 的索引规则处理，中文文本不要在前端二次改写后再套原索引。
• 来源页面标题和 URL 需要原样保留，清洗只去掉展示层不需要的追踪参数。
• 对日期、价格、政策等问题设置人工复核或来源白名单，不把模型置信语气当作证据强度。
• 当响应没有引用时，明确区分“模型判断无需搜索”和“搜索链异常”。

常见问题

Google Search Grounding 会每次都搜索吗？

不会。模型会先判断搜索是否能改善回答，因此验收逻辑不能假设每个请求都有搜索调用。

怎样从响应里提取来源？

读取最终文本块上的 URL 引用标注，并结合起止位置关联到对应句子；搜索词和搜索建议只能作为辅助信息。

可以同时使用 URL Context 吗？

可以。官方文档说明 Google Search Grounding 能与 URL Context 等工具组合，但组合后应分别记录各工具步骤，避免把指定网页和搜索网页混成一个来源集合。

没有引用的回答能直接展示吗？

对于实时事实，不建议直接以“已核验”状态展示。可以返回普通回答，但要降低可信等级并提示用户通过官方来源复查。

把实时检索做成可回放的证据链

Grounding 的价值不只在于让模型查网页，更在于把查询、检索动作和文本引用连成一条可复核记录。先保存原始响应，再做引用边界检查和来源分级，系统才有能力解释“为什么这样回答”，也能在来源失效时快速回退。