Gérer les index

Les sections suivantes vous expliquent comment configurer, créer, lister et supprimer des index.

Présentation des index

Un index désigne un ou plusieurs fichiers comportant des vecteurs d'embedding. Ces vecteurs sont constitués de grandes quantités de données que vous souhaitez déployer et interroger avec Vector Search. Vector Search vous permet de créer deux types d'index, en fonction de la manière dont vous prévoyez de les mettre à jour avec vos données. Vous pouvez créer un index conçu pour les mises à jour groupées ou les mises à jour par flux continu.

Un index par lot vous permet de mettre à jour votre index dans un lot avec des données stockées sur une période définie, comme des systèmes traités chaque semaine ou chaque mois. Un index par flux continu consiste à mettre à jour les données d'index à mesure que de nouvelles données sont ajoutées à votre datastore, par exemple si vous possédez une librairie et que vous souhaitez afficher le nouvel inventaire en ligne dès que possible. Le type que vous choisissez est important, car la configuration et les exigences sont différentes.

Configurer les paramètres d'index

Avant de créer un index, vous devez configurer ses paramètres.

Par exemple, créez un fichier nommé index_metadata.json :

{
  "contentsDeltaUri": "gs://BUCKET_NAME/path",
  "config": {
    "dimensions": 100,
    "approximateNeighborsCount": 150,
    "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
    "shardSize": "SHARD_SIZE_MEDIUM",
    "algorithm_config": {
      "treeAhConfig": {
        "leafNodeEmbeddingCount": 5000,
        "fractionLeafNodesToSearch": 0.03
      }
    }
  }
}

Vous trouverez la définition de chacun de ces champs sur la page Paramètres de configuration des index.

Créer un index

Taille de l'index

Les données d'index sont divisées en parties égales à traiter, appelées segments. Lorsque vous créez un index, vous devez spécifier la taille des segments à utiliser. Les tailles acceptées sont les suivantes :

  • SHARD_SIZE_SMALL : 2 Gio par segment.
  • SHARD_SIZE_MEDIUM : 20 Gio par segment.
  • SHARD_SIZE_LARGE : 50 Gio par segment.

Les types de machines que vous pouvez utiliser pour déployer votre index (sur des points de terminaison publics ou des points de terminaison VPC) dépendent de la taille des segments de l'index. Le tableau suivant indique les tailles de segment acceptées par chaque type de machine :

Type de machine SHARD_SIZE_SMALL SHARD_SIZE_MEDIUM SHARD_SIZE_LARGE
n1-standard-16
n1-standard-32
e2-standard-2 (par défaut)
e2-standard-16 (par défaut)
e2-highmem-16 (par défaut)
n2d-standard-32

Pour savoir comment la taille des segments et le type de machine affectent la tarification, consultez la page des tarifs de Vertex AI. Pour savoir comment la taille des segments affecte les performances, consultez Paramètres de configuration ayant un impact sur les performances.

Créer un index pour la mise à jour groupée

Suivez les instructions ci-dessous pour créer et déployer votre index. Si vous n'avez pas encore préparé vos embeddings, vous pouvez passer à l'étape Créer un index par lots vide. Avec cette option, aucune donnée d'embedding n'est requise au moment de la création de l'index.

Pour créer un index :

gcloud

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_NAME : nom à afficher de l'index.
  • LOCATION : région dans laquelle vous utilisez Vertex AI.
  • PROJECT_ID : ID de votre projet Google Cloud .

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud ai indexes create \
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
    --display-name=INDEX_NAME \
    --region=LOCATION \
    --project=PROJECT_ID

Windows (PowerShell)

gcloud ai indexes create `
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE `
    --display-name=INDEX_NAME `
    --region=LOCATION `
    --project=PROJECT_ID

Windows (cmd.exe)

gcloud ai indexes create ^
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^
    --display-name=INDEX_NAME ^
    --region=LOCATION ^
    --project=PROJECT_ID

Vous devriez obtenir un résultat semblable à celui-ci :

You can poll for the status of the operation for the response
to include "done": true. Use the following example to poll the status.

  $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1

Consultez gcloud ai operations pour en savoir plus sur la commande describe.

REST

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

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

Méthode HTTP et URL : 

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

Corps JSON de la requête :

{
  "display_name": "INDEX_NAME",
  "metadata": {
    "contentsDeltaUri": "INPUT_DIR",
    "config": {
      "dimensions": 100,
      "approximateNeighborsCount": 150,
      "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
      "algorithm_config": {
        "treeAhConfig": {
          "leafNodeEmbeddingCount": 500,
          "leafNodesToSearchPercent": 7
        }
      }
    }
  }
}

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.CreateIndexOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-08T01:21:10.147035Z",
      "updateTime": "2022-01-08T01:21:10.147035Z"
    }
  }
}

Terraform

L'exemple suivant utilise la ressource Terraform google_vertex_ai_index afin de créer un index pour les mises à jour groupées.

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez Commandes Terraform de base.

# Cloud Storage bucket name must be unique
resource "random_id" "bucket_name_suffix" {
  byte_length = 8
}

# Create a Cloud Storage bucket
resource "google_storage_bucket" "bucket" {
  name                        = "vertex-ai-index-bucket-${random_id.bucket_name_suffix.hex}"
  location                    = "us-central1"
  uniform_bucket_level_access = true
}

# Create index content
resource "google_storage_bucket_object" "data" {
  name    = "contents/data.json"
  bucket  = google_storage_bucket.bucket.name
  content = <<EOF
{"id": "42", "embedding": [0.5, 1.0], "restricts": [{"namespace": "class", "allow": ["cat", "pet"]},{"namespace": "category", "allow": ["feline"]}]}
{"id": "43", "embedding": [0.6, 1.0], "restricts": [{"namespace": "class", "allow": ["dog", "pet"]},{"namespace": "category", "allow": ["canine"]}]}
EOF
}

resource "google_vertex_ai_index" "default" {
  region       = "us-central1"
  display_name = "sample-index-batch-update"
  description  = "A sample index for batch update"
  labels = {
    foo = "bar"
  }

  metadata {
    contents_delta_uri = "gs://${google_storage_bucket.bucket.name}/contents"
    config {
      dimensions                  = 2
      approximate_neighbors_count = 150
      distance_measure_type       = "DOT_PRODUCT_DISTANCE"
      algorithm_config {
        tree_ah_config {
          leaf_node_embedding_count    = 500
          leaf_nodes_to_search_percent = 7
        }
      }
    }
  }
  index_update_method = "BATCH_UPDATE"

  timeouts {
    create = "2h"
    update = "1h"
  }
}

Python

Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'API Python. 

def vector_search_create_index(
    project: str, location: str, display_name: str, gcs_uri: Optional[str] = None
) -> aiplatform.MatchingEngineIndex:
    """Create a vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        display_name (str): Required. The index display name
        gcs_uri (str): Optional. The Google Cloud Storage uri for index content

    Returns:
        The created MatchingEngineIndex.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create Index
    index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
        display_name=display_name,
        contents_delta_uri=gcs_uri,
        description="Matching Engine Index",
        dimensions=100,
        approximate_neighbors_count=150,
        leaf_node_embedding_count=500,
        leaf_nodes_to_search_percent=7,
        index_update_method="BATCH_UPDATE",  # Options: STREAM_UPDATE, BATCH_UPDATE
        distance_measure_type=aiplatform.matching_engine.matching_engine_index_config.DistanceMeasureType.DOT_PRODUCT_DISTANCE,
    )

    return index

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java décrites dans le guide de démarrage rapide de Vertex AI sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Java.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 


import com.google.cloud.aiplatform.v1.CreateIndexRequest;
import com.google.cloud.aiplatform.v1.Index;
import com.google.cloud.aiplatform.v1.Index.IndexUpdateMethod;
import com.google.cloud.aiplatform.v1.IndexServiceClient;
import com.google.cloud.aiplatform.v1.IndexServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.util.concurrent.TimeUnit;

public class CreateIndexSample {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String location = "YOUR_LOCATION";
    String displayName = "YOUR_INDEX_DISPLAY_NAME";
    String contentsDeltaUri = "gs://YOUR_BUCKET/";
    String metadataJson =
        String.format(
            "{\n"
                + "  \"contentsDeltaUri\": \"%s\",\n"
                + "  \"config\": {\n"
                + "    \"dimensions\": 100,\n"
                + "        \"approximateNeighborsCount\": 150,\n"
                + "        \"distanceMeasureType\": \"DOT_PRODUCT_DISTANCE\",\n"
                + "        \"shardSize\": \"SHARD_SIZE_MEDIUM\",\n"
                + "        \"algorithm_config\": {\n"
                + "      \"treeAhConfig\": {\n"
                + "        \"leafNodeEmbeddingCount\": 5000,\n"
                + "            \"fractionLeafNodesToSearch\": 0.03\n"
                + "      }\n"
                + "    }\n"
                + "  }\n"
                + "}",
            contentsDeltaUri);

    createIndexSample(project, location, displayName, metadataJson);
  }

  public static Index createIndexSample(
      String project, String location, String displayName, String metadataJson) throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IndexServiceClient indexServiceClient =
        IndexServiceClient.create(
            IndexServiceSettings.newBuilder()
                .setEndpoint(location + "-aiplatform.googleapis.com:443")
                .build())) {
      Value.Builder metadataBuilder = Value.newBuilder();
      JsonFormat.parser().merge(metadataJson, metadataBuilder);

      CreateIndexRequest request =
          CreateIndexRequest.newBuilder()
              .setParent(LocationName.of(project, location).toString())
              .setIndex(
                  Index.newBuilder()
                      .setDisplayName(displayName)
                      .setMetadata(metadataBuilder)
                      .setIndexUpdateMethod(IndexUpdateMethod.BATCH_UPDATE))
              .build();

      return indexServiceClient.createIndexAsync(request).get(5, TimeUnit.MINUTES);
    }
  }
}

Console

Suivez ces instructions pour créer un index pour les mises à jour groupées.

  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. Cliquez sur Créer un index pour ouvrir le volet Index. Le volet Créer un index s'affiche.
  3. Dans le champ Nom à afficher, indiquez un nom permettant d'identifier de manière unique votre index.
  4. Dans le champ Description, indiquez une description de l'index.
  5. Dans le champ Région, sélectionnez une région dans le menu déroulant.
  6. Dans le champ Cloud Storage, recherchez et sélectionnez le dossier Cloud Storage dans lequel vos données vectorielles sont stockées.
  7. Dans le menu déroulant Type d'algorithme, sélectionnez le type d'algorithme utilisé par Vector Search pour effectuer une recherche efficace. Si vous sélectionnez l'algorithme "treeAh", saisissez le nombre approximatif de voisins.
  8. Dans le champ Dimensions, saisissez le nombre de dimensions de vos vecteurs d'entrée.
  9. Dans le champ Méthode de mise à jour, sélectionnez Lot.
  10. Dans le champ Taille des segments, sélectionnez la taille des segments souhaitée dans le menu déroulant.
  11. Cliquez sur Créer. Votre nouvel index apparaît dans votre liste d'index une fois qu'il est prêt. Remarque : sa création peut prendre jusqu'à une heure.

Créer un index par lots vide

Pour créer et déployer votre index immédiatement, vous pouvez créer un index par lots vide. Avec cette option, aucune donnée d'embedding n'est requise au moment de la création de l'index.

Pour créer un index vide, la requête est presque identique à la création d'un index pour les mises à jour groupées. La différence est que vous supprimez le champ contentsDeltaUri, car vous n'associez pas d'emplacement de données. Voici un exemple d'index par lots vide :

Exemple de requête d'index vide

{
  "display_name": INDEX_NAME,
  "indexUpdateMethod": "BATCH_UPDATE",
  "metadata": {
    "config": {
      "dimensions": 100,
      "approximateNeighborsCount": 150,
      "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
      "algorithm_config": {
        "treeAhConfig": {
          "leafNodeEmbeddingCount": 500,
          "fractionLeafNodesToSearch": 0.07
        }
      }
    }
  }
}

Créer un index pour les mises à jour par flux

Suivez ces instructions pour créer et déployer votre index par flux. Si vos embeddings ne sont pas encore prêts, passez à Créer un index vide pour les mises à jour par flux. Avec cette option, aucune donnée d'embedding n'est requise au moment de la création de l'index.

REST

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

  • INDEX_NAME : nom à afficher de l'index.
  • DESCRIPTION : description de l'index.
  • INPUT_DIR : chemin d'accès au répertoire Cloud Storage du contenu de l'index.
  • DIMENSIONS : nombre de dimensions du vecteur d'embedding.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • PROJECT_NUMBER : numéro de projet généré automatiquement pour votre projet.
  • LOCATION : région dans laquelle vous utilisez Vertex AI.

Méthode HTTP et URL : 

POST https://ENDPOINT-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes

Corps JSON de la requête :

{
  displayName: "INDEX_NAME",
  description: "DESCRIPTION",
  metadata: {
     contentsDeltaUri: "INPUT_DIR",
     config: {
        dimensions: "DIMENSIONS",
        approximateNeighborsCount: 150,
        distanceMeasureType: "DOT_PRODUCT_DISTANCE",
        algorithmConfig: {treeAhConfig: {leafNodeEmbeddingCount: 10000, leafNodesToSearchPercent: 2}}
     },
  },
  indexUpdateMethod: "STREAM_UPDATE"
}

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/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.ui.CreateIndexOperationMetadata",
    "genericMetadata": {
      "createTime": "2023-12-05T23:17:45.416117Z",
      "updateTime": "2023-12-05T23:17:45.416117Z",
      "state": "RUNNING",
      "worksOn": [
        "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID"
      ]
    }
  }
}

Terraform

L'exemple suivant utilise la ressource Terraform google_vertex_ai_index afin de créer un index pour les mises à jour par flux.

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez Commandes Terraform de base.

# Cloud Storage bucket name must be unique
resource "random_id" "default" {
  byte_length = 8
}

# Create a Cloud Storage bucket
resource "google_storage_bucket" "bucket" {
  name                        = "vertex-ai-index-bucket-${random_id.default.hex}"
  location                    = "us-central1"
  uniform_bucket_level_access = true
}

# Create index content
resource "google_storage_bucket_object" "data" {
  name    = "contents/data.json"
  bucket  = google_storage_bucket.bucket.name
  content = <<EOF
{"id": "42", "embedding": [0.5, 1.0], "restricts": [{"namespace": "class", "allow": ["cat", "pet"]},{"namespace": "category", "allow": ["feline"]}]}
{"id": "43", "embedding": [0.6, 1.0], "restricts": [{"namespace": "class", "allow": ["dog", "pet"]},{"namespace": "category", "allow": ["canine"]}]}
EOF
}

resource "google_vertex_ai_index" "streaming_index" {
  region       = "us-central1"
  display_name = "sample-index-streaming-update"
  description  = "A sample index for streaming update"
  labels = {
    foo = "bar"
  }

  metadata {
    contents_delta_uri = "gs://${google_storage_bucket.bucket.name}/contents"
    config {
      dimensions                  = 2
      approximate_neighbors_count = 150
      distance_measure_type       = "DOT_PRODUCT_DISTANCE"
      algorithm_config {
        tree_ah_config {
          leaf_node_embedding_count    = 500
          leaf_nodes_to_search_percent = 7
        }
      }
    }
  }
  index_update_method = "STREAM_UPDATE"

  timeouts {
    create = "2h"
    update = "1h"
  }
}

Python

Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'API Python. 

def vector_search_create_streaming_index(
    project: str, location: str, display_name: str, gcs_uri: Optional[str] = None
) -> aiplatform.MatchingEngineIndex:
    """Create a vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        display_name (str): Required. The index display name
        gcs_uri (str): Optional. The Google Cloud Storage uri for index content

    Returns:
        The created MatchingEngineIndex.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create Index
    index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
        display_name=display_name,
        contents_delta_uri=gcs_uri,
        description="Matching Engine Index",
        dimensions=100,
        approximate_neighbors_count=150,
        leaf_node_embedding_count=500,
        leaf_nodes_to_search_percent=7,
        index_update_method="STREAM_UPDATE",  # Options: STREAM_UPDATE, BATCH_UPDATE
        distance_measure_type=aiplatform.matching_engine.matching_engine_index_config.DistanceMeasureType.DOT_PRODUCT_DISTANCE,
    )

    return index

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java décrites dans le guide de démarrage rapide de Vertex AI sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Java.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 


import com.google.cloud.aiplatform.v1.CreateIndexRequest;
import com.google.cloud.aiplatform.v1.Index;
import com.google.cloud.aiplatform.v1.Index.IndexUpdateMethod;
import com.google.cloud.aiplatform.v1.IndexServiceClient;
import com.google.cloud.aiplatform.v1.IndexServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.util.concurrent.TimeUnit;

public class CreateStreamingIndexSample {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String location = "YOUR_LOCATION";
    String displayName = "YOUR_INDEX_DISPLAY_NAME";
    String contentsDeltaUri = "gs://YOUR_BUCKET/";
    String metadataJson =
        String.format(
            "{\n"
                + "  \"contentsDeltaUri\": \"%s\",\n"
                + "  \"config\": {\n"
                + "    \"dimensions\": 100,\n"
                + "        \"approximateNeighborsCount\": 150,\n"
                + "        \"distanceMeasureType\": \"DOT_PRODUCT_DISTANCE\",\n"
                + "        \"shardSize\": \"SHARD_SIZE_MEDIUM\",\n"
                + "        \"algorithm_config\": {\n"
                + "      \"treeAhConfig\": {\n"
                + "        \"leafNodeEmbeddingCount\": 5000,\n"
                + "            \"fractionLeafNodesToSearch\": 0.03\n"
                + "      }\n"
                + "    }\n"
                + "  }\n"
                + "}",
            contentsDeltaUri);

    createStreamingIndexSample(project, location, displayName, metadataJson);
  }

  public static Index createStreamingIndexSample(
      String project, String location, String displayName, String metadataJson) throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IndexServiceClient indexServiceClient =
        IndexServiceClient.create(
            IndexServiceSettings.newBuilder()
                .setEndpoint(location + "-aiplatform.googleapis.com:443")
                .build())) {
      Value.Builder metadataBuilder = Value.newBuilder();
      JsonFormat.parser().merge(metadataJson, metadataBuilder);

      CreateIndexRequest request =
          CreateIndexRequest.newBuilder()
              .setParent(LocationName.of(project, location).toString())
              .setIndex(
                  Index.newBuilder()
                      .setDisplayName(displayName)
                      .setMetadata(metadataBuilder)
                      .setIndexUpdateMethod(IndexUpdateMethod.STREAM_UPDATE))
              .build();

      return indexServiceClient.createIndexAsync(request).get(5, TimeUnit.MINUTES);
    }
  }
}

Console

Suivez ces instructions pour créer un index pour les mises à jour par flux dans la console Google Cloud .

Pour créer un index disponible pour les mises à jour par flux, vous devez suivre des étapes semblables à celles permettant de configurer un index de mise à jour groupée, sauf que vous devez définir indexUpdateMethod sur STREAM_UPDATE.

  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. Cliquez sur Créer un index pour ouvrir le volet Index. Le volet Créer un index s'affiche.
  3. Dans le champ Nom à afficher, indiquez un nom permettant d'identifier de manière unique votre index.
  4. Dans le champ Description, indiquez une description de l'index.
  5. Dans le champ Région, sélectionnez une région dans le menu déroulant.
  6. Dans le champ Cloud Storage, recherchez et sélectionnez le dossier Cloud Storage dans lequel vos données vectorielles sont stockées.
  7. Dans le menu déroulant Type d'algorithme, sélectionnez le type d'algorithme que Vector Search utilisera pour effectuer votre recherche. Si vous sélectionnez l'algorithme "treeAh", saisissez le nombre approximatif de voisins.
  8. Dans le champ Dimensions, saisissez le nombre de dimensions de vos vecteurs d'entrée.
  9. Dans le champ Méthode de mise à jour, sélectionnez Flux.
  10. Dans le champ Taille des segments, sélectionnez la taille des segments souhaitée dans le menu déroulant.
  11. Cliquez sur Créer. Votre nouvel index apparaît dans votre liste d'index une fois qu'il est prêt. Remarque : sa création peut prendre jusqu'à une heure.

Créer un index vide pour les mises à jour par flux

Pour créer et déployer votre index immédiatement, vous pouvez créer un index vide pour les mises à jour par flux. Avec cette option, aucune donnée d'embedding n'est requise au moment de la création de l'index.

Pour créer un index vide, la requête est presque identique à la création d'un index pour les mises à jour par flux. La différence est que vous supprimez le champ contentsDeltaUri, car vous n'associez pas d'emplacement de données. Voici un exemple d'index par flux :

Exemple de requête d'index vide

{
  "display_name": INDEX_NAME,
  "indexUpdateMethod": "STREAM_UPDATE",
  "metadata": {
    "config": {
      "dimensions": 100,
      "approximateNeighborsCount": 150,
      "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
      "algorithm_config": {
        "treeAhConfig": {
          "leafNodeEmbeddingCount": 500,
          "leafNodesToSearchPercent": 7
        }
      }
    }
  }
}

Lister les index

gcloud

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

  • INDEX_NAME : nom à afficher de l'index.
  • LOCATION : région dans laquelle vous utilisez Vertex AI.
  • PROJECT_ID : ID de votre projet Google Cloud .

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud ai indexes list \
    --region=LOCATION \
    --project=PROJECT_ID

Windows (PowerShell)

gcloud ai indexes list `
    --region=LOCATION `
    --project=PROJECT_ID

Windows (cmd.exe)

gcloud ai indexes list ^
    --region=LOCATION ^
    --project=PROJECT_ID

Vous devriez obtenir un résultat semblable à celui-ci :

You can poll for the status of the operation for the response
to include "done": true. Use the following example to poll the status.

  $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1

Consultez gcloud ai operations pour en savoir plus sur la commande describe.

REST

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

  • INDEX_NAME : nom à afficher de l'index.
  • LOCATION : région dans laquelle vous utilisez Vertex AI.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • PROJECT_NUMBER : numéro de projet généré automatiquement pour votre projet.

Méthode HTTP et URL : 

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

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

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

{
 "indexes": [
   {
     "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID",
     "displayName": "INDEX_NAME",
     "metadataSchemaUri": "gs://google-cloud-aiplatform/schema/matchingengine/metadata/nearest_neighbor_search_1.0.0.yaml",
     "metadata": {
       "config": {
         "dimensions": 100,
         "approximateNeighborsCount": 150,
         "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
         "featureNormType": "NONE",
         "algorithmConfig": {
           "treeAhConfig": {
             "maxLeavesToSearch": 50,
             "leafNodeCount": 10000
           }
         }
       }
     },
     "etag": "AMEw9yNU8YX5IvwuINeBkVv3yNa7VGKk11GBQ8GkfRoVvO7LgRUeOo0qobYWuU9DiEc=",
     "createTime": "2020-11-08T21:56:30.558449Z",
     "updateTime": "2020-11-08T22:39:25.048623Z"
   }
 ]
}

Python

Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'API Python. 

def vector_search_list_index(
    project: str, location: str
) -> List[aiplatform.MatchingEngineIndex]:
    """List vector search indexes.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name

    Returns:
        List of aiplatform.MatchingEngineIndex
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # List Indexes
    return aiplatform.MatchingEngineIndex.list()

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java décrites dans le guide de démarrage rapide de Vertex AI sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Java.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 


import com.google.cloud.aiplatform.v1.Index;
import com.google.cloud.aiplatform.v1.IndexServiceClient;
import com.google.cloud.aiplatform.v1.IndexServiceClient.ListIndexesPagedResponse;
import com.google.cloud.aiplatform.v1.IndexServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;

public class ListIndexesSample {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String location = "YOUR_LOCATION";

    for (Index index : listIndexesSample(project, location).iterateAll()) {
      System.out.println(index.getName());
    }
  }

  public static ListIndexesPagedResponse listIndexesSample(String project, String location)
      throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IndexServiceClient indexServiceClient =
        IndexServiceClient.create(
            IndexServiceSettings.newBuilder()
                .setEndpoint(location + "-aiplatform.googleapis.com:443")
                .build())) {
      String parent = LocationName.of(project, location).toString();
      return indexServiceClient.listIndexes(parent);
    }
  }
}

Console

Suivez ces instructions pour afficher la liste de vos index.

  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. La liste de vos index actifs s'affiche.

Régler des index

Pour régler des index, vous devez définir les paramètres de configuration qui ont une incidence sur les performances des index déployés, en particulier le rappel et la latence. Ces paramètres sont définis lors de la création de l'index. Vous pouvez utiliser des index de force brute pour mesurer le rappel.

Paramètres de configuration ayant un impact sur les performances

Les paramètres de configuration suivants peuvent être définis au moment de la création de l'index et peuvent affecter le rappel, la latence, la disponibilité et les coûts lors de l'utilisation de Vector Search. Ces conseils s'appliquent à la plupart des cas. Toutefois, testez toujours vos configurations pour vous assurer qu'elles fonctionnent bien pour votre cas d'utilisation.

Pour les définitions de paramètres, consultez Paramètres de configuration d'index.

Paramètre À propos Impact sur les performances
shardSize

Contrôle la quantité de données sur chaque machine.

Lorsque vous choisissez une taille de segments, estimez la taille future de votre ensemble de données. Si la taille de votre ensemble de données comporte une limite supérieure, choisissez la taille de segments appropriée pour l'adapter. S'il n'y a pas de limite supérieure ou si votre cas d'utilisation est extrêmement sensible à la variabilité de la latence, il est recommandé de choisir une grande taille de segments.

Si vous configurez un plus grand nombre de segments plus petits, le nombre de résultats candidats sera plus élevé lors de la recherche. Un plus grand nombre de segments peut affecter les performances des manières suivantes :

  • Rappel : augmentation
  • Latence : augmentation potentielle, plus de variabilité
  • Disponibilité : les interruptions de segments affectent un faible pourcentage de données
  • Coût : peut augmenter si la même machine est utilisée avec davantage de segments

Si vous configurez un plus petit nombre de segments plus volumineux, moins de résultats candidats seront traités lors de la recherche. Un nombre réduit de segments peut affecter les performances des manières suivantes :

  • Rappel : diminution
  • Latence : réduite, moins de variabilité
  • Disponibilité : les interruptions de segments affectent un pourcentage plus élevé de données
  • Coût : peut diminuer si la même machine est utilisée avec moins de segments
distanceMeasureType

Détermine l'algorithme utilisé pour le calcul de la distance entre les points de données et le vecteur de requête.

Les paramètres distanceMeasureType suivants peuvent vous aider à réduire la latence des requêtes :

  • DOT_PRODUCT_DISTANCE est le plus optimisé pour réduire la latence.
  • Il est recommandé d'utiliser DOT_PRODUCT_DISTANCE conjointement avec la définition de FeatureNormType sur UNIT_L2_NORM pour la similarité cosinus.
leafNodeEmbeddingCount

Nombre d'embeddings pour chaque nœud feuille. Par défaut, ce nombre est défini sur 1 000.

En règle générale, modifier la valeur de leafNodeEmbeddingCount a moins d'effet que modifier la valeur des autres paramètres.

L'augmentation du nombre d'embeddings pour chaque nœud feuille peut réduire la latence, mais également la qualité de rappel. Cela peut affecter les performances des manières suivantes :

  • Rappel : diminution en raison d'une recherche moins ciblée
  • Latence : réduite, tant que la valeur n'est pas supérieure à 15 000 dans la plupart des cas d'utilisation
  • Disponibilité : aucun impact
  • Coût : peut diminuer, car moins d'instances répliquées sont nécessaires pour un même RPS

La réduction du nombre d'embeddings pour chaque nœud feuille peut affecter les performances des manières suivantes :

  • Rappel : peut augmenter, car des feuilles plus ciblées sont collectées
  • Latence : augmentation
  • Disponibilité : aucun impact
  • Coût : peut augmenter, car davantage d'instances répliquées sont nécessaires pour un même RPS

Utiliser un index de force brute pour mesurer le rappel

Pour obtenir les voisins les plus proches, utilisez des index avec l'algorithme de force brute. L'algorithme de force brute offre un rappel de 100 % au détriment de la latence. L'utilisation d'un index de force brute pour mesurer le rappel n'est généralement pas un choix approprié pour la mise en service, mais elle peut être utile pour évaluer le rappel de diverses options d'indexation hors connexion.

Pour créer un index à l'aide de l'algorithme de force brute, spécifiez brute_force_config dans les métadonnées de l'index :

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes \
-d '{
    displayName: "'${DISPLAY_NAME}'",
    description: "'${DESCRIPTION}'",
    metadata: {
       contentsDeltaUri: "'${INPUT_DIR}'",
       config: {
          dimensions: 100,
          approximateNeighborsCount: 150,
          distanceMeasureType: "DOT_PRODUCT_DISTANCE",
          featureNormType: "UNIT_L2_NORM",
          algorithmConfig: {
             bruteForceConfig: {}
          }
       },
    },
}'

Supprimer un index

gcloud

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

  • INDEX_ID : ID de l'index.
  • LOCATION : région dans laquelle vous utilisez Vertex AI.
  • PROJECT_ID : ID de votre projet Google Cloud .

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud ai indexes delete INDEX_ID \
    --region=LOCATION \
    --project=PROJECT_ID

Windows (PowerShell)

gcloud ai indexes delete INDEX_ID `
    --region=LOCATION `
    --project=PROJECT_ID

Windows (cmd.exe)

gcloud ai indexes delete INDEX_ID ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

  • INDEX_ID : ID de l'index.
  • LOCATION : région dans laquelle vous utilisez Vertex AI.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • PROJECT_NUMBER : numéro de projet généré automatiquement pour votre projet.

Méthode HTTP et URL : 

DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID

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.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-08T02:35:56.364956Z",
      "updateTime": "2022-01-08T02:35:56.364956Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Python

Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'API Python. 

def vector_search_delete_index(
    project: str, location: str, index_name: str
) -> None:
    """Delete a vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        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".
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index instance from an existing index
    index = aiplatform.MatchingEngineIndex(index_name=index_name)

    # Delete the index
    index.delete()

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java décrites dans le guide de démarrage rapide de Vertex AI sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Java.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 


import com.google.cloud.aiplatform.v1.IndexName;
import com.google.cloud.aiplatform.v1.IndexServiceClient;
import com.google.cloud.aiplatform.v1.IndexServiceSettings;
import java.util.concurrent.TimeUnit;

public class DeleteIndexSample {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String location = "YOUR_LOCATION";
    String indexId = "YOUR_INDEX_ID";

    deleteIndexSample(project, location, indexId);
  }

  public static void deleteIndexSample(String project, String location, String indexId)
      throws Exception {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IndexServiceClient indexServiceClient =
        IndexServiceClient.create(
            IndexServiceSettings.newBuilder()
                .setEndpoint(location + "-aiplatform.googleapis.com:443")
                .build())) {
      String indexName = IndexName.of(project, location, indexId).toString();
      indexServiceClient.deleteIndexAsync(indexName).get(5, TimeUnit.MINUTES);
    }
  }
}

Console

Suivez les instructions ci-dessous pour supprimer un ou plusieurs index.

  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. La liste de vos index actifs s'affiche.
  3. Pour supprimer un index, accédez au menu d'options situé sur la même ligne que l'index, puis sélectionnez Supprimer.

Étapes suivantes