提取训练数据

如需提取用于模型训练的特征数据，请使用批量传送。如果您需要导出特征值以进行归档或临时分析，请改为导出特征值。

提取用于模型训练的特征值

对于模型训练，您需要一个包含预测任务示例的训练数据集。这些示例由包含特征和标签的实例组成。实例是您要进行预测的对象。例如，实例可能是一个住宅，您想要确定其市场价值。其特征可能包括位置、房龄和最近出售的周边住宅的平均价格。标签是预测任务的答案，例如住宅最终以 10 万美元售出。

由于每个标签都是特定时间点的观察结果，因此您需要提取观察时与该时间点对应的特征值，例如售出特定住宅时附近住宅的价格。随着时间的推移收集标签和特征值时，这些特征值会发生变化。Vertex AI Feature Store（旧版）可以执行时间点查询，以便您可以提取特定时间的特征值。

时间点查询示例

以下示例涉及检索具有 L1 和 L2 标签的两个训练实例的特征值。这两个标签分别在 T1 和 T2 观察到。假设冻结这些时间戳上的特征值状态。因此，对于 T1 的时间点查询，Vertex AI Feature Store（旧版）会返回 Feature 1、Feature 2、Feature 3 截止到 T1 的最新特征值，并且不会返回 T1 之后的任何值。随着时间的推移，特征值会发生变化，标签也会变化。因此，在 T2 时，Feature Store 会返回该时间点的不同特征值。

示例时间点查询

批量传送输入

作为批量传送请求的一部分，您需要以下信息：

要获取其值的现有特征列表。
包含每个训练示例信息的读取实例列表。它会列出特定时间点的观察结果。可以是 CSV 文件或 BigQuery 表。该列表必须包含以下信息：
- 时间戳：观察或衡量标签的时间。时间戳是必需的，以便 Vertex AI Feature Store（旧版）可以执行时间点查询。
- 实体 ID：与标签对应的实体的一个或多个 ID。
写入输出所采用的目标 URI 和格式。在输出中，Vertex AI Feature Store（旧版）实际上会联接读取实例列表中的表与特征存储区中的特征值。为输出指定以下格式和位置之一：
- 单区域或多区域数据集中的 BigQuery 表。
- 单区域或多区域 Cloud Storage 存储桶中的 CSV 文件。但是，如果特征值包含数组，则必须选择其他格式。
- Cloud Storage 存储桶中的 Tfrecord 文件。

区域要求

对于读取实例和目的地，源数据集或存储桶必须与特征存储区位于同一区域或多区域位置。例如，us-central1 中的特征存储区只能从位于 us-central1 或美国多区域位置的 Cloud Storage 存储桶或 BigQuery 数据集读取数据或向其中传送数据。例如，您无法使用 us-east1 中的数据。此外，系统也不支持使用双区域存储桶读取或传送数据。

读取实例列表

读取实例列表指定要检索的特征值的实体和时间戳。CSV 文件或 BigQuery 表必须包含以下列（任意顺序）。每一列都需要列标题。

必须包含时间戳列，其中标题名称为 timestamp，列值是采用 RFC 3339 格式的时间戳。
必须包含一个或多个实体类型列，其中标题是实体类型 ID，列值是实体 ID。
可选：您可以包含传递值（额外的列），这些值会按原样传递给输出。如果您希望在输出中包含不在 Vertex AI Feature Store（旧版）中的数据，这将非常有用。

示例 (CSV)

假设某个特征存储区包含实体类型 users 和 movies 及其特征。例如，users 的特征可能包括 age 和 gender，而 movies 的特征可能包括 ratings 和 genre。

在此示例中，您要收集有关用户的电影偏好的训练数据。您可以检索两个用户实体 alice 和 bob 的特征值，以及他们观看过的影片的特征。从另一个数据集中，您知道 alice 观看了 movie_01 并且喜欢它，bob 观看了 movie_02 但不喜欢。因此，读取实例列表可能如下所示：

users,movies,timestamp,liked
"alice","movie_01",2021-04-15T08:28:14Z,true
"bob","movie_02",2021-04-15T08:28:14Z,false

Vertex AI Feature Store（旧版）会在给定时间戳或之前检索所列实体的特征值。您可以指定应作为批量传送请求的一部分（而不是在读取实例列表中）获取的特定特征。

此示例还包含一个名为 liked 的列，表明用户是否喜欢影片。特征存储区中不包含此列，但您仍然可以将这些值传递给批量传送输出。在输出中，这些传递值与特征存储区中的值联接。

Null 值

如果在给定时间戳，特征值为 null，则 Vertex AI Feature Store（旧版）会返回之前的非 null 特征值。如果没有之前的值，Vertex AI Feature Store（旧版）会返回 null。

批量传送特征值

从特征存储区批量传送特征值以获取数据，由读取实例列表文件确定。

如果要通过读取最近的训练数据并排除旧数据来降低离线存储空间使用费，请指定开始时间。如需了解如何通过指定开始时间来降低离线存储使用费，请参阅指定在批量传送和批量导出期间优化离线存储费用的开始时间。

网页界面

请使用其他方法。您无法通过 Google Cloud 控制台批量传送特征。

REST

如需批量传送特征值，请使用 featurestores.batchReadFeatureValues 方法发送 POST 请求。

以下示例输出包含 users 和 movies 实体类型的特征值的 BigQuery 表。请注意，在提交请求之前，可能需要满足每个输出目标的一些前提条件。例如，如果要为 bigqueryDestination 字段指定表名称，则必须已有数据集。API 参考文档中说明了这些要求。

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

LOCATION_ID：在其中创建特征存储区的区域。例如 us-central1。
PROJECT_ID：您的项目 ID。
FEATURESTORE_ID：特征存储区的 ID。
DATASET_NAME：目标 BigQuery 数据集的名称。
TABLE_NAME：目标 BigQuery 表的名称。
STORAGE_LOCATION：读取实例 CSV 文件的 Cloud Storage URI。

HTTP 方法和网址：

POST http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID:batchReadFeatureValues

请求 JSON 正文：

{
  "destination": {
    "bigqueryDestination": {
      "outputUri": "bq://PROJECT_ID.DATASET_NAME.TABLE_NAME"
    }
  },
  "csvReadInstances": {
    "gcsSource": {
      "uris": ["STORAGE_LOCATION"]
    }
  },
  "entityTypeSpecs": [
    {
      "entityTypeId": "users",
      "featureSelector": {
        "idMatcher": {
          "ids": ["age", "liked_genres"]
        }
      }
    },
    {
      "entityTypeId": "movies",
      "featureSelector": {
        "idMatcher": {
          "ids": ["title", "average_rating", "genres"]
        }
      }
    }
  ],
  "passThroughFields": [
    {
      "fieldName": "liked"
    }
  ]
}

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

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 \
     "http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID:batchReadFeatureValues"

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 "http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID:batchReadFeatureValues" | Select-Object -Expand Content

您应该会看到类似如下所示的输出。您可以使用响应中的 OPERATION_ID 来获取操作的状态。

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.BatchReadFeatureValuesOperationMetadata",
    "genericMetadata": {
      "createTime": "2021-03-02T00:03:41.558337Z",
      "updateTime": "2021-03-02T00:03:41.558337Z"
    }
  }
}

Python

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

from google.cloud import aiplatform

def batch_serve_features_to_bq_sample(
    project: str,
    location: str,
    featurestore_name: str,
    bq_destination_output_uri: str,
    read_instances_uri: str,
    sync: bool = True,
):

    aiplatform.init(project=project, location=location)

    fs = aiplatform.featurestore.Featurestore(featurestore_name=featurestore_name)

    SERVING_FEATURE_IDS = {
        "users": ["age", "gender", "liked_genres"],
        "movies": ["title", "average_rating", "genres"],
    }

    fs.batch_serve_to_bq(
        bq_destination_output_uri=bq_destination_output_uri,
        serving_feature_ids=SERVING_FEATURE_IDS,
        read_instances_uri=read_instances_uri,
        sync=sync,
    )

其他语言

您可以安装并使用以下 Vertex AI 客户端库来调用 Vertex AI API。Cloud 客户端库使用每种受支持语言的自然规范和样式，为开发者带来优化的体验。

Java
Node.js

查看批量传送作业

使用 Google Cloud 控制台查看 Google Cloud 项目中的批量传送作业。

网页界面

在 Google Cloud 控制台的“Vertex AI”部分，转到特征页面。

转到“特征”页面

从区域下拉列表中选择一个区域。
在操作栏中，点击查看批量传送作业，以列出所有特征存储区的批量传送作业。
点击批量传送作业的 ID 以查看其详细信息，例如使用的读取实例源和输出目标。

后续步骤

了解如何批量注入特征值。
了解如何通过在线传送来提供特征。
查看 Vertex AI Feature Store（旧版）并发批量作业配额。
排查 Vertex AI Feature Store（旧版）常见问题。