Gemini Search Grounding

Gemini Search Grounding 讓支援該能力的 Gemini 模型使用 Google Search 取得近期資訊，並透過 groundingMetadata 把回答片段與網頁來源關聯起來。

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": "今天有哪些值得關注的人工智慧新聞？請給出來源。"
          }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

模型會判斷是否需要搜尋，並可能生成一個或多個搜尋查詢。不要假設每次啟用工具都會產生 Grounding Metadata。

Grounding 的處理流程

1. 提交問題和搜尋工具

將使用者問題放入 contents[].parts，並在 tools 中啟用 Google Search。

2. 讀取回答文字

從候選的 content.parts 中讀取模型生成的文字，不要假設始終只有一個候選或一個 Part。

3. 讀取 Grounding Metadata

儲存搜尋查詢、網頁來源以及回答片段與來源索引的關聯。

4. 顯示可點擊引用

根據片段結束位置插入引用標記，或在回答旁顯示來源卡片，讓使用者可以回到原始網頁核對。

理解 `groundingMetadata`

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "根據近期報道，相關進展包括……"}
        ]
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "人工智慧 新聞 今天"
        ],
        "groundingChunks": [
          {
            "web": {
              "uri": "https://example.com/article",
              "title": "來源標題"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 12,
              "text": "根據近期報道"
            },
            "groundingChunkIndices": [0]
          }
        ]
      }
    }
  ]
}

欄位	用戶端用途
`webSearchQueries`	記錄模型實際使用的搜尋查詢，便於疑難排解和解釋搜尋範圍
`groundingChunks`	儲存網頁 URI、標題等來源資訊
`groundingSupports`	將回答文字片段映射到一個或多個來源索引

回應可能沒有其中某些欄位，用戶端需要使用可選存取和空陣列作為預設值。

在文字中插入引用

插入引用時，應按 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。
回答文字、查詢、來源和片段映射分別儲存。
引用索引無效時不會導致頁面崩潰。
外部網頁內容不會被直接當作可信業務指令。
沒有來源時不會生成虛假 Citation。

如果應用使用 Chat 而不是 Gemini 原生結構，請改用目標模型明確支援的 Chat 搜尋欄位，不要直接複製 groundingMetadata 解析器。

本頁目錄