Buscar mediante incorporaciones

En el caso de las instancias de tienda en línea creadas para la entrega en línea optimizada, puedes realizar una búsqueda de similitud de vectores para recuperar una lista de entidades semánticamente similares o relacionadas, también llamadas vecinos más cercanos aproximados. Puedes realizar búsquedas según un ID de entidad o una incorporación.

Según el tipo de extremo configurado para la instancia de tu tienda en línea, puedes realizar una de las siguientes acciones:

• Buscar coincidencias de vecinos más cercanos con un extremo público: Elige esta opción solo si la tienda en línea está configurada para la entrega en línea optimizada desde un extremo público.

• Buscar coincidencias de vecinos más cercanos con un extremo de Private Service Connect: Elige esta opción solo si la tienda en línea está configurada para la entrega en línea optimizada desde un extremo de entrega dedicado a través de Private Service Connect.

Antes de comenzar

Para buscar los vecinos cercanos más próximos, primero debes hacer lo siguiente:

• Configurar la fuente de datos de BigQuery para admitir incorporaciones mediante la inclusión de la columna embedding. De manera opcional, incluye columnas de filtrado y agrupamiento. Para obtener más información, consulta Lineamientos de preparación de fuentes de datos.

• Crea una instancia de tienda en línea para la entrega en línea optimizada.

• Crea una vista de atributos que admita incorporaciones asociando directamente la fuente de datos de BigQuery. Cuando crees la vista de datos de entrenamiento, especifica la columna embedding. Para obtener más información sobre cómo crear una vista de entidad que admita incorporaciones, consulta Configura la recuperación de vectores para una vista de entidad.

• Si deseas buscar coincidencias de vecinos más cercanos con un extremo 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 muestras de Python de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  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.

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

  REST

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

  After installing the Google Cloud CLI, initialize it by running the following command:

  gcloud init

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Si deseas obtener más información, consulta Autentica para usar REST en la Google Cloud documentación de autenticación.

Busca coincidencias de vecinos más cercanos con un extremo público

Si configuraste la instancia de tu tienda en línea para que entregue valores de atributos con la entrega en línea optimizada desde un extremo público, debes hacer lo siguiente para recuperar coincidencias de vecinos más cercanos aproximados:

1. Recupera el nombre de dominio del extremo público de la tienda en línea

2. Recupera las coincidencias de vecino más cercano de una incorporación o entidad

Recupera el nombre de dominio del extremo público de la tienda en línea

Cuando creas una instancia de tienda en línea para la entrega en línea optimizada, Vertex AI Feature Store genera un nombre de dominio de extremo público para el almacén en línea. Antes de comenzar a buscar vecinos más cercanos desde una vista de atributos en la tienda en línea, debes recuperar el nombre de dominio del extremo público de los detalles de la tienda en línea.

Usa la siguiente muestra para recuperar los detalles de una instancia de tienda en línea.

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

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"

$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

{
  "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 recuperar los vecinos más cercanos en el siguiente paso.

Recupera los vecinos más cercanos aproximados con un extremo público

Después de recuperar el nombre de dominio del extremo público de la tienda en línea, puedes usarlo para buscar los vecinos más cercanos aproximados de una incorporación o entidad.

Recupera los vecinos más cercanos aproximados de una incorporación

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

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

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

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"

$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

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

Recupera 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 extremo público.

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

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

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"

$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

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

Cómo buscar coincidencias de vecinos más cercanos con un extremo de Private Service Connect

Si configuraste la instancia de tu tienda en línea para que entregue valores de atributos con la entrega optimizada en línea desde un extremo de Private Service Connect, debes realizar los siguientes pasos para recuperar coincidencias aproximadas de vecinos más cercanos:

1. Recupera la cadena de adjunto de servicio para la tienda en línea.

2. Agrega un extremo para Private Service Connect a tu configuración de red.

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

4. Recupera las coincidencias de vecino más cercano de una incorporación o entidad

Recupera la cadena de adjunto de servicio para la tienda en línea

Cuando creas una instancia de tienda en línea para la entrega en línea optimizada con un extremo de Private Service Connect, Vertex AI Feature Store genera una cadena de adjunto de servicio. Puedes recuperar la cadena de adjunto de servicio de los detalles de la tienda en línea y usarla para configurar el extremo de Private Service Connect.

Usa la siguiente muestra para recuperar los detalles de una instancia de tienda en línea.

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

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"

$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

{
  "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 recuperar los valores de los atributos en el siguiente paso.

Agrega un extremo para Private Service Connect

Si quieres agregar un extremo de Private Service Connect para la entrega en línea optimizada a la configuración de tu red, sigue estos pasos:

1. En la consola de Google Cloud , selecciona el proyecto que contiene la instancia de la tienda en línea.

2. Crea un extremo para Private Service Connect especificando SERVICE_ATTACHMENT_STRING como el servicio de destino.

Después de crear el extremo, aparecerá en la pestaña Extremos conectados en la página de Private Service Connect. La dirección IP del extremo aparece en la columna Direcciones IP.

Ir a la pestaña Extremos conectados

Deberás usar esta dirección IP para conectarte al extremo de tu instancia de almacenamiento en línea al extremo de Private Service Connect mediante gRPC en el siguiente paso.

Conéctate al extremo de Private Service Connect a través de gRPC

Usa la siguiente muestra de código a fin de conectarte al extremo de Private Service Connect creado para tu almacén en línea a través de gRPC.

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

Reemplaza lo siguiente:

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

Recupera los vecinos más cercanos aproximados con un extremo de Private Service Connect

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

Recupera los vecinos más cercanos aproximados de una incorporación

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

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

Reemplaza lo siguiente:

• LOCATION_ID: región en donde se encuentra la tienda en línea, como us-central1.

• PROJECT_ID: ID del proyecto

• FEATUREONLINESTORE_NAME: Es el nombre de la tienda en línea que contiene la vista de atributos.

• FEATUREVIEW_NAME: El nombre de la vista de atributos en la que deseas buscar las coincidencias de vecino más cercano aproximado.

• EMBEDDING: Es la incorporación para la que deseas recuperar las coincidencias de vecino más cercano aproximado. Una incorporación se representa con un array de valores de double.

• FORMAT: Opcional: El formato en el que deseas recuperar los valores del atributo. Los formatos compatibles incluyen el par clave-valor JSON y los formatos proto Struct. Ten en cuenta que el formato Struct de proto no admite el tipo de valor de la función de bytes. Si deseas recuperar valores de atributos con formato de bytes, usa JSON como formato de respuesta.

• RETURN_FULL_ENTITY: Opcional: Especifica si deseas incluir o excluir las funciones de las entidades en la respuesta. Para incluir los atributos junto con las entidades en la respuesta, ingresa true. El valor predeterminado es false.

• NEIGHBOR_COUNT: Es la cantidad de vecinos más cercanos aproximados que deseas recuperar.

Recupera 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 extremo privado.

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

Reemplaza lo siguiente:

• LOCATION_ID: región en donde se encuentra la tienda en línea, como us-central1.

• PROJECT_ID: ID del proyecto

• FEATUREONLINESTORE_NAME: Es el nombre de la tienda en línea que contiene la vista de atributos.

• FEATUREVIEW_NAME: El nombre de la vista de atributos en la que deseas buscar las coincidencias de vecino más cercano aproximado.

• ENTITY_ID: Es el ID de la entidad para la que deseas recuperar las coincidencias de vecino más cercano aproximado.

• FORMAT: Opcional: El formato en el que deseas recuperar los valores del atributo. Los formatos compatibles incluyen el par clave-valor JSON y los formatos proto Struct. Ten en cuenta que el formato Struct de proto no admite el tipo de valor de la función de bytes. Si deseas recuperar valores de atributos con formato de bytes, usa JSON como formato de respuesta.

• RETURN_FULL_ENTITY: Opcional: Especifica si deseas incluir o excluir las funciones de las entidades en la respuesta. Para incluir los atributos junto con las entidades en la respuesta, ingresa true. El valor predeterminado es false.

• NEIGHBOR_COUNT: Es la cantidad de vecinos más cercanos aproximados que deseas recuperar.