Mettre à jour et recompiler un index actif

Présentation

Avec des requêtes de recherche volumineuses, la mise à jour de vos index est importante pour toujours disposer des informations les plus précises. Aujourd'hui, vous pouvez mettre à jour vos index Vector Search à l'aide d'une mise à jour groupée, qui vous permet d'insérer et de supprimer des points de données via une programmation par lots ou avec la mise à jour en continu, ce qui vous permet de mettre à jour et d'interroger votre index en seulement quelques secondes.

Vous pouvez également utiliser UpdateIndex pour mettre à jour vos champs de métadonnées importants, tels que display_name, description et labels. Vous pouvez également ajouter des tags facultatifs à votre index pour faciliter la diversification des résultats ou le filtrage des requêtes avant indexation.

Mettre à jour un index de traitement par lot

Pour mettre à jour le contenu d'un index Index existant, utilisez la méthode IndexService.UpdateIndex.

Pour remplacer le contenu existant d'un Index :

  • Définissez Index.metadata.contentsDeltaUri sur l'URI Cloud Storage incluant les vecteurs que vous souhaitez mettre à jour.
  • Définissez isCompleteOverwrite sur "true".

Si vous définissez le champ contentsDeltaUri lorsque vous appelez IndexService.UpdateIndex, aucun autre champ d'index (tel que displayName, description ou userLabels) ne peut être mis à jour au cours du même appel.

gcloud

  1. Mettez à jour votre fichier de métadonnées d'index.
  2. Exécutez la commande gcloud ai indexes update.

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • LOCAL_PATH_TO_METADATA_FILE : chemin d'accès local au fichier de métadonnées.
  • INDEX_ID : ID de l'index.
  • LOCATION : région dans laquelle vous utilisez Vertex AI.
  • PROJECT_ID : L'ID de votre projet Google Cloud.

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud ai indexes update INDEX_ID \
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
    --region=LOCATION \
    --project=PROJECT_ID

Windows (PowerShell)

gcloud ai indexes update INDEX_ID `
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE `
    --region=LOCATION `
    --project=PROJECT_ID

Windows (cmd.exe)

gcloud ai indexes update INDEX_ID ^
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

  • INPUT_DIR : chemin d'accès au répertoire Cloud Storage du contenu de l'index.
  • INDEX_ID : ID de l'index.
  • LOCATION : région dans laquelle vous utilisez Vertex AI.
  • PROJECT_ID : L'ID de votre projet Google Cloud.
  • PROJECT_NUMBER : numéro de projet généré automatiquement pour votre projet.

Méthode HTTP et URL :

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID

Corps JSON de la requête :

{
 "metadata": {
   "contentsDeltaUri": "INPUT_DIR",
   "isCompleteOverwrite": true
 }
}

Pour envoyer votre requête, développez l'une des options suivantes :

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

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateIndexOperationMetadata",
   "genericMetadata": {
     "createTime": "2022-01-12T23:56:14.480948Z",
     "updateTime": "2022-01-12T23:56:14.480948Z"
   }
 }
}

Console

Suivez ces instructions pour mettre à jour le contenu d'un index par lot.

  1. Dans la section "Vertex AI" de la console Google Cloud, accédez à la section Déployer et utiliser. Sélectionnez Vector Search.

    Accéder à Vector Search

  2. Sélectionnez l'index que vous souhaitez mettre à jour. La page Informations sur l'index s'affiche.
  3. Sélectionnez Modifier l'index. Un volet de modification d'index s'ouvre.
  4. Dans le champ Cloud Storage, recherchez et sélectionnez le dossier Cloud Storage dans lequel vos données vectorielles sont stockées.
  5. (Facultatif) Cochez la case d'écrasement complet si vous souhaitez écraser toutes les données existantes.
  6. Cliquez sur Mettre à jour.
  7. Cliquez sur Terminé pour fermer le panneau.

Si des déploiements sont associés à l'Index (voir le champ Index.deployed_indexes), lorsque des modifications de l'Index d'origine sont en cours, la propriété DeployedIndex est automatiquement mise à jour de manière asynchrone en arrière-plan pour refléter ces changements.

Pour vérifier que la modification a été propagée, comparez l'heure de fin de l'opération de mise à jour de l'index et la valeur DeployedIndex.index_sync_time.

Mettre à jour un index en continu

Avec les mises à jour en continu, vous pouvez mettre à jour et interroger votre index en quelques secondes. Pour le moment, vous ne pouvez pas utiliser les mises à jour en continu sur un index de mise à jour groupée existant. Vous devez donc créer un nouvel index. Pour en savoir plus, consultez la section Créer un index pour la mise à jour en continu.

Vous êtes facturé 0,45 $ par Go utilisé pour les mises à jour en continu. Pour connaître le détail des tarifs, consultez la page Tarification de Vertex AI. Les mises à jour en continu sont directement appliquées aux index déployés en mémoire, qui sont ensuite reflétés dans les résultats de la requête après un court délai.

Effectuer une opération upsert sur des points de données

Utilisez ces exemples pour voir comment effectuer une opération upsert sur un point de données. N'oubliez pas que upsert-datapoints accepte les formats JSON sous forme de tableau uniquement.

Python

Python

def stream_update_vector_search_index(
    project: str, location: str, index_name: str, datapoints: Sequence[dict]
) -> None:
    """Stream update an existing vector search index

    Args:
      project (str): Required. The Project ID
      location (str): Required. The region name, e.g. "us-central1"
      index_name (str): Required. The index to update. A fully-qualified index
        resource name or a index ID.  Example:
        "projects/123/locations/us-central1/indexes/my_index_id" or
        "my_index_id".
      datapoints: Sequence[dict]: Required. The datapoints to be updated. The dict
        element should be of the IndexDatapoint type.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index instance from an existing index with stream_update
    # enabled
    my_index = aiplatform.MatchingEngineIndex(index_name=index_name)

    # Upsert the datapoints to the index
    my_index.upsert_datapoints(datapoints=datapoints)

Curl

La limite de quota de débit concerne la quantité de données incluse dans une opération upsert. Si l'ID de point de données existe dans l'index, la représentation vectorielle continue est mise à jour. Dans le cas contraire, une nouvelle représentation vectorielle continue est ajoutée.

  
  DATAPOINT_ID_1=
  DATAPOINT_ID_2=
  curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
  -d '{datapoints: [{datapoint_id: "'${DATAPOINT_ID_1}'", feature_vector: [...]},
  {datapoint_id: "'${DATAPOINT_ID_2}'", feature_vector: [...]}]}'
  
  

Console

Console

Suivez les instructions ci-dessous pour mettre à jour du contenu vers un index en continu.

  1. Dans la section "Vertex AI" de la console Google Cloud, accédez à la section Déployer et utiliser. Sélectionnez Vector Search.

    Accéder à Vector Search

  2. Sélectionnez l'index que vous souhaitez mettre à jour. La page Informations sur l'index s'affiche.
  3. Sélectionnez Modifier l'index. Un volet de modification d'index s'ouvre.
  4. Dans le volet, sélectionnez Faire l'upsert d'un point de données pour ajouter du contenu.
  5. Saisissez l'ID du point de données.
  6. Saisissez les valeurs des vecteurs de caractéristiques pour le point de données qui fait l'objet d'un upsert. Ce champ doit contenir des nombres séparés par une virgule (par exemple, 9.32, 0.12, -2.35).
  7. Saisissez la chaîne.
  8. Cliquez sur Faire un upsert.
  9. Cliquez sur Terminé pour fermer le panneau.

La limite de quota de débit concerne la quantité de données incluse dans une opération upsert. Si l'ID de point de données existe dans l'index, la représentation vectorielle continue est mise à jour. Dans le cas contraire, une nouvelle représentation vectorielle continue est ajoutée.

Mettre à jour les métadonnées dynamiques

Vous pouvez être amené à mettre à jour les restrictions de flux ou les restrictions numériques pour différentes raisons. Par exemple, lorsque vous traitez un volume important de données évoluant rapidement, vous pouvez donner la priorité à certains flux de données. La mise à jour directe des restrictions ou des restrictions numériques vous permet d'affiner le centre d'intérêt en temps réel, garantissant ainsi que les données les plus importantes sont traitées ou mises en évidence immédiatement.

Vous pouvez mettre à jour directement les restrictions de points de données et les restrictions numériques dans un index de diffusion sans le coût de compactage d'une mise à jour complète.

Pour effectuer ces mises à jour exclusivement sur les métadonnées, vous devez ajouter le champ update_mask à la requête. La valeur de update_mask doit être définie sur all_restricts. Les valeurs de restriction et de restriction numérique définies dans les points de données doivent correspondre aux nouvelles valeurs que vous souhaitez appliquer dans la mise à jour.

L'exemple suivant montre comment ajouter des restrictions à deux points de données existants.

DATAPOINT_ID_1=
DATAPOINT_ID_2=

curl -H "Content-Type: application/json" -H "Authorization: Bearer gcloud auth print-access-token" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
-d '{datapoints:
[{datapoint_id: "'${DATAPOINT_ID_1}'", feature_vector: [...],  restricts:[{namespace: "color", allow_list: ["red"]}]},
{datapoint_id: "'${DATAPOINT_ID_2}'", feature_vector: [...],  restricts:[{namespace: "color", allow_list: ["red"]}]}
], update_mask: "all_restricts"}'

Supprimer des points de données

Vous devrez peut-être supprimer des points de données de votre index en continu. Pour ce faire, utilisez curl ou la console Google Cloud.

Un cas d'utilisation clé pour la suppression d'un point de données d'un index consiste à maintenir la parité entre l'index et sa source réelle. Prenons l'exemple d'un librairie qui utilise une représentation vectorielle continue de vecteurs pour représenter son inventaire de livres à des fins de recherche et de recommandation. Lorsqu'un livre est vendu ou retiré des stocks, la suppression du point de données correspondant de l'index garantit que les résultats de recherche et les recommandations restent précis et à jour.

Curl


curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{REGION}/indexes/{INDEX_ID}:removeDatapoints -d '{datapoint_ids: ["'{DATAPOINT_ID_1}'", "'{DATAPOINT_ID_2}'"]}'

Console

Console

Suivez ces instructions pour supprimer un point de données de l'index en continu.

  1. Dans la section "Vertex AI" de la console Google Cloud, accédez à la section Déployer et utiliser. Sélectionnez Vector Search.

    Accéder à Vector Search

  2. Sélectionnez l'index en continu que vous souhaitez mettre à jour. La page Informations sur l'index s'affiche.
  3. Sélectionnez Modifier l'index. Un volet de modification d'index s'ouvre.
  4. Dans le volet, sélectionnez l'onglet Supprimer des points de données.
  5. Ajoutez jusqu'à 20 points de données en spécifiant une liste d'ID de points de données séparés par une virgule.
  6. Cliquez sur Supprimer.
  7. Cliquez sur Terminé pour fermer le panneau.

Compactage

Votre index est régulièrement recompilé pour prendre en compte toutes les mises à jour depuis votre dernière recompilation. Cette recompilation, ou "compactage", améliore les performances et la fiabilité des requêtes. Les compactages se produisent à la fois pour les mises à jour en continu et pour les mises à jour groupées.

  • Mise à jour en continu : Vector Search utilise des métriques basées sur l'heuristique pour déterminer à quel moment déclencher le compactage. Si les données non compactées les plus anciennes datent de cinq jours, le compactage est toujours déclenché. Vous êtes facturé pour le coût de la recompilation de l'index au même tarif que la mise à jour groupée, en plus des coûts de mise à jour en continu.

  • Mise à jour groupée : se produit lorsque la taille de l'ensemble de données incrémentiel est supérieure à 20 % de la taille de l'ensemble de données de base.

Recompiler et interroger votre index

Vous pouvez envoyer des requêtes de correspondance ou de correspondance par lot comme d'habitude à l'aide de la CLI grpc, de la bibliothèque cliente ou du SDK Vertex AI pour Python. Lorsque vous recompilez la requête, les mises à jour devraient s'afficher en quelques secondes. Pour savoir comment interroger un index, consultez la section Interroger les index pour obtenir les voisins les plus proches.

Champs facultatifs

Lorsque vous créez un index, vous pouvez utiliser certains champs facultatifs pour affiner vos requêtes.

Opération upsert avec restrictions

Une opération upsert sur votre index avec l'ajout d'une restriction permet d'appliquer des tags à vos points de données afin qu'ils soient déjà identifiés pour le filtrage au moment de la requête. Vous pouvez ajouter des tags de restriction pour limiter les résultats présentés dans vos données avant l'envoi d'une requête. Par exemple, un client souhaite exécuter une requête sur un index, mais veut s'assurer que les résultats n'affichent que des articles correspondant à "rouge" dans une recherche de chaussures. Dans l'exemple suivant, l'index est en train d'être mis à jour et de filtrer toutes les paires de chaussure rouges, mais refuse les bleues. Cela garantit, avant l'exécution, des filtres de recherche dans les meilleures options spécifiques parmi un index volumineux et varié.

En plus des restrictions de jeton, l'exemple utilise des restrictions numériques. Dans ce cas, le point de données est associé à un prix de 20, à une longueur de 0,3 et à une largeur de 0,5. Au moment de la requête, vous pouvez utiliser ces restrictions numériques pour filtrer les résultats afin de limiter les résultats de la requête en fonction des valeurs de prix, de longueur et de largeur. Par exemple, ce point de données apparaîtra dans une requête filtrant les critères de prix > 25, de longueur < 1 et de largeur < 1.

Pour en savoir plus sur le filtrage, consultez la page Vector Search pour l'indexation.

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${ENDPOINT}/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints: [
  {
    datapoint_id: "'${DATAPOINT_ID_1}'",
    feature_vector: [...],
    restricts: { namespace: "color", allow_list: ["red"], deny_list: ["blue"]},
    numeric_restricts: [{namespace: "price", value_int: 20}, {namespace: "length", value_float: 0.3}, {namespace: "width", value_double: 0.5}]
  }
]}'

Opération upsert avec regroupement

Le tag de regroupement limite les résultats similaires en améliorant la diversité des résultats. Le regroupement est une contrainte sur une liste de voisins, produite par une recherche des voisins les plus proches qui nécessite qu'un certain nombre de valeurs, au maximum, parmi un groupe de résultats, renvoient la même valeur de crowding_attribute. Par exemple, supposons que vous reveniez sur votre site d'achat en ligne pour acheter des chaussures. Vous souhaitez voir une grande variété de couleurs dans les résultats, mais peut-être dans un style unique, comme des chaussures de football. Vous pouvez demander qu'un maximum de trois paires de chaussures de la même couleur soient renvoyées en définissant per_crowding_attribute_num_neighbors = 3 dans votre requête, en supposant que vous définissiez crowding_Attribute sur la couleur des chaussures lors de l'insertion du point de données.

Ce champ représente le nombre maximal de correspondances autorisées avec le même tag de regroupement.

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${ENDPOINT}/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints: [
  {
    datapoint_id: "'${DATAPOINT_ID_1}'",
    feature_vector: [...],
    restricts: { namespace: "type", allow_list: ["cleats"]}
    crowding_tag: { crowding_attribute: "red-shoe"},
  }
]}'

Étapes suivantes