此页面由 Cloud Translation API 翻译。

使用嵌入进行搜索

对于为优化在线传送创建的在线存储区实例，您可以执行矢量相似性搜索来检索在语义上相似或相关的实体（也称为近似最近邻）的列表。您可以根据实体 ID 或嵌入进行搜索。

根据为在线商店实例配置的端点类型，您可以执行以下任一操作：

使用公共端点搜索最近邻匹配项：仅当在线存储区配置为从公共端点优化在线传送时，才选择此选项。
使用 Private Service Connect 端点搜索最近邻匹配项：只有当在线存储区配置了通过 Private Service Connect 实现的专用传送端点的优化在线传送时，才选择此选项。

准备工作

要搜索近似最近邻，首先需要执行以下操作：

通过添加 embedding 列，设置 BigQuery 数据源以支持嵌入。（可选）添加过滤和数量上限列。如需了解详情，请参阅数据源准备准则。
为优化在线传送创建在线存储区实例。
通过直接关联 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，然后使用您的用户凭据设置应用默认凭据。
1. Install the Google Cloud CLI.
2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
3. To initialize the gcloud CLI, run the following command:
  gcloud init
4. 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。如需了解详情，请参阅身份验证文档中的为本地开发环境设置 ADC。
REST

如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。
如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

使用公共端点搜索最近邻匹配项

如果您已将在线存储区实例配置为使用公共端点的优化在线传送来提供特征值，则必须执行以下操作才能检索近似最近邻匹配项：

检索在线存储区的公共端点域名
检索嵌入或实体的最近邻匹配项

检索在线存储区的公共端点域名

当您为优化在线传送创建在线存储区实例时，Vertex AI Feature Store 会为在线存储区生成公共端点域名。必须先从在线存储区详细信息中检索公共端点域名，然后才能开始从在线存储区中的特征视图搜索最近邻。

使用以下示例检索在线存储区实例的详细信息。

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

注意：以下命令假定您已使用您的用户账号通过运行 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 方法和网址：

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

注意：以下命令假定您已使用您的用户账号通过运行 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 方法和网址：

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

注意：以下命令假定您已使用您的用户账号通过运行 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
    } ]
  }
}

使用 Private Service Connect 端点搜索最近邻匹配项

如果您已将在线存储区实例配置为使用 Private Service Connect 端点的优化在线传送来提供特征值，则必须执行以下操作才能检索近似最近邻匹配项：

检索在线存储区的服务连接字符串。
将 Private Service Connect 的端点添加到您的网络配置。
通过 gRPC 连接到 Private Service Connect 端点。
检索嵌入或实体的最近邻匹配项

检索在线存储区的服务连接字符串

在创建使用 Private Service Connect 端点优化在线传送的在线存储区实例时，Vertex AI Feature Store 会生成服务连接字符串。您可以从在线存储区详情中检索服务连接字符串，并使用此字符串设置 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

注意：以下命令假定您已使用您的用户账号通过运行 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": {
    "privateServiceConnectConfig": {
      "enablePrivateServiceConnect": "true",
      "projectAllowlist": [
        "PROJECT_NAME"
      ]
    },
    serviceAttachment: "SERVICE_ATTACHMENT_STRING"
  },
  "optimized": {}
}

您需要来自响应的 SERVICE_ATTACHMENT_STRING 才能在接下来的步骤中提取特征值。

为 Private Service Connect 添加端点

如需将用于优化在线传送的 Private Service Connect 端点添加到您的网络配置，请执行以下步骤：

在 Google Cloud 控制台中，选择包含在线存储区实例的项目。
通过将 SERVICE_ATTACHMENT_STRING 指定为目标服务，为 Private Service Connect 创建端点。

创建端点后，它将显示在 Private Service Connect 页面上的已连接的端点标签页中。端点的 IP 地址会显示在 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 地址列中。

使用 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：要检索的近似最近邻的数量。

使用嵌入进行搜索 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

Python

REST

使用公共端点搜索最近邻匹配项

检索在线存储区的公共端点域名

REST

curl

PowerShell

使用公共端点检索近似最近邻

检索嵌入的近似最近邻

REST

curl

PowerShell

检索实体的近似最近邻

REST

curl

PowerShell

使用 Private Service Connect 端点搜索最近邻匹配项

检索在线存储区的服务连接字符串

REST

curl

PowerShell

为 Private Service Connect 添加端点

通过 gRPC 连接到 Private Service Connect 端点

Python

使用 Private Service Connect 端点检索近似最近邻

检索嵌入的近似最近邻

Python

检索实体的近似最近邻

Python

使用嵌入进行搜索