Utiliser Vector Search 2.0 avec RAG

Cette page vous explique comment le moteur RAG sur Gemini Enterprise Agent Platform utilise Gemini Enterprise Agent Platform Vector Search 2.0, un produit Cloud de Confiance by S3NS qui sert de système complet de stockage et de récupération pour stocker et gérer les représentations vectorielles de vos documents. Gemini Enterprise Agent Platform Vector Search 2.0 est ensuite utilisé pour récupérer les documents pertinents en fonction de leur similarité sémantique avec une requête donnée.

RAG gérera les collections Vector Search 2.0 pour vous, et vous aurez un accès complet aux collections Vector Search 2.0 de votre projet.

Choisir un backend RAG

Lorsque vous utilisez le moteur RAG sur Gemini Enterprise Agent Platform, vous pouvez choisir entre différentes options de stockage backend pour vos corpus RAG. Le tableau suivant récapitule les principales différences :

Choisissez RagManagedVertexVectorSearch pour bénéficier des dernières fonctionnalités, d'une gestion automatisée et d'une transparence sur vos données Vector Search 2.0. Si la compatibilité avec les CMEK est une exigence stricte, envisagez d'utiliser RagManagedDb, en gardant à l'esprit l'absence de visibilité directe sur la base de données backend.

Activer l'API Vector Search

Pour utiliser Gemini Enterprise Agent Platform Vector Search géré par RAG, vous devez d'abord activer l'API Vector Search.

Créer un corpus RAG avec RagManagedVertexVectorSearch

Cet exemple de code montre comment créer un corpus RAG à l'aide de RagManagedVertexVectorSearch.

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

vector_db = rag.RagManagedVertexVectorSearch()
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "vector_db_config": {
        "rag_managed_vertex_vector_search": {}
      }
    }'

Importation de vos données dans RagManagedVertexVectorSearch…

Vous pouvez utiliser l'API ImportRagFiles ou l'API UploadRagFile pour importer vos données dans RagManagedVertexVectorSearch.

Pour importer votre fichier local dans votre corpus RAG, consultez Importer un fichier RAG. Pour importer des données dans votre corpus RAG, consultez l'exemple de code suivant, qui montre comment importer des données depuis Cloud Storage. Pour en savoir plus sur les sources de données compatibles, consultez Sources de données compatibles avec le RAG.

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
CORPUS_ID = YOUR_CORPUS_ID
PATHS = ["gs://my_bucket/my_files_dir"]

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

corpus_name = f"projects/{PROJECT_ID}/locations/{LOCATION}/ragCorpora/{CORPUS_ID}"
# This is a non blocking call.
response = await rag.import_files_async(
    corpus_name=corpus_name,
    paths=PATHS,
)

# Wait for the import to complete.
await response.result()

GCS_URI=GCS_URI

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URI}"\"',
      },
  }
}'

Créer un index pour votre corpus

Le moteur RAG crée une collection Vector Search 2.0 pour chaque corpus, mais il ne crée pas d'index sur cette collection. Tant que vous n'en avez pas créé, chaque récupération est une analyse KNN par force brute.

Une analyse par force brute est plus lente qu'une recherche indexée, et KNN ne s'exécute que sur des collections de 100 000 objets de données maximum. Le moteur RAG stocke un fragment par objet de données. Par conséquent, une fois qu'un corpus dépasse cette limite, la récupération échoue jusqu'à ce qu'un index existe.

N'indexez pas tous les corpus. Un index s'exécute sur sa propre infrastructure de diffusion et est facturé tant qu'il existe, qu'il soit interrogé ou non. Pour déterminer les corpus qui en ont besoin, consultez Déterminer les corpus à indexer.

Une fois qu'un index existe, la récupération l'utilise automatiquement. Le corpus ne change pas et vos données n'ont pas besoin d'être réimportées.

Si vous indexez plusieurs corpus, créez un script pour la boucle : il n'existe pas de chemin de création groupée. Les opérations d'index simultanées sont limitées par des quotas. Créez donc les index en série ou par petits lots. Pour en savoir plus, consultez la page consacrée aux quotas.

Avant de commencer

La création d'un index nécessite l'autorisation vectorsearch.indexes.create sur la collection, et le comptage de ses objets de données nécessite l'autorisation vectorsearch.dataObjects.query. Ces deux autorisations sont incluses dans le rôle Administrateur Vector Search (roles/vectorsearch.admin). Le rôle Rédacteur d'index Vector Search (roles/vectorsearch.indexWriter) n'accorde que la première. L'API Vector Search doit également être activée sur le projet.

Trouver vos ID de corpus

Dans votre projet, chaque corpus possède exactement une collection, nommée vertex-rag-RAG_CORPUS_ID. Répertoriez vos corpus pour obtenir leurs ID.

Remplacez PROJECT_ID par l'ID de votre projet :

PROJECT_ID=PROJECT_ID
LOCATION=us-central1

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora?pageSize=100"

La partie numérique à la fin de chaque name de corpus est l'RAG_CORPUS_ID. Chaque corpus indique également le nom complet de la ressource Collection dans vectorDbConfig.ragManagedVertexVectorSearch.collectionName.

La réponse liste au maximum 100 corpus, et au maximum 25 si vous omettez pageSize. Si la réponse inclut un nextPageToken, transmettez cette valeur en tant que pageToken pour récupérer la page suivante.

Si vous connaissez déjà le RAG_CORPUS_ID que vous souhaitez indexer, récupérez plutôt ce corpus. La réponse contient le même collectionName :

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/RAG_CORPUS_ID"

Choisir les corpus à indexer

Pour chaque corpus, comptez les objets de données de sa collection. Transmettez un filter vide pour compter l'ensemble de la collection :

COLLECTION_ID=vertex-rag-RAG_CORPUS_ID

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://vectorsearch.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/collections/${COLLECTION_ID}/dataObjects:aggregate" \
-d '{"aggregate": "COUNT", "filter": {}}'

Le nombre est renvoyé dans aggregateResults :

{
  "aggregateResults": [
    {
      "count": 95217
    }
  ]
}

Créez un index pour ce corpus lorsque l'une des conditions suivantes est remplie :

• Le nombre est proche de 100 000 ou supérieur. La limite comptabilise les objets de données, et non les fichiers. Un corpus contenant un petit nombre de fichiers volumineux peut donc largement la dépasser.
• La récupération est trop lente pour votre taux de requêtes. Une recherche indexée est plus rapide qu'une analyse par force brute, et l'écart se creuse à mesure que la collection s'agrandit.

Sinon, laissez le corpus non indexé et évitez les coûts de diffusion. Vous pourrez ajouter un index plus tard si elle s'agrandit.

Examiner le schéma de la collection

Le moteur RAG crée chaque collection avec le schéma suivant. Utilisez ces noms lorsque vous spécifiez le champ d'index et les champs de filtre.

Choisir les paramètres d'index

UpdateIndex ne modifie que le nom à afficher, la description, les étiquettes et le nombre d'instances répliquées. Par conséquent, pour modifier l'un des paramètres de cette section, vous devez supprimer l'index et en créer un autre.

Champ d'index : définissez-le sur text_embedding, le seul champ vectoriel du schéma de la collection.

Métrique de distance : définissez-la sur "Cosinus". Le moteur RAG envoie toujours COSINE_DISTANCE sur ses requêtes de récupération, et Vector Search 2.0 rejette une requête de récupération dont la métrique ne correspond pas à l'index. La métrique est définie par défaut sur DOT_PRODUCT lorsque vous l'omettez. Par conséquent, un index créé sans cette métrique interrompt la récupération pour ce corpus. Le moteur RAG signale l'échec en tant que FAILED_PRECONDITION avec le message Failed to process Rag Managed Vertex Vector Search response., qui n'identifie pas la métrique comme cause. L'orthographe diffère selon la surface : le corps REST prend COSINE_DISTANCE et l'option gcloud CLI prend cosine-distance.

Infrastructure : laissez l'index sur l'infrastructure par défaut optimisée pour les performances, car la distance cosinus n'est pas compatible avec l'infrastructure optimisée pour le stockage. Un index s'exécute sur une infrastructure de diffusion dédiée et est facturé tant qu'il existe. Sur v1, min_replica_count et max_replica_count sont tous deux définis par défaut sur 2. Par défaut, l'index est donc diffusé par deux instances répliquées et n'effectue pas d'autoscaling. Pour en savoir plus, consultez Index de collection.

Champs de filtre : définissez filter_fields sur file_id uniquement. Il s'agit du seul champ sur lequel le moteur RAG filtre au moment de la récupération, et il ne le fait que lorsqu'une requête de récupération limite la recherche à des fichiers spécifiques. En particulier, corpus_id contient la même valeur pour chaque objet de données d'une collection donnée. Par conséquent, le filtrage n'offre aucun avantage.

Le filtrage des métadonnées ne nécessite pas non plus de champs de filtre supplémentaires. Lorsqu'une requête de récupération définit ragRetrievalConfig.filter.metadataFilter, le moteur RAG résout d'abord le filtre par rapport aux métadonnées de votre fichier, convertit le résultat en un ensemble d'ID de fichiers RAG correspondants, puis envoie cet ensemble à Vector Search en tant que filtre file_id. L'ajout de rag_metadata à filter_fields augmente la taille de l'index sans modifier la récupération.

Champs de stockage : laissez store_fields non défini. Le moteur RAG demande tous les champs de données à chaque récupération, ce qui n'est jamais éligible à la diffusion intégrée. Par conséquent, les données de fragment sont lues à partir de la base de données de sauvegarde, quel que soit le cas. Les champs listés dans store_fields sont transférés vers l'index et sont pris en compte dans sa taille. Par conséquent, les définir augmente les coûts sans modifier la récupération.

Créer l'index

from google.cloud import vectorsearch_v1

client = vectorsearch_v1.VectorSearchServiceClient()

index = vectorsearch_v1.Index(
    index_field="text_embedding",
    distance_metric=vectorsearch_v1.DistanceMetric.COSINE_DISTANCE,
    filter_fields=["file_id"],
)
request = vectorsearch_v1.CreateIndexRequest(
    parent="projects/PROJECT_ID/locations/us-central1/collections/vertex-rag-RAG_CORPUS_ID",
    index_id="vertex-rag-RAG_CORPUS_ID-index",
    index=index,
)

operation = client.create_index(request=request)

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

PROJECT_ID=PROJECT_ID
RAG_CORPUS_ID=RAG_CORPUS_ID
LOCATION=us-central1
COLLECTION_ID=vertex-rag-${RAG_CORPUS_ID}
INDEX_ID=${COLLECTION_ID}-index

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://vectorsearch.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/collections/${COLLECTION_ID}/indexes?indexId=${INDEX_ID}" \
-d '{
      "index_field": "text_embedding",
      "distance_metric": "COSINE_DISTANCE",
      "filter_fields": ["file_id"]
    }'

gcloud vector-search collections indexes create vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --index-field=text_embedding \
  --distance-metric=cosine-distance \
  --filter-fields=file_id \
  --location=us-central1 \
  --project=PROJECT_ID

Interroger l'état d'avancement

La création d'un index renvoie une opération de longue durée :

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/operation-1770302393524-64a14a54fa197-0dea326c-5a90efda",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.OperationMetadata",
    "createTime": "2026-02-05T14:39:53.558308609Z",
    "target": "projects/PROJECT_ID/locations/us-central1/collections/vertex-rag-RAG_CORPUS_ID/indexes/vertex-rag-RAG_CORPUS_ID-index",
    "verb": "create",
    "apiVersion": "v1"
  },
  "done": false
}

Interrogez l'opération à l'aide du nom de cette réponse :

OPERATION_NAME=OPERATION_NAME

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://vectorsearch.googleapis.com/v1/${OPERATION_NAME}"

Lorsque done est défini sur true, un champ response signifie que l'index a bien été créé, et un champ error indique la raison de l'échec. La création d'un index prend plusieurs minutes, et plus longtemps pour un corpus volumineux.

Pour lister les opérations dans le projet et l'emplacement, exécutez la commande suivante :

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/operations"

Pour inspecter un index existant, exécutez la commande suivante :

gcloud vector-search collections indexes describe vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --location=us-central1 \
  --project=PROJECT_ID

Pour supprimer un index (ce que vous devez faire pour modifier l'un de ses paramètres permanents), exécutez la commande suivante. La récupération revient à une analyse KNN par force brute jusqu'à ce que l'index de remplacement soit créé, et échoue complètement si le corpus dépasse 100 000 fragments.

gcloud vector-search collections indexes delete vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --location=us-central1 \
  --project=PROJECT_ID

Étapes suivantes

• Pour importer des fichiers et des dossiers depuis Google Drive ou Cloud Storage, consultez l'exemple d'importation de fichiers RAG.

• Pour lister les fichiers RAG, consultez Exemple de listage de fichiers RAG.

• Pour utiliser un reclasseur pour la récupération, consultez Reclassement pour le moteur RAG de Gemini Enterprise Agent Platform.

• Pour régler l'infrastructure d'index, les métriques de distance et les paramètres ScaNN, consultez Index de collection.