查看 Model Armor 轨迹 span

本文档介绍了轨迹中的 Model Armor span，以及如何查看其详细信息。如需详细了解轨迹，请参阅查看代理轨迹。

关于 Cloud Trace 和代理可观测性

轨迹表示请求在分布式应用各部分中的路径。也就是说，每个轨迹都代表一个端到端操作。由于跟踪记录由 span 组成，而 span 是单个函数或操作的记录，因此您可以跟踪请求的流程并检查延迟时间数据。此信息可帮助您确定问题的根本原因。

Cloud Trace 是 Google Cloud的分布式跟踪系统，它提供了一些功能，可用于探索轨迹或使用 SQL 分析轨迹数据。不过，许多Google Cloud 服务（例如应用监控和代理注册表）都可以显示由 Cloud Trace 管理的数据。借助这些服务，您可以在所用服务的上下文中查看轨迹数据。

准备工作

  1. 启用 Cloud Trace、Cloud Logging、Telemetry 和 Model Armor API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    启用 API

  2. 为代理设置跟踪。
  3. 在网关或 Google CloudMCP 服务器上配置 Model Armor。

所需的角色

如需获得查看跟踪记录数据所需的权限，请让管理员为您授予项目的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如需了解您可能需要的其他角色，请参阅 Cloud Trace 访问权限控制和 Cloud Logging 访问权限控制。

支持的载荷

如需查看支持的载荷列表，请参阅支持和不支持的载荷。

对于包含不受支持的载荷的请求，Model Armor 会生成一个包含错误的 span。

Model Armor span 名称和属性

以下 Model Armor 范围可供使用：

  • 父级 span：apply_guardrail "Google Cloud Model Armor"
  • 子 span：Request Path
  • 子 span：Response Path

以下部分列出了 Model Armor span 的所有可能属性。并非所有属性都存在于每个 span 中。 这些属性名称可能会发生变化。

父 span 属性

父 span apply_guardrail "Google Cloud Model Armor" 具有以下属性：

  • cloud.provider：与操作关联的云提供商。
  • cloud.region：发生操作的 Google Cloud 区域。
  • gcp.project_id：发生操作的项目的 ID。
  • rpc.system：用于操作的底层远程过程调用 (RPC) 框架或协议，例如 grpc。
  • service.name：与操作关联的 Google Cloud 服务。 对于 Model Armor span，此字段的值为 modelarmor。

请求路径属性

Request Path 子 span 具有以下属性：

  • gen_ai.security.target.type：安全措施所应用到的内容或操作类型。在 Request Path span 中，此值始终为 input。
  • gen_ai.security.decision.type：Model Armor 应用的判决或操作。值 modify 表示 Model Armor 已根据提供的模板对内容中的敏感数据进行了隐去（去标识化）。
  • gen_ai.security.decision.code：安全决策的数字代码。
  • gen_ai.security.decision.reason：用户易于理解的决策原因。
  • gen_ai.security.policy.id：Model Armor 模板的完整资源名称，格式为 projects/PROJECT_ID/locations/LOCATION/templates/MODEL_ARMOR_TEMPLATE_ID。
  • gen_ai.security.policy.name：用于相应操作的 Model Armor 模板的名称。
  • gcp.modelarmor.filter.match.state：内容是否违反了任何 Model Armor 过滤条件（也称为检测器）。
  • gcp.modelarmor.violations：内容违反的 Model Armor 过滤条件。 值 deidentified 表示 Model Armor 已根据提供的模板从内容中编辑掉敏感数据。
  • gcp.modelarmor.rai.violation：内容违反的 Responsible AI 类别。如需了解详情，请参阅 Responsible AI 安全过滤器。
  • error.type：所遇到错误的标识符。

响应路径属性

Response Path 子 span 具有以下属性：

  • gen_ai.security.target.type：安全措施所应用到的内容或操作类型。在 Response Path span 中，此值始终为 output。
  • gen_ai.security.decision.type：Model Armor 应用的判决或操作。值 modify 表示 Model Armor 根据提供的模板从内容中编辑（去标识化）了敏感数据。
  • gen_ai.security.decision.code：安全决策的数字代码。
  • gen_ai.security.decision.reason：用户易于理解的决策原因。
  • gen_ai.security.policy.id：Model Armor 模板的完整资源名称，格式为 projects/PROJECT_ID/locations/LOCATION/templates/MODEL_ARMOR_TEMPLATE_ID。
  • gen_ai.security.policy.name：用于相应操作的 Model Armor 模板的名称。
  • gcp.modelarmor.filter.match.state：内容是否违反了任何 Model Armor 过滤条件（也称为检测器）。
  • gcp.modelarmor.violations：内容违反的 Model Armor 过滤条件。 值 deidentified 表示 Model Armor 已根据提供的模板从内容中编辑掉敏感数据。
  • gcp.modelarmor.rai.violation：内容违反的 Responsible AI 类别。如需了解详情，请参阅 Responsible AI 安全过滤器。
  • error.type：所遇到错误的标识符。

查看 Model Armor 跨度的详细信息

如需查看 Model Armor span 及其详细信息（包括属性和 DAG），请按以下步骤操作：

  1. 在 Google Cloud 控制台中，前往 Agent Registry。

    前往 Agent Registry

  2. 选择您的项目。
  3. 点击代理的名称。
  4. 点击跟踪记录标签页。
  5. 点击要查看的轨迹的 ID。如果轨迹涉及 Model Armor span，则轨迹会包含 apply_guardrail "Google Cloud Model Armor" span。

  6. 探索轨迹：

    • 如需以有向无环图 (DAG) 的形式查看轨迹，请点击图表视图。此视图将代理的执行轨迹表示为节点-链接图。DAG 强调不同轨迹 span 之间的因果关系和依赖关系，并显示一个操作如何触发下一个操作。图中的每个节点都是一个 span。
    • 如需以时间轴形式查看轨迹，请点击时间轴视图。时间轴中的每个条形都代表一个 span。

  7. 点击某个 span 以查看其属性。

或者，您也可以点击在 Cloud Trace 中查看，通过 Trace 探索器查看项目中的所有 span。应用跨度过滤条件来搜索 apply_guardrail "Google Cloud Model Armor" 跨度。

后续步骤