Gemini API と AI Studio の Google 検索によるグラウンディング機能を使用すると、モデルからの回答の精度と新しさを高めることができます。Google 検索によるグラウンディングが有効になっている場合、Gemini API は、回答コンテンツとともに、より事実に基づく回答に加えて、グラウンディング ソース（インラインの補足リンク）と Google 検索の検索候補を返します。検索候補は、グラウンディングされた回答に対応する検索結果をユーザーに示します。
このガイドでは、Gemini API SDK または REST API のいずれかを使用して、Google 検索によるグラウンディングの使用を開始する方法について説明します。
検索グラウンディングを構成する
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 日あたり 1,500 件の Google 検索によるグラウンディング クエリを無料で実行できます。それを超えるクエリは、1,000 件あたり 35 ドルの標準料金で請求されます。
詳しくは、検索ツール ノートブックを試すをご覧ください。
Google 検索の検索候補
Google 検索でグラウンディングを使用するには、Google 検索の候補を表示する必要があります。これは、グラウンディングされたレスポンスのメタデータに含まれる候補クエリです。ディスプレイの要件について詳しくは、Google 検索の検索候補を使用するをご覧ください。
Google 検索の取得
動的取得
検索語句によっては、Google 検索によるグラウンディングの効果が他よりも大きい場合があります。動的取得機能を使用すると、Google 検索でグラウンディングを使用するタイミングをさらに細かく制御できます。
動的取得モードが指定されていない場合、Google 検索によるグラウンディングは常にトリガーされます。モードが動的に設定されている場合、モデルは、構成可能なしきい値に基づいて、グラウンドを使用するタイミングを決定します。しきい値は [0,1] の範囲内の浮動小数点値で、デフォルトは 0.3 です。しきい値が 0 の場合、レスポンスは常に Google 検索でグラウンディングされます。1 の場合、グラウンディングされません。
動的取得の仕組み
リクエストで動的取得を使用すると、Google 検索でグラウンディングをオンにするタイミングを選択できます。これは、プロンプトで 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 です。しきい値が 0 の場合、回答は常に 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 検索の検索候補を使用するをご覧ください。