使用 Google 搜索建立依据

本页介绍了如何使用 Google 搜索引擎的结果(该搜索引擎使用公开提供的 Web 数据)来为 Gemini 回答提供依据。此外,还说明了回答中包含的搜索建议。

如果您想将模型与世界知识、各种可能的主题或互联网上的最新信息相关联,请使用“依托 Google 搜索进行接地”功能。

如需详细了解 Gemini Enterprise Agent Platform 中的模型接地功能,请参阅接地概览

支持的模型

本部分列出了支持“依托搜索进行接地”的模型。

点击即可展开支持的型号

支持的语言

如需查看支持的语言列表,请参阅语言

按照以下说明借助公开提供的网络数据让模型接地。

注意事项

  • 如需使用“依托 Google 搜索进行接地”,您必须启用 Google 搜索建议。如需了解详情,请参阅使用 Google 搜索建议

  • 为了获得理想的结果,请使用 1.0 温度。如需详细了解如何设置此配置,请参阅模型参考文档中的 Gemini API 请求正文

  • “借助 Google 搜索接地”功能的查询次数上限为每天 100 万次。如果您需要更多查询,请与Google Cloud 支持团队联系以获取帮助。

  • 工具组合:Gemini API 不支持在同一 generateContent 请求中将搜索工具(例如 googleSearch)与非搜索工具(例如函数调用或 Gemini Enterprise Agent Platform RAG Engine retrieval 工具)相结合。 只有当所有工具均为搜索工具时,才支持多种工具。

通过使用纬度和经度坐标,可以针对最终用户的特定地理位置自定义搜索结果。如需了解详情,请参阅基础 API

控制台

如需将“依托 Google 搜索进行接地”与 Gemini Enterprise Agent Platform 上的 Agent Studio 搭配使用,请按照以下步骤操作:

  1. 在 Google Cloud 控制台中,前往 Agent Studio 页面。

    前往 Agent Studio

  2. 在侧边栏中,前往模型设置下方的接地部分,然后开启 Google 搜索开关。
  3. 在文本框中输入提示,然后点击提交

您的提示回答现在会使用“依托 Google 搜索进行接地”。

Python

安装

pip install --upgrade google-genai

如需了解详情,请参阅 SDK 参考文档

设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai.types import (
    GenerateContentConfig,
    GoogleSearch,
    HttpOptions,
    Tool,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="When is the next total solar eclipse in the United States?",
    config=GenerateContentConfig(
        tools=[
            # Use Google Search Tool
            Tool(
                google_search=GoogleSearch(
                    # Optional: Domains to exclude from results
                    exclude_domains=["domain.com", "domain2.com"]
                )
            )
        ],
    ),
)

print(response.text)
# Example response:
# 'The next total solar eclipse in the United States will occur on ...'

Go

了解如何安装或更新 Go

如需了解详情,请参阅 SDK 参考文档

设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithGoogleSearch shows how to generate text using Google Search.
func generateWithGoogleSearch(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "When is the next total solar eclipse in the United States?"},
		},
			Role: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{GoogleSearch: &genai.GoogleSearch{ExcludeDomains: []string{"example.com", "example.org"}}},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The next total solar eclipse in the United States will occur on March 30, 2033, but it will only ...

	return nil
}

Java

了解如何安装或更新 Java

如需了解详情,请参阅 SDK 参考文档

设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.GoogleSearch;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Tool;

public class ToolsGoogleSearchWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates content with Google Search tool
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Create a GenerateContentConfig and set Google Search tool
      GenerateContentConfig contentConfig =
          GenerateContentConfig.builder()
              .tools(Tool.builder().googleSearch(GoogleSearch.builder().build()).build())
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              modelId, "When is the next total solar eclipse in the United States?", contentConfig);

      System.out.print(response.text());
      // Example response:
      // The next total solar eclipse in the United States will occur on...
      return response.text();
    }
  }
}

Node.js

安装

npm install @google/genai

如需了解详情,请参阅 SDK 参考文档

设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateGoogleSearch(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'When is the next total solar eclipse in the United States?',
    config: {
      tools: [
        {
          googleSearch: {},
        },
      ],
    },
  });

  console.log(response.text);

  // Example response:
  //    'The next total solar eclipse in United States will occur on ...'

  return response.text;
}

REST

在使用任何请求数据之前,请先进行以下替换:

  • LOCATION:处理请求的区域。 如需使用全球端点,请清除端点名称中的相应位置,并将资源位置配置为全球。
  • PROJECT_ID:您的 [项目 ID](/resource-manager/docs/creating-managing-projects#identifiers)。。
  • MODEL_ID:多模态模型的模型 ID。
  • TEXT:要包含在提示中的文本说明。
  • EXCLUDE_DOMAINS:可选:不用于接地的网域列表。
  • LATITUDE:可选:最终用户所在位置的纬度。例如,纬度 37.7749 表示旧金山。您可以使用 Google 地图等服务或其他地理编码工具获取纬度和经度坐标。
  • LONGITUDE:可选:最终用户所在位置的经度。例如,经度 -122.4194 表示旧金山。

HTTP 方法和网址:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

请求 JSON 正文:

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "googleSearch": {
      "exclude_domains": [ "domain.com", "domain2.com" ]
    }
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      }
    }
  },
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

如需发送您的请求,请展开以下选项之一:

您应该收到类似以下内容的 JSON 响应:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "The weather in Chicago this weekend, will be partly cloudy. The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday. There is a slight chance of rain on both days.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "groundingMetadata": {
        "webSearchQueries": [
          "weather in Chicago this weekend"
        ],
        "searchEntryPoint": {
          "renderedContent": "..."
        },
        "groundingChunks": [
          {
            "web": {
              "uri": "https://www.google.com/search?q=weather+in+Chicago,+IL",
              "title": "Weather information for locality: Chicago, administrative_area: IL",
              "domain": "google.com"
            }
          },
          {
            "web": {
              "uri": "...",
              "title": "weatherbug.com",
              "domain": "weatherbug.com"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 85,
              "endIndex": 214,
              "text": "The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday."
            },
            "groundingChunkIndices": [
              0
            ],
            "confidenceScores": [
              0.8662828
            ]
          },
          {
            "segment": {
              "startIndex": 215,
              "endIndex": 261,
              "text": "There is a slight chance of rain on both days."
            },
            "groundingChunkIndices": [
              1,
              0
            ],
            "confidenceScores": [
              0.62836814,
              0.6488607
            ]
          }
        ],
        "retrievalMetadata": {}
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 98,
    "totalTokenCount": 108,
    "trafficType": "ON_DEMAND",
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 10
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 98
      }
    ]
  },
  "modelVersion": "gemini-2.0-flash",
  "createTime": "2025-05-19T14:42:55.000643Z",
  "responseId": "b0MraIMFoqnf-Q-D66G4BQ"
}

通过 Google 图片搜索建立依据可让模型在生成图片时,使用从 Google 图片搜索中检索到的网络图片作为视觉背景信息。Google 图片搜索是现有“依托 Google 搜索进行接地”工具中的一种新搜索类型,与标准的 Google 网页搜索并存。“使用 Google 图片搜索进行接地”功能目前仅在预览版中提供,且仅适用于 Gemini 3.1 Flash Image 模型

API 请求配置

如需启用 Google 图片搜索,请在 API 请求中配置 googleSearch 工具,并在 searchTypes 对象中指定 imageSearch。您可以单独使用 Google 图片搜索,也可以将其与 Google 网页搜索搭配使用。

REST

在使用任何请求数据之前,请先进行以下替换:

  • LOCATION:处理请求的区域。如需使用 全球端点,请清除端点名称中的相应位置,并将资源位置配置为全球。
  • PROJECT_ID:。
  • MODEL_ID:多模态模型的模型 ID。
  • SEARCH_TERM:用于搜索图片的搜索字词。
  • HTTP 方法和网址:

    POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

    请求 JSON 正文:

    {
      "contents": [
        {
          "role": "user",
          "parts": [
            {
            "text": "SEARCH_TERM"
            }
          ]
        }
      ],
      "tools": [
        {
          "googleSearch": {
            "searchTypes": {
              "imageSearch": {},
              "webSearch": {}
            }
          }
        }
      ],
      "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
    }
    

    如需发送请求,请选择以下方式之一:

    curl

    将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

    PowerShell

    将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

    您应该会收到一个成功的状态代码 (2xx) 和一个空响应。

显示要求

将 Google 图片搜索与“依托 Google 搜索进行接地”功能搭配使用时,您必须遵守以下条件:

  • 来源信息提供:您必须以用户能够识别为链接的方式,提供包含来源图片的网页(“包含网页”,而非图片文件本身)的链接。

  • 直接导航:如果您还选择显示来源图片,则必须提供从来源图片到其所在来源网页的直接单点点击路径。任何其他会延迟或抽象化最终用户对源网页的访问的实现方式(包括但不限于任何多点击路径或使用中间图片查看器)均不允许。

响应

对于使用图片搜索的有依据的回答,该 API 会提供清晰的提供方信息和元数据,以将其输出内容与经过验证的来源相关联。groundingMetadata 对象包含以下字段:

  • imageSearchQueries:模型用于视觉上下文的特定查询(也称为“图片搜索”)。

  • groundingChunks:包含检索到的结果的来源信息。对于图片来源,这些信息会以重定向网址的形式返回,并使用新的图片块类型。相应块包含以下内容:

    • url:用于提供提供方信息的网页网址(也称为“着陆页”)。
    • image_url:直接图片网址。
  • groundingSupports:提供将生成的内容与块中的相关引用来源相关联的具体映射。

  • searchEntryPoint:包含 Google 搜索条状标签,其中包含符合要求的 HTML 和 CSS,用于呈现 Google 搜索建议。

理解回答

如果您的模型提示从 Agent Studio 或 API 成功使用依托 Google 搜索进行接地,则回答会包含带有来源链接(网址)的元数据。但是,有多种原因可能会导致此元数据无法提供,并且提示回答不会落地。这些原因包括模型回答中的来源相关性低或信息不完整。

文内引用

内嵌引用使用 API 返回的结构化 grounding_metadata 将生成的文本的特定部分与可验证的来源相关联。

此 capability 支持所有建立依据方法,包括 Search、Google 地图和 Agent Search,可提供在应用中显示准确的互动式引用所需的精确来源详细信息。

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="Where will the next FIFA World Cup be held?",
   config=types.GenerateContentConfig(
       tools=[types.Tool(google_search=types.GoogleSearch())],
   ),
)

display(Markdown(response.text))
print(response.candidates[0].grounding_metadata.grounding_chunks)
display(HTML(response.candidates[0].grounding_metadata.search_entry_point.rendered_content))

输出示例:

…

Citations:
Wikipedia. "2026 FIFA World Cup." Retrieved February 11, 2026. (https://en.wikipedia.org/wiki/2026_FIFA_World_Cup)
US Soccer Players. "2026 FIFA World Cup FAQ — Dates, Hosts, Tickets, Teams & More." (https://ussoccerplayers.com/2026-fifa-world-cup-faq)
Holafly. "2026 World Cup host cities and countries: Full list of stadiums." (https://travel.holafly.com/esims/2026-world-cup-host-cities/)
…

接地支持

必须显示接地支持,因为这有助于您验证发布方的回答,并为用户提供更多学习途径。

对来自网络来源的回答的接地支持应以内嵌和汇总形式显示。例如,请参阅下图,了解如何执行此操作。

接地支持示例

使用备用搜索引擎选项

使用“依托 Google 搜索进行接地”时,客户应用可以:

  • 提供备用搜索引擎选项,
  • 将其他搜索引擎设为默认选项,
  • 展示自有或第三方搜索建议或搜索结果,但前提是:任何非 Google 结果都必须与 Google 的 Grounded Results 和搜索建议分开展示,并且展示方式不会让用户感到困惑,也不会暗示这些结果来自 Google。

优势

将“依托 Google 搜索进行接地”作为工具使用时,可以执行以下需要规划、推理和思考的复杂提示和工作流:

  • 您可以进行接地,以帮助确保回答基于最新、最准确的信息。
  • 您可以从 Web 检索制品以进行分析。
  • 您可以找到相关图片、视频或其他媒体,以辅助进行多模态推理或任务生成。
  • 您可以执行编码、技术问题排查和其他专业任务。
  • 查找特定于某个区域的信息或协助准确翻译内容。
  • 您可以找到相关网站以供浏览。

使用 Google 搜索建议

使用“依托 Google 搜索进行接地”时,如果您在回答中收到搜索建议,则必须在生产环境和应用中显示搜索建议。

具体而言,您必须显示接地的回答的元数据中包含的搜索查询。回答包括:

  • "content":LLM 生成的回答。
  • "webSearchQueries":用于搜索建议的查询。

例如,在以下代码段中,Gemini 会回答 Google 搜索连接提示,该提示询问一种热带植物。

"predictions": [
  {
    "content": "Monstera is a type of vine that thrives in bright indirect light…",
    "groundingMetadata": {
      "webSearchQueries": ["What's a monstera?"],
    }
  }
]

您可以使用 Google 搜索建议获取此输出并进行显示。

搜索建议的要求

以下是搜索建议的必需条件:

要求 说明
正确做法
  • 在符合显示要求的同时,搜索建议将完全按照提供的内容显示,不会进行任何更改。
  • 当您与搜索建议互动时,系统会直接将您带到“搜索结果”页 (SRP)。
错误做法
  • 在用户点按与 SRP 显示之间包含任何屏幕或其他步骤
  • 在搜索建议或关联的接地 LLM 回答旁边显示任何其他搜索结果或建议。

显示要求

以下是显示要求:

  • 完全按照所提供的方式显示搜索建议,不对颜色、字体或外观进行任何修改。确保搜索建议按照以下模拟中指定的方式进行渲染,包括针对浅色和深色模式:

  • 每当显示接地回答时,其相应的 Google 搜索建议都应保持可见。
  • 在品牌塑造方面,您必须严格遵循 Google 的指南(第三方使用 Google 品牌特征时适用),详见欢迎访问我们的品牌资源中心
  • 当您使用“使用 Google 搜索建立依据”时,系统会显示搜索建议条状标签。包含搜索建议条状标签的字段必须与 LLM 提供的接地回答宽度相同。

点按时的行为

用户点按条状标签后,会直接前往条状标签中显示的搜索字词的对应 Google 搜索结果页 (SRP)。SRP 可以在应用内浏览器或单独的浏览器应用中打开。请务必不要以任何方式最小化、移除或遮挡 SRP 的显示内容。以下动画模拟展示了点按与 SRP 的交互。

点按时的行为

应用/桌面示例

实现搜索建议的代码

当您使用 API 为搜索回答建立依据时,模型回答会在 renderedContent 字段中提供合规的 HTML 和 CSS 样式,您可以实现该字段以在应用中显示搜索建议。

此外,搜索建议之前也称为搜索入口点。虽然您可能会在某些 API 字段中看到对“搜索入口点”的引用,但这两个术语都指您在 API 响应中收到的当前搜索建议。

以下示例展示了如何使用 curl 将回答与搜索结果相关联:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "Why is the sky blue?"
      }
    },
    "tools": [
      {
        "googleSearch": {}
      }
    ]
  }'

Gemini 3 带来的结算变化

在 Gemini 3 模型上使用“依托 Google 搜索进行接地”功能时,系统会针对 Gemini 生成并发送给 Google 搜索的每个搜索查询进行结算。单个提示可能会生成一个或多个搜索查询。

示例

此示例展示了可能会产生费用的用户提示和搜索查询示例。

  • 用户提示:Tell me about the life of Albert Einstein.
  • Gemini 可能会生成以下搜索查询:
    • 阿尔伯特·爱因斯坦的出生和早期教育
    • 阿尔伯特·爱因斯坦的相对论
    • 阿尔伯特·爱因斯坦在美国的生活

在此示例中,这三个搜索查询会产生费用。

后续步骤