通过批量导入,您可以从有效数据源批量导入特征值。在批量导入请求中,您可以为一种实体类型导入最多 100 个特征的值。请注意,每种实体类型只能运行一个批量导入作业,以避免冲突。
在批量导入请求中,指定源数据的位置及其映射到特征存储区中特征的方式。由于每个批量导入请求针对单个实体类型,因此源数据也必须针对单个实体类型。
导入顺利完成后,后续读取操作可以使用特征值。
- 如需详细了解源数据要求,请参阅源数据要求。
- 如需了解 Vertex AI Feature Store(旧版)在离线存储区中保留数据的时长,请参阅配额和限制中的 Vertex AI Feature Store(旧版)。
- 如需了解您可以导入的最早特征值时间戳,请参阅配额和限制中的 Vertex AI Feature Store(旧版)。
- 您无法导入时间戳表示未来日期或时间的特征值。
导入作业性能
Vertex AI Feature Store(旧版)提供高吞吐量导入,但最短延迟时间可能需要几分钟。对 Vertex AI Feature Store(旧版)的每个请求都会启动一个作业以完成相关工作。即使您要导入单个记录,导入作业也需要几分钟才能完成。
如果要调整作业的性能,请更改下面两个变量:
- 特征存储区在线传送节点的数量。
- 用于导入作业的工作器数量。工作器处理数据并写入特征存储区。
推荐的工作器数量是特征存储区中每 10 个在线传送节点一个工作器。如果在线传送负载较低,您可以提高工作器数量。您最多可以指定 100 个工作器。如需了解详情,请参阅相应地监控和调优资源以优化批量导入。
如果在线传送集群预配不足,则导入作业可能会失败。如果失败,请在在线传送负载较低时重试导入请求,或者增加特征存储区的节点数,然后重试请求。
如果特征存储区没有在线存储区(零在线传送节点),则导入作业仅将数据写入离线存储区,并且作业的性能仅取决于导入工作器的数量。
数据一致性
如果源数据在导入过程中被修改,则可能会出现不一致。确保在启动导入作业之前完成所有源数据修改。此外,重复的特征值可能会导致在线请求和批量请求之间传送不同的值。确保每个实体 ID 和时间戳对都有一个特征值。
如果导入操作失败,则特征存储区可能只包含部分数据,这可能导致在线传送请求和批量传送请求之间返回不一致的值。为避免这种不一致,请再次重试同一导入请求,并等到请求成功完成为止。
Null 值和空数组
在导入期间,Vertex AI Feature Store(旧版)会将 null 标量值或空数组视为空值。其中包括 CSV 列中的空值。Vertex AI Feature Store(旧版)不支持非标量 null 值,例如数组中的 null
值。
当在线传送和批量传送时,Vertex AI Feature Store(旧版)会返回该特征的最新非 null 或非空值。如果特征的历史值不可用,则 Vertex AI Feature Store(旧版)会返回 null
。
NaN 值
Vertex AI Feature Store(旧版)支持 Double
和 DoubleArray
中的 NaN(非数字)值。在注入期间,您可以在传送输入 CSV 文件中输入 NaN
来表示 NaN 值。当在线传送和批量传送时,Vertex AI Feature Store(旧版)会对 NaN 值返回 NaN
。
批量导入
将值批量导入到单个实体类型的一个或多个特征的特征存储区。
网页界面
- 在 Google Cloud 控制台的“Vertex AI”部分,转到特征页面。
- 从区域下拉列表中选择一个区域。
- 在特征表中,查看实体类型列,并找到包含您要导入其值的特征的实体类型。
- 点击实体类型的名称。
- 在操作栏中,点击注入值。
- 在数据源部分,选择以下选项之一:
- Cloud Storage CSV 文件:选择此选项可从 Cloud Storage 的多个 CSV 文件导入数据。指定 CSV 文件的路径和名称。如需指定更多文件,请点击添加其他文件。
- Cloud Storage AVRO 文件:选择此选项可从 Cloud Storage 的 AVRO 文件导入数据。指定 AVRO 文件的路径和名称。
- BigQuery 表:选择此选项可从 BigQuery 表或 BigQuery 视图导入数据。浏览并选择要使用的表或视图,其格式如下:
PROJECT_ID.DATASET_ID.TABLE_ID
- 点击继续。
- 在将列映射到特征部分,指定源数据中的哪些列会映射到特征存储区中的实体和特征。
- 指定源数据中包含实体 ID 的列名称。
- 对于时间戳,在源数据中指定时间戳列,或指定与您导入的所有特征值关联的单个时间戳。
- 在特征列表中,输入映射到每个特征的源数据列名称。默认情况下,Vertex AI Feature Store(旧版)假定特征名称和列名称匹配。
- 点击注入。
REST
如需导入现有特征的特征值,请使用 featurestores.entityTypes.importFeatureValues 方法发送 POST 请求。请注意,如果源数据列的名称和目标特征 ID 不同,请添加 sourceField
参数。
在使用任何请求数据之前,请先进行以下替换:
- LOCATION_ID:在其中创建特征存储区的区域。例如
us-central1
。 - PROJECT_ID:您的项目 ID。
- FEATURESTORE_ID:特征存储区的 ID。
- ENTITY_TYPE_ID:实体类型的 ID。
- ENTITY_SOURCE_COLUMN_ID:包含实体 ID 的源列的 ID。
- FEATURE_TIME_ID:包含特征值的特征时间戳的源列的 ID。
- FEATURE_ID:待导入特征存储区中现有特征的 ID。
- FEATURE_SOURCE_COLUMN_ID:包含实体特征值的源列的 ID。
- SOURCE_DATA_DETAILS:源数据位置,还表示 BigQuery 表或 BigQuery 视图的格式,例如
"bigquerySource": { "inputUri": "bq://test.dataset.sourcetable" }
。 - WORKER_COUNT:将数据写入特征存储区的工作器数量。
HTTP 方法和网址:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:importFeatureValues
请求 JSON 正文:
{ "entityIdField": "ENTITY_SOURCE_COLUMN_ID", "featureTimeField": "FEATURE_TIME_ID", SOURCE_DATA_DETAILS, "featureSpecs": [{ "id": "FEATURE_ID", "sourceField": "FEATURE_SOURCE_COLUMN_ID" }], "workerCount": WORKER_COUNT }
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 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/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:importFeatureValues"
PowerShell
将请求正文保存在名为 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/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:importFeatureValues" | Select-Object -Expand Content
您应该会看到类似如下所示的输出。您可以使用响应中的 OPERATION_ID 来获取操作的状态。
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.ImportFeatureValuesOperationMetadata", "genericMetadata": { "createTime": "2021-03-02T00:04:13.039166Z", "updateTime": "2021-03-02T00:04:13.039166Z" } } }
Python
如需了解如何安装或更新 Vertex AI SDK for Python,请参阅安装 Vertex AI SDK for Python。 如需了解详情,请参阅 Python API 参考文档。
Java
在尝试此示例之前,请按照《Vertex AI 快速入门:使用客户端库》中的 Java 设置说明执行操作。 如需了解详情,请参阅 Vertex AI Java API 参考文档。
如需向 Vertex AI 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
在尝试此示例之前,请按照《Vertex AI 快速入门:使用客户端库》中的 Node.js 设置说明执行操作。 如需了解详情,请参阅 Vertex AI Node.js API 参考文档。
如需向 Vertex AI 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
查看导入作业
使用 Google Cloud 控制台查看 Google Cloud 项目中的批量导入作业。
网页界面
- 在 Google Cloud 控制台的“Vertex AI”部分,转到特征页面。
- 从区域下拉列表中选择一个区域。
- 在操作栏中,点击查看注入作业以列出所有特征存储区的导入作业。
- 点击导入作业的 ID 以查看其详细信息,例如其数据源、导入实体的数量,以及导入的特征值的数量。
覆盖特征存储区中的现有数据
如果现有特征值与导入值具有相同的时间戳,您可以通过重新导入值来覆盖现有特征值。您无需先删除现有特征值。例如,您可能依赖于最近更改的底层源数据。要使特征存储区与该底层数据保持一致,请再次导入特征值。如果时间戳不匹配,则导入的值会被视为唯一,旧值会继续存在(不会被覆盖)。
要确保在线和批量传送请求之间的一致性,请等待导入作业完成后再发出任何传送请求。
回填历史数据
如果您要回填数据(即导入过去的特征值),请停用导入作业的在线传送功能。在线传送仅用于传送回填不包含的最新特征值。停用在线传送非常有用,因为您可以消除在线传送节点上的任何负载,并提高导入作业的吞吐量,从而缩短其完成时间。
使用 API 或客户端库时,您可以停用导入作业的在线传送。如需了解详情,请参阅 importFeatureValue 方法的 disableOnlineServing
字段。
后续步骤
- 了解如何通过在线传送或批量传送来传送特征。
- 了解如何监控一段时间内导入的特征值。
- 查看 Vertex AI Feature Store(旧版)并发批量作业配额。
- 排查 Vertex AI Feature Store(旧版)常见问题。