对于为优化在线传送创建的在线存储区实例,您可以执行矢量相似性搜索来检索在语义上相似或相关的实体(也称为近似最近邻)的列表。您可以根据实体 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
执行以下命令:
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 } ] } }