使用嵌入进行搜索

对于为优化在线传送创建的在线存储区实例，您可以执行矢量相似性搜索来检索在语义上相似或相关的实体（也称为近似最近邻）的列表。您可以根据实体 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 方法和网址：

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