Rechercher à l'aide d'embeddings

Pour les instances de magasin en ligne créées pour la diffusion en ligne optimisée, vous pouvez effectuer une recherche de similarité de vecteurs pour récupérer une liste d'entités sémantiquement similaires ou associées, également appelées voisins approximatifs les plus proches. Vous pouvez effectuer une recherche en fonction d'un ID d'entité ou d'une intégration.

Pour rechercher les voisins approximatifs les plus proches, vous devez d'abord effectuer les opérations suivantes :

Configurez la source de données BigQuery pour accepter les représentations vectorielles continues en incluant la colonne embedding. Vous pouvez également inclure des colonnes de filtrage et de regroupement. Pour en savoir plus, consultez les consignes de préparation des sources de données.
Créer une instance de magasin en ligne pour la diffusion en ligne optimisée.
Spécifiez la colonne embedding lors de la création de la vue des caractéristiques. Pour en savoir plus sur la création d'une vue de caractéristiques compatible avec les embeddings, consultez la section Configurer la récupération vectorielle pour une vue de caractéristiques.

Cette page explique comment effectuer les opérations suivantes :

Récupérer le nom de domaine du point de terminaison public pour le magasin en ligne
Récupérer les correspondances des voisins les plus proches d'un embedding
Récupérer les correspondances des plus proches voisins d'une entité

Avant de commencer

Authentifiez-vous auprès de Vertex AI, sauf si vous l'avez déjà fait.

Pour utiliser les exemples d'API REST de cette page dans un environnement de développement local, vous devez utiliser les identifiants que vous fournissez à gcloud CLI.

Install the Google Cloud CLI, then initialize it by running the following command:

gcloud init

Pour en savoir plus, consultez la section S'authentifier pour utiliser REST dans la documentation sur l'authentification Google Cloud.

Récupérer le nom de domaine du point de terminaison public pour le magasin en ligne

Lorsque vous créez une instance de magasin en ligne pour la diffusion en ligne optimisée, Vertex AI Feature Store génère un nom de domaine de point de terminaison public pour la boutique en ligne. Avant de pouvoir rechercher les voisins les plus proches à partir d'une vue des caractéristiques de la boutique en ligne, vous devez récupérer le nom de domaine du point de terminaison public à partir des détails de la boutique en ligne.

Basez-vous sur l'exemple suivant pour récupérer les détails d'une instance de magasin en ligne.

REST

Pour récupérer les détails d'une ressource FeatureOnlineStore au sein de votre projet, envoyez une requête GET à l'aide de la méthode featureOnlineStores.get.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

LOCATION_ID : région où se trouve la boutique en ligne, par exemple us-central1.
PROJECT_ID : ID de votre projet
FEATUREONLINESTORE_NAME : nom de l'instance de magasin en ligne.

Méthode HTTP et URL :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Exécutez la commande suivante :

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

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Vous aurez besoin de la valeur PUBLIC_ENDPOINT_DOMAIN_NAME dans la réponse pour récupérer les voisins approximatifs les plus proches à l'étape suivante.

Récupérer les voisins approximatifs les plus proches d'un embedding

Utilisez l'exemple suivant pour utiliser un embedding afin de rechercher des entités sémantiquement liées en spécifiant un embedding.

REST

Pour rechercher les représentations voisines les plus proches, envoyez une requête POST à l'aide de la méthode featureViews.searchNearestEntities.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

PUBLIC_ENDPOINT_DOMAIN_NAME : nom de domaine du point de terminaison public pour l'instance de magasin en ligne, que vous avez récupéré à l'aide de la méthode featureOnlineStores.get.
PROJECT_ID : ID de votre projet
LOCATION_ID : région où se trouve l'instance de boutique en ligne, telle que us-central1.
FEATUREONLINESTORE_NAME : nom de l'instance de boutique en ligne contenant la vue de la caractéristique dans laquelle vous souhaitez rechercher des correspondances de type "plus proches voisins approximatifs".
FEATUREVIEW_NAME : nom de la vue de la caractéristique dans laquelle vous souhaitez rechercher les correspondances voisines approximatives les plus proches.
EMBEDDING : embedding pour lequel vous souhaitez récupérer les correspondances de voisins approximatifs les plus proches. Un embedding est représenté par un tableau de valeurs double.
RETURN_FULL_ENTITY Facultatif : indiquez si vous souhaitez inclure ou exclure les caractéristiques des entités de la réponse. Pour inclure les caractéristiques avec les entités dans la réponse, saisissez true. La valeur par défaut est false.
NEIGHBOR_COUNT : nombre de voisins approximatifs les plus proches que vous souhaitez récupérer.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Récupérer les voisins approximatifs les plus proches d'une entité

Utilisez l'exemple suivant pour utiliser un embedding afin d'effectuer une recherche d'entités sémantiquement liées en spécifiant un ID d'entité.

REST

Pour rechercher les ID des entités voisines les plus proches, envoyez une requête POST à l'aide de la méthode featureViews.searchNearestEntities.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

PUBLIC_ENDPOINT_DOMAIN_NAME : nom de domaine du point de terminaison public pour l'instance de magasin en ligne, que vous avez récupéré à l'aide de la méthode featureOnlineStores.get.
PROJECT_ID : ID de votre projet
LOCATION_ID : région où se trouve l'instance de boutique en ligne, telle que us-central1.
FEATUREONLINESTORE_NAME : nom de l'instance de boutique en ligne contenant la vue de la caractéristique dans laquelle vous souhaitez rechercher des correspondances de type "plus proches voisins approximatifs".
FEATUREVIEW_NAME : nom de la vue de la caractéristique dans laquelle vous souhaitez rechercher les correspondances voisines approximatives les plus proches.
ENTITY_ID : ID de l'entité pour laquelle vous souhaitez récupérer les correspondances des voisins approximatifs les plus proches.
RETURN_FULL_ENTITY Facultatif : indiquez si vous souhaitez inclure ou exclure les caractéristiques des entités de la réponse. Pour inclure les caractéristiques avec les entités dans la réponse, saisissez true. La valeur par défaut est false.
NEIGHBOR_COUNT : nombre de voisins approximatifs les plus proches que vous souhaitez récupérer.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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