Buscar usando incrustaciones

En las instancias de tiendas online creadas para el servicio online optimizado, puedes realizar una búsqueda de similitud de vectores para obtener una lista de entidades semánticamente similares o relacionadas, también llamadas vecinos más cercanos aproximados. Puedes buscar por ID de entidad o por embedding.

En función del tipo de endpoint configurado para tu instancia de tienda online, puedes hacer lo siguiente:

Antes de empezar

Para buscar los vecinos más cercanos aproximados, primero debes hacer lo siguiente:

  • Configura la fuente de datos de BigQuery para que admita las inserciones incluyendo la columna embedding. Si quieres, puedes incluir columnas de filtrado y de saturación. Para obtener más información, consulta las directrices de preparación de fuentes de datos.

  • Crea una instancia de tienda online para el servicio online optimizado.

  • Crea una vista de características que admita las inserciones asociando directamente la fuente de datos de BigQuery. Al crear la vista de la función, especifica la columna embedding. Para obtener más información sobre cómo crear una vista de características que admita las inserciones, consulta Configurar la recuperación de vectores de una vista de características.

  • Si quieres buscar coincidencias de vecinos más cercanos mediante un endpoint de Private Service Connect, instala o actualiza a la versión más reciente del SDK de Python. Ejecuta el siguiente comando:
    pip3 install --upgrade --quiet google-cloud-aiplatform

  • Sigue estas instrucciones para autenticarte en Vertex AI, a menos que ya lo hayas hecho.

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

    Python

    Para usar las Python muestras de esta página en un entorno de desarrollo local, instala e inicializa la CLI de gcloud y, a continuación, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

      Instala Google Cloud CLI.

      Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

      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.

    Para obtener más información, consulta Set up authentication for a local development environment.

    REST

    Para usar las muestras de la API REST de esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la CLI de gcloud.

      Instala Google Cloud CLI.

      Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

    Para obtener más información, consulta el artículo Autenticarse para usar REST de la documentación sobre autenticación de Google Cloud .

Buscar coincidencias de vecinos más cercanos con un endpoint público

Si ha configurado su instancia de tienda online para que sirva valores de características mediante el servicio online optimizado desde un endpoint público, debe hacer lo siguiente para obtener coincidencias de vecinos más cercanos aproximadas:

  1. Recuperar el nombre de dominio del endpoint público de la tienda online

  2. Obtener las coincidencias de vecinos más cercanos de una inserción o una entidad

Recuperar el nombre de dominio del endpoint público de la tienda online

Cuando creas una instancia de almacén online para la entrega online optimizada, Vertex AI Feature Store genera un nombre de dominio de endpoint público para el almacén online. Antes de poder buscar los vecinos más cercanos desde una vista de características en la tienda online, debes obtener el nombre de dominio del endpoint público de los detalles de la tienda online.

Usa el siguiente ejemplo para obtener los detalles de una instancia de tienda online.

REST

Para obtener los detalles de un recurso FeatureOnlineStore de tu proyecto, envía una solicitud GET mediante el método featureOnlineStores.get.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION_ID: región en la que se encuentra la tienda online, como us-central1.
  • PROJECT_ID: tu ID de proyecto.
  • FEATUREONLINESTORE_NAME: nombre de la instancia de la tienda online.

Método HTTP y URL: 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente: 

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

Ejecuta el comando siguiente: 

$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

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "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": {}
}

Necesitarás el PUBLIC_ENDPOINT_DOMAIN_NAME de la respuesta para obtener los vecinos más cercanos aproximados en el siguiente paso.

Obtener los vecinos más cercanos aproximados mediante un endpoint público

Una vez que hayas obtenido el nombre de dominio del endpoint público de la tienda online, puedes usarlo para buscar los vecinos más cercanos aproximados de una inserción o una entidad.

Obtener los vecinos más cercanos aproximados de una inserción

Usa el siguiente ejemplo para buscar entidades relacionadas semánticamente especificando una inserción mientras usas un endpoint público.

REST

Para buscar los vecinos más cercanos de una inserción, envía una solicitud POST mediante el método featureViews.searchNearestEntities.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PUBLIC_ENDPOINT_DOMAIN_NAME: nombre de dominio del endpoint público de la instancia de la tienda online que has obtenido con el método featureOnlineStores.get.
  • PROJECT_ID: tu ID de proyecto.
  • LOCATION_ID: región en la que se encuentra la instancia de la tienda online, como us-central1.
  • FEATUREONLINESTORE_NAME: nombre de la instancia de la tienda online que contiene la vista de características en la que quiere buscar coincidencias de vecinos más próximos aproximadas.
  • FEATUREVIEW_NAME: el nombre de la vista de características en la que quiere buscar coincidencias de vecinos más próximos aproximadas.
  • EMBEDDING: inserción de la que quieres obtener las coincidencias de vecinos más cercanos aproximadas. Una inserción se representa mediante una matriz de valores double.
  • RETURN_FULL_ENTITY: opcional. Especifica si quieres incluir o excluir las funciones de las entidades en la respuesta. Para incluir las funciones junto con las entidades en la respuesta, introduce true. El valor predeterminado es false.
  • NEIGHBOR_COUNT: número de vecinos más cercanos aproximados que quieres obtener.

Método HTTP y URL: 

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

Cuerpo JSON de la solicitud: 

{
  "query": {
    "embedding": {
      "value": EMBEDDING
    },
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": RETURN_FULL_ENTITY
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

$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

Deberías recibir una respuesta JSON similar a la siguiente:

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

Obtener los vecinos más cercanos aproximados de una entidad

Usa el siguiente ejemplo para buscar entidades relacionadas semánticamente especificando un ID de entidad al usar un endpoint público.

REST

Para buscar los vecinos más cercanos de un ID de entidad, envía una solicitud POST mediante el método featureViews.searchNearestEntities.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PUBLIC_ENDPOINT_DOMAIN_NAME: nombre de dominio del endpoint público de la instancia de la tienda online que has obtenido con el método featureOnlineStores.get.
  • PROJECT_ID: tu ID de proyecto.
  • LOCATION_ID: región en la que se encuentra la instancia de la tienda online, como us-central1.
  • FEATUREONLINESTORE_NAME: nombre de la instancia de la tienda online que contiene la vista de características en la que quiere buscar coincidencias de vecinos más próximos aproximadas.
  • FEATUREVIEW_NAME: el nombre de la vista de características en la que quiere buscar coincidencias de vecinos más próximos aproximadas.
  • ENTITY_ID: ID de la entidad de la que quieres obtener las coincidencias de vecinos más próximos aproximadas.
  • RETURN_FULL_ENTITY: opcional. Especifica si quieres incluir o excluir las funciones de las entidades en la respuesta. Para incluir las funciones junto con las entidades en la respuesta, introduce true. El valor predeterminado es false.
  • NEIGHBOR_COUNT: número de vecinos más cercanos aproximados que quieres obtener.

Método HTTP y URL: 

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

Cuerpo JSON de la solicitud: 

{
  "query": {
    "entity_id": ENTITY_ID,
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": RETURN_FULL_ENTITY
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

$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

Deberías recibir una respuesta JSON similar a la siguiente:

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

Buscar coincidencias de vecinos más cercanos mediante un endpoint de Private Service Connect

Si ha configurado su instancia de tienda online para que proporcione valores de características mediante el servicio online optimizado desde un endpoint de Private Service Connect, debe hacer lo siguiente para obtener las coincidencias de vecinos más cercanos aproximadas:

  1. Recupera la cadena de vinculación de servicio de la tienda online.

  2. Añade un endpoint de Private Service Connect a tu configuración de red.

  3. Conéctate al endpoint de Private Service Connect a través de gRPC.

  4. Obtener las coincidencias de vecinos más cercanos de una inserción o una entidad

Recuperar la cadena de adjunto de servicio de la tienda online

Cuando creas una instancia de tienda online para el servicio online optimizado con un punto final de Private Service Connect, Vertex AI Feature Store genera una cadena de vinculación de servicio. Puedes obtener la cadena de adjunto de servicio de los detalles de la tienda online y usarla para configurar el punto final de Private Service Connect.

Usa el siguiente ejemplo para obtener los detalles de una instancia de tienda online.

REST

Para obtener los detalles de un recurso FeatureOnlineStore de tu proyecto, envía una solicitud GET mediante el método featureOnlineStores.get.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • LOCATION_ID: región en la que se encuentra la tienda online, como us-central1.
  • PROJECT_ID: tu ID de proyecto.
  • FEATUREONLINESTORE_NAME: nombre de la instancia de la tienda online.

Método HTTP y URL: 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente: 

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

Ejecuta el comando siguiente: 

$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

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "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": {}
}

Necesitarás el SERVICE_ATTACHMENT_STRING de la respuesta para obtener los valores de las características en el siguiente paso.

Añadir un endpoint para Private Service Connect

Para añadir un endpoint de Private Service Connect para el servicio online optimizado a la configuración de tu red, sigue estos pasos:

  1. En la Google Cloud consola, selecciona el proyecto que contiene la instancia de la tienda online.

  2. Crea un punto final para Private Service Connect especificando SERVICE_ATTACHMENT_STRING como Servicio de destino.

Una vez que hayas creado el punto final, aparecerá en la pestaña Puntos finales conectados de la página Private Service Connect. La dirección IP del endpoint aparece en la columna Direcciones IP.

Ir a la pestaña Puntos finales conectados

Deberás usar esta dirección IP para conectarte al endpoint de tu instancia de tienda online al endpoint de Private Service Connect a través de gRPC en el siguiente paso.

Conectarse al endpoint de Private Service Connect a través de gRPC

Usa el siguiente fragmento de código para conectarte al endpoint de Private Service Connect creado para tu tienda online a través de gRPC.

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")
  )
)

Haz los cambios siguientes:

  • ENDPOINT_IP: la dirección IP del endpoint de la columna Direcciones IP de la página Private Service Connect.

Obtener los vecinos más cercanos aproximados mediante un endpoint de Private Service Connect

Después de conectarte al endpoint de Private Service Connect a través de gRPC, puedes buscar los vecinos más cercanos aproximados de una inserción o una entidad.

Obtener los vecinos más cercanos aproximados de una inserción

Usa el siguiente ejemplo para buscar entidades relacionadas semánticamente especificando una inserción mientras usas un endpoint privado.

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
  ))

Haz los cambios siguientes:

  • LOCATION_ID: región en la que se encuentra la tienda online, como us-central1.

  • PROJECT_ID: tu ID de proyecto.

  • FEATUREONLINESTORE_NAME: nombre de la tienda online que contiene la vista de la función.

  • FEATUREVIEW_NAME: el nombre de la vista de la función en la que quieras buscar coincidencias de vecinos más próximos aproximadas.

  • EMBEDDING: embedding del que quieres obtener las coincidencias aproximadas del vecino más cercano. Una inserción se representa mediante una matriz de valores double.

  • FORMAT: opcional. Es el formato en el que quieres obtener los valores de la función. Entre los formatos admitidos se incluyen los pares clave-valor JSON y los formatos proto.Struct Ten en cuenta que el formato proto Struct no admite el tipo de valor de la función de bytes. Si quieres obtener valores de características que tengan el formato de bytes, usa JSON como formato de respuesta.

  • RETURN_FULL_ENTITY: opcional. Especifica si quieres incluir o excluir las funciones de las entidades en la respuesta. Para incluir las funciones junto con las entidades en la respuesta, introduce true. El valor predeterminado es false.

  • NEIGHBOR_COUNT: número de vecinos más cercanos aproximados que quieres obtener.

Obtener los vecinos más cercanos aproximados de una entidad

Usa el siguiente ejemplo para buscar entidades relacionadas semánticamente especificando un ID de entidad mientras usas un endpoint privado.

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
  ))
 ```

Haz los cambios siguientes:

  • LOCATION_ID: región en la que se encuentra la tienda online, como us-central1.

  • PROJECT_ID: tu ID de proyecto.

  • FEATUREONLINESTORE_NAME: nombre de la tienda online que contiene la vista de la función.

  • FEATUREVIEW_NAME: el nombre de la vista de la función en la que quieras buscar coincidencias de vecinos más próximos aproximadas.

  • ENTITY_ID: ID de la entidad de la que quieres obtener las coincidencias de vecinos más cercanos aproximadas.

  • FORMAT: opcional. Es el formato en el que quieres obtener los valores de la función. Entre los formatos admitidos se incluyen los pares clave-valor JSON y los formatos proto.Struct Ten en cuenta que el formato proto Struct no admite el tipo de valor de la función de bytes. Si quieres obtener valores de características que tengan el formato de bytes, usa JSON como formato de respuesta.

  • RETURN_FULL_ENTITY: opcional. Especifica si quieres incluir o excluir las funciones de las entidades en la respuesta. Para incluir las funciones junto con las entidades en la respuesta, introduce true. El valor predeterminado es false.

  • NEIGHBOR_COUNT: número de vecinos más cercanos aproximados que quieres obtener.