Gemini Search Grounding

Google Search Groundingを使用し、回答部分とWebページの出典を関連付けます。

Gemini Search Groundingを使用すると、対応するGeminiモデルがGoogle Searchから最新情報を取得し、groundingMetadataによって回答部分とWebページの出典を関連付けられます。

Groundingは単に「検索を有効にする」だけではありません。クライアントプログラムは、検索クエリ、出典、テキスト部分の対応関係を読み取り、確認可能な引用を画面に表示する必要があります。

プロトコル対応はモデル対応を意味しません

Generate ContentはGoogle Searchツールを表現できますが、実際の利用範囲はモデルとアカウントによって異なります。モデルマーケットプレイスでモデルを確認し、Gemini Generate Content Referenceを参照してください。

Groundingリクエストを送信する

GeminiネイティブパスはサイトOriginに/v1betaを連結します。すでに/v1を含むBase URLの後ろに/v1betaを再度追加しないでください。

curl --request POST \
  'https://api.agtcloud.cn/v1beta/models/MODEL_ID:generateContent' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "今日注目すべきAIニュースを出典付きで教えてください。"
          }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

モデルは検索が必要かを判断し、1つ以上の検索クエリを生成する場合があります。ツールを有効にするたびにGrounding Metadataが生成されるとは限りません。

Groundingの処理フロー

1. 質問と検索ツールを送信する

ユーザーの質問をcontents[].partsに配置し、toolsでGoogle Searchを有効にします。

2. 回答テキストを読み取る

候補のcontent.partsからモデルのテキストを読み取り、候補やPartが常に1つだけとは仮定しないでください。

3. Grounding Metadataを読み取る

検索クエリ、Webページの出典、回答部分と出典インデックスの関連を保存します。

4. クリック可能な引用を表示する

部分の終了位置に引用マーカーを挿入するか、回答の横に出典カードを表示し、ユーザーが元ページを確認できるようにします。

`groundingMetadata`を理解する

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "最近の報道によると、主な動きは……"}
        ]
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "AI ニュース 今日"
        ],
        "groundingChunks": [
          {
            "web": {
              "uri": "https://example.com/article",
              "title": "出典タイトル"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 12,
              "text": "最近の報道によると"
            },
            "groundingChunkIndices": [0]
          }
        ]
      }
    }
  ]
}

フィールド	クライアントでの用途
`webSearchQueries`	モデルが実際に使用した検索クエリを記録し、調査と検索範囲の説明に利用する
`groundingChunks`	WebページのURI、タイトルなどの出典情報を保存する
`groundingSupports`	回答テキストの一部を1つ以上の出典インデックスに対応付ける

レスポンスに一部のフィールドがない場合があります。クライアントではOptional Chainingを使用し、空配列をデフォルト値にしてください。

テキストに引用を挿入する

引用を挿入するときは、先の挿入で後続位置が変わらないように、segment.endIndexの大きい順に処理します。

function addCitations(text, supports = [], chunks = []) {
  const sorted = [...supports].sort(
    (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
  );

  for (const support of sorted) {
    const endIndex = support.segment?.endIndex;
    if (endIndex == null) continue;

    const links = (support.groundingChunkIndices ?? [])
      .map((index) => {
        const source = chunks[index]?.web;
        return source?.uri ? `[${index + 1}](${source.uri})` : null;
      })
      .filter(Boolean);

    if (links.length > 0) {
      text = `${text.slice(0, endIndex)}${links.join('')}${text.slice(endIndex)}`;
    }
  }

  return text;
}

モデルが返した内容をブラウザで表示するときは、安全なMarkdownまたはHTML処理を使用し、外部リンクに新規タブの安全属性を追加してください。

失敗とフォールバック

状況	処理方法
`groundingMetadata`がない	回答を通常どおり表示し、今回は表示できるGrounding出典がないことを明示する
出典インデックスが範囲外	無効な関連を無視して機密情報を除いたレスポンスを記録し、誤ったリンクを挿入しない
テキスト位置が一致しない	回答末尾の出典一覧に切り替え、誤った位置に引用を挿入しない
検索が失敗	レスポンスエラーに応じて限定的に再試行するか、検索なし回答へ切り替える
出典内容が矛盾	複数の出典と日付を表示し、重要な相違を隠さない

公開前の確認

現在のモデルがGoogle Search Groundingに対応している。
Gemini EndpointはサイトOriginを使用し、/v1/v1betaを生成しない。
回答テキスト、クエリ、出典、部分の対応関係を個別に保存する。
引用インデックスが無効でもページがクラッシュしない。
外部Webページの内容を信頼済みの業務指示として直接扱わない。
出典がない場合に偽のCitationを生成しない。

Geminiネイティブ構造ではなくChatを使用する場合は、対象モデルが明示的に対応するChat検索フィールドを使用し、groundingMetadataパーサーをそのままコピーしないでください。

このページの内容