排查问题

本页面介绍了如何解决 Model Armor 的问题。

本部分介绍了在使用 Model Armor 遇到问题时可能会有帮助的问题排查步骤。

对 Model Armor 的所有 API 调用均返回 404（未找到网页）错误

建立与 Model Armor API 的 Private Service Connect 连接。此错误通常会在使用专用 Google 访问通道或不使用 Private Service Connect 访问 Model Armor 区域端点 (REP) 时发生。如需了解详情，请参阅关于通过 Private Service Connect 端点访问区域端点。

Sensitive Data Protection 过滤条件报错或被跳过

请验证以下内容：

  • Sensitive Data Protection 模板与所调用的 Model Armor 端点位于同一区域。
  • 发出 Model Armor 请求的服务代理在包含 Sensitive Data Protection 模板的项目中拥有 dlp.User 和 dlp.Reader 角色。

此错误是由于 SanitizeUserPrompt 或 SanitizeModelResponse 请求中的客户端错误或 Sensitive Data Protection 模板问题导致的。

Model Armor 全局端点错误

确保您向适当的区域端点（而非全球端点）发出 API 请求。

Model Armor 仅在其区域端点上支持以下操作：

  • 对模板执行创建、读取、更新、删除和列出操作。
  • SanitizeUserPrompt 和 SanitizeModelResponse API 请求。

如果您向全球端点发出针对这些操作的 API 请求，则会看到以下错误：

{
  "error": {
    "code": 403,
    "message": "Write access to project '<PROJECT_ID>' was denied",
    "status": "PERMISSION_DENIED"
  }
}

访问 Model Armor 区域端点时出现证书错误

当使用专用 Google 访问通道或 VPC Service Controls 从 VPC 网络内访问 Model Armor 区域端点，并且证书验证失败时，通常会发生此错误。

例如，您可能会看到类似如下的出错提示：

curl: (60) SSL: no alternative certificate subject name matches target host name 'modelarmor.europe-west4.rep.googleapis.com'

如需解决此问题，请创建指向 Model Armor API 的 Private Service Connect 端点。如需了解详情，请参阅关于通过 Private Service Connect 端点访问区域端点。

区域不支持请求的功能

您可能会看到类似如下内容的错误消息：

Region '<var>REGION</var>' does not support the requested capabilities: '<var>CAPABILITIES</var>'

如果您尝试在具有功能限制的区域中创建或更新模板，并且请求启用了该区域不支持的功能，则会发生此错误。

要解决此问题，请执行以下操作：

  1. 确定出错提示中列出的不受支持的功能。
  2. 查看按区域划分的功能可用性，确认目标区域不支持哪些功能。
  3. 从您正在创建或更新的模板中移除不受支持的功能。

或者，如果您的数据驻留要求允许，请使用支持这些功能的其他 Model Armor 区域。

必须遵守模板数据驻留要求

您可能会看到类似于以下内容的 400 (FAILED_PRECONDITION) 出错提示：

Template data residency compliance is required. The 'Enforce data residency' field must not be set to false.

当强制执行要求 Model Armor 模板符合数据驻留合规性 (constraints/modelarmor.managed.requireTemplateDataResidencyCompliance) 托管式 Organization Policy Service 限制条件，并且您创建或更新了已停用数据驻留合规性的 Model Armor 模板时，就会发生此错误。当您将 data_residency_compliant 设置为 false 或清除强制执行数据驻留选项时，数据驻留合规性会被停用。由于此限制条件默认强制执行，因此在已将 data_residency_compliant 设置为 false 的现有模板上修改任何设置（例如过滤条件）也会触发此错误。除非您更新模板，否则现有模板以及清理提示和回答的请求不会受到影响。

如需解决此问题，请执行以下某项操作：

  • 通过将 data_residency_compliant 设置为 true 或选择强制执行数据驻留选项，在模板上启用数据驻留合规性。
  • 如果您需要为模板停用数据驻留合规性，请按照停用数据驻留的组织政策限制条件中的步骤操作，让组织政策管理员停用该限制条件。

对于大型提示或载荷，系统会跳过政策控制或过滤条件

在筛查大型提示或回答（例如检索增强生成 [RAG] 载荷或多步智能体对话历史记录）时，个别过滤器可能无法运行，或者清理结果可能会返回 EXECUTION_SKIPPED，并在 messageItems 字段中显示以下警告消息之一：

Detection skipped as token limit exceeded.

Input size exceeded the limit of 4194304 bytes.

如果一元清理请求或缓冲流式传输请求超出过滤器的词元系统限制（提示词注入和越狱检测、Responsible AI 和 CSAM 为 65,536 个词元；Sensitive Data Protection 为 130,000 个词元）或 4 MB 的输入大小限制，就会出现此问题。当输入超出过滤器的 token 限制且未检测到匹配项时，过滤器会返回 EXECUTION_SKIPPED 和 NO_MATCH_FOUND，从而允许请求在内嵌集成中继续。

如需验证是否因词元或输入大小限制而跳过了过滤条件，请在 Cloud Logging 中查询 SanitizeOperation 日志：

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
"EXECUTION_SKIPPED"

要解决此问题，请执行以下操作：

  1. 对于流式工作负载或长时间运行的智能体交互，请使用实时流式传输清理（StreamSanitizeUserPrompt 和 StreamSanitizeModelResponse）。对于使用 Agent Gateway 的智能体开发套件智能体，请使用 streamQuery，它会分块处理输入并支持无限数量的 token。
  2. 对于一元请求，请先对大型 RAG 载荷进行分块或剪裁多步智能体对话历史记录，然后再将其发送到 Model Armor，以便每个请求都保持在 token 系统限制和 4 MB 输入大小限制内。