将单个实体类型的所有实体的特征值导出到 BigQuery 表或 Cloud Storage 存储桶。您可以选择获取快照或完整导出特征值。与可为每个特征返回多个值的完整导出相比,快照只会为每个特征返回一个值。导出特征值时,您不能选择特定实体 ID,也不能包含多个实体类型。
导出特征值在归档数据或对数据执行即时分析时非常有用。例如,您可以存储特征存储区的常规快照以保存其在不同时间点的状态。如果您需要获取用于构建训练数据集的特征值,请改用批量传送。
快照和完整导出比较
快照和完整导出选项都允许您通过指定单个时间戳(开始时间或结束时间)或同时指定这两个时间戳来查询数据。对于快照,Vertex AI Feature Store(旧版)会返回给定时间范围内的最新特征值。在输出中,每个特征值的关联时间戳是快照的时间戳(而不是特征值的时间戳)。
对于完整导出,Vertex AI Feature Store(旧版)会返回给定时间范围内的所有特征值。在输出中,每个特征值的关联时间戳是特征的时间戳(即注入特征值时指定的时间戳)。
下表总结了 Vertex AI Feature Store(旧版)根据您选择的选项和您提供的时间戳返回的内容。
选项 | 仅开始时间(含边界值) | 仅结束时间(含边界值) | 开始时间和结束时间(含边界值) |
---|---|---|---|
快照 | 从当前时间(接收到请求的时间)开始一直回溯到开始时间,返回这段时间内的最新值。 快照时间戳设置为当前时间。 |
从结束时间开始一直回溯到每个特征的第一个值,返回这段时间内的最新值。 快照时间戳设置为指定的结束时间。 |
返回指定时间范围内的最新值。 快照时间戳设置为指定的结束时间。 |
完整导出 | 返回开始时间及其之后,直至当前时间(发送请求的时间)的所有值。 | 返回到结束时间之前的所有值,此过程会回溯到每个特征的第一个值。 | 返回指定时间范围内的所有值。 |
Null 值
对于快照,如果给定时间戳的最新特征值为 null,Vertex AI Feature Store(旧版)会返回之前的非 null 特征值。如果之前没有非 null 值,Vertex AI Feature Store(旧版)会返回 null。
对于完整导出,如果给定时间戳的特征值为 null,则 Vertex AI Feature Store(旧版)会针对该时间戳返回 null。
示例
例如,假设您的特征存储区中有以下值,其中 Feature_A
和 Feature_B
的值具有相同的时间戳:
实体 ID | 特征值时间戳 | Feature_A | Feature_B |
---|---|---|---|
123 | T1 | A_T1 | B_T1 |
123 | T2 | A_T2 | NULL |
123 | T3 | A_T3 | NULL |
123 | T4 | A_T4 | B_T4 |
123 | T5 | NULL | B_T5 |
快照
对于快照,Vertex AI Feature Store(旧版)会根据给定的时间戳值返回以下值:
- 如果仅开始时间设置为
T3
,则快照会返回以下值:
实体 ID | 快照时间戳 | Feature_A | Feature_B |
---|---|---|---|
123 | CURRENT_TIME | A_T4 | B_T5 |
- 如果仅结束时间设置为
T3
,则快照会返回以下值:
实体 ID | 快照时间戳 | Feature_A | Feature_B |
---|---|---|---|
123 | T3 | A_T3 | B_T1 |
- 如果开始和结束时间设置为
T2
和T3
,则快照会返回以下值:
实体 ID | 快照时间戳 | Feature_A | Feature_B |
---|---|---|---|
123 | T3 | A_T3 | NULL |
完整导出
对于完整导出,Vertex AI Feature Store(旧版)会根据给定的时间戳值返回以下值:
- 如果仅开始时间设置为
T3
,则完整导出将返回以下值:
实体 ID | 特征值时间戳 | Feature_A | Feature_B |
---|---|---|---|
123 | T3 | A_T3 | NULL |
123 | T4 | A_T4 | B_T4 |
123 | T5 | NULL | B_T5 |
- 如果仅结束时间设置为
T3
,则完整导出将返回以下值:
实体 ID | 特征值时间戳 | Feature_A | Feature_B |
---|---|---|---|
123 | T1 | A_T1 | B_T1 |
123 | T2 | A_T2 | NULL |
123 | T3 | A_T3 | NULL |
- 如果开始和结束时间设置为
T2
和T4
,则完整导出将返回以下值:
实体 ID | 特征值时间戳 | Feature_A | Feature_B |
---|---|---|---|
123 | T2 | A_T2 | NULL |
123 | T3 | A_T3 | NULL |
123 | T4 | A_T4 | B_T4 |
导出特征值
导出特征值时,您需要选择要查询的特征以及它是快照还是完整导出。以下部分展示了每个选项的示例。
对于这两个选项,输出目的地必须与源特征存储区位于同一区域。例如,如果特征存储区位于 us-central1
,则目标 Cloud Storage 存储桶或 BigQuery 表也必须位于 us-central1
。
快照
导出给定时间范围内的最新特征值。
网页界面
请使用其他方法。您无法从 Google Cloud 控制台导出特征值。
REST
如需导出特征值,请使用 entityTypes.exportFeatureValues 方法发送 POST 请求。
以下示例会输出一个 BigQuery 表,但您也可以输出到 Cloud Storage 存储桶。在提交请求之前,可能需要满足每个输出目标的一些前提条件。例如,如果要为 bigqueryDestination
字段指定表名称,则必须已有数据集。API 参考文档中说明了这些要求。
在使用任何请求数据之前,请先进行以下替换:
- LOCATION_ID:特征存储区所在的区域。例如
us-central1
。 - PROJECT_ID:您的项目 ID。
- FEATURESTORE_ID:特征存储区的 ID。
- ENTITY_TYPE_ID:实体类型的 ID。
- START_TIME 和 END_TIME:(可选)如果仅指定开始时间,则系统会从当前时间(发送请求的时间)开始一直回溯到开始时间,返回这段时间内的最新值。如果仅指定结束时间,则系统会从结束时间(含边界值)开始一直回溯到第一个值,返回这段时间内的最新值。如果同时指定开始时间和结束时间,则系统会返回指定时间范围内(含边界值)的最新值。如果这两个时间均未指定,则系统会从当前时间开始一直回溯到第一个值,返回这段时间内每个特征的最新值。
- DATASET_NAME:目标 BigQuery 数据集的名称。
- TABLE_NAME:目标 BigQuery 表的名称。
- FEATURE_ID:一个或多个特征的 ID。指定一个
*
(星号)可以选择所有特征。
HTTP 方法和网址:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:exportFeatureValues
请求 JSON 正文:
{ "snapshotExport": { "start_time": "START_TIME", "snapshot_time": "END_TIME" }, "destination" : { "bigqueryDestination": { "outputUri": "bq://PROJECT_ID.DATASET_NAME.TABLE_NAME" } }, "featureSelector": { "idMatcher": { "ids": ["FEATURE_ID", ...] } } }
如需发送请求,请选择以下方式之一:
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:exportFeatureValues"
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:exportFeatureValues" | Select-Object -Expand Content
您应会收到如下所示的 JSON 响应:
{ "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.ExportFeatureValuesOperationMetadata", "genericMetadata": { "createTime": "2021-12-03T22:55:25.974976Z", "updateTime": "2021-12-03T22:55:25.974976Z" } } }
Java
在尝试此示例之前,请按照《Vertex AI 快速入门:使用客户端库》中的 Java 设置说明执行操作。如需了解详情,请参阅 Vertex AI Java API 参考文档。
如需向 Vertex AI 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
在尝试此示例之前,请按照《Vertex AI 快速入门:使用客户端库》中的 Node.js 设置说明执行操作。如需了解详情,请参阅 Vertex AI Node.js API 参考文档。
如需向 Vertex AI 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
其他语言
如需了解如何安装和使用 Python 版 Vertex AI SDK,请参阅使用 Python 版 Vertex AI SDK。如需了解详情,请参阅 Python 版 Vertex AI SDK API 参考文档。
完整导出
导出给定时间范围内的所有特征值。
网页界面
请使用其他方法。您无法从 Google Cloud 控制台导出特征值。
REST
如需导出特征值,请使用 entityTypes.exportFeatureValues 方法发送 POST 请求。
以下示例会输出一个 BigQuery 表,但您也可以输出到 Cloud Storage 存储桶。在提交请求之前,可能需要满足每个输出目标的一些前提条件。例如,如果要为 bigqueryDestination
字段指定表名称,则必须已有数据集。API 参考文档中说明了这些要求。
在使用任何请求数据之前,请先进行以下替换:
- LOCATION_ID:特征存储区所在的区域。例如
us-central1
。 - PROJECT_ID:您的项目 ID。
- FEATURESTORE_ID:特征存储区的 ID。
- ENTITY_TYPE_ID:实体类型的 ID。
- START_TIME 和 END_TIME:(可选)如果仅指定开始时间,则系统会返回当前时间(发送请求的时间)和开始时间(含边界值)之间的所有值。如果仅指定结束时间,则系统会返回结束时间(含边界值)和第一个值的时间戳(对于每个特征)之间的所有值。如果同时指定开始时间和结束时间,则系统会返回指定时间范围内(含边界值)的所有值。如果这两个时间均未指定,则系统会返回当前时间与第一个值的时间戳(对于每个特征)之间的所有值。
- DATASET_NAME:目标 BigQuery 数据集的名称。
- TABLE_NAME:目标 BigQuery 表的名称。
- FEATURE_ID:一个或多个特征的 ID。指定一个
*
(星号)可以选择所有特征。
HTTP 方法和网址:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:exportFeatureValues
请求 JSON 正文:
{ "fullExport": { "start_time": "START_TIME", "end_time": "END_TIME" }, "destination" : { "bigqueryDestination": { "outputUri": "bq://PROJECT.DATASET_NAME.TABLE_NAME" } }, "featureSelector": { "idMatcher": { "ids": ["FEATURE_ID", ...] } } }
如需发送请求,请选择以下方式之一:
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/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:exportFeatureValues"
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/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:exportFeatureValues" | Select-Object -Expand Content
您应会收到如下所示的 JSON 响应:
{ "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.ExportFeatureValuesOperationMetadata", "genericMetadata": { "createTime": "2021-12-03T22:55:25.974976Z", "updateTime": "2021-12-03T22:55:25.974976Z" } } }
Java
在尝试此示例之前,请按照《Vertex AI 快速入门:使用客户端库》中的 Java 设置说明执行操作。如需了解详情,请参阅 Vertex AI Java API 参考文档。
如需向 Vertex AI 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
在尝试此示例之前,请按照《Vertex AI 快速入门:使用客户端库》中的 Node.js 设置说明执行操作。如需了解详情,请参阅 Vertex AI Node.js API 参考文档。
如需向 Vertex AI 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
其他语言
如需了解如何安装和使用 Python 版 Vertex AI SDK,请参阅使用 Python 版 Vertex AI SDK。如需了解详情,请参阅 Python 版 Vertex AI SDK API 参考文档。
后续步骤
- 了解如何批量注入特征值。
- 了解如何通过在线传送来提供特征。
- 查看 Vertex AI Feature Store(旧版)并发批量作业配额。
- 排查 Vertex AI Feature Store(旧版)常见问题。