配置对象丰富化

如需为 Cloud Storage 存储桶中的图片和 PDF 文档生成结构化元数据，请创建功能配置 (FeatureConfig) 资源。您还必须授权对象丰富化服务代理访问您的数据。配置对象丰富化功能后，Cloud Storage 会使用您选择的机器学习模型异步评估匹配的对象，并将结果作为对象上下文直接附加到对象。

本页面介绍了如何创建、列出、查看、更新和删除特征配置。此外，还介绍了如何向服务代理授予所需的 Identity and Access Management (IAM) 权限。

完整的工作流涉及以下步骤：

  1. 创建特征配置 (FeatureConfig) 资源，以定义范围并选择模型。
  2. 授权服务代理访问您的存储桶。
  3. 查看和管理对象上的丰富元数据。
  4. 在 BigQuery 中使用 SQL 批量分析丰富数据。
  5. 随着工作负载的变化，更新或删除功能配置。

如需了解概念性详情和支持的用例，请参阅对象丰富化概览。

准备工作

在配置对象丰富化之前，请完成以下设置步骤：

获取所需的角色

如需获得创建和管理功能配置所需的权限，请让您的管理员为您授予项目的 Storage Admin (roles/storage.admin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含创建和管理特征配置所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需创建和管理特征配置，需要具备以下权限：

  • storage.featureConfigs.create
  • storage.featureConfigs.list
  • storage.featureConfigs.get
  • storage.featureConfigs.update
  • storage.featureConfigs.delete

您也可以使用自定义角色或其他预定义角色来获取这些权限。

（可选）准备 Storage Insights 数据集以进行 SQL 分析

如果您计划在 BigQuery 中使用 SQL 查询和分析数百万个对象的丰富元数据，则必须先存储空间分析。存储空间分析数据集会自动将对象上下文直接导出到可查询的 BigQuery 表中。

如果您只想使用 Google Cloud 控制台、Google Cloud CLI 或 API 检查单个对象，则可以跳过此步骤。

创建功能配置

功能配置 (FeatureConfig) 指定 Cloud Storage 监控哪些存储桶，以及哪些机器学习模型评估您的对象。在配置中指定确切的存储桶名称；对象丰富化功能不支持正则表达式或通配符。如果您在创建配置后创建、重新创建（删除并再次创建）或重新定位存储桶，则必须更新功能配置以包含这些存储桶。如需了解详情，请参阅配置和范围管理。

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 JSON API 创建功能配置。

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Storage 对象丰富化页面。

    前往“对象丰富化”

  2. 点击创建。

  3. 在定义来源步骤中，指定配置名称和目标存储桶：

    1. 在名称字段中，输入功能配置的唯一名称。名称必须为 1-63 个字符，并且只能包含小写字母、数字或连字符。此外，名称必须以小写字母开头且不能以连字符结尾。创建配置后，您将无法更改此名称。
    2. 可选：为便于识别配置，请在说明字段中输入说明（最多 256 个字符）。
    3. 如需指定要扩充的存储桶，请在存储桶名称字段中输入一个或多个存储桶名称，并以英文逗号或空格分隔。或者，点击浏览，选择一个存储桶，然后点击选择。
    4. 点击继续。

  4. 在选择模型步骤中，选中要启用的一个或多个机器学习模型的复选框，然后点击继续：

    • 图片对象检测 (object-detector)：识别并定位图片中的多个对象。
    • 图片人脸检测 (face-detector)：检测图片中的人脸及其属性。
    • 图片标签 (label-detector)：根据图片内容为其分配标签。
    • 图片露骨内容检测 (content-safety)：检测成人内容、暴力内容或其他敏感内容。
    • PDF 分类 (pdf-classification)：识别文档主题类别。

    如需详细了解每个模型及其输出架构，请参阅支持的模型和架构。

  5. 在选择处理位置步骤中，从处理位置菜单中选择一个多区域位置（美国、欧盟或亚洲），然后点击继续。

  6. 在授予所需权限步骤中，选择如何向对象丰富化服务代理授予所需的 IAM 角色：

    • 授予项目级权限：自动向服务代理授予所需角色（roles/storage.annotationGeneratorService 和 roles/storage.bucketViewer），以处理项目中所有当前及未来的 Cloud Storage 存储桶。选择此选项需要对项目拥有 resourcemanager.projects.setIamPolicy 权限。如果您没有此权限，则无法使用该选项。
    • 请在稍后手动提供授权权限：创建配置，但不立即授予权限。您必须先向服务代理授予权限，然后 Cloud Storage 才能处理对象。

  7. 点击创建。

    创建功能配置会启动一项长时间运行的操作。操作完成后， Google Cloud 控制台会打开配置详情页面。如果您选择了授予项目级权限，则 Google Cloud 控制台会在创建配置后应用 IAM 政策绑定。

命令行

如需创建功能配置，请使用 gcloud alpha storage feature-configs create 命令：

gcloud alpha storage feature-configs create FEATURE_CONFIG_ID \
    --description="DESCRIPTION" \
    --auto-annotate-models=MODELS \
    --auto-annotate-processing-location=PROCESSING_LOCATION \
    --include-bucket-id-regexes=BUCKET_NAME

其中：

  • FEATURE_CONFIG_ID 是地图项配置的唯一 ID。长度必须介于 1 到 63 个字符之间，以小写字母开头，并且只能包含小写字母、数字或连字符。不能以连字符结尾。
  • DESCRIPTION 是功能配置的可选说明。例如 Scan invoices and receipts。
  • MODELS 是要启用的机器学习模型的英文逗号分隔列表：face-detector、object-detector、label-detector、content-safety 或 pdf-classification。如需详细了解每个模型及其输出架构，请参阅支持的模型和架构。
  • PROCESSING_LOCATION 是进行数据处理的多区域处理位置。支持的值为 us、eu 或 asia。
  • BUCKET_NAME 是要包含在此配置中的存储桶的确切名称。您可以指定以英文逗号分隔的确切存储桶名称列表。

JSON API

  1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

  2. 创建一个包含功能配置设置的 JSON 文件：

    {
  "description": "DESCRIPTION",
  "autoAnnotateConfig": {
    "models": [
      { "name": "MODEL_NAME" }
    ],
    "processingLocation": "PROCESSING_LOCATION"
  },
  "filter": {
    "includedCloudStorageBuckets": {
      "bucketIdRegexes": [
        "BUCKET_NAME"
      ]
    }
  }
}

    其中：

    • DESCRIPTION 是功能配置的可选说明。例如 Scan invoices and receipts。

    • MODEL_NAME 是要启用的机器学习模型的名称：face-detector、object-detector、label-detector、content-safety 或 pdf-classification。如需详细了解每个模型及其输出架构，请参阅支持的模型和架构。如需启用多个模型，请向 models 数组添加其他模型对象。

    • PROCESSING_LOCATION 是进行数据处理的多区域处理位置。支持的值为 us、eu 或 asia。

    • BUCKET_NAME 是要包含在配置中的存储桶的确切名称。例如 my-bucket。 如需包含多个存储桶，请在 bucketIdRegexes 数组中指定其他存储桶名称字符串。

  3. 使用 cURL 向 JSON API 发送 featureConfigs.create 请求：

    curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage./v2/projects/PROJECT_ID/locations/global/featureConfigs?featureConfigId=FEATURE_CONFIG_ID"

    其中：

    • JSON_FILE_NAME 是您在上一步中创建的 JSON 文件的路径。例如 config.json。
    • PROJECT_ID 是您的 Google Cloud 项目 ID。例如 my-project。
    • FEATURE_CONFIG_ID 是功能配置的唯一 ID。例如 my-feature-config。长度必须介于 1 到 63 个字符之间，以小写字母开头，并且只能包含小写字母、数字或连字符。不能以连字符结尾。

  4. 可选：如需检查用于创建特征配置的长时间运行的操作的状态，请使用 cURL 向 JSON API 发送 operations.get 请求：

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage./v2/projects/PROJECT_ID/locations/global/operations/OPERATION_ID"

    其中：

    • PROJECT_ID 是您的 Google Cloud 项目 ID。例如 my-project。
    • OPERATION_ID 是创建响应中返回的操作 ID。

  5. 可选：如需列出所有活跃和历史操作，请使用 cURL 向 JSON API 发送 operations.list 请求：

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage./v2/projects/PROJECT_ID/locations/global/operations"

    其中，PROJECT_ID 是您的 Google Cloud项目 ID。例如 my-project。

向服务代理授予权限

创建功能配置时， Google Cloud 会为您的项目预配一个专用服务代理：service-PROJECT_NUMBER@gcp-sa-autoannotate.。

如需让此服务代理扫描您的存储桶、读取非结构化对象并附加丰富化元数据，您必须向其授予所需的 IAM 角色。

控制台

如果您在创建功能配置时选择了稍后手动授予权限，或者需要重新应用项目级权限，则可以从配置详情页面授予权限：

  1. 在 Google Cloud 控制台中，前往 Cloud Storage 对象丰富化页面。

    前往“对象丰富化”

  2. 在配置名称列中，点击功能配置的名称。

  3. 在操作栏中，点击授予权限。

  4. 在授予权限窗格中，点击授予项目范围的权限。

    此操作会向服务代理授予项目的 Storage Annotation Generator Service (roles/storage.annotationGeneratorService) 和 Storage Bucket Viewer (roles/storage.bucketViewer) 角色。在 Google Cloud 控制台中授予项目范围的权限需要对项目具有 resourcemanager.projects.setIamPolicy 权限。

    如需针对单个存储桶（而非整个项目）授予 roles/storage.annotationGeneratorService 角色，请使用 Google Cloud CLI。

命令行

  1. 向每个受监控存储桶或项目级层的服务代理授予 Storage Annotation Generator Service (roles/storage.annotationGeneratorService) 角色：

    • 如需在特定存储桶上授予角色，请使用 gcloud storage buckets add-iam-policy-binding 命令：

      gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate. \
    --role=roles/storage.annotationGeneratorService

      其中：

      • BUCKET_NAME 是您要授予权限的存储桶的名称。
      • PROJECT_NUMBER 是您的 Google Cloud项目编号。

    • 如需在项目中的所有存储桶中授予该角色，请使用 gcloud projects add-iam-policy-binding 命令：

      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate. \
    --role=roles/storage.annotationGeneratorService

      其中：

      • PROJECT_ID 是您的 Google Cloud项目 ID。
      • PROJECT_NUMBER 是您的 Google Cloud项目编号。

  2. 如需在项目级层授予 Storage Bucket Viewer (roles/storage.bucketViewer) 角色，以便服务代理可以检查存储桶配置，请使用 gcloud projects add-iam-policy-binding 命令：

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate. \
    --role=roles/storage.bucketViewer

    其中：

    • PROJECT_ID 是您的 Google Cloud 项目 ID。
    • PROJECT_NUMBER 是您的 Google Cloud项目编号。

授予角色后，IAM 权限可能需要几分钟时间才能完成同步，然后异步处理才会开始。

列出所有功能配置

如需列出项目中的所有功能配置，请完成以下步骤：

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Storage 对象丰富化页面。

    前往“对象丰富化”

    配置标签页会列出项目中的所有特征配置，包括其启用的模型、处理位置、范围、存储桶过滤条件、创建日期和上次更新日期。

  2. 可选：如需过滤列表，请在过滤条件字段中输入属性名称或值。

命令行

使用 gcloud alpha storage feature-configs list 命令：

gcloud alpha storage feature-configs list

JSON API

  1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

  2. 使用 cURL 向 JSON API 发送 featureConfigs.list 请求：

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage./v2/projects/PROJECT_ID/locations/global/featureConfigs"

    其中，PROJECT_ID 是Google Cloud 项目的 ID。例如 my-project。

查看功能配置详情

如需检查特定功能配置的模型、目标存储桶和处理位置，请完成以下步骤：

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Storage 对象丰富化页面。

    前往“对象丰富化”

  2. 在配置名称列中，点击要检查的功能配置的名称。

    配置详情页面会显示配置名称、说明、范围、包含的存储桶、处理位置、启用的模型、创建日期和上次更新日期。

命令行

使用 gcloud alpha storage feature-configs describe 命令：

gcloud alpha storage feature-configs describe FEATURE_CONFIG_ID

将 FEATURE_CONFIG_ID 替换为功能配置的 ID。

JSON API

  1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

  2. 使用 cURL 向 JSON API 发送 featureConfigs.get 请求：

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage./v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID"

    其中：

    • PROJECT_ID 是您的Google Cloud 项目的 ID。例如 my-project。
    • FEATURE_CONFIG_ID 是功能配置的 ID。例如 my-feature-config。

更新功能配置

您可以更新现有特征配置，以添加或移除机器学习模型、更改目标存储桶、修改处理位置或更新说明。

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Storage 对象丰富化页面。

    前往“对象丰富化”

  2. 在配置名称列中，点击要更新的功能配置的名称。

  3. 在配置详情页面上，更新要更改的设置：

    • 如需更新说明，请点击配置说明旁边的 修改配置说明。在修改说明窗格中，更新说明字段中的文本，然后点击保存。
    • 如需更新存储桶范围，请点击配置范围旁边的 修改配置范围。在定义范围步骤中，在存储桶名称字段中添加或移除目标存储桶，然后点击继续。在授予所需权限步骤中，为服务代理选择权限选项，然后点击保存。
    • 如需更新处理位置，请点击处理位置旁边的 修改配置处理位置。在修改处理位置窗格中，从处理位置菜单中选择一个多区域位置（us、eu 或 asia），然后点击保存。
    • 如需更新已启用的模型，请点击已启用的模型旁边的 修改已启用配置的模型。在修改模型窗格中，选中或清除要更新的模型对应的复选框，然后点击保存。

命令行

使用 gcloud alpha storage feature-configs update 命令更新说明、模型、处理位置或存储桶过滤条件：

gcloud alpha storage feature-configs update FEATURE_CONFIG_ID \
    --description="DESCRIPTION" \
    --auto-annotate-models=MODELS \
    --auto-annotate-processing-location=PROCESSING_LOCATION \
    --include-bucket-id-regexes=BUCKET_NAME

替换以下内容：

  • FEATURE_CONFIG_ID：您要更新的功能配置的 ID。
  • DESCRIPTION：功能配置的可选说明。例如 Scan invoices and receipts。
  • MODELS：要启用的机器学习模型的英文逗号分隔列表：face-detector、object-detector、label-detector、content-safety 或 pdf-classification。
  • PROCESSING_LOCATION：进行数据处理的多区域处理位置。有效值为 us、eu 或 asia。
  • BUCKET_NAME：要扫描的确切存储桶名称的逗号分隔列表。对象丰富化不支持通配符或正则表达式。如果您创建、重新创建或重新定位存储桶，则必须更新此列表以包含这些存储桶。

JSON API

  1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

  2. 创建一个包含要更新的设置的 JSON 文件。 例如，如需更新说明、启用的模型和目标存储桶，请运行以下命令：

    {
  "description": "DESCRIPTION",
  "autoAnnotateConfig": {
    "models": [
      { "name": "MODEL_NAME" }
    ],
    "processingLocation": "PROCESSING_LOCATION"
  },
  "filter": {
    "includedCloudStorageBuckets": {
      "bucketIdRegexes": [
        "BUCKET_NAME"
      ]
    }
  }
}

    其中：

    • DESCRIPTION 是功能配置的可选说明。例如 Scan invoices and receipts。

    • MODEL_NAME 是要包含的机器学习模型：face-detector、object-detector、label-detector、content-safety 或 pdf-classification。如需详细了解每个模型及其输出架构，请参阅支持的模型和架构。如需启用多个模型，请向 models 数组添加其他模型对象。

    • PROCESSING_LOCATION 是进行数据处理的多区域处理位置。有效值为 us、eu 或 asia。

    • BUCKET_NAME 是要包含在扫描中的存储桶的确切名称。例如 my-bucket。 对象丰富化功能不支持正则表达式或通配符。如果您创建、重新创建或重新定位存储桶，则必须更新此列表以包含这些存储桶。如需包含多个存储桶，请在 bucketIdRegexes 数组中指定其他存储桶名称字符串。

  3. 使用 cURL 向 JSON API 发送 featureConfigs.patch 请求：

    curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  "https://storage./v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID?updateMask=UPDATE_MASK"

    其中：

    • JSON_FILE_NAME 是您在第 2 步中创建的 JSON 请求文件的本地路径。例如 update.json。
    • PROJECT_ID 是您的Google Cloud 项目的 ID。例如 my-project。
    • FEATURE_CONFIG_ID 是要更新的功能配置的 ID。例如 my-feature-config。
    • UPDATE_MASK 是您要更新的字段的英文逗号分隔列表，例如 description,filter 或 autoAnnotateConfig.models。如需了解语法规则，请参阅 FieldMask。

删除特征配置

删除功能配置会阻止 Cloud Storage 为匹配的存储桶生成新的丰富内容。删除配置不会删除已附加到存储对象的现有丰富内容。

如需删除特征配置，请完成以下步骤：

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Storage 对象丰富化页面。

    前往“对象丰富化”

  2. 在配置名称列中，点击要删除的功能配置的名称，然后点击 删除。

  3. 在确认对话框中，点击确认。

命令行

使用 gcloud alpha storage feature-configs delete 命令：

gcloud alpha storage feature-configs delete FEATURE_CONFIG_ID

将 FEATURE_CONFIG_ID 替换为功能配置的 ID。

JSON API

  1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

  2. 使用 cURL 向 JSON API 发送 featureConfigs.delete 请求：

    curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage./v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID"

    其中：

    • PROJECT_ID 是您的Google Cloud 项目的 ID。例如 my-project。
    • FEATURE_CONFIG_ID 是要删除的功能配置的 ID。例如 my-feature-config。

后续步骤