エンベディングを使用した検索

最適化されたオンライン サービング用に作成されたオンライン ストア インスタンスでは、ベクトル類似性検索を実行して、意味的に類似したエンティティまたは意味的に関連するエンティティのリストを取得できます。これは近似最近傍探索とも呼ばれます。エンティティ 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

詳細については、Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

オンライン ストアのパブリック エンドポイント ドメイン名を取得する

最適化されたオンライン サービング用のオンライン ストア インスタンスを作成すると、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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

$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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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
    } ]
  }
}