将单个实体类型的所有实体的特征值导出到 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 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
其他语言
如需了解如何安装和使用 Vertex AI SDK for Python,请参阅使用 Vertex AI SDK for Python。如需了解详情,请参阅 Vertex AI SDK for Python 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 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
其他语言
如需了解如何安装和使用 Vertex AI SDK for Python,请参阅使用 Vertex AI SDK for Python。如需了解详情,请参阅 Vertex AI SDK for Python API 参考文档。
后续步骤
- 了解如何批量注入特征值。
- 了解如何通过在线传送来提供特征。
- 查看 Vertex AI Feature Store(旧版)并发批量作业配额。
- 排查 Vertex AI Feature Store(旧版)常见问题。