Gemini API 和 AI Studio 中的「以 Google 搜尋做為依據」功能，可用於改善模型回覆的準確性和新鮮度。除了提供更多事實回覆，啟用「以 Google 搜尋建立基準」功能後，Gemini API 會一併傳回基準來源 (內嵌輔助連結) 和 Google 搜尋建議，以及回覆內容。搜尋建議會將使用者導向與回應相關的搜尋結果。
本指南將協助您開始使用 Grounding with Google Search，並使用 Gemini API SDK 或 REST API。
設定搜尋基準建立
從 Gemini 2.0 開始，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 個 Grounding with Google Search 查詢，額外查詢則以每 1,000 個查詢 35 美元的標準費用計費。
如要進一步瞭解，請試用搜尋工具的 Notebook。
Google 搜尋建議
如要使用「以 Google 搜尋建立基準」功能，您必須顯示 Google 搜尋建議，這是在已建立基準回應的中繼資料中提供的建議查詢。如要進一步瞭解顯示規定，請參閱「使用 Google 搜尋建議」。
Google 搜尋擷取
動態擷取
部分查詢可能比其他查詢更能從「以 Google 搜尋建立基準」功能中受益。動態擷取功能可讓您進一步控管使用「以 Google 搜尋建立基準」功能的時機。
如果未指定動態擷取模式，系統一律會觸發 Google 搜尋 Grounding。如果模式設為動態，模型會根據可設定的閾值決定何時使用接地。門檻值是 [0,1] 範圍內的浮點值，預設值為 0.3。如果閾值值為 0，回應一律會與 Google 搜尋相關；如果閾值值為 1，則一律不會。
動態擷取的運作方式
您可以在要求中使用動態擷取功能，選擇何時要啟用 Google 搜尋的 Grounding 功能。當提示不需要 Google 搜尋的答案，且模型可以根據自身知識提供答案時，這項功能就很實用。這有助於您更有效地管理延遲時間、品質和成本。
在要求中叫用動態擷取設定之前，請先瞭解下列術語：
預測分數：當您要求具體答案時，Gemini 會為提示指令指派預測分數。預測分數是 [0,1] 範圍內的浮點值。這項屬性的值取決於提示是否能從 Google 搜尋中取得最新資訊，並將這些資訊納入答案。因此，如果提示需要根據網路上最新的事實提供答案，則預測分數會較高。如果模型產生的答案足以回應提示，預測分數就會偏低。
以下列舉一些提示和相應的預測分數。
提示 預測分數 註解 「寫一首關於牡丹的詩」 0.13 模型可依據自身知識提供答案，而無須建立基準。 「推薦適合 2 歲兒童的玩具」 0.36 模型可依據自身知識提供答案，而無須建立基準。 「請提供亞洲風味酪梨醬食譜。」 0.55 Google 搜尋可提供基準答案，但不一定需要建立基準；模型知識可能就足夠了。 「Agent Builder 是什麼？如何在 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 會重新導向至用於產生依據結果的內容發布者。這些 URI 包含 vertexaisearch 子網域，如以下截斷的範例所示：https://vertexaisearch.cloud.google.com/grounding-api-redirect/...。這些中繼資料也包含發布商的網域。提供的 URI 會在產生依據結果後的 30 天內保留。
searchEntryPoint 中的 renderedContent 欄位是實作 Google 搜尋建議功能的程式碼。詳情請參閱「使用 Google 搜尋建議」。