Gemini Search Tool (Google 検索でのグラウンディング)¶

本プラットフォームの Gemini シリーズモデルは、**Google ネイティブの Generate Content インターフェース**と、**OpenAI Chat Completions 互換インターフェース**の両方でツール（tools）を使用できます。この記事では、**新しい API プラットフォームで Gemini 向けに Google Search Grounding (ウェブ検索) ツールを有効にする方法**に焦点を当て、Google 公式の REST の例と比較します。

公式リファレンス

🌐 Google 検索を使用した根拠の構築 (概要)¶

Google 検索ツール google_search は、Gemini モデルをリアルタイムのインターネットコンテンツに接続し、回答を次のようにします：

より正確で信頼性が高い: リアルタイムのウェブコンテンツに基づいて生成され、ハルシネーションを低減します。
リアルタイム情報をサポート: 最近のイベントや時間的制約の強い質問に回答します。
引用元付き: groundingMetadata フィールドを通じてウェブリンクと引用スニペットを返し、フロントエンドでクリック可能な引用の表示を容易にします。

OpenAI の Web search ツール（gpt/search-tool を参照、OpenAI Web search ドキュメントを参照）と比較して、Gemini の google_search は設計上非常によく似ています：リクエストでツールを有効にするだけで、モデルは必要に応じて自動的に検索を開始するかどうかを決定し、レスポンスに構造化された引用情報を付与します。

🧩 基本的な REST 呼び出しの例 (curl)¶

以下の例は、当プラットフォームと Google 公式インターフェースで google_search ツールを有効にし、2024 年のユーロの優勝者について尋ねる方法を示しています。

当サイトの REST の例 (新しい API ゲートウェイ経由)¶

curl "https://api-cs-al.naci-tech.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "2024年のユーロで優勝したのは誰ですか？答えと、2〜3個の参考リンクを提供してください。"
          }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

Google 公式の REST の例¶

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          { "text": "Who won the Euro 2024? Please provide 2-3 reference links." }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

両者の**リクエストボディは完全に互換性があります**。主な違いは次のとおりです：

ゲートウェイドメインと認証方法: 当サイトは https://api-cs-al.naci-tech.com/... + $API_KEY を介して行いますが、Google 公式は https://generativelanguage.googleapis.com/... + $GEMINI_API_KEY を介して行います。
モデル名: google_search を公式にサポートしている最新の Gemini 3 / 2.5 モデルを使用することをお勧めします（以下の「サポートされているモデル」を参照）。

⚙️ 動作原理 (How grounding works)¶

Google の公式ドキュメントを参照すると、リクエストで google_search ツールを有効にした場合、全体のプロセスは次のようになります：

ユーザーリクエスト: アプリケーションは、ユーザーの質問（「2024 年のユーロで優勝したのは誰ですか？」など）を google_search ツールと一緒に Gemini API に送信します。
プロンプトの分析: モデルはまず現在の質問を分析し、回答の質を向上させるために Google 検索を呼び出す必要があるかどうかを判断します。
自動検索: 検索が役立つと判断した場合、モデルは自動的に 1 つまたは複数の検索クエリを作成し、Google 検索を呼び出します。
結果の処理: モデルは検索結果を読み取り、複数のソースからの情報を統合して、最終的な回答を生成します。
グラウンディングされたレスポンスの返却: API が返す候補には、通常のテキスト回答と、その回答がどのウェブコンテンツに基づいているかを示す groundingMetadata フィールドが含まれます。

開発者にとって、使用体験は非常にシンプルです： リクエストで google_search ツールを有効にするだけで、残りはモデルと Google 検索が自動的に処理します。

📦 レスポンスの理解: `groundingMetadata` 構造¶

Gemini がグラウンディングに Google 検索を使用すると、レスポンス内の候補（candidates[i]）に groundingMetadata フィールドが含まれます。以下は簡略化された例です：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "スペインは 2024 年ユーロ決勝でイングランドを 2:1 で破り、優勝しました。"
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "UEFA Euro 2024 winner",
          "who won euro 2024"
        ],
        "groundingChunks": [
          { "web": { "uri": "https://www.uefa.com/...", "title": "UEFA.com" } },
          { "web": { "uri": "https://www.aljazeera.com/...", "title": "Al Jazeera" } }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 50,
              "text": "スペインは 2024 年ユーロ決勝でイングランドを 2:1 で破り"
            },
            "groundingChunkIndices": [0, 1]
          }
        ]
      }
    }
  ]
}

主要なフィールドの意味は公式ドキュメントと一致しています：

webSearchQueries: モデルが実際に発行した検索クエリのリストであり、デバッグやモデルの検索意図を理解するのに役立ちます。
groundingChunks: 各要素は外部のウェブソース（例：uri と title）を表し、「引用元リスト」に似ています。
groundingSupports: モデルの回答内のあるテキストスニペット（segment.startIndex 〜 segment.endIndex）を 1 つまたは複数の groundingChunks に関連付けます。つまり、「このスニペットはどのウェブコンテンツに基づいているか」を示します。

これらのフィールドを利用して、フロントエンドで詳細な引用表示（文末に [1][2] を表示するなど）を構築し、ユーザーがクリックして対応するソースに直接ジャンプできるようにすることができます。

🔗 フロントエンドでのインライン引用 (Inline citations) の表示¶

Google の公式ドキュメントには、groundingSupports と groundingChunks を**インライン引用**付きのテキストに変換する方法を示す Python / JavaScript の例が用意されています。ここでは、一般的な処理パターンを説明するための疑似コードを示します（ロジックは公式ドキュメントと一致していますが、簡略化されています）：

レスポンスから抽出：
元のテキスト：text = candidate.content.parts[0].text
サポート配列：supports = candidate.groundingMetadata.groundingSupports
引用元配列：chunks = candidate.groundingMetadata.groundingChunks
引用を挿入する際に後続のインデックスが崩れるのを防ぐため、supports を segment.endIndex の降順でソートします。
各 support について：
support.groundingChunkIndices を読み取り、対応する chunks[i].web.uri を見つけます。
各インデックスに対して引用文字列を構築します（例：[1](uri1)、[2](uri2)）。
構築した引用文字列を text の segment.endIndex 位置の後に挿入します。
最終的に、フロントエンドで直接レンダリングできる Markdown リンク付きの text_with_citations を返します。

疑似コードの図解（JavaScript スタイル）：

function addCitations(response) {
  let text = response.text;
  const supports = response.candidates[0]?.groundingMetadata?.groundingSupports ?? [];
  const chunks = response.candidates[0]?.groundingMetadata?.groundingChunks ?? [];

  const sortedSupports = [...supports].sort(
    (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0)
  );

  for (const support of sortedSupports) {
    const endIndex = support.segment?.endIndex;
    if (endIndex == null || !support.groundingChunkIndices?.length) continue;

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

    if (citationLinks.length > 0) {
      const citationString = citationLinks.join(", ");
      text = text.slice(0, endIndex) + citationString + text.slice(endIndex);
    }
  }

  return text;
}

これに基づいて、UI の表示スタイル（マウスホバーでウェブページのタイトルを表示する、リンクを新しいタブで開くなど）をカスタマイズできます。

✅ サポートされているモデル (Supported models)¶

Google の公式ドキュメントによると、現在以下のモデルが Grounding with Google Search（google_search ツール）をサポートしています：

モデル	Google Search Grounding をサポート
`gemini-3.1-flash-image-preview`	✔︎
`gemini-3.1-pro-preview`	✔︎
`gemini-3-pro-image-preview`	✔︎
`gemini-3-flash-preview`	✔︎
`gemini-2.5-pro`	✔︎
`gemini-2.5-flash`	✔︎
`gemini-2.5-flash-lite`	✔︎
`gemini-2.0-flash`	✔︎

注意: 古いモデルでは google_search_retrieval ツールが使用されていましたが、現在のモデルでは google_search に統一して使用してください。

本プラットフォームで呼び出す場合、最新世代の Gemini 3 / 2.5 モデルを優先して選択することをお勧めします。例：

高速シナリオ：gemini-3-flash-preview、gemini-2.5-flash
高精度シナリオ：gemini-3.1-pro-preview、gemini-2.5-pro