使用嵌入搜尋

如果是為「最佳化線上服務」建立的網路商店執行個體，您可以執行向量相似度搜尋，擷取語意相似或相關的實體清單，也就是近似最鄰近項目。您可以根據實體 ID 或嵌入內容進行搜尋。

視為網路商店執行個體設定的端點類型而定，您可以執行下列其中一項操作：

事前準備

如要搜尋近似最鄰近項目，請先執行下列操作：

  • 設定 BigQuery 資料來源，加入 embedding 欄位來支援嵌入。視需要加入篩選和擁擠程度資料欄。 詳情請參閱「資料來源準備指南」。

  • 建立網路商店執行個體，以提供最佳化線上服務。

  • 直接關聯 BigQuery 資料來源，建立支援嵌入的特徵檢視區塊。建立特徵檢視區塊時，請指定 embedding 資料欄。如要進一步瞭解如何建立支援嵌入的特徵檢視區塊，請參閱「為特徵檢視區塊設定向量擷取功能」。

  • 如要使用 Private Service Connect 端點搜尋最接近的鄰近項目，請安裝或升級至最新版 Python SDK。執行下列指令：
    pip3 install --upgrade --quiet google-cloud-aiplatform

  • 除非您已完成驗證，否則請按照這些指示向 Vertex AI 進行驗證。

    Select the tab for how you plan to use the samples on this page:

    Python

    如要在本機開發環境中使用本頁的 Python 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

      安裝 Google Cloud CLI。

      如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    詳情請參閱 Set up authentication for a local development environment。

    REST

    如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

      安裝 Google Cloud CLI。

      如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

    詳情請參閱 Google Cloud 驗證說明文件中的「Authenticate for using REST」。

使用公開端點搜尋最鄰近的相符項目

如果已將線上商店例項設定為使用「透過公開端點放送最佳化線上服務」放送特徵值，則必須執行下列步驟，才能擷取近似最近鄰項比對結果：

  1. 擷取網路商店的公開端點網域名稱

  2. 擷取嵌入或實體的最鄰近項目

擷取網路商店的公開端點網域名稱

為「最佳化線上服務」建立線上商店執行個體時，Vertex AI 特徵儲存庫會產生線上商店的公開端點網域名稱。如要開始從線上商店的特徵檢視畫面搜尋最鄰近的鄰居，請先從線上商店詳細資料中擷取公開端點網域名稱。

使用下列範例擷取網路商店執行個體的詳細資料。

REST

如要擷取專案中 FeatureOnlineStore 資源的詳細資料，請使用 featureOnlineStores.get 方法傳送 GET 要求。

使用任何要求資料之前，請先替換以下項目：

  • LOCATION_ID：線上商店所在的區域，例如 us-central1。
  • PROJECT_ID：您的專案 ID。
  • FEATUREONLINESTORE_NAME：線上商店執行個體的名稱。

HTTP 方法和網址：

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 方法和網址：

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 方法和網址：

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

使用 Private Service Connect 端點搜尋最鄰近的項目

如果您已將線上商店執行個體設定為使用 Private Service Connect 端點的「最佳化線上服務」提供特徵值，則必須執行下列步驟，才能擷取近似最近鄰項比對結果：

  1. 擷取網路商店的服務連結字串。

  2. 在網路設定中新增 Private Service Connect 的端點。

  3. 透過 gRPC 連線至 Private Service Connect 端點。

  4. 擷取嵌入或實體的最鄰近項目

擷取網路商店的服務附件字串

使用 Private Service Connect 端點建立線上商店執行個體，以進行最佳化線上服務時，Vertex AI 特徵儲存庫會產生服務附件字串。您可以從線上商店詳細資料中擷取服務連結字串，並使用這個字串設定 Private Service Connect 端點。

使用下列範例擷取網路商店執行個體的詳細資料。

REST

如要擷取專案中 FeatureOnlineStore 資源的詳細資料，請使用 featureOnlineStores.get 方法傳送 GET 要求。

使用任何要求資料之前，請先替換以下項目：

  • LOCATION_ID：線上商店所在的區域，例如 us-central1。
  • PROJECT_ID：您的專案 ID。
  • FEATUREONLINESTORE_NAME：線上商店執行個體的名稱。

HTTP 方法和網址：

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": {
    "privateServiceConnectConfig": {
      "enablePrivateServiceConnect": "true",
      "projectAllowlist": [
        "PROJECT_NAME"
      ]
    },
    serviceAttachment: "SERVICE_ATTACHMENT_STRING"
  },
  "optimized": {}
}

您需要回應中的 SERVICE_ATTACHMENT_STRING，才能在下一個步驟中擷取特徵值。

新增 Private Service Connect 的端點

如要將最佳化線上服務的 Private Service Connect 端點新增至網路設定，請按照下列步驟操作：

  1. 在 Google Cloud 控制台選取包含線上商店例項的專案。

  2. 指定 SERVICE_ATTACHMENT_STRING 做為目標服務，建立 Private Service Connect 的端點。

建立端點後，該端點會顯示在「Private Service Connect」頁面的「Connected endpoints」(已連線的端點) 分頁中。端點的 IP 位址會顯示在「IP addresses」(IP 位址) 欄中。

前往「已連線的端點」分頁

在下一個步驟中，您需要使用這個 IP 位址，透過 gRPC 連線至線上商店執行個體的 Private Service Connect 端點。

透過 gRPC 連線至 Private Service Connect 端點

使用下列程式碼範例，透過 gRPC 連線至為線上商店建立的 Private Service Connect 端點。

Python

from google.cloud.aiplatform_v1 import FeatureOnlineStoreServiceClient
from google.cloud.aiplatform_v1.services.feature_online_store_service.transports.grpc import FeatureOnlineStoreServiceGrpcTransport
import grpc

data_client = FeatureOnlineStoreServiceClient(
  transport = FeatureOnlineStoreServiceGrpcTransport(
    # Add the IP address of the Endpoint you just created.
    channel = grpc.insecure_channel("ENDPOINT_IP:10002")
  )
)

更改下列內容：

  • ENDPOINT_IP：Private Service Connect 頁面「IP 位址」欄中的端點 IP 位址。

使用 Private Service Connect 端點擷取近似最鄰近項目

透過 gRPC 連線至 Private Service Connect 端點後，即可搜尋嵌入或實體的近似最近鄰。

擷取嵌入內容的近似最鄰近項目

使用私人端點時，您可以指定嵌入項目，藉此搜尋語意相關的實體，如下列範例所示。

Python

data_client.search_nearest_entities(
  request=feature_online_store_service_pb2.SearchNearestEntitiesRequest(
      feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
      query=feature_online_store_service_pb2.NearestNeighborQuery(
          embedding = "EMBEDDING",
          neighbor_count = NEIGHBOR_COUNT,
      ),
      return_full_entity=RETURN_FULL_ENTITY
  ))

更改下列內容：

  • LOCATION_ID：線上商店所在的區域，例如 us-central1。

  • PROJECT_ID：您的專案 ID。

  • FEATUREONLINESTORE_NAME：包含特徵檢視區塊的網路商店名稱。

  • FEATUREVIEW_NAME：要搜尋近似最近鄰項比對結果的特徵檢視區塊名稱。

  • EMBEDDING：您要擷取近似最鄰近項目比對結果的嵌入。嵌入會以 double 值的陣列表示。

  • FORMAT：選用：要擷取特徵值的格式。支援的格式包括 JSON 鍵/值組合和 proto Struct 格式。請注意，proto Struct 格式不支援位元組功能值型別。如要擷取以位元組格式設定的特徵值，請使用 JSON 做為回應格式。

  • RETURN_FULL_ENTITY：選用：指定是否要在回應中納入或排除實體的特徵。如要在回應中加入特徵和實體，請輸入 true。預設值為 false。

  • NEIGHBOR_COUNT：要擷取的近似最鄰近項目數量。

擷取實體的近似最鄰近項目

使用私人端點時，請指定實體 ID，即可使用下列範例搜尋語意相關的實體。

Python

data_client.search_nearest_entities(
  request=feature_online_store_service_pb2.SearchNearestEntitiesRequest(
      feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
      query=feature_online_store_service_pb2.NearestNeighborQuery(
          entity_id = "ENTITY_ID",
          neighbor_count = NEIGHBOR_COUNT,
      ),
      return_full_entity=RETURN_FULL_ENTITY
  ))
 ```

更改下列內容：

  • LOCATION_ID：線上商店所在的區域，例如 us-central1。

  • PROJECT_ID：您的專案 ID。

  • FEATUREONLINESTORE_NAME：包含特徵檢視區塊的網路商店名稱。

  • FEATUREVIEW_NAME：要搜尋近似最近鄰項比對結果的特徵檢視區塊名稱。

  • ENTITY_ID：要擷取近似最近鄰項比對結果的實體 ID。

  • FORMAT：選用：要擷取特徵值的格式。支援的格式包括 JSON 鍵/值組合和 proto Struct 格式。請注意，proto Struct 格式不支援位元組功能值型別。如要擷取以位元組格式設定的特徵值，請使用 JSON 做為回應格式。

  • RETURN_FULL_ENTITY：選用：指定是否要在回應中納入或排除實體的特徵。如要在回應中加入特徵和實體，請輸入 true。預設值為 false。

  • NEIGHBOR_COUNT：要擷取的近似最鄰近項目數量。