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

エンベディングをサポートするようにオンラインストアを構成している場合は、ベクトル類似性検索を実行して、意味的に類似したエンティティまたは関連するエンティティのリストを取得できます。これは近似最近傍探索ともいいます。エンティティ ID またはエンベディングに基づいて検索できます。

近似最近傍を検索するには、まず次の操作を行う必要があります。

embedding 列を追加して、エンベディングをサポートするように BigQuery データソースを設定します。必要に応じて、フィルタリング列とクラウディング列を追加します。詳細については、データソースの準備のガイドラインをご覧ください。
エンベディング管理をサポートするオンラインストアインスタンスを作成します。エンベディング管理をサポートするオンラインストアインスタンスを作成する方法については、オンラインストアのエンベディング管理を構成するをご覧ください。
特徴ビューの作成時に embedding 列を指定します。エンベディングをサポートする特徴ビューを作成する方法については、特徴ビューのベクトル取得を構成するをご覧ください。

このページでは、次の方法について説明します。

オンラインストアのパブリックエンドポイントドメイン名を取得する
エンベディングの最近傍の一致を取得する
エンティティの最近傍の一致を取得する

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

埋め込み管理用のオンラインショップインスタンスを作成して構成すると、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 値の配列として表されます。
BOOLEAN: 省略可。レスポンスのエンティティの特徴を含めるかどうかを指定します。レスポンスにエンティティとともに特徴を含めるには、「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": BOOLEAN
}

リクエストを送信するには、次のいずれかのオプションを選択します。

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。
BOOLEAN: 省略可。レスポンスのエンティティの特徴を含めるかどうかを指定します。レスポンスにエンティティとともに特徴を含めるには、「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": BOOLEAN
}

リクエストを送信するには、次のいずれかのオプションを選択します。

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
    } ]
  }
}

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

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

REST

curl

PowerShell

エンベディングの近似最近傍を取得する

REST

curl

PowerShell

エンティティの近似最近傍を取得する

REST

curl

PowerShell

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