最適化されたオンライン サービング用に作成されたオンライン ストア インスタンスでは、ベクトル類似性検索を実行して、意味的に類似したエンティティまたは意味的に関連するエンティティのリストを取得できます。これは近似最近傍探索とも呼ばれます。エンティティ ID またはエンベディングに基づいて検索できます。
近似最近傍を検索するには、まず次の操作を行う必要があります。
embedding
列を追加して、エンベディングをサポートするように BigQuery データソースを設定します。必要に応じて、フィルタリング列とクラウディング列を追加します。詳細については、データソースの準備のガイドラインをご覧ください。特徴ビューの作成時に
embedding
列を指定します。エンベディングをサポートする特徴ビューを作成する方法については、特徴ビューのベクトル取得を構成するをご覧ください。
このページでは、次の方法について説明します。
始める前に
まだ行っていない場合は、Vertex AI に対する認証を行います。
このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
オンライン ストアのパブリック エンドポイント ドメイン名を取得する
最適化されたオンライン サービング用のオンライン ストア インスタンスを作成すると、Vertex AI Feature Store がオンライン ストア用のパブリック エンドポイント ドメイン名を生成します。オンライン ショップの特徴ビューから最近傍の検索を開始する前に、オンライン ショップの詳細からパブリック エンドポイント ドメイン名を取得する必要があります。
次のサンプルを使用して、オンライン ストア インスタンスの詳細を取得します。
REST
プロジェクト内の FeatureOnlineStore
リソースの詳細を取得するには、featureOnlineStores.get
メソッドを使用して GET
リクエストを送信します。
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: オンライン ストアがあるリージョン(
us-central1
など)。 - PROJECT_ID: プロジェクト ID。
- FEATUREONLINESTORE_NAME: オンライン ストア インスタンスの名前。
HTTP メソッドと URL:
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME
リクエストを送信するには、次のいずれかのオプションを選択します。
curl
次のコマンドを実行します。
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME"
PowerShell
次のコマンドを実行します。
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME_1", "createTime": "2023-09-06T23:25:04.256314Z", "updateTime": "2023-09-06T23:25:04.256314Z", "etag": "AMEw9yMgoV0bAsYuKwVxz4Y7lOmxV7riNVHg217KaQAKORqvdqGCrQ1DIt8yHgoGXf8=", "state": "STABLE", "dedicatedServingEndpoint": { "publicEndpointDomainName": "PUBLIC_ENDPOINT_DOMAIN_NAME" }, "optimized": {} }
次のステップで近似最近傍を取得するには、レスポンスの PUBLIC_ENDPOINT_DOMAIN_NAME が必要です。
エンベディングの近似最近傍を取得する
次のサンプルを使用してエンベディングを指定し、意味的に関連するエンティティを検索します。
REST
エンベディングの最近傍を検索するには、featureViews.searchNearestEntities メソッドを使用して POST
リクエストを送信します。
リクエストのデータを使用する前に、次のように置き換えます。
- PUBLIC_ENDPOINT_DOMAIN_NAME:
featureOnlineStores.get
メソッドを使用して取得したオンライン ストア インスタンスのパブリック エンドポイント ドメイン名。 - PROJECT_ID: プロジェクト ID。
- LOCATION_ID: オンライン ストア インスタンスが配置されているリージョン(
us-central1
など)。 - FEATUREONLINESTORE_NAME: 近似最近傍を検索する特徴ビューを含むオンライン ストア インスタンスの名前。
- FEATUREVIEW_NAME: 近似最近傍を検索する特徴ビューの名前。
- EMBEDDING: 近似最近傍を検索するエンベディング。エンベディングは、
double
値の配列として表されます。 - RETURN_FULL_ENTITY: 省略可。レスポンスのエンティティの特徴を含めるかどうかを指定します。レスポンスにエンティティとともに特徴を含めるには、「
true
」と入力します。デフォルト値はfalse
です。 - NEIGHBOR_COUNT: 取得する近似最近傍の数。
HTTP メソッドと URL:
POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities
リクエストの本文(JSON):
{ "query": { "embedding": { "value": EMBEDDING }, "neighbor_count": NEIGHBOR_COUNT }, "return_full_entity": RETURN_FULL_ENTITY }
リクエストを送信するには、次のいずれかのオプションを選択します。
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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"
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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
{ "nearestNeighbors": { "neighbors": [ { "entityId": "305281", "distance": -41.115459442138672 }, { "entityId": "80280", "distance": -38.703567504882812 }, { "entityId": "80280", "distance":-38.703567504882812 }, { "entityId": "903779", "distance": -38.214759826660156 }, { "entityId": "1008145", "distance": -36.271354675292969 }, { "entityId": "606431", "distance": -34.791431427001953 } ] } }
エンティティの近似最近傍を取得する
次のサンプルを使用して、エンベディングを使用してエンティティ ID を指定し、意味的に関連するエンティティを検索します。
REST
最近傍でエンティティ ID を検索するには、featureViews.searchNearestEntities メソッドを使用して POST
リクエストを送信します。
リクエストのデータを使用する前に、次のように置き換えます。
- PUBLIC_ENDPOINT_DOMAIN_NAME:
featureOnlineStores.get
メソッドを使用して取得したオンライン ストア インスタンスのパブリック エンドポイント ドメイン名。 - PROJECT_ID: プロジェクト ID。
- LOCATION_ID: オンライン ストア インスタンスが配置されているリージョン(
us-central1
など)。 - FEATUREONLINESTORE_NAME: 近似最近傍を検索する特徴ビューを含むオンライン ストア インスタンスの名前。
- FEATUREVIEW_NAME: 近似最近傍を検索する特徴ビューの名前。
- ENTITY_ID: 近似最近傍探索を取得するエンティティのエンティティ ID。
- RETURN_FULL_ENTITY: 省略可。レスポンスのエンティティの特徴を含めるかどうかを指定します。レスポンスにエンティティとともに特徴を含めるには、「
true
」と入力します。デフォルト値はfalse
です。 - NEIGHBOR_COUNT: 取得する近似最近傍の数。
HTTP メソッドと URL:
POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities
リクエストの本文(JSON):
{ "query": { "entity_id": ENTITY_ID, "neighbor_count": NEIGHBOR_COUNT }, "return_full_entity": RETURN_FULL_ENTITY }
リクエストを送信するには、次のいずれかのオプションを選択します。
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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"
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://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
{ "nearestNeighbors": { "neighbors": [ { "entityId": "305281", "distance": -41.115459442138672 }, { "entityId": "80280", "distance": -38.703567504882812 }, { "entityId": "80280", "distance":-38.703567504882812 }, { "entityId": "903779", "distance": -38.214759826660156 }, { "entityId": "1008145", "distance": -36.271354675292969 }, { "entityId": "606431", "distance": -34.791431427001953 } ] } }