設定自訂 MCP 資料儲存庫的引用來源

自訂 Model Context Protocol (MCP) 資料儲存庫的引用資訊對應，可讓您在 Gemini Enterprise 使用自訂 MCP 伺服器上的工具回答問題時，顯示來源引用資訊方塊。由於每個 MCP 伺服器都會以自己的 JSON 結構傳回結果，您可以使用 Discovery Engine REST API 設定 citation_mappings 動作參數，指定每個工具的回應中，各項結果的連結、標題、摘要和 ID 儲存位置。

您只能使用 v1 REST API 設定 citation_mappings。 Google Cloud 控制台不提供這項參數。

事前準備

為自訂 MCP 資料儲存庫設定引用來源對應前，請務必完成下列必要條件：

引用對應的運作方式

Gemini Enterprise 呼叫自訂 MCP 伺服器上的工具來回答使用者問題時，答案可能會顯示引用資訊方塊 (小型資訊卡，可將答案中的論述連結至來源文件)。引用方塊與內嵌 Markdown 連結不同，後者是模型根據指令在答案文字中生成的連結。

為建立引用資料方塊，Gemini Enterprise 會從工具傳回的每項結果中，擷取最多四個欄位：連結 (uri)、標題 (title)、簡短文字摘錄 (snippet) 和來源 ID (id)。您可以使用下列概念，定義這些欄位在各工具回覆中的位置：

  • 工具：MCP 伺服器公開的單一函式，以裸名識別，例如 search_docs。
  • 工具回覆：工具針對單一呼叫傳回的 JSON 酬載。
  • Item：工具回覆中的單一結果物件。每個項目都會成為一項引用。
  • Role：JSON 指標填入的引用欄位：items、uri、title、snippet 或 id。
  • JSON 指標：RFC 6901 標準化的路徑字串，用於從 JSON 文件中選取值。例如，/results 會選取 results 欄位，而 /author/name 會選取 author 內的 name。

citation_mappings 參數的結構

citation_mappings 參數是 JSON 物件。每個鍵都是工具名稱，每個值都是將引用角色對應至 JSON 指標的物件。

items 指標會從工具回覆的根目錄找出結果清單。其餘四個指標 (uri、title、snippet 和 id) 則是相對於個別項目進行評估，而非從工具回覆的根目錄開始。在實務上，uri 和 title 對使用者看到的內容影響最大，且必須提供 uri。

下表說明工具對應物件中支援的各個角色：

角色 指向 讀取來源 省略時的行為
items 結果清單 工具回覆 系統會使用常見的欄位名稱 (例如 results、items、documents 或 content) 自動找出清單。
uri 引用內容方塊開啟的連結 每項 這是必要旗標，每個涵蓋的工具都必須直接或透過預設項目 ("") 提供 uri。
title 引用方塊中顯示的標題 每項 引用內容方塊會顯示 Untitled。
snippet 引用方塊上顯示的簡短文字 每項 系統會自動從項目的常見欄位中選取摘要，例如 snippet、text、description 或 summary。
id 來源的固定 ID 每項 系統會使用 uri 值做為 ID。

引用內容對應範例

假設名為 search_docs 的工具傳回下列 JSON 酬載：

{
  "results": [
    {
      "doc_id": "kb-1042",
      "name": "Expense policy 2026",
      "link": "https://intranet.cymbal.com/kb/1234",
      "summary": "Meals are reimbursed up to 60 USD per day."
    }
  ]
}

下列 citation_mappings 設定會將 search_docs 的欄位對應至引用內容方塊：

{
  "search_docs": {
    "items": "/results",
    "uri": "/link",
    "title": "/name",
    "snippet": "/summary",
    "id": "/doc_id"
  }
}

在這個範例中，/results 會找出項目清單，並從清單中的每個項目讀取 /link、/name、/summary 和 /doc_id。產生的引用方塊會顯示 Expense policy 2026、連結至 https://intranet.cymbal.com/kb/1234，並顯示摘要做為摘要。

如果多個工具傳回相同形式的結果，您可以定義預設項目 ("")，並視需要覆寫特定角色：

{
  "": {
    "items": "/results",
    "uri": "/link",
    "title": "/name"
  },
  "get_doc": {
    "items": ""
  }
}

在這個設定中，get_doc 會從預設項目繼承 uri (/link) 和 title (/name)，並將 items 覆寫為 ""，因為 get_doc 會傳回單一文件物件，而不是 /results 下方的清單。

工具重要規則

citation_mappings 中的工具金鑰適用下列規則：

  • 使用不含前置字元的工具名稱：請按照 MCP 伺服器宣告的名稱指定工具，不含伺服器或連接器前置字元。
  • 預設項目 ("")：空白鍵 "" 定義的預設對應關係，適用於連接器上的所有工具。具名工具項目會逐一覆寫預設項目。舉例來說，如果工具項目只設定 uri，則會從預設項目繼承 items、title、snippet 和 id。
  • 未對應的工具：如果沒有預設項目 ("")，任何沒有具名項目的工具都不會涵蓋在對應中。
  • 項目數量上限：citation_mappings 最多支援 101 個項目 (最多 100 個具名工具，加上 "" 預設項目)。

JSON 指標評估規則

citation_mappings 中的 JSON 指標遵循 RFC 6901。編寫指標時，請注意下列規則：

  • 空白指標 ("")：空白字串 "" 是指整個 JSON 文件或項目。如果是 items，當工具回覆本身是項目清單或單一結果物件時，請使用 ""。
  • 開頭斜線 (/)：每個非空指標都必須以 / 開頭，長度上限為 512 個字元。舉例來說，/results 有效，results 則無效。
  • 陣列索引：非負整數會選取以零為基準的清單位置。例如，/links/0/href 會選取 links 中第一個元素的 href 欄位。
  • 逸出字元：欄位名稱中的兩個字元必須逸出：/ 寫成 ~1，~ 寫成 ~0。例如，將常值「a/b」寫入為「/a~1b」。
  • 完全比對，區分大小寫：指標比對必須完全相符，且區分大小寫。除了 snippet 之外，如果指標與欄位不符，Gemini Enterprise 不會猜測其他欄位：
    • 如果未命中 title 分球，引用方塊會顯示 Untitled。
    • 如果個別項目缺少 uri 指標，表示該項目仍用於生成答案，但不會顯示該項目的引用連結。
    • 如果找不到 snippet 指標，系統會自動從項目的常見欄位中選取摘要。
  • 單一物件 items：如果 items 解析為 JSON 物件而非清單，Gemini Enterprise 會將該物件視為單一結果項目。
  • 自動備用：如果對應找不到可用的呼叫，例如 items 指標沒有相符項目，或沒有結果項目具有 uri，對應就會停止，Gemini Enterprise 會改用自動回應處理機制處理該回應。

MCP 回應包裝函式的處理方式

items 指標的寫法取決於 MCP 伺服器如何設定工具回應的格式：

  • 文字區塊內序列化的 JSON：許多 MCP 伺服器會將 JSON 以字串形式傳回文字內容區塊 ({"content": [{"type": "text", "text": "..."}]})。text 欄位必須包含有效的序列化 JSON 字串。Gemini Enterprise 會先解碼該 JSON 字串，因此您要針對工具傳回的解碼 JSON 編寫指標，而不是針對外部 content 包裝函式。如果工具傳回非結構化純文字 (例如原始 Markdown 或任意形式字串)，JSON 指標就無法評估，citation_mappings 也不會擷取引用內容方塊。
  • 結構化內容：如果 MCP 工具傳回結構化內容，指標會指向頂層 MCP 結果物件。如要存取 structuredContent 內的清單，請在指標中加入 /structuredContent，例如 /structuredContent/results。當 items 為 "" 且 structuredContent.result 為物件時，項目指標 (uri、title、snippet 和 id) 會根據 structuredContent.result 本身解析。例如，單一物件工具可以使用 /url，而非 /structuredContent/result/url。

設定或更新引用對應

如要在自訂 MCP 資料儲存庫上設定 citation_mappings，請呼叫 v1 API 中的 updateDataConnector 方法，並將 updateMask 查詢參數設為 action_config.action_params。

執行更新要求前，請留意下列行為：

  • 整個對應關係都會被取代：傳送 citation_mappings 會覆寫對應關係中所有現有的工具項目。如要新增或修改單一工具，請傳送完整的 citation_mappings 物件，並附上變更內容。如果您已對應現有工具，請按照下列步驟操作：
    1. 執行 getDataConnector (GET)，並僅從 actionParams 複製 citation_mappings JSON 區塊。
    2. 在複製的區塊中，新增或修改工具的項目。
    3. 在 PATCH 要求中傳送更新後的 citation_mappings 區塊。
  • 保留其他連接器參數：要求中省略的動作參數 (例如 OAuth 設定) 會保留現有值。actionParams 中只能包含 citation_mappings。請勿將 GET 回應中的所有 actionParams 欄位複製到 PATCH 要求：在 OAuth 連接器上，GET 不會傳回 client_id，因此傳回 GET 輸出內容會失敗，並顯示 Connector params must contain client_id。
  • 使用窄更新遮罩：指定 updateMask=action_config.action_params。雖然系統也接受 updateMask=action_config，但會重寫要求中未包含的其他 actionConfig 欄位。
  • 變更會套用至新對話：已開啟的對話會保留原先的連接器設定。啟動新的對話工作階段，測試更新後的引用內容對應。
  • 對應關係屬於單一連接器：如果刪除自訂 MCP 資料儲存庫並重新建立，重新建立的資料儲存庫不會有引用對應關係，您必須再次設定 citation_mappings。

如要設定或更新 citation_mappings，請執行下列指令：

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  "https://ENDPOINT/v1/projects/PROJECT_NUMBER/locations/LOCATION/collections/COLLECTION_ID/dataConnector?updateMask=action_config.action_params" \
  -d '{
    "actionConfig": {
      "actionParams": {
        "citation_mappings": {
          "search_docs": {
            "items": "/results",
            "uri": "/link",
            "title": "/name"
          }
        }
      }
    }
  }'

更改下列內容：

  • PROJECT_ID：專案 ID。
  • ENDPOINT：資料儲存庫位置的 API 端點：
    • discoveryengine.googleapis.com 適用於global位置
    • us-discoveryengine.googleapis.com 適用於us多區域
    • eu-discoveryengine.googleapis.com 適用於eu多區域
  • PROJECT_NUMBER： Google Cloud 專案的編號。
  • LOCATION：資料儲存庫的位置 (global、us 或 eu)。
  • COLLECTION_ID：自訂 MCP 資料儲存庫所在集合的 ID。

如要確認更新是否成功，請參閱「驗證引用項目對應」。

查看引用內容對應

如要讀取自訂 MCP 資料儲存庫目前的引用資料對應，請在資料連接器資源上呼叫 getDataConnector 方法：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  "https://ENDPOINT/v1/projects/PROJECT_NUMBER/locations/LOCATION/collections/COLLECTION_ID/dataConnector"

更改下列內容：

  • PROJECT_ID：專案 ID。
  • ENDPOINT：資料儲存庫位置的 API 端點：
    • discoveryengine.googleapis.com 適用於global位置
    • us-discoveryengine.googleapis.com 適用於us多區域
    • eu-discoveryengine.googleapis.com 適用於eu多區域
  • PROJECT_NUMBER： Google Cloud 專案的編號。
  • LOCATION：資料儲存庫的位置 (global、us 或 eu)。
  • COLLECTION_ID：自訂 MCP 資料儲存庫所在集合的 ID。

在回應中，設定的對應會顯示在 actionConfig.actionParams.citation_mappings 下方。如果未設定任何對應，包括在傳送 "citation_mappings": {} 後，回應會完全省略 actionConfig.actionParams 中的 citation_mappings，而不是傳回 {}。

驗證引用內容對應

設定或更新引用資訊對應後，請檢查是否正常運作：

  1. 按照「查看引用對應」一節所述呼叫 getDataConnector，並確認對應關係顯示在 actionConfig.actionParams.citation_mappings 下方。
  2. 在 Gemini Enterprise 發起新對話。已開啟的即時通訊會保留原先的連接器設定。
  3. 提出問題，讓代理呼叫其中一項對應工具。
  4. 在對話回覆中，查看工具執行指標或資訊卡 (例如「顯示思考過程」下方)，確認代理叫用了對應的工具。如果模型根據自身知識回答，未呼叫工具，就不會顯示引用內容方塊。
  5. 確認答案顯示的引用資訊方塊包含預期的標題、說明或摘要和連結。

如果未顯示引用晶片，請參閱「排解引用對應問題」。

移除引用資料對應

如要從自訂 MCP 資料儲存庫中移除所有引用資料對應，請在 actionConfig.actionParams 中傳送空白物件 ("citation_mappings": {})：

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  "https://ENDPOINT/v1/projects/PROJECT_NUMBER/locations/LOCATION/collections/COLLECTION_ID/dataConnector?updateMask=action_config.action_params" \
  -d '{
    "actionConfig": {
      "actionParams": {
        "citation_mappings": {}
      }
    }
  }'

更改下列內容：

  • PROJECT_ID：專案 ID。
  • ENDPOINT：資料儲存庫位置的 API 端點：
    • discoveryengine.googleapis.com 適用於global位置
    • us-discoveryengine.googleapis.com 適用於us多區域
    • eu-discoveryengine.googleapis.com 適用於eu多區域
  • PROJECT_NUMBER： Google Cloud 專案的編號。
  • LOCATION：資料儲存庫的位置 (global、us 或 eu)。
  • COLLECTION_ID：自訂 MCP 資料儲存庫所在集合的 ID。

排解引用內容對應問題

如果 API 拒絕引用項目對應，或引用項目方塊未如預期顯示，請檢查下列驗證錯誤和常見問題。

驗證錯誤

格式錯誤的對應會遭到拒絕，並顯示 400 INVALID_ARGUMENT 錯誤。錯誤訊息會指出發生錯誤的工具和角色：

錯誤訊息 (簡短) 原因和解決方法
must be an object mapping each tool name to its citation field pointers citation_mappings 不是 JSON 物件。確認 citation_mappings 的值是 JSON 物件 ({...})。
declares N tools, more than the supported maximum of 101 對應項目過多。請減少項目數量，最多只能有 100 個具名工具和預設項目 ("")。
entry for tool "TOOL_NAME" must be an object mapping citation role to JSON Pointer 工具的值不是 JSON 物件。將每個工具名稱對應至包含角色對指標鍵/值組合的物件。
entry for tool "TOOL_NAME" has unknown citation role "ROLE" 角色名稱拼寫錯誤，例如 titel 而非 title。有效角色為 items、uri、title、snippet 和 id。
role "ROLE" on tool "TOOL_NAME" must be a string JSON Pointer 指標值不是字串。將每個 JSON 指標值格式化為 JSON 字串。
exceeds the maximum pointer length of 512 characters JSON 指標過長。請將指標縮短至 512 個半形字元以內。
is not a valid RFC 6901 JSON Pointer 非空白指標缺少開頭的 /，或含有無效的 ~ 逸出序列。請使用 ~0 處理 ~，並使用 ~1 處理 /。
entry for tool "TOOL_NAME" declares no "uri" role 具名工具項目和預設項目 ("") 都未指定 uri 指標。在工具項目或預設項目中新增 uri 角色。
Data Connector parameters must be one of: ... but got: citation_mapping actionParams 中的參數名稱拼寫錯誤。使用 citation_mappings。

常見問題

如果對應儲存時未發生錯誤，但未顯示引用資料方塊，或顯示非預期的值，請檢查下列常見錯誤：

  • 從回應根目錄寫入項目指標：items 選取結果清單後，系統會讀取與單一項目相關的角色指標 (uri、title、snippet 和 id)。請指定 /link，而非 /results/0/link。
  • 工具名稱前置字串：請勿在工具名稱前加上 MCP 伺服器名稱或連接器名稱。使用 MCP 伺服器宣告的裸工具名稱。
  • 在更新中只傳送變更的工具：更新 citation_mappings 會取代整個對應物件。修改某個工具的對應關係時，請一併加入要保留的所有其他工具項目。
  • 在現有對話中測試：更新後的對應關係只會套用至新對話。更新 citation_mappings 後，請啟動新的對話工作階段。
  • 混淆引用方塊和內嵌連結：模型根據指令寫入答案文字的 Markdown 連結，與 citation_mappings 控制的來源引用方塊不同。

後續步驟