Index de collections

Pour préparer votre application à la production en termes d'échelle et de performances, vous devez créer des index de collection. Sans index, les recherches ANN sont lentes, car elles effectuent une analyse par force brute. La création d'un index permet d'effectuer des recherches très rapidement dans les champs vectoriels indexés.

Choisir une métrique de distance

Il est essentiel de choisir la bonne métrique de distance pour votre index afin d'obtenir des résultats de recherche de similarité précis et pertinents. Le choix optimal dépend principalement des caractéristiques de vos embeddings vectoriels et de la nature de vos données. La règle la plus importante est d'utiliser la métrique de distance sur laquelle votre modèle d'embedding a été entraîné. Les modèles d'embedding sont optimisés pour produire des représentations vectorielles dans lesquelles la similarité est mieux capturée par un calcul de distance spécifique. L'utilisation d'une autre métrique peut entraîner des résultats de recherche non optimaux ou incorrects.

Consultez la documentation de votre modèle d'embedding : c'est le moyen le plus fiable de déterminer la métrique de distance prévue.
Tenez compte de votre cas d'utilisation : pour trouver du texte ou des images sémantiquement similaires, la similarité cosinus est souvent le meilleur choix. Si la "force" ou l'"intensité" représentées par l'amplitude du vecteur sont importantes, envisagez d'utiliser la distance L2.
Analysez vos vecteurs : déterminez s'ils sont normalisés. Si c'est le cas, vous pouvez utiliser la similarité cosinus ou le produit scalaire et vous attendre à un classement similaire.

En examinant attentivement ces facteurs, vous pouvez sélectionner la métrique de distance la plus appropriée pour votre index, ce qui vous permettra d'obtenir des résultats de recherche par similarité plus précis et plus pertinents.

Créer un index ANN

Vous pouvez créer un index ANN sur un champ d'intégration spécifique. Par défaut, tous les champs de chaîne, numériques et booléens des objets de données sont transférés à l'index pour permettre le filtrage intégré.

Pour optimiser les coûts de calcul, vous pouvez spécifier exactement quels champs doivent être filtrables (filter_fields) et lesquels doivent simplement être stockés en tant que charge utile uniquement (store_fields).

L'exemple suivant montre comment créer un index, INDEX_ID, dans une collection avec l'ID COLLECTION_ID.

REST

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

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

Méthode HTTP et URL :

POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes?indexId=INDEX_ID

Corps JSON de la requête :

{
    "index_field": "plot_embedding",
    "filter_fields": [
      "year",
      "genre"
    ],
    "store_fields": [
      "title"
    ]
}

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

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que 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.

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://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes?indexId=INDEX_ID"

PowerShell (Windows)

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://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes?indexId=INDEX_ID" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770302393524-64a14a54fa197-0dea326c-5a90efda",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1beta.OperationMetadata",
    "createTime": "2026-02-05T14:39:53.558308609Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1beta"
  },
  "done": false
}

gcloud

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

INDEX_ID : ID de l'index.
COLLECTION_ID : ID de la collection.
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 beta vector-search indexes create INDEX_ID \
  --collection=COLLECTION_ID \
  --index-field=plot_embedding \
  --filter-fields=year,genre \
  --store-fields=title \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search indexes create INDEX_ID `
  --collection=COLLECTION_ID `
  --index-field=plot_embedding `
  --filter-fields=year,genre `
  --store-fields=title `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search indexes create INDEX_ID ^
  --collection=COLLECTION_ID ^
  --index-field=plot_embedding ^
  --filter-fields=year,genre ^
  --store-fields=title ^
  --location=LOCATION ^
  --project=PROJECT_ID

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

Created index [INDEX_ID].

Python

from google.cloud import vectorsearch_v1beta

# Create a client
client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request argument(s)
index = vectorsearch_v1beta.Index(
    index_field="plot_embedding",
    filter_fields=["year", "genre"],
    store_fields=["title"],
)
request = vectorsearch_v1beta.CreateIndexRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    index_id="INDEX_ID",
    index=index,
)

# Make the request
operation = client.create_index(request=request)

# Wait for the result (note this may take up to several minutes)
operation.result()

Dans l'exemple, la requête indique que year et genre sont filtrables (transmis en tant que champs de filtre à l'index), et que le champ de charge utile title n'est pas filtrable.

Obtenir un index

L'exemple suivant montre comment obtenir un index existant, INDEX_ID, stocké dans une collection avec l'ID COLLECTION_ID.

REST

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

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

Méthode HTTP et URL :

GET https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID

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

curl (Linux, macOS ou Cloud Shell)

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID"

PowerShell (Windows)

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
  "createTime": "2026-02-05T14:39:53.550302019Z",
  "updateTime": "2026-02-05T14:39:53.550302019Z",
  "distanceMetric": "DOT_PRODUCT",
  "indexField": "plot_embedding",
  "filterFields": [
    "year",
    "genre"
  ],
  "storeFields": [
    "title"
  ]
}

gcloud

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

INDEX_ID : ID de l'index.
COLLECTION_ID : ID de la collection.
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 beta vector-search indexes describe INDEX_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search indexes describe INDEX_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search indexes describe INDEX_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

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

createTime: '2026-02-05T14:39:53.550302019Z'
distanceMetric: DOT_PRODUCT
filterFields:
- year
- genre
indexField: plot_embedding
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID
storeFields:
- title
updateTime: '2026-02-05T14:39:53.550302019Z'

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.GetIndexRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
)

# Make the request
response = vector_search_service_client.get_index(request=request)

# Handle the response
print(response)

Lister les index

L'exemple suivant montre comment lister tous les index d'une collection avec l'ID COLLECTION_ID.

REST

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

COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Vertex AI.
PROJECT_ID : ID de votre projet Google Cloud .

Méthode HTTP et URL :

GET https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes

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

curl (Linux, macOS ou Cloud Shell)

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes"

PowerShell (Windows)

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes" | Select-Object -Expand Content

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

{
  "indexes": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
      "createTime": "2026-02-05T14:39:53.550302019Z",
      "updateTime": "2026-02-05T14:39:53.550302019Z",
      "distanceMetric": "DOT_PRODUCT",
      "indexField": "plot_embedding",
      "filterFields": [
        "year",
        "genre"
      ],
      "storeFields": [
        "title"
      ]
    }
  ]
}

gcloud

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

COLLECTION_ID : ID de la collection.
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 beta vector-search indexes list \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search indexes list `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search indexes list ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

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

---
createTime: '2026-02-05T14:39:53.550302019Z'
distanceMetric: DOT_PRODUCT
filterFields:
- year
- genre
indexField: plot_embedding
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID
storeFields:
- title
updateTime: '2026-02-05T14:39:53.550302019Z'

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.ListIndexesRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
)

# Make the request
page_result = vector_search_service_client.list_indexes(request=request)

# Handle the response
for response in page_result:
    print(response)

Supprimer un index

L'exemple suivant montre comment supprimer un index existant, INDEX_ID, d'une collection dont l'ID est COLLECTION_ID.

REST

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

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

Méthode HTTP et URL :

DELETE https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID

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

curl (Linux, macOS ou Cloud Shell)

Exécutez la commande suivante :

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID"

PowerShell (Windows)

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770303323075-64a14dcb7734e-eb6a75d5-6798cef3",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1beta.OperationMetadata",
    "createTime": "2026-02-05T14:55:23.086771813Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1beta"
  },
  "done": false
}

gcloud

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

INDEX_ID : ID de l'index.
COLLECTION_ID : ID de la collection.
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 beta vector-search indexes delete INDEX_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search indexes delete INDEX_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search indexes delete INDEX_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

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

Deleted index [INDEX_ID].

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.DeleteIndexRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
)

# Make the request
operation = vector_search_service_client.delete_index(request=request)

# Wait for the result (note this may take up to several minutes)
operation.result()

Étape suivante

Découvrez comment interroger des objets de données.
Découvrez comment rechercher des objets de données à l'aide de la recherche sémantique ou hybride.

Index de collections Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Choisir une métrique de distance

Créer un index ANN

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Obtenir un index

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Lister les index

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Supprimer un index

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Étape suivante

Index de collections