使用 Google 搜索建立依据

依托 Google 搜索进行接地功能会将 Gemini 模型连接到实时网络内容,并支持所有可用语言。这样,Gemini 就可以提供更准确的回答,并引用知识截点之外的可验证来源。

使用依据功能可帮助您构建能够执行以下操作的应用:

  • 提高事实准确性: 以真实世界的信息为依据,减少模型幻觉。
  • 访问实时信息: 回答有关近期活动和主题的问题。
  • 提供引用: 通过显示模型声明的来源来建立用户信任。

Python

from google import genai
from google.genai import types

client = genai.Client()

grounding_tool = types.Tool(
    google_search=types.GoogleSearch()
)

config = types.GenerateContentConfig(
    tools=[grounding_tool]
)

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Who won the euro 2024?",
    config=config,
)

print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const groundingTool = {
  googleSearch: {},
};

const config = {
  tools: [groundingTool],
};

const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: "Who won the euro 2024?",
  config,
});

console.log(response.text);

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "Who won the euro 2024?"}
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

您可以试用搜索工具 笔记本,了解更多信息。

依托 Google 搜索进行接地功能的运作方式

启用 google_search 工具后,模型会自动处理搜索、处理和引用信息的整个工作流。

grounding-overview

  1. 用户提示: 您的应用会在启用 google_search 工具的情况下将用户提示发送给 Gemini API。
  2. 提示分析: 模型会分析提示,并确定 Google 搜索是否可以改进回答。
  3. Google 搜索: 如果需要,模型会自动生成一个或多个搜索查询并执行这些查询。
  4. 搜索结果处理: 模型会处理搜索结果、综合信息并制定回答。
  5. 有依据的回答: API 会返回一个最终的、用户友好的回答,该回答以搜索结果为依据。此回答包含模型的文本回答和 groundingMetadata,其中包含搜索查询、网页结果和引用。

了解有依据的回答

如果回答成功建立依据,则该回答会包含 groundingMetadata 字段。此结构化数据对于验证声明和在应用中构建丰富的引用体验至关重要。

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "UEFA Euro 2024 winner",
          "who won euro 2024"
        ],
        "searchEntryPoint": {
          "renderedContent": "<!-- HTML and CSS for the search widget -->"
        },
        "groundingChunks": [
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "aljazeera.com"}},
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "uefa.com"}}
        ],
        "groundingSupports": [
          {
            "segment": {"startIndex": 0, "endIndex": 85, "text": "Spain won Euro 2024, defeatin..."},
            "groundingChunkIndices": [0]
          },
          {
            "segment": {"startIndex": 86, "endIndex": 210, "text": "This victory marks Spain's..."},
            "groundingChunkIndices": [0, 1]
          }
        ]
      }
    }
  ]
}

Gemini API 会随 groundingMetadata 返回以下信息:

  • webSearchQueries:所用搜索查询的数组。这有助于调试和了解模型的推理过程。
  • searchEntryPoint :包含用于呈现所需搜索建议的 HTML 和 CSS。如需了解完整的使用要求,请参阅服务 条款
  • groundingChunks :包含网页来源(urititle)的对象数组。
  • groundingSupports :用于将模型回答 text 连接到 groundingChunks 中的来源的块数组。每个块都会将文本 segment(由 startIndexendIndex 定义)链接到一个或多个 groundingChunkIndices。这是构建内嵌引用的关键。

依托 Google 搜索进行接地功能还可以与 网址 上下文工具结合使用,以便根据公开 网络数据和您提供的特定网址来建立回答依据。

使用内嵌引用来提供来源信息

API 会返回结构化引用数据,让您可以完全控制在用户界面中显示来源的方式。您可以使用 groundingSupportsgroundingChunks 字段将模型的声明直接链接到其来源。以下是处理元数据以创建包含内嵌可点击引用的回答的常见模式。

Python

def add_citations(response):
    text = response.text
    supports = response.candidates[0].grounding_metadata.grounding_supports
    chunks = response.candidates[0].grounding_metadata.grounding_chunks

    # Sort supports by end_index in descending order to avoid shifting issues when inserting.
    sorted_supports = sorted(supports, key=lambda s: s.segment.end_index, reverse=True)

    for support in sorted_supports:
        end_index = support.segment.end_index
        if support.grounding_chunk_indices:
            # Create citation string like [1](link1)[2](link2)
            citation_links = []
            for i in support.grounding_chunk_indices:
                if i < len(chunks):
                    uri = chunks[i].web.uri
                    citation_links.append(f"[{i + 1}]({uri})")

            citation_string = ", ".join(citation_links)
            text = text[:end_index] + citation_string + text[end_index:]

    return text

# Assuming response with grounding metadata
text_with_citations = add_citations(response)
print(text_with_citations)

JavaScript

function addCitations(response) {
    let text = response.text;
    const supports = response.candidates[0]?.groundingMetadata?.groundingSupports;
    const chunks = response.candidates[0]?.groundingMetadata?.groundingChunks;

    // Sort supports by end_index in descending order to avoid shifting issues when inserting.
    const sortedSupports = [...supports].sort(
        (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
    );

    for (const support of sortedSupports) {
        const endIndex = support.segment?.endIndex;
        if (endIndex === undefined || !support.groundingChunkIndices?.length) {
        continue;
        }

        const citationLinks = support.groundingChunkIndices
        .map(i => {
            const uri = chunks[i]?.web?.uri;
            if (uri) {
            return `[${i + 1}](${uri})`;
            }
            return null;
        })
        .filter(Boolean);

        if (citationLinks.length > 0) {
        const citationString = citationLinks.join(", ");
        text = text.slice(0, endIndex) + citationString + text.slice(endIndex);
        }
    }

    return text;
}

const textWithCitations = addCitations(response);
console.log(textWithCitations);

包含内嵌引用的新回答将如下所示:

Spain won Euro 2024, defeating England 2-1 in the final.[1](https:/...), [2](https:/...), [4](https:/...), [5](https:/...) This victory marks Spain's record-breaking fourth European Championship title.[5]((https:/...), [2](https:/...), [3](https:/...), [4](https:/...)

价格

如果您将依托 Google 搜索进行接地功能与 Gemini 3 搭配使用,则系统会针对模型决定执行的每个搜索查询向您的项目收费。如果模型决定执行多个搜索查询来回答单个提示(例如,在同一 API 调用中搜索 "UEFA Euro 2024 winner""Spain vs England Euro 2024 final score"),则此请求将计为该工具的两次付费使用。出于结算目的,我们在统计唯一查询时会忽略空网页搜索查询。此结算模式仅适用于 Gemini 3 模型;如果您将搜索依据功能与 Gemini 2.5 或更早版本的模型搭配使用,则系统会按提示向您的项目收费。

如需详细了解价格信息,请参阅 Gemini API 价格 页面

支持的模型

您可以在模型 概览页面上找到完整的功能。

模型 依托 Google 搜索进行接地
Gemini 3.1 Flash Image 预览版 ✔️
Gemini 3.1 Pro 预览版 ✔️
Gemini 3 Pro Image 预览版 ✔️
Gemini 3 Flash 预览版 ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

支持的工具组合

您可以将依托 Google 搜索进行接地功能与其他工具(例如 代码执行网址上下文)搭配使用,以支持更复杂的用例。

Gemini 3 模型支持将内置工具(例如使用 Google 搜索建立依据)与自定义工具(函数调用)相结合。如需了解详情,请参阅 工具组合页面。

后续步骤