1 つのエンティティ タイプのすべてのエンティティの特徴値を BigQuery テーブルまたは Cloud Storage バケットにエクスポートします。スナップショットの取得か特徴値の完全なエクスポートを選択できます。完全なエクスポートでは特徴ごとに複数の値を返す場合がありますが、スナップショットでは特徴ごとに 1 つの値を返します。特徴値をエクスポートするときに、特定のエンティティ ID を選択することはできません。また、複数のエンティティ タイプを含めることもできません。
特徴値のエクスポートは、データのアーカイブやアドホック分析に役立ちます。たとえば、featurestore の定期的なスナップショットを保存すると、さまざまな時点での状態を保存できます。トレーニング データセットの特徴値を取得する必要がある場合は、バッチ サービングを使用してください。
スナップショットと完全なエクスポートの比較
スナップショットと完全なエクスポートのどちらのオプションでも、単一のタイムスタンプ(開始時間か終了時間)を指定するか両方のタイムスタンプを指定することで、データをクエリできます。スナップショットの場合、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 を返します。
例
たとえば、featurestore に次の値があるとします。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 |
特徴値のエクスポート
特徴値をエクスポートするときに、クエリする特徴と対象(スナップショットまたは完全なエクスポート)を選択します。以降のセクションでは、各オプションのサンプルを示します。
どちらのオプションでも、出力先はソース featurestore と同じリージョンに存在する必要があります。たとえば、featurestore が us-central1
にある場合、宛先の Cloud Storage バケットまたは BigQuery テーブルも us-central1
に存在する必要があります。
スナップショット
指定した期間内の最新の特徴値をエクスポートします。
ウェブ UI
別の方法を使用してください。Google Cloud コンソールから特徴値をエクスポートすることはできません。
REST
特徴値をエクスポートするには、entityTypes.exportFeatureValues メソッドを使用して POST リクエストを送信します。
次のサンプルでは、BigQuery テーブルを出力しますが、Cloud Storage バケットに出力することもできます。なお、各出力先には、リクエストの送信前に用意しなければならないものがあります。たとえば、bigqueryDestination
フィールドにテーブル名を指定する場合は、データセットが存在する必要があります。こうした要件については、API リファレンスをご覧ください。
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: featurestore が配置されているリージョン。例:
us-central1
- PROJECT_ID: 実際のプロジェクト ID。
- FEATURESTORE_ID: featurestore の ID。
- ENTITY_TYPE_ID: エンティティ タイプの ID。
- START_TIME、END_TIME: (省略可)開始時間のみを指定した場合、現在の時刻(リクエストが送信された時間)からの最新の値を返し、開始時間まで遡ります。終了時間のみを指定した場合、終了時間(指定した時間を含む)から最新の値を返し、最初の値に遡ります。開始時間と終了時間を指定すると(指定時間を含む)、指定された時間内で最新の値が返されます。どちらも指定しない場合は、現在の特徴から最初の値まで遡って各特徴の最新値を返します。
- DATASET_NAME: 出力先 BigQuery データセットの名前。
- TABLE_NAME: 出力先 BigQuery テーブルの名前。
- FEATURE_ID: 1 つ以上の特徴の ID。すべての特徴を選択するには、単一の
*
(アスタリスク)を指定します。
HTTP メソッドと URL:
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 のリファレンス ドキュメントをご覧ください。
完全なエクスポート
指定期間内のすべての特徴値をエクスポートします。
ウェブ UI
別の方法を使用してください。Google Cloud コンソールから特徴値をエクスポートすることはできません。
REST
特徴値をエクスポートするには、entityTypes.exportFeatureValues メソッドを使用して POST リクエストを送信します。
次のサンプルでは、BigQuery テーブルを出力しますが、Cloud Storage バケットに出力することもできます。なお、各出力先には、リクエストの送信前に用意しなければならないものがあります。たとえば、bigqueryDestination
フィールドにテーブル名を指定する場合は、データセットが存在する必要があります。こうした要件については、API リファレンスをご覧ください。
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: featurestore が配置されているリージョン。例:
us-central1
- PROJECT_ID: 実際のプロジェクト ID。
- FEATURESTORE_ID: featurestore の ID。
- ENTITY_TYPE_ID: エンティティ タイプの ID。
- START_TIME と END_TIME: (省略可)開始時間のみを指定した場合、現在の時刻(リクエストが送信された時間)から開始時間(指定時間を含む)までのすべての値が返されます。終了時間のみを指定すると、終了時間(指定時間を含む)から最初の値のタイムスタンプ(各特徴を含む)までのすべての値が返されます。開始時刻と終了時刻を指定すると(指定時間を含む)、指定期間内のすべての値が返されます。どちらも指定しない場合は、各特徴で現在の時刻と最初の値のタイムスタンプの間のすべての値が返されます。
- DATASET_NAME: 出力先 BigQuery データセットの名前。
- TABLE_NAME: 出力先 BigQuery テーブルの名前。
- FEATURE_ID: 1 つ以上の特徴の ID。すべての特徴を選択するには、単一の
*
(アスタリスク)を指定します。
HTTP メソッドと URL:
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(従来版)に関する一般的な問題のトラブルシューティングを行う。