Utiliser RagManagedDb avec le moteur RAG sur Gemini Enterprise Agent Platform

Les contrôles de sécurité VPC-SC et les clés CMEK sont compatibles avec le moteur RAG d'Agent Platform. Les contrôles de sécurité pour la résidence des données et Access Transparency ne sont pas compatibles.

L'instance Spanner gérée par le moteur RAG est utilisée comme base de données vectorielle et est en disponibilité générale avec la facturation activée. Pour en savoir plus, consultez Facturation du moteur RAG sur Gemini Enterprise Agent Platform.

Cette page explique comment le moteur RAG sur Gemini Enterprise Agent Platform utilise RagManagedDb, une base de données vectorielle d'entreprise permettant de stocker et de gérer les représentations vectorielles de vos documents. La base de données vectorielle est ensuite utilisée pour récupérer les documents pertinents en fonction de leur similarité sémantique avec une requête donnée.

Cette page vous explique également comment implémenter les CMEK.

Important : RagManagedDb est utilisé par défaut et utilise Spanner. Les clients seront facturés pour l'utilisation d'une instance Spanner gérée par Google provisionnée dans un projet locataire Google à l'aide de SKU Spanner standards.

Gérer votre stratégie de récupération

RagManagedDb propose les stratégies de récupération suivantes pour prendre en charge vos cas d'utilisation de RAG :

Stratégie de récupération	Description
k plus proches voisins (KNN) (par défaut)	Recherche les voisins les plus proches en comparant tous les points de données de votre corpus RAG. Si vous ne spécifiez pas de stratégie lors de la création de votre corpus RAG, KNN est la stratégie de récupération par défaut utilisée.	Vérifie le rappel parfait (1,0) lors de la récupération. Idéal pour les applications sensibles au rappel. Idéal pour les corpus RAG de petite à moyenne taille, qui stockent moins de 10 000 fichiers RAG. Nécessite une recherche sur chaque point de données. Par conséquent, la latence augmente avec le nombre de fichiers RAG dans le corpus.
Voisin le plus proche (ANN)	Utilise des techniques d'approximation pour trouver des voisins similaires plus rapidement que la technique KNN.	Réduit considérablement la latence des requêtes sur les grands corpus RAG. Le rappel est légèrement réduit en raison des techniques d'approximation utilisées. Devient très efficace lorsque vous disposez de grands corpus RAG, soit environ plus de 10 000 fichiers RAG. La perte de rappel acceptable dépend du cas d'utilisation, mais dans la plupart des cas à grande échelle, perdre un peu de rappel en échange d'une amélioration des performances des requêtes est un compromis acceptable.

Créer un corpus RAG avec KNN RagManagedDb

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

Python

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.RagManagedDb(retrieval_strategy=rag.KNN())
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

Remplacez les variables suivantes :

• PROJECT_ID : ID de votre projet.
• LOCATION : région dans laquelle traiter la requête.
• CORPUS_DISPLAY_NAME : nom à afficher du corpus RAG.

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

Aperçu

Certaines fonctionnalités RAG sont des versions Preview, soumises aux "Conditions des Offres de pré-DG" des Conditions spécifiques aux services Google Cloud. Les fonctionnalités et produits pré-DG sont disponibles "en l'état" et sont susceptibles de présenter une compatibilité limitée. De plus, il est possible que les modifications apportées à ces fonctionnalités ou produits ne soient pas compatibles avec d'autres versions pré-DG. Pour en savoir plus, consultez les descriptions des étapes de lancement. En utilisant l'API Gemini sur Gemini Enterprise Agent Platform, vous acceptez les Conditions d'utilisation de l'IA générative (conditions Preview).

Créer un corpus RAG avec ANN RagManagedDb

Pour proposer la fonctionnalité ANN, RagManagedDb utilise une structure arborescente pour partitionner les données et accélérer les recherches. Pour optimiser le rappel et la latence, la structure de cette arborescence doit être configurée par expérimentation pour s'adapter à la taille et à la distribution de vos données. RagManagedDb vous permet de configurer les éléments tree_depth et leaf_count de l'arborescence.

tree_depth détermine le nombre de couches ou de niveaux dans l'arborescence. Suivez les instructions ci-dessous :

• Si vous avez environ 10 000 fichiers RAG dans le corpus RAG, définissez la valeur sur 2.
• Si vous avez plus de fichiers RAG, définissez cette valeur sur 3.
• Si tree_depth n'est pas spécifié, le moteur RAG attribue une valeur par défaut de 2 à ce paramètre.

leaf_count détermine le nombre de nœuds feuilles dans la structure arborescente. Chaque nœud feuille contient des groupes de vecteurs étroitement liés ainsi que leur centroïde correspondant. Suivez les instructions ci-dessous :

• La valeur recommandée est 10 * sqrt(num of RAG files in your RAG corpus).

• Si aucune valeur n'est spécifiée, le moteur RAG attribue une valeur par défaut de 500 à ce paramètre.

Python

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
TREE_DEPTH = YOUR_TREE_DEPTH # Optional: Acceptable values are 2 or 3. Default is 2.
LEAF_COUNT = YOUR_LEAF_COUNT # Optional: Default is 500.

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

ann_config = rag.ANN(tree_depth=TREE_DEPTH, leaf_count=LEAF_COUNT)
vector_db = rag.RagManagedDb(retrieval_strategy=ann_config)
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

Remplacez les variables suivantes :

• PROJECT_ID : ID de votre projet.
• LOCATION : région dans laquelle traiter la requête.
• CORPUS_DISPLAY_NAME : nom à afficher du corpus RAG.
• TREE_DEPTH : profondeur de l'arbre.
• LEAF_COUNT : votre nombre de feuilles.

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME
TREE_DEPTH=TREE_DEPTH
LEAF_COUNT=LEAF_COUNT

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": {
        "ragManagedDb": {
          "ann": {
            "tree_depth": '"${TREE_DEPTH}"',
            "leaf_count": '"${LEAF_COUNT}"'
          }
        }
      }
    }'

Aperçu

Certaines fonctionnalités RAG sont des versions Preview, soumises aux "Conditions des Offres de pré-DG" des Conditions spécifiques aux services Google Cloud. Les fonctionnalités et produits pré-DG sont disponibles "en l'état" et sont susceptibles de présenter une compatibilité limitée. De plus, il est possible que les modifications apportées à ces fonctionnalités ou produits ne soient pas compatibles avec d'autres versions pré-DG. Pour en savoir plus, consultez les descriptions des étapes de lancement. En utilisant l'API Gemini sur Gemini Enterprise Agent Platform, vous acceptez les Conditions d'utilisation de l'IA générative (conditions Preview).

Importation de vos données dans ANN RagManagedDb…

Vous pouvez utiliser l'API ImportRagFiles ou l'API UploadRagFile pour importer vos données dans l'RagManagedDb ANN. Toutefois, contrairement à la stratégie de récupération KNN, l'approche ANN nécessite que l'index sous-jacent basé sur l'arborescence soit recréé au moins une fois et, éventuellement, après l'importation de quantités importantes de données pour un rappel optimal. Pour que le moteur RAG reconstruise votre index ANN, définissez rebuild_ann_index sur "true" dans votre requête API ImportRagFiles.

Voici les points importants :

1. Avant d'interroger le corpus RAG, vous devez recompiler l'index ANN au moins une fois.
2. Une seule recompilation d'index simultanée est acceptée sur un projet dans chaque emplacement.

Pour importer votre fichier local dans votre corpus RAG, consultez Importer un fichier RAG. Pour importer des données dans votre corpus RAG et déclencher une recompilation de l'index ANN, 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.

Python

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"]
REBUILD_ANN_INDEX = REBUILD_ANN_INDEX # Choose true or false.

# 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,
    rebuild_ann_index=REBUILD_ANN_INDEX
)

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

REST

GCS_URI=GCS_URI
REBUILD_ANN_INDEX=<true/false>

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}"\"',
      },
    "rebuild_ann_index": '${REBUILD_ANN_INDEX}'
  }
}'

Gérer votre chiffrement

Le moteur RAG propose des options robustes pour gérer le chiffrement de vos données au repos. Par défaut, toutes les données utilisateur de RagManagedDb sont chiffrées à l'aide d'une Google-owned and Google-managed encryption key, qui est le paramètre par défaut. Ce paramètre par défaut vous permet de vérifier que vos données sont sécurisées sans nécessiter de configuration spécifique.

Si vous avez besoin de plus de contrôle sur les clés utilisées pour le chiffrement, le moteur RAG est compatible avec les clés de chiffrement gérées par le client (CMEK). Avec les CMEK, vous pouvez utiliser vos clés cryptographiques, gérées dans Cloud Key Management Service (Cloud KMS), pour protéger les données de votre corpus RAG.

Pour en savoir plus sur les limites des CMEK pour les corpus RAG, consultez Limites des CMEK pour le moteur RAG sur Gemini Enterprise Agent Platform.

Configurer votre clé Cloud KMS et accorder des autorisations

Avant de pouvoir créer un corpus RAG chiffré avec une CMEK, vous devez configurer une clé cryptographique dans Google Cloud KMS et accorder au compte de service du moteur RAG les autorisations nécessaires pour utiliser cette clé.

Prérequis

Pour effectuer les étapes de configuration suivantes, vérifiez que votre compte utilisateur dispose des autorisations IAM (Identity and Access Management) appropriées dans le projet Google Cloud où vous avez l'intention de créer la clé Cloud KMS et le corpus RAG. En règle générale, un rôle tel que le rôle d'administrateur Cloud KMS (roles/cloudkms.admin) est requis.

Activer l'API

Pour activer l'API Cloud Key Management Service, procédez comme suit :

1. Accédez à la console Google Cloud .
2. Sélectionnez le projet dans lequel vous souhaitez gérer vos clés, puis créez votre corpus RAG.
3. Dans la barre de recherche, saisissez "Gestion des clés", puis sélectionnez le service "Gestion des clés".
4. Si elle n'est pas activée, cliquez sur Activer. Vous devrez peut-être patienter quelques minutes pour que l'API soit entièrement provisionnée.

Créer votre trousseau de clés et votre clé Cloud KMS

Pour créer un trousseau de clés, procédez comme suit :

1. Dans la section Gestion des clés, cliquez sur Créer un trousseau de clés.

   Saisissez ce qui suit :

   • Nom du trousseau de clés : saisissez un nom unique pour votre trousseau de clés, par exemple "rag-engine-cmek-keys".
   • Type d'emplacement : sélectionnez "Région". Le trousseau de clés Cloud KMS doit se trouver dans la même région que le point de terminaison du moteur RAG que vous utilisez lorsque vous chiffrez un corpus RAG avec une CMEK.
   • Emplacement : choisissez la région sélectionnée, par exemple us-central1. Idéalement, cette région doit correspondre à celle où se trouveront vos ressources de moteur RAG.

2. Cliquez sur Créer.

Pour créer une clé dans le trousseau de clés, procédez comme suit :

1. Une fois le trousseau de clés créé, vous serez invité à créer une clé, ou vous pourrez accéder à Créer une clé.

   Saisissez ce qui suit :

   • Nom de la clé : saisissez un nom unique pour votre clé, par exemple my-rag-corpus-key.
   • Niveau de protection : choisissez un niveau de protection (Logiciel ou HSM). Si vous avez besoin de clés intégrées au matériel, sélectionnez HSM.
   • Objectif : sélectionnez Chiffrement/Déchiffrement symétriques. Cette étape est obligatoire pour les CMEK.
   • Source du matériel de clé : sélectionnez Clé générée.
   • Période de rotation : facultatif. Recommended. Configurez un calendrier de rotation des clés conformément aux règles de sécurité de votre organisation (par exemple, tous les 90 jours).

2. Cliquez sur Créer.

Pour copier le nom de ressource de la clé, procédez comme suit :

1. Une fois la clé créée, accédez à sa page d'informations.

2. Recherchez le nom de la ressource. Le format est le suivant : projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1.

   Important : Pour le EncryptionSpec de votre corpus RAG, vous devez utiliser le nom de ressource de la clé sans le numéro de version.

3. Copiez le nom de la ressource et supprimez la partie /cryptoKeyVersions/VERSION_NUMBER. Le nom de ressource correctement formaté est projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME.

Accorder des autorisations à l'agent de service du moteur RAG

Pour que le moteur RAG puisse chiffrer et déchiffrer des données à l'aide de votre clé Cloud KMS, son agent de service doit disposer des autorisations appropriées sur cette clé spécifique.

Pour identifier votre agent de service de moteur RAG, procédez comme suit :

1. Accédez à la page IAM et administration > IAM dans la console Google Cloud de votre projet.

2. Sur la page Identity and Access Management, cochez la case Inclure les attributions de rôles fournies par Google.

3. Dans la barre de filtre ou de recherche de la liste des comptes principaux, recherchez l'agent de service du moteur RAG. Il suit le modèle [e-mail].

   Remplacez YOUR_PROJECT_NUMBER par votre numéro de projet Google Cloud .

Si votre agent de service de moteur RAG n'est pas encore présent, procédez comme suit pour déclencher sa création :

1. Activez l'API Resource Manager.

2. Exécutez cette commande dans Cloud Shell ou sur la ligne de commande :

   gcloud beta services identity create --service=aiplatform.googleapis.com \
       --projects=PROJECT_ID
   

   Vous pouvez également envoyer l'appel d'API REST :

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json; charset=utf-8" -d "" "https://serviceusage.googleapis.com/v1beta1/projects/PROJECT_ID/services/aiplatform.googleapis.com:generateServiceIdentity"
   

3. Vérifiez que l'agent de service du moteur RAG a été créé.

Pour accorder des autorisations sur la clé Cloud KMS, procédez comme suit :

1. Revenez au service Cloud KMS dans la console Google Cloud .

2. Sélectionnez le trousseau de clés contenant la clé que vous avez créée.

3. Sélectionnez la clé que vous avez créée.

4. Sur la page d'informations de la clé, accédez à l'onglet Autorisations.

5. Cliquez sur Ajouter un compte principal.

6. Dans le champ Nouveaux comptes principaux, saisissez l'adresse e-mail de l'agent de service du moteur RAG.

7. Dans le menu déroulant Sélectionner un rôle, sélectionnez le rôle "Chiffreur/Déchiffreur de CryptoKeys Cloud KMS" (roles/cloudkms.cryptoKeyEncrypterDecrypter). Ce rôle accorde à l'agent de service les autorisations nécessaires pour utiliser la clé pour les opérations de chiffrement et de déchiffrement.

8. Cliquez sur Enregistrer.

Créer un corpus RAG avec un chiffrement géré par le client

Cet exemple de code montre comment créer un corpus RAG chiffré avec des clés de chiffrement gérées par le client (CMEK).

Remplacez les variables dans les exemples de code suivants :

Python

import vertexai
from google.cloud import aiplatform
from vertexai import rag
from google.cloud.aiplatform_v1.types.encryption_spec import EncryptionSpec

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

vertexai.init(project=PROJECT_ID)

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, encryption_spec=EncryptionSpec(kms_key_name=KMS_KEY_NAME))

REST

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

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

Quotas

Lorsque vous utilisez des CMEK avec les services Gemini Enterprise Agent Platform, tels que le moteur RAG sur Gemini Enterprise Agent Platform, un quota s'applique au nombre de clés Cloud KMS uniques pouvant être utilisées par projet et par région. Ce quota est suivi par la métrique aiplatform.googleapis.com/in_use_customer_managed_encryption_keys.

Chaque fois que vous utilisez une nouvelle clé Cloud KMS unique pour créer une ressource telle qu'un corpus RAG dans un projet et une région, la clé Cloud KMS consomme une unité de ce quota. Cette unité de quota n'est pas libérée, même si les ressources utilisant cette clé spécifique sont supprimées.

Si vous avez besoin de plus de clés uniques que la limite actuelle, vous devez demander une augmentation de quota pour aiplatform.googleapis.com/in_use_customer_managed_encryption_keys pour la région sélectionnée.

Pour savoir comment demander une augmentation de quota, consultez Afficher et modifier les quotas dans la console Google Cloud .

Étapes suivantes

• Pour en savoir plus sur RagManagedDb, consultez Modes de déploiement.
• 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.