排查 Gemini Enterprise 数据存储区问题

您可以使用本页面来诊断和解决 Gemini Enterprise 数据存储区的任何问题。当数据存储区无法检索信息时，您可以按照连贯、循序渐进的可观测性流程，独立调试问题。

如需全面了解错误，请了解 Google Cloud的可观测性工具如何协同工作：

  • Cloud Monitoring：检测问题何时发生。您可以使用它来查看数据存储区的高级趋势、错误率，并为数据存储区设置提醒。
  • Cloud Trace：发现问题发生在何处。您可以使用它来查看请求的生命周期、分析 span，并准确找出导致高延迟或失败的步骤。
  • Cloud Logging：说明问题发生的原因。使用此工具可读取与失败请求关联的确切出错提示和载荷。
  • Cloud Audit Logs：识别谁或什么政策阻止了该操作。使用它来跟踪安全合规性、权限更改以及可能导致访问遭拒的管理操作。

调试工作流

在调查数据存储区问题时，请按照以下顺序工作流程来找出并解决根本原因：

  1. 查看错误率趋势
  2. 查找失败的具体请求
  3. 查看错误载荷
  4. 交叉引用使用情况审核日志

  1. 在 Google Cloud 控制台中，前往 Metrics Explorer 页面。

    转到 Metrics Explorer

  2. 查看信息中心，查看数据存储区请求计数，并按工具 ID 和引擎 ID 进行过滤。 您可以确定问题是一次性错误，还是需要立即关注的大范围系统性激增。

查找失败的具体请求

  1. 在 Google Cloud 控制台中，前往 Trace 探索器页面：

    转到 Trace 探索器

    您也可以使用搜索栏查找此页面。

  2. 检查散点图，找出带有错误图标（红色感叹号）或延迟时间异常长的跟踪记录。
  3. 点击某个轨迹即可查看其甘特图。
  4. 检查 invoke_connector span，了解进程在何处停滞或失败。
  5. 此外，您还可以找到与特定请求关联的唯一辅助令牌。如果您需要将复杂问题上报给 Google Cloud 支持团队，请分享此辅助令牌，以便加快调查速度。

查看错误载荷

  1. 在 Trace 探索器中点击失败的 span。
  2. 在详细信息窗格中，点击显示日志。
  3. 这会自动将您转到 Cloud Logging，并过滤出该确切请求。在这里，您可以读取原始日志载荷，以确定确切的错误签名（例如 RESOURCE_EXHAUSTED 或 PERMISSION_DENIED）。

交叉引用使用情况审核日志

如果日志载荷指示存在 IAM 问题、缺少范围或权限被拒，请交叉对比您的 Cloud Audit Logs：

  1. 在 Google Cloud 控制台中，前往 Logs Explorer 页面。

    转到日志浏览器

  2. 查看管理历史记录。验证您的管理员最近是否修改了操作过滤条件或撤消了所需权限。

示例：跟踪失败的数据存储区请求

假设用户提示 Gemini Enterprise 代理获取 Jira 问题的状态，但代理返回了一条通用失败消息。您可以通过以下方式使用可观测性工作流来找出根本原因：

  1. 检查错误趋势：在查找个别错误之前，您需要了解问题的普遍程度。在 Cloud Monitoring 中打开 Metrics Explorer，然后按 tool_id: get_issue 过滤数据存储区请求指标。您可能会看到 RESOURCE_EXHAUSTED 错误突然激增。这证实了这是一个系统性问题，而不仅仅是一次性的用户拼写错误。
  2. 查找失败的请求：打开 Trace Explorer，并将时间过滤条件设置为过去一小时。在散点图中，您会注意到有一组带有红色错误图标的跟踪记录，表示失败。点击其中一个近期跟踪记录进行调查。
  3. 检查甘特图：甘特图直观地展示了请求的历程。您会看到初始代理路由的父 span 成功，但其下方嵌套了一个专门针对 Jira Cloud 数据存储区的失败 invoke_connector span。
  4. 切换到日志：点击失败的 invoke_connector span。在“跟踪记录详细信息”窗格中，点击显示日志。

  5. 找出根本原因：Logs Explorer 随即打开，并已预过滤出确切的跟踪记录 ID。现在，您可以检查数据存储区生成的日志载荷，以找出确切的错误：

    
"message": "Connector Error: Cause: Failed to execute spec-based tool 'get_issue': Request failed: HTTP error 403: {\"errorMessages\":[\"permission denied: [User] does not have access to [Resource]"],\"errors\":{}}"

    在此载荷出错提示中，您可以看到失败的具体工具 (get_issue)，以及明确指出执行请求的用户无权访问目标系统中特定资源的显式消息。

  6. 解决：通过常见错误部分，您可以确定这是缺少最终用户资源访问权限错误。Gemini Enterprise 代理已成功连接到 Jira Cloud，但 Jira Cloud 因用户权限不足而拒绝了查询。如需解决此问题，请让您的 Jira Cloud 管理员向用户授予对特定资源的访问权限。

常见错误

在 Cloud Logging 中查看错误载荷时，请重点关注宽泛的错误特征。大多数数据存储区错误都可以完全自行解决。在以下列表中找到您遇到的错误，以确定根本原因和解决方法。

身份验证和访问权限错误

如果凭据、范围或管理政策存在问题，导致无法访问所需资源，就会发生这些错误。如果您遇到这些错误，Cloud Audit Logs 可帮助您调试近期的 IAM 更改、操作过滤条件更新或已撤消的权限。

OAuth 令牌已过期或无效

  • 错误签名： HTTP request failed with status code 401 / 401 Unauthorized
  • 根本原因：OAuth 令牌已过期或无效。
  • 解决方法：在 Gemini Enterprise 设置中重新授权数据存储区，以生成新的令牌。

工具被操作过滤器屏蔽

  • 错误签名： Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
  • 根本原因：管理员使用操作过滤器屏蔽了该工具。
  • 解决方法：管理员必须更新操作或工具许可清单。

缺少 OAuth 范围

  • 错误签名： Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted 或 Cause: Insufficient Permission
  • 根本原因：第三方平台中的应用注册缺少必需的范围。
  • 解决方法：管理员必须授予日志中指定的确切范围，并重新授权应用。

缺少 IAM 项目权限

  • 错误签名： Access Denied: User does not have [permission] / mcp.tools.call permission
  • 根本原因：调用方或服务账号在目标项目中缺少所需的 Google Cloud IAM 权限。
  • 解决方法：向调用方授予指定的 IAM 权限。

性能和限制错误

当请求量超出目标 API 或服务设置的限制时，就会触发这些错误。Cloud Trace 可帮助您准确识别这些被限制的请求在失败之前挂起了多长时间。

第三方 API 429 节流

  • 错误签名： Cause: Request has been rate limited
  • 根本原因：您发出请求的速度超过了第三方 API 允许的速度。
  • 解决方法：降低请求速率、实施退避策略，或向第三方提供商申请增加配额。

“启用操作”按钮未显示

  • 错误特征：创建数据存储区后，控制台中未显示启用操作按钮，或该按钮处于停用状态。
  • 根本原因：数据存储区的功能有限（例如仅支持联合搜索、仅支持提取或仅支持搜索），不支持操作。
  • 解决方法：无法在这些数据存储区类型上启用操作。

公开范围和资源错误

这些错误表示，虽然身份验证可能成功，但用户或应用没有查看所请求数据或与之交互的特定权限。

第三方公开范围限制

  • 错误签名： 422 ... you do not have permission to view [Resource/Users]
  • 根本原因：第三方平台中的公开范围限制或组织政策阻止了数据检索。
  • 解决方法：调整您的第三方组织成员资格，或缩小查询范围。

缺少最终用户资源访问权限

  • 错误签名： permission denied: [user] does not have access to [Resource]
  • 根本原因：执行请求的最终用户缺少对目标系统中特定组件或资源的访问权限。
  • 解决方法：直接在目标系统中向用户授予对资源的访问权限。

系统和服务器端错误

这些错误是由基础架构问题、超时或后端配置错误导致的，通常无法自行解决。

第三方端点速度慢或过载

  • 错误签名： context deadline exceeded
  • 根本原因：第三方端点速度缓慢或过载，导致 Google 端请求超时。
  • 解决方法：请重试请求。如果错误仍然存在，请联系 Google Cloud 支持团队以调整超时。

MCP 服务器凭证绑定配置错误

  • 错误签名： CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • 根本原因：存在服务器端政策问题，即 MCP 服务器凭证绑定配置不正确。客户无法自行解决此问题。
  • 解决方法：请与 Google Cloud 支持团队联系。

获取支持

如果您遇到持续的 context deadline exceeded 或 CredsPermissionException 错误，您可能需要向 Google Cloud 支持团队提交支持服务工单。

为加快解决速度，请在开立工单之前从可观测性工具中收集以下工件：

  • 来自 Cloud Logging：错误的完整 JSON 日志载荷。
  • 从 Cloud Trace：与失败请求关联的辅助令牌和特定 span 详细信息（包括跟踪记录 ID）。
  • 来自使用情况审核日志：可能触发了问题的任何相关 IAM 修改时间戳或政策更改。