屏幕图片

Model Armor 会筛查提示和回答中的独立图片以及嵌入在受支持富文本文档中的图片，帮助保护您的生成式 AI 应用免受图片中嵌入的风险的影响。

Model Armor 使用以下方法筛查图片：

规范和限制

使用 Model Armor 筛查图片时，请考虑以下规范和限制：

  • 支持的图片格式：Model Armor 会筛查 JPEG、PNG 和 BMP 格式的独立图片。它还会从受支持的富文本文件中提取并筛查嵌入的图片。
  • 大小限制：每张独立图片的大小不得超过 4 MB。富文本文件的总大小不得超过 4 MB，且最多包含 5 张嵌入图片。超出其中任何限制都会导致 Model Armor 跳过扫描整个文件。如需了解详情，请参阅文件大小系统限制和扫描文档中的嵌入图片。
  • 独立提示：当您使用独立图片调用 SanitizeUserPrompt 和 SanitizeModelResponse 方法时，Model Armor 会针对每个请求过滤单张图片。不支持在单个请求中筛查多张独立图片。此外，Model Armor 不支持在单个请求中组合文本和图片的独立提示。不过，您可以同时启用文本和图片模态，以筛查同时包含文本和图片的富文本文档。
  • 去标识化：配置 Sensitive Data Protection 去标识化模板时，Model Armor 会遮盖文本或独立图片，但不会同时遮盖两者。选择图片模态 (MODALITY_IMAGE) 时，不支持对富文本文档进行去标识化。如需了解详情，请参阅遮盖独立图片中的敏感数据和屏蔽文档中的嵌入图片。
  • 流式传输：Model Armor 流式传输方法仅支持文本输入，不支持图片或文件。
  • 支持的集成：您可以通过直接调用 Model Armor REST API 或通过 Gemini Enterprise 集成来筛查图片。所有其他 Model Armor 集成仅扫描和清理文本。如需了解详情，请参阅支持的模态。
  • 区域可用性：仅在特定多区域支持图片筛查。如果您向 Model Armor 不支持图片过滤的端点发送包含图片的提示，则回答中的 invocationResult 字段会指示 FAILURE。如需查看支持图片筛查的位置列表，请参阅各区域支持的功能。

图片的 token 计算和价格

Model Armor 采用统一的基于 token 的定价模式，其中图片 token 的费率与文本 token 相同。

如果 Model Armor 在过滤处理之前拒绝或跳过输入（例如空输入或超出文件大小或嵌入图片限制的文件和图片），则不会向您收费。不过，如果输入通过了初始验证，即使在以下情况下，您也需要为计算出的 token 付费：

  • 跳过所有检测器：跳过部分或全部已配置的过滤器（检测器），并返回 EXECUTION_SKIPPED（例如，当检测器无法解析 4 MB 限制内的图片载荷时，或者当跳过某个模态的过滤器时）。
  • 使用 IMAGE 字节数据类型封装的非图片文件：发送非图片文件（例如 ZIP、CSV 或 Microsoft Word 文档），并将 byteDataType 设置为 IMAGE（最大 4 MB）。即使过滤条件返回 EXECUTION_SKIPPED，Model Armor 也会使用独立图片 token 计算方式对请求进行结算。

Model Armor 会根据输入类型和配置的模态计算图片和文档的 token：

  • 独立图片：Model Armor 会将每张处理后的图片（不超过 4 MB）转换为 token，每张图片的基本 token 数量为 5,000 个，图片大小每增加 1 兆字节 (MB)，token 数量增加 1,000 个。在计算基于大小的 token 时，Model Armor 会将图片大小向上舍入到下一个整数 MB：

    每张图片的 token 数量 = 5,000 +（1,000 × 图片大小 [以 MB 为单位，向上舍入到下一个整数 MB]）

    通过 OCR 从图片中提取的文本会包含在图片 token 计算中，不会产生单独的文本 token 费用。

  • 富文本文档：词元计算取决于模板中配置的模态：

    • 文本模态 (MODALITY_TEXT)：Model Armor 会根据从文档中提取的文本计算 token（每个 token 约 4 个字符）。系统不会提取嵌入的图片，也不会对其计费。
    • 图片模态 (MODALITY_IMAGE)：Model Armor 使用图片 token 公式为每个处理的嵌入图片单独计算 token。文档文本不计费。
    • 文本和图片模态（MODALITY_TEXT 和 MODALITY_IMAGE）：Model Armor 会将总 token 数量计算为提取的文档文本中的 token 数量与每个处理后的嵌入图片中的 token 数量之和。

下表举例说明了 Model Armor 如何计算已处理图片的 token：

图片大小 用于计算的四舍五入大小 Token 计算 token 总数
500 KB 1 MB 5,000 + (1 × 1,000) 6,000 个 token
1.9 MB 2 MB 5,000 + (2 × 1,000) 7,000 个 token
4 MB 4 MB 5,000 + (4 × 1,000) 9,000 个 token

准备工作

在筛选图片之前，请先满足以下前提条件：

创建或更新已启用图片模态的模板

创建或更新模板时，选择要包含的模态 MODALITY_IMAGE（在 Google Cloud 控制台中选择图片或全部，或在使用 REST API 时在 templateMetadata 中选择 "modalities": ["MODALITY_IMAGE", "MODALITY_TEXT"]）。如果您未指定模态、将 modalities 字段留空或仅指定 MODALITY_TEXT，则 Model Armor 仅扫描文本，并针对扫描跳过模态的过滤器返回 EXECUTION_SKIPPED。

获取所需的权限

确保您拥有清理提示和回答所需的 Identity and Access Management 角色（例如 roles/modelarmor.user），并且如果您跨项目使用高级 Sensitive Data Protection 模式，请向 Model Armor 服务代理授予所需的 DLP 角色。如需了解相关说明，请参阅获取所需权限。

清理独立图片

如需在用户提示或模型回答中筛查独立图片，请将 byteDataType 字段设置为 IMAGE，并在 byteData 字段中提供采用受支持格式（JPEG、PNG 或 BMP）的 base64 编码图片。

使用以下命令清理包含图片的提示：

curl -X POST \
    -d "$(jq -n \
    --arg data "$(base64 -w 0 -i IMAGE)" \
    '{userPromptData: {byteItem: {byteDataType: "IMAGE", byteData: $data}}}')" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"

替换以下内容：

  • PROJECT_ID：包含模板的项目的 ID。
  • LOCATION：模板的位置。
  • TEMPLATE_ID：配置为扫描映像的模板的 ID (MODALITY_IMAGE)。
  • IMAGE：受支持格式的图片文件的路径。

响应类似于以下示例：

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "MATCH_FOUND",
          "confidenceLevel": "HIGH"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "MATCH_FOUND"
          }
        }
      }
    }
  }
}

遮盖独立图片中的敏感数据

使用 Sensitive Data Protection 高级模式时，如果您同时使用 Sensitive Data Protection 检查模板和 Sensitive Data Protection 去标识化模板配置 Model Armor 模板，Model Armor 会对独立图片中的敏感发现结果进行隐去。请确保在去标识化模板中配置图片隐去。如需详细了解如何在 Model Armor 中配置 Sensitive Data Protection，请参阅设置 Sensitive Data Protection 设置。如需了解去标识化限制，请参阅规范和限制以及屏蔽文档中的嵌入图片。

以下示例展示了启用 Sensitive Data Protection 隐去功能的过滤条件配置：

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate": "projects/PROJECT_ID/locations/LOCATION/inspectTemplates/INSPECT_TEMPLATE_ID",
        "deidentifyTemplate": "projects/PROJECT_ID/locations/LOCATION/deidentifyTemplates/DEIDENTIFY_TEMPLATE_ID"
      }
    }
  }
}

替换以下内容：

  • PROJECT_ID：包含 Sensitive Data Protection 模板的项目的 ID。
  • LOCATION：模板的位置。
  • INSPECT_TEMPLATE_ID：检查模板的 ID。
  • DEIDENTIFY_TEMPLATE_ID：去标识化模板的 ID。

使用启用了图片隐去功能的模板对独立图片进行清理时，响应中会包含隐去后的图片以及每个发现结果的边界框坐标：

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "redactResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "MATCH_FOUND",
            "redactedImage": "[REDACTED_IMAGE]",
            "findings": [
              {
                "infoType": "EMAIL_ADDRESS",
                "likelihood": "LIKELY",
                "location": {
                  "contentLocations": [
                    {
                      "imageFindingLocation": {
                        "boundingBoxes": {
                          "top": 16,
                          "left": 121,
                          "width": 620,
                          "height": 90
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  }
}

筛查文档中的嵌入图片

如果您在模板中启用图片模态 (MODALITY_IMAGE) 并清理富文本文档（PDF、WORD_DOCUMENT、EXCEL_DOCUMENT 或 POWERPOINT_DOCUMENT），Model Armor 会自动提取并筛查文档中最多 5 张嵌入图片。如果您同时启用 MODALITY_TEXT 和 MODALITY_IMAGE，Model Armor 会同时筛查文档文本和嵌入的图片。

无论您是仅启用 MODALITY_IMAGE，还是同时启用 MODALITY_IMAGE 和 MODALITY_TEXT，Model Armor 都会跳过扫描整个文档（包括文本和嵌入式图片），而不会进行部分扫描。在以下情况下，它会为所有已配置的过滤条件（包括检查）返回 EXECUTION_SKIPPED，并返回总体 filterMatchState NO_MATCH_FOUND：

如需查看演示如何使用 REST 和客户端库发送基于文件的提示的代码示例，请参阅基于文件的提示。

部分文件检查

Model Armor 仅在整个文件的过滤器（检测器）级别返回部分结果 (invocationResult: PARTIAL)，而不是针对每个图片返回结果：

  • 单张图片失败（跳过整个文件）：如果文件中的某些嵌入图片已成功扫描，但文件中的一个或多个其他图片无法提取或扫描，Model Armor 会跳过整个文件。它会为所有已配置的过滤条件返回 executionState: EXECUTION_SKIPPED，并返回总体 filterMatchState NO_MATCH_FOUND。
  • 检测器级失败（部分结果）：如果某些配置的过滤器在整个文件中成功运行，而一个或多个其他过滤器在整个文件中被跳过（例如，由于检测器超时），Model Armor 会返回包含以下字段的部分结果：
    • 调用结果：invocationResult 字段设置为 PARTIAL（而不是 SUCCESS），表示系统跳过了对该文件的一个或多个已配置过滤条件的检查，但完成了其他过滤条件的检查。
    • 过滤条件执行状态：文件报告中跳过的过滤条件executionState: EXECUTION_SKIPPED。在文件报告 executionState: EXECUTION_SUCCESS 中完成检查的过滤器。
    • 匹配状态：filterMatchState 字段反映了已完成检查的过滤条件中的发现结果。如果任何已完成的过滤条件检测到违规行为，filterMatchState 会设置为 MATCH_FOUND。如果已完成的过滤条件未检测到任何违规行为，则 filterMatchState 会设置为 NO_MATCH_FOUND。

部分检查的安全注意事项

从安全角度来看，invocationResult 值为 PARTIAL 表示一个或多个已配置的过滤条件无法评估文件。跳过的过滤器所针对的潜在安全威胁或违规行为可能仍然存在于文件中。

默认情况下，如果完成检查的过滤条件未检测到任何违规行为，则 filterMatchState 为 NO_MATCH_FOUND。如果您的应用要求所有配置的过滤条件在允许提示到达 AI 模型之前完成检查，请检查回答中的 invocationResult 字段。如果值为 PARTIAL，请配置应用逻辑，以便根据组织的风险承受能力处理请求，例如拒绝提示或将其转送以进行二次审核。

部分检查响应示例

以下示例展示了一个响应，其中文件跳过了儿童性虐待内容 (CSAM) 过滤器，而其他已配置的过滤器完成了检查。Model Armor 会返回 PARTIAL 的 invocationResult、CSAM 过滤条件的 EXECUTION_SKIPPED 状态以及其余过滤条件的 EXECUTION_SUCCESS：

{
  "sanitizationResult": {
    "filterMatchState": "NO_MATCH_FOUND",
    "invocationResult": "PARTIAL",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SKIPPED",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "NO_MATCH_FOUND"
          }
        }
      }
    }
  }
}

后续步骤