创建特征组

特征组是一种与包含特征数据的 BigQuery 表或视图相关联的特征注册表资源。一个特征组可以包含多个特征，其中每个特征都与特征数据源中的一列相关联。如果您想在特征注册表中注册特征数据源，请创建一个特征组，然后向其中添加特征。

创建特征组并关联 BigQuery 数据源后，您可以创建与数据源中的列相关联的特征。请注意，虽然在创建特征组时关联数据源是可选操作，但您必须先关联 BigQuery 表或视图，然后才能在该特征组中创建特征。每个特征都对应于与特征组关联的数据源中的一列。

为什么要使用特征组和特征？

注册特征数据源是可选操作。不过，在以下情况下，您必须通过创建特征组和特征来注册特征数据：

使用时序格式的历史数据训练模型：如果特征数据源包含最新特征数据以及具有相同实体 ID 的多个特征记录的历史特征数据，请添加 feature_timestamp 列，将此数据格式化为时序格式。在此场景中，您必须使用特征组和特征注册数据源。然后，您可以按如下方式传送特征：
- 使用在线传送功能，根据时间戳传送最新的特征值，以进行实时预测。
- 使用离线传送来传送最新特征值和历史特征值，以训练模型。
汇总来自多个来源的特征：在创建特征视图实例时，使用特征组汇总来自多个 BigQuery 数据源的特定列。
传送 null 特征值：在在线传送期间，如果您只想传送最新的特征值（包括 null 值），请通过创建将 dense 参数设置为 true 的特征组来注册特征数据源。

注意：如需传送 null 特征值，您还必须使用配置了 Bigtable 在线传送的在线存储区实例，并在特征视图中使用预定数据同步。
在特征视图中使用持续数据同步：注册特征是在特征视图中使用持续数据同步的前提条件。
注意：
如需使用持续数据同步，您还必须满足以下要求：
- 在线存储区实例必须配置为 Bigtable 在线传送。
- 关联的 BigQuery 数据源必须位于 eu、us 或 us-central1 中。
监控特征是否存在异常：如果您想设置特征监控，以检索特征统计信息并检测特征漂移，则必须注册特征。

何时不应使用特征组和特征

如果您想从特征数据源传送嵌入，请不要通过创建特征组和特征来注册该数据源。在这种情况下，您必须通过将 BigQuery 表或视图直接与特征视图相关联来设置在线传送。

如需详细了解如何在不注册特征数据源的情况下设置在线传送，请参阅根据 BigQuery 来源创建特征视图。

控制访问权限

您可以在以下级别控制特征组的访问权限：

控制对 FeatureGroup 资源的访问权限：如需控制特定个人、Google 群组、网域或服务账号对特征组的访问权限，请为该特征组设置 IAM 政策。
控制对 BigQuery 数据源的访问权限：默认情况下，特征组使用为项目配置的默认服务账号。Vertex AI Feature Store 会为此服务账号分配 BigQuery Data Viewer Identity and Access Management (IAM) 角色。这样一来，任何具有在项目中创建特征组权限的用户都可以访问 BigQuery 中的特征数据源。如需限制对 BigQuery 数据源的访问权限或向其他用户授予访问权限，您可以设置特征组以使用其自己的专用服务账号。Vertex AI Feature Store 会为配置为具有专用服务账号的每个特征组生成唯一的服务账号邮箱。
注意：
您可以通过以下任一方式查看特征组的专用服务账号邮箱：
- 使用 featureGroups.list 方法检索所有特征组的列表。
- 使用 featureGroups.get 方法检索特征组的详细信息。

准备工作

在创建特征组之前，请完成以下前提条件：

确保您的项目中至少已创建一个在线存储区实例，即使您想创建新的在线存储区实例也是如此。如果您使用的是新项目，请先创建在线存储区实例，然后再创建特征组。
设置 BigQuery 表或视图中的特征数据格式，使其符合数据源准备准则。
验证您的 BigQuery 数据源是否包含至少一个具有 string 或 int 值的实体 ID 列。
向 Vertex AI 进行身份验证，除非您已完成此操作。
Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
Python

如需在本地开发环境中使用本页面上的 Python 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭证设置应用默认凭证。
如需了解详情，请参阅 Set up authentication for a local development environment。如需了解详情，请参阅身份验证文档中的为本地开发环境设置 ADC。
REST

如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。
如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

创建特征组以注册特征数据源

使用以下示例可创建特征组并关联特征数据源（例如 BigQuery 表或视图）。

控制台

请按照以下说明使用 Google Cloud 控制台创建特征组：

在 Google Cloud 控制台的 Vertex AI 部分中，前往 Feature Store 页面。

转到 Feature Store 页面
在特征组部分中，点击创建以打开创建特征组页面上的基本信息窗格。
指定特征组名称。
可选：若要添加标签，请点击添加标签，然后指定标签名称和值。您可以为一个特征组添加多个标签。
在 BigQuery 路径字段中，点击浏览，以选择要与特征组关联的 BigQuery 源表或视图。
在实体 ID 列列表中，选择 BigQuery 源表或视图中的实体 ID 列。

请注意，如果 BigQuery 源表或视图具有名为 entity_id 的列，则此参数为可选。在这种情况下，如果您未选择实体 ID 列，则特征组会使用 entity_id 列作为默认实体 ID 列。
点击继续。
在注册窗格中，点击以下选项之一，以指示是否要向新特征组添加特征：
- 包括 BigQuery 表中的所有列 - 在特征组中为 BigQuery 源表或视图中的所有列创建特征。
- 手动输入特征 - 根据 BigQuery 来源中的特定列创建特征。对于每个特征，请输入特征名称，然后点击列表中相应的 BigQuery 源列名称。
  
  如需添加更多特征，请点击添加其他特征。
- 创建空特征组 - 创建特征组而不向其添加特征。
点击创建。

Python

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。如需了解详情，请参阅 Python API 参考文档。


from google.cloud import aiplatform
from vertexai.resources.preview import feature_store
from typing import List


def create_feature_group_sample(
    project: str,
    location: str,
    feature_group_id: str,
    bq_table_uri: str,
    entity_id_columns: List[str],
):
    aiplatform.init(project=project, location=location)
    fg = feature_store.FeatureGroup.create(
        name=feature_group_id,
        source=feature_store.utils.FeatureGroupBigQuerySource(
            uri=bq_table_uri, entity_id_columns=entity_id_columns
        ),
    )
    return fg

project：您的项目 ID。
location：要在其中创建特征组的区域，例如 us-central1。
feature_group_id：您要创建的新特征组的名称。
bq_table_uri：您要为特征组注册的 BigQuery 源表或视图的 URI。
entity_id_columns：包含实体 ID 的列的名称。您可以指定一列或多列。
- 如需仅指定一个实体 ID 列，请按以下格式指定列名称：
  "entity_id_column_name"。
- 如需指定多个实体 ID 列，请按以下格式指定列名称：
  ["entity_id_column_1_name", "entity_id_column_2_name", ...]。

REST

如需创建 FeatureGroup 资源，请使用 featureGroups.create 方法发送 POST 请求。

在使用任何请求数据之前，请先进行以下替换：

LOCATION_ID：要在其中创建特征组的区域，例如 us-central1。
SERVICE_AGENT_TYPE：可选。特征组的服务账号配置。如需为特征组使用专用服务账号，请输入 SERVICE_AGENT_TYPE_FEATURE_GROUP。
PROJECT_ID：您的项目 ID。
ENTITY_ID_COLUMNS：包含实体 ID 的列名称。您可以指定一列或多列。
- 如需仅指定一个实体 ID 列，请按以下格式指定列名称：
  "entity_id_column_name"。
- 如需指定多个实体 ID 列，请按以下格式指定列名称：
  ["entity_id_column_1_name", "entity_id_column_2_name", ...]。
FEATUREGROUP_NAME：您要创建的新特征组的名称。
BIGQUERY_SOURCE_URI：您要为特征组注册的 BigQuery 源表或视图的 URI。
TIMESTAMP_COLUMN：可选。指定 BigQuery 源表或视图中包含特征时间戳的列的名称。
您只需在数据格式化为时间序列且包含特征时间戳的列未命名为 feature_timestamp 时，才需要指定时间戳列的名称。

注意：如果您将 static_data_source 参数设置为 true，请勿添加 time_series 参数。
STATIC_DATA_SOURCE：可选。如果数据的格式不是时序格式，请输入 true。默认设置为 false。

注意：如果您使用 time_series 参数，请勿添加 static_data_source 参数。
DENSE：可选。指明 Vertex AI Feature Store 在从与特征组关联的特征视图中传送数据时如何处理 null 值：
- false - 这是默认设置。Vertex AI Feature Store 仅传送最新的非 null 特征值。如果特征的最新值为 null，Vertex AI Feature Store 会传送最新的非 null 历史值。不过，如果该特征的当前值和历史值均为 null，Vertex AI Feature Store 会将 null 作为特征值。
- true - 对于具有预定数据同步的特征视图，Vertex AI Feature Store 仅传送最新的特征值，包括 null 值。对于具有持续数据同步的特征视图，Vertex AI Feature Store 仅传送最新的非 null 特征值。不过，如果特征的当前值和历史值均为 null，则 Vertex AI Feature Store 会将 null 作为特征值进行传送。如需详细了解数据同步类型以及如何在特征视图中配置数据同步类型，请参阅同步特征视图中的数据。

HTTP 方法和网址：

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups?feature_group_id=FEATUREGROUP_NAME

请求 JSON 正文：

{
  "service_agent_type": "SERVICE_AGENT_TYPE",
  "big_query": {
    "entity_id_columns": "ENTITY_ID_COLUMNS",
    "big_query_source": {
      "input_uri": "BIGQUERY_SOURCE_URI",
    }
    "time_series": {
      "timestamp_column": ""TIMESTAMP_COLUMN"",
    },
    "static_data_source": STATIC_DATA_SOURCE,
    "dense": DENSE
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups?feature_group_id=FEATUREGROUP_NAME"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups?feature_group_id=FEATUREGROUP_NAME" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateFeatureGroupOperationMetadata",
    "genericMetadata": {
      "createTime": "2023-09-18T03:00:13.060636Z",
      "updateTime": "2023-09-18T03:00:13.060636Z"
    }
  }
}

后续步骤

了解如何创建特征。
了解如何更新特征组。
了解如何删除特征组。

创建特征组 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

为什么要使用特征组和特征？

何时不应使用特征组和特征

控制访问权限

准备工作

Console

Python

REST

创建特征组以注册特征数据源

控制台

Python

REST

curl

PowerShell

后续步骤

创建特征组