Gemini API 和 AI Studio 中的“利用 Google 搜索进行接地”功能可用于提高模型回答的准确性和时效性。除了更具事实依据的回答之外，启用“依托 Google 搜索进行接地”后，Gemini API 会随回答内容一起返回依据来源（内嵌的支持链接）和 Google 搜索建议。搜索建议会将用户引导至与接地回答对应的搜索结果。
本指南将帮助您开始使用 Gemini API SDK 或 REST API 使用“依托 Google 搜索进行接地”功能。
配置搜索接地
从 Gemini 2.0 开始，Google 搜索可用作工具。这意味着，模型可以决定何时使用 Google 搜索。以下示例展示了如何将 Google 搜索配置为工具。
from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch
client = genai.Client()
model_id = "gemini-2.0-flash"
google_search_tool = Tool(
google_search = GoogleSearch()
)
response = client.models.generate_content(
model=model_id,
contents="When is the next total solar eclipse in the United States?",
config=GenerateContentConfig(
tools=[google_search_tool],
response_modalities=["TEXT"],
)
)
for each in response.candidates[0].content.parts:
print(each.text)
# Example response:
# The next total solar eclipse visible in the contiguous United States will be on ...
# To get grounding metadata as web content.
print(response.candidates[0].grounding_metadata.search_entry_point.rendered_content)
“将搜索用作工具”功能还支持多轮搜索和多工具查询（例如，将“着陆点”与 Google 搜索和代码执行结合使用）。
将搜索用作工具，可实现需要规划、推理和思考的复杂提示和工作流：
- 建立依据，以增强事实性和新近性，并提供更准确的回答
- 从网络检索工件，以便进一步分析
- 查找相关图片、视频或其他媒体，以协助执行多模态推理或生成任务
- 编码、技术问题排查和其他专门任务
- 查找特定地区的信息或协助准确翻译内容
- 查找相关网站以供进一步浏览
在显示文字提示时，“依托 Google 搜索进行接地”功能支持所有可用语言。在 Gemini Developer API 的付费层级，您每天可以免费执行 1,500 次“依托 Google 搜索进行接地”查询，超出此数量的查询将按标准费率（每 1,000 次查询 35 美元）计费。
如需了解详情，请试用“搜索工具”笔记本。
Google 搜索建议
如需使用“依托 Google 搜索进行接地”，您必须显示 Google 搜索建议，即有依据的回答的元数据中包含的建议查询。如需详细了解显示要求，请参阅使用 Google 搜索建议。
Google 搜索检索
动态检索
有些查询可能比其他查询更适合使用“与 Google 搜索连接”功能。借助动态检索功能，您可以更好地控制何时使用“依托 Google 搜索进行接地”。
如果未指定动态检索模式，系统将始终触发“与 Google 搜索连接”功能。如果模式设为“动态”，则模型会根据您可以配置的阈值来决定何时使用接地。阈值是一个介于 [0,1] 范围内的浮点值，默认为 0.3。如果阈值为 0，则回答始终基于 Google 搜索；如果阈值为 1，则回答从不基于 Google 搜索。
动态检索的运作方式
您可以在请求中使用动态检索功能，选择何时启用“依托 Google 搜索进行接地”。如果提示不需要依托 Google 搜索给出回答，并且模型可以根据自己的知识提供回答，而不依托任何依据，这会非常有用。这有助于您更有效地管理延迟时间、质量和费用。
在请求中调用动态检索配置之前，请先了解以下术语：
预测得分：当你请求获取相关回答时，Gemini 会为相应问题分配一个预测得分。预测得分是一个介于 [0,1] 范围内的浮点值。其价值取决于问题是否可以通过使用 Google 搜索中的最新信息来为回答提供依据。因此，如果问题需要根据网络上的最新事实给出答案，则其预测得分较高。如果模型生成的回答足以回答提示，则预测得分较低。
下面是一些问题及其预测得分示例。
提示 预测分数 评论 “写一首关于牡丹的诗歌” 0.13 模型可以依靠自己的知识，并且答案不需要接地。 “为 2 岁儿童推荐玩具” 0.36 模型可以依赖自己的知识，并且答案不需要接地。 “您能提供亚洲风味的鳄梨酱食谱吗？” 0.55 Google 搜索可以提供依据充分的回答，但并非必须提供依据；模型知识可能已经足够。 “什么是 Agent Builder？How is grounding billed in Agent Builder?" 0.72 要求 Google 搜索生成有依据的回答。 “谁赢得了最新的 F1 大奖赛？” 0.97 要求 Google 搜索生成有依据的回答。 阈值：在 API 请求中，您可以指定带有阈值的动态检索配置。阈值是一个介于 [0,1] 范围内的浮点值，默认为 0.3。如果阈值为零，则回答始终依托 Google 搜索进行接地。对于所有其他阈值，请遵循以下规则：
- 如果预测得分大于或等于阈值，则系统会根据 Google 搜索来回答问题。阈值越低，表示有更多问题的回答是使用“依托 Google 搜索进行接地”功能生成的。
- 如果预测得分低于阈值，模型可能仍会生成回答，但不会以 Google 搜索为依据。
如需了解如何使用 SDK 或 REST API 设置动态检索阈值，请参阅相应的代码示例。
为了找到适合您业务需求的阈值，您可以创建一组代表您预计会遇到的查询。然后，您可以根据响应中的预测得分对查询进行排序，并为您的用例选择合适的阈值。
为回答提供事实依据
如果您的提示成功连接到 Google 搜索，则回答将包含 groundingMetadata。有依据的回答可能如下所示（为简洁起见，省略了部分回答）：
{
"candidates": [
{
"content": {
"parts": [
{
"text": "Carlos Alcaraz won the Gentlemen's Singles title at the 2024 Wimbledon Championships. He defeated Novak Djokovic in the final, winning his second consecutive Wimbledon title and fourth Grand Slam title overall. \n"
}
],
"role": "model"
},
...
"groundingMetadata": {
"searchEntryPoint": {
"renderedContent": "\u003cstyle\u003e\n.container {\n align-items: center;\n border-radius: 8px;\n display: flex;\n font-family: Google Sans, Roboto, sans-serif;\n font-size: 14px;\n line-height: 20px;\n padding: 8px 12px;\n}\n.chip {\n display: inline-block;\n border: solid 1px;\n border-radius: 16px;\n min-width: 14px;\n padding: 5px 16px;\n text-align: center;\n user-select: none;\n margin: 0 8px;\n -webkit-tap-highlight-color: transparent;\n}\n.carousel {\n overflow: auto;\n scrollbar-width: none;\n white-space: nowrap;\n margin-right: -12px;\n}\n.headline {\n display: flex;\n margin-right: 4px;\n}\n.gradient-container {\n position: relative;\n}\n.gradient {\n position: absolute;\n transform: translate(3px, -9px);\n height: 36px;\n width: 9px;\n}\n@media (prefers-color-scheme: light) {\n .container {\n background-color: #fafafa;\n box-shadow: 0 0 0 1px #0000000f;\n }\n .headline-label {\n color: #1f1f1f;\n }\n .chip {\n background-color: #ffffff;\n border-color: #d2d2d2;\n color: #5e5e5e;\n text-decoration: none;\n }\n .chip:hover {\n background-color: #f2f2f2;\n }\n .chip:focus {\n background-color: #f2f2f2;\n }\n .chip:active {\n background-color: #d8d8d8;\n border-color: #b6b6b6;\n }\n .logo-dark {\n display: none;\n }\n .gradient {\n background: linear-gradient(90deg, #fafafa 15%, #fafafa00 100%);\n }\n}\n@media (prefers-color-scheme: dark) {\n .container {\n background-color: #1f1f1f;\n box-shadow: 0 0 0 1px #ffffff26;\n }\n .headline-label {\n color: #fff;\n }\n .chip {\n background-color: #2c2c2c;\n border-color: #3c4043;\n color: #fff;\n text-decoration: none;\n }\n .chip:hover {\n background-color: #353536;\n }\n .chip:focus {\n background-color: #353536;\n }\n .chip:active {\n background-color: #464849;\n border-color: #53575b;\n }\n .logo-light {\n display: none;\n }\n .gradient {\n background: linear-gradient(90deg, #1f1f1f 15%, #1f1f1f00 100%);\n }\n}\n\u003c/style\u003e\n\u003cdiv class=\"container\"\u003e\n \u003cdiv class=\"headline\"\u003e\n \u003csvg class=\"logo-light\" width=\"18\" height=\"18\" viewBox=\"9 9 35 35\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M42.8622 27.0064C42.8622 25.7839 42.7525 24.6084 42.5487 23.4799H26.3109V30.1568H35.5897C35.1821 32.3041 33.9596 34.1222 32.1258 35.3448V39.6864H37.7213C40.9814 36.677 42.8622 32.2571 42.8622 27.0064V27.0064Z\" fill=\"#4285F4\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M26.3109 43.8555C30.9659 43.8555 34.8687 42.3195 37.7213 39.6863L32.1258 35.3447C30.5898 36.3792 28.6306 37.0061 26.3109 37.0061C21.8282 37.0061 18.0195 33.9811 16.6559 29.906H10.9194V34.3573C13.7563 39.9841 19.5712 43.8555 26.3109 43.8555V43.8555Z\" fill=\"#34A853\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M16.6559 29.8904C16.3111 28.8559 16.1074 27.7588 16.1074 26.6146C16.1074 25.4704 16.3111 24.3733 16.6559 23.3388V18.8875H10.9194C9.74388 21.2072 9.06992 23.8247 9.06992 26.6146C9.06992 29.4045 9.74388 32.022 10.9194 34.3417L15.3864 30.8621L16.6559 29.8904V29.8904Z\" fill=\"#FBBC05\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M26.3109 16.2386C28.85 16.2386 31.107 17.1164 32.9095 18.8091L37.8466 13.8719C34.853 11.082 30.9659 9.3736 26.3109 9.3736C19.5712 9.3736 13.7563 13.245 10.9194 18.8875L16.6559 23.3388C18.0195 19.2636 21.8282 16.2386 26.3109 16.2386V16.2386Z\" fill=\"#EA4335\"/\u003e\n \u003c/svg\u003e\n \u003csvg class=\"logo-dark\" width=\"18\" height=\"18\" viewBox=\"0 0 48 48\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n \u003ccircle cx=\"24\" cy=\"23\" fill=\"#FFF\" r=\"22\"/\u003e\n \u003cpath d=\"M33.76 34.26c2.75-2.56 4.49-6.37 4.49-11.26 0-.89-.08-1.84-.29-3H24.01v5.99h8.03c-.4 2.02-1.5 3.56-3.07 4.56v.75l3.91 2.97h.88z\" fill=\"#4285F4\"/\u003e\n \u003cpath d=\"M15.58 25.77A8.845 8.845 0 0 0 24 31.86c1.92 0 3.62-.46 4.97-1.31l4.79 3.71C31.14 36.7 27.65 38 24 38c-5.93 0-11.01-3.4-13.45-8.36l.17-1.01 4.06-2.85h.8z\" fill=\"#34A853\"/\u003e\n \u003cpath d=\"M15.59 20.21a8.864 8.864 0 0 0 0 5.58l-5.03 3.86c-.98-2-1.53-4.25-1.53-6.64 0-2.39.55-4.64 1.53-6.64l1-.22 3.81 2.98.22 1.08z\" fill=\"#FBBC05\"/\u003e\n \u003cpath d=\"M24 14.14c2.11 0 4.02.75 5.52 1.98l4.36-4.36C31.22 9.43 27.81 8 24 8c-5.93 0-11.01 3.4-13.45 8.36l5.03 3.85A8.86 8.86 0 0 1 24 14.14z\" fill=\"#EA4335\"/\u003e\n \u003c/svg\u003e\n \u003cdiv class=\"gradient-container\"\u003e\u003cdiv class=\"gradient\"\u003e\u003c/div\u003e\u003c/div\u003e\n \u003c/div\u003e\n \u003cdiv class=\"carousel\"\u003e\n \u003ca class=\"chip\" href=\"https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4x8Epe-gzpwRBvp7o3RZh2m1ygq1EHktn0OWCtvTXjad4bb1zSuqfJd6OEuZZ9_SXZ_P2SvCpJM7NaFfQfiZs6064MeqXego0vSbV9LlAZoxTdbxWK1hFeqTG6kA13YJf7Fbu1SqBYM0cFM4zo0G_sD9NKYWcOCQMvDLDEJFhjrC9DM_QobBIAMq-gWN95G5tvt6_z6EuPN8QY=\"\u003ewho won wimbledon 2024\u003c/a\u003e\n \u003c/div\u003e\n\u003c/div\u003e\n"
},
"groundingChunks": [
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4whET1ta3sDETZvcicd8FeNe4z0VuduVsxrT677KQRp2rYghXI0VpfYbIMVI3THcTuMwggRCbFXS_wVvW0UmGzMe9h2fyrkvsnQPJyikJasNIbjJLPX0StM4Bd694-ZVle56MmRA4YiUvwSqad1w6O2opmWnw==",
"title": "wikipedia.org"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4wR1M-9-yMPUr_KdHlnoAmQ8ZX90DtQ_vDYTjtP2oR5RH4tRP04uqKPLmesvo64BBkPeYLC2EpVDxv9ngO3S1fs2xh-e78fY4m0GAtgNlahUkm_tBm_sih5kFPc7ill9u2uwesNGUkwrQlmP2mfWNU5lMMr23HGktr6t0sV0QYlzQq7odVoBxYWlQ_sqWFH",
"title": "wikipedia.org"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4wsDmROzbP-tmt8GdwCW_pqISTZ4IRbBuoaMyaHfcQg8WW-yKRQQvMDTPAuLxJh-8_U8_iw_6JKFbQ8M9oVYtaFdWFK4gOtL4RrC9Jyqc5BNpuxp6uLEKgL5-9TggtNvO97PyCfziDFXPsxylwI1HcfQdrz3Jy7ZdOL4XM-S5rC0lF2S3VWW0IEAEtS7WX861meBYVjIuuF_mIr3spYPqWLhbAY2Spj-4_ba8DjRvmevIFUhRuESTKvBfmpxNSM",
"title": "cbssports.com"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4yzjLkorHiUKjhOPkWaZ9b4cO-cLG-02vlEl6xTBjMUjyhK04qSIclAa7heR41JQ6AAVXmNdS3WDrLOV4Wli-iezyzW8QPQ4vgnmO_egdsuxhcGk3-Fp8-yfqNLvgXFwY5mPo6QRhvplOFv0_x9mAcka18QuAXtj0SPvJfZhUEgYLCtCrucDS5XFc5HmRBcG1tqFdKSE1ihnp8KLdaWMhrUQI21hHS9",
"title": "jagranjosh.com"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4y9L4oeNGWCatFz63b9PpP3ys-Wi_zwnkUT5ji9lY7gPUJQcsmmE87q88GSdZqzcx5nZG9usot5FYk2yK-FAGvCRE6JsUQJB_W11_kJU2HVV1BTPiZ4SAgm8XDFIxpCZXnXmEx5HUfRqQm_zav7CvS2qjA2x3__qLME6Jy7R5oza1C5_aqjQu422le9CaigThS5bvJoMo-ZGcXdBUCj2CqoXNVjMA==",
"title": "apnews.com"
}
}
],
"groundingSupports": [
{
"segment": {
"endIndex": 85,
"text": "Carlos Alcaraz won the Gentlemen's Singles title at the 2024 Wimbledon Championships."
},
"groundingChunkIndices": [
0,
1,
2,
3
],
"confidenceScores": [
0.97380733,
0.97380733,
0.97380733,
0.97380733
]
},
{
"segment": {
"startIndex": 86,
"endIndex": 210,
"text": "He defeated Novak Djokovic in the final, winning his second consecutive Wimbledon title and fourth Grand Slam title overall."
},
"groundingChunkIndices": [
1,
0,
4
],
"confidenceScores": [
0.96145374,
0.96145374,
0.96145374
]
}
],
"webSearchQueries": [
"who won wimbledon 2024"
]
}
}
],
...
}
如果响应不包含 groundingMetadata，则表示响应未成功接地。出现这种情况的原因有很多，包括模型回答中的来源相关性低或信息不完整。
生成基于事实的结果时，元数据中会包含重定向到用于生成基于事实的结果的内容发布商的 URI。这些 URI 包含 vertexaisearch 子网域，如以下截断示例所示：https://vertexaisearch.cloud.google.com/grounding-api-redirect/...。元数据还包含发布商的网域。在生成基于地理位置的结果后，所提供的 URI 将在 30 天内保持可访问状态。
searchEntryPoint 中的 renderedContent 字段是用于实现 Google 搜索建议的提供的代码。如需了解详情，请参阅使用 Google 搜索建议。