Buscar mediante incorporaciones

Si configuraste tu tienda en línea para que admita incorporaciones, puedes realizar una búsqueda de similitud vectorial para recuperar una lista de entidades similares o relacionadas de manera semántica, también llamadas vecinos más cercanos. Puedes buscar según una 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, incluye columnas de filtrado y amontonamiento. Para obtener más información, consulta Lineamientos de preparación de fuentes de datos.
Crea una instancia de tienda en línea que admita la administración de incorporaciones. Para obtener más información sobre cómo crear una instancia de almacén en línea que admita la administración de incorporaciones, consulta Configura la administración de incorporaciones para una tienda en línea.
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 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

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

Cuando creas y configuras una instancia de tienda en línea para la administración de incorporaciones, Vertex AI Feature Store genera un nombre de dominio de extremo público para la tienda 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 http://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)" \
     "http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME"

PowerShell

Nota: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante 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 "http://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 aproximados en el siguiente paso.

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

Usa la siguiente muestra para usar una incorporación a fin de realizar una búsqueda de entidades relacionadas de forma 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 mediante 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: Es el nombre de la vista de atributos en la que deseas buscar coincidencias del vecino más cercano.
EMBEDDING: Es la incorporación para la que deseas recuperar coincidencias de vecino más cercano. Una incorporación se representa con un arreglo de valores double.
BOOLEAN: Especifica si deseas incluir o excluir los atributos de las entidades de la respuesta (opcional). 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.

Método HTTP y URL:

POST http://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 \
     "http://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 "http://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 a fin de usar una incorporación para realizar búsquedas de entidades relacionadas de forma semántica mediante la especificación de un ID de entidad.

REST

Para buscar los 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: Es el nombre de la vista de atributos en la que deseas buscar coincidencias del vecino más cercano.
ENTITY_ID: ID de la entidad de la que deseas recuperar las coincidencias de vecino más cercano.
BOOLEAN: Especifica si deseas incluir o excluir los atributos de las entidades de la respuesta (opcional). 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.

Método HTTP y URL:

POST http://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 \
     "http://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 "http://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
    } ]
  }
}