为自定义 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)。您可以使用以下概念定义这些字段在每个工具的响应中的位置：

  • 工具：MCP 服务器公开的单个函数，由其裸名称（例如 search_docs）标识。
  • 工具响应：工具针对单次调用返回的 JSON 载荷。
  • Item：工具响应中的单个结果对象。每项内容都会成为一个引用。
  • 角色：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 控制的来源引用条状标签是分开的。

后续步骤