Buscar mediante incorporaciones

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

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, puedes incluir el filtrado y la agrupamiento de columnas. 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.
Especifica la columna embedding mientras creas la vista de atributos. Para obtener más información sobre cómo crear una vista de atributos que admita incorporaciones, consulta Configura la recuperación de vectores para una vista de atributos.

En esta página, se describe cómo puedes hacer lo siguiente:

Recupera el nombre de dominio del extremo público de la tienda en línea
Recupera las coincidencias de vecino más cercano de una incorporación
Recupera las coincidencias de vecino más cercano de una entidad

Antes de comenzar

Autentícate en Vertex AI, a menos que ya lo hayas hecho.

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.

Instala Google Cloud CLI y, luego, inicializa la ejecución del siguiente comando:

gcloud init

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

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.

REST

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

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

LOCATION_ID: región en donde se encuentra la tienda en línea, como us-central1.
PROJECT_ID: ID del proyecto
FEATUREONLINESTORE_NAME: El nombre de la instancia de tienda en línea.

HTTP method and 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

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

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

Nota: En el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente comando:

$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 que se muestra a continuación:

{
  "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 de una incorporación

Usa el siguiente ejemplo para usar una incorporación a fin de realizar la búsqueda de entidades relacionadas de manera semántica mediante la especificación de una incorporación.

REST

Para buscar vecinos más cercanos para una incorporación, envía una solicitud POST con el método featureViews.searchNearestEntities.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PUBLIC_ENDPOINT_DOMAIN_NAME: Es el nombre de dominio del extremo público para la instancia de tienda en línea que recuperaste mediante el método featureOnlineStores.get.
PROJECT_ID: ID del proyecto
LOCATION_ID: región en donde se encuentra la tienda en línea, como us-central1.
FEATUREONLINESTORE_NAME: El nombre de la instancia de la tienda en línea que contiene la vista de atributos en la que deseas buscar las coincidencias de vecino más cercano aproximado.
FEATUREVIEW_NAME: El nombre de la vista de características en la que deseas buscar las coincidencias aproximadas de los vecinos más cercanos.
EMBEDDING: Embedding para el que deseas recuperar las coincidencias de vecino más cercano aproximado. Una incorporación se representa con un array de valores double.
BOOLEAN: Opcional: Especifica si deseas incluir o excluir los atributos 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: La cantidad de vecinos más cercanos aproximados que deseas recuperar.

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

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 que se muestra a continuación:

{
  "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 usar una incorporación para realizar búsquedas de entidades relacionadas de manera semántica mediante la especificación de un ID de entidad.

REST

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

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PUBLIC_ENDPOINT_DOMAIN_NAME: Es el nombre de dominio del extremo público para la instancia de tienda en línea que recuperaste mediante el método featureOnlineStores.get.
PROJECT_ID: ID del proyecto
LOCATION_ID: región en donde se encuentra la tienda en línea, como us-central1.
FEATUREONLINESTORE_NAME: El nombre de la instancia de la tienda en línea que contiene la vista de atributos en la que deseas buscar las coincidencias de vecino más cercano aproximado.
FEATUREVIEW_NAME: El nombre de la vista de características en la que deseas buscar las coincidencias aproximadas de los vecinos más cercanos.
ENTITY_ID: El ID de la entidad para la que deseas recuperar las coincidencias de vecino más cercano aproximado.
BOOLEAN: Opcional: Especifica si deseas incluir o excluir los atributos 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: La cantidad de vecinos más cercanos aproximados que deseas recuperar.

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

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 que se muestra a continuación:

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