Utiliser RagManagedDb avec le moteur RAG de Vertex AI

Cette page vous explique comment le moteur RAG Vertex AI utilise RagManagedDb, une base de données vectorielle adaptée aux entreprises qui permet 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 CMEK.

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 RAG :

Créer un corpus RAG avec KNN RagManagedDb

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

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Vertex AI 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))

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

Créer un corpus RAG avec ANN RagManagedDb

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

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

• Si votre corpus RAG contient environ 10 000 fichiers 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 de Vertex AI 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 de Vertex AI attribue une valeur par défaut de 500 à ce paramètre.

from vertexai 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 Vertex AI 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))

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}"'
          }
        }
      }
    }'

Importer vos données dans ANN RagManagedDb

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

Voici les points importants :

1. Avant d'interroger le corpus RAG, vous devez reconstruire l'index ANN au moins une fois.
2. Une seule reconstruction d'index simultanée est acceptée par projet et par 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 reconstruction 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 RAG.

from vertexai 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 Vertex AI 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()

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 Vertex AI offre 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 de 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 Vertex AI est compatible avec les clés de chiffrement gérées par le client (CMEK). Avec CMEK, vous pouvez utiliser vos clés cryptographiques, gérées dans Cloud Key Management Service (KMS), pour protéger les données de votre corpus RAG.

Pour en savoir plus sur les limites CMEK pour les corpus RAG, consultez Limites CMEK pour le moteur RAG Vertex AI.

Configurer votre clé KMS et accorder des autorisations

Avant de pouvoir créer un corpus RAG chiffré avec CMEK, vous devez configurer une clé cryptographique dans Google Cloud KMS et accorder au compte de service Vertex AI RAG Engine 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 prévoyez de créer la clé KMS et le corpus RAG. En général, un rôle tel que celui d'administrateur Cloud KMS (roles/cloudkms.admin) est requis.

Activer l'API

Pour activer l'API Cloud KMS :

1. Accédez à la console Google Cloud .
2. Sélectionnez le projet dans lequel vous souhaitez gérer vos clés et créer votre corpus RAG.
3. Dans la barre de recherche, saisissez "Key Management" (Gestion des clés), puis sélectionnez le service "Key Management".
4. Si l'API 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éez votre trousseau et votre clé KMS

Pour créer un trousseau de clés :

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".
   • Emplacement : sélectionnez la région de votre choix, par exemple us-central1. Cette région doit idéalement correspondre à celle où se trouveront vos ressources RAG Engine.

2. Cliquez sur Créer.

Pour créer une clé dans le trousseau de clés :

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 avec support matériel, sélectionnez HSM.
   • Objectif : sélectionnez Chiffrement/déchiffrement symétriques. 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 en fonction des règles de sécurité de votre organisation (tous les 90 jours, par exemple).

2. Cliquez sur Créer.

Pour copier le nom de ressource de la clé :

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

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

3. Copiez le nom de la ressource et supprimez la partie /cryptoKeyVersions/VERSION_NUMBER. Le nom de ressource au format correct 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 Vertex AI

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

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

1. Accédez à la page IAM et administration > IAM de la console Google Cloud pour 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 entités principales, recherchez l'agent de service du moteur RAG Vertex AI. Il respecte le modèle service-YOUR_PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.com.

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

1. Revenez au service de gestion des clés 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é spécifique 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 Vertex AI RAG Engine.

7. Dans le menu déroulant Sélectionner un rôle, sélectionnez le rôle Chiffreur/Déchiffreur de clés cryptographiques 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 une clé de chiffrement gérée par le client (CMEK).

Remplacez les variables dans les exemples de code suivants :

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))

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}"\"'
      }
    }'

Étapes suivantes

• Pour en savoir plus sur RagManagedDb, consultez Comprendre RagManagedDb.
• 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 l'exemple de listage de fichiers RAG.