Utiliser Pinecone avec le moteur RAG Vertex AI

Cette page explique comment connecter votre corpus RAG à votre base de données Pinecone.

Vous pouvez également suivre avec ce notebook Moteur RAG Vertex AI avec Pinecone.

Vous pouvez utiliser votre instance de base de données Pinecone avec le moteur RAG Vertex AI pour indexer et effectuer une recherche de similarité basée sur les vecteurs. Une recherche de similarité permet de trouver des éléments de texte similaires au texte recherché et nécessite l'utilisation d'un modèle d'embedding. Le modèle d'embedding produit des données vectorielles pour chaque élément de texte comparé. La recherche de similarités permet de récupérer les contextes sémantiques pour l'ancrage afin de renvoyer les contenus les plus pertinents de votre LLM.

Avec le moteur RAG Vertex AI, vous pouvez continuer à utiliser votre instance de base de données vectorielle entièrement gérée dont vous êtes chargé du provisionnement. Le moteur RAG Vertex AI utilise votre base de données vectorielle pour le stockage, la gestion des index et la recherche.

Décider d'utiliser Pinecone avec le moteur RAG Vertex AI

Pour déterminer si la base de données Pinecone constitue le meilleur choix pour votre application RAG, examinez les points suivants :

  • Vous devez créer, configurer et gérer le scaling de votre instance de base de données Pinecone.

  • Le moteur RAG Vertex AI utilise l'espace de noms par défaut de votre index. Assurez-vous que cet espace de noms ne peut pas être modifié par un autre élément.

  • Vous devez fournir une clé API Pinecone, qui permet au moteur RAG Vertex AI d'interagir avec la base de données Pinecone. Le moteur RAG Vertex AI ne stocke pas ni ne gère votre clé API Pinecone. Vous devez effectuer les actions suivantes :

    • Stockez votre clé dans Google Cloud Secret Manager.
    • Accordez au compte de service de votre projet les autorisations nécessaires pour accéder à votre secret.
    • Fournissez au moteur RAG Vertex AI un accès au nom de ressource de votre secret.
    • Lorsque vous interagissez avec votre corpus RAG, le moteur RAG Vertex AI accède à votre ressource de secret à l'aide de votre compte de service.

  • Le corpus RAG et l'index Pinecone présentent un mappage de type "un à un". Cette association est effectuée lors de l'appel d'API CreateRagCorpus ou lors de l'appel d'API UpdateRagCorpus.

Créer votre index Pinecone

Pour créer votre index Pinecone, procédez comme suit :

  1. Consultez le guide de démarrage rapide de Pinecone pour obtenir les configurations d'index à spécifier sur votre index afin de le rendre compatible avec le corpus RAG.

  2. Vous devez vous assurer que l'emplacement de l'index Pinecone est identique à celui où vous utilisez le moteur RAG Vertex AI (ou proche de celui-ci) pour les raisons suivantes :

    • Vous souhaitez réduire les latences.
    • Vous souhaitez respecter les exigences de résidence des données définies par les lois applicables.

  3. Lors de la création de l'index Pinecone, spécifiez la dimension d'embedding à utiliser avec le moteur RAG Vertex AI. Ce tableau fournit les dimensions ou leur emplacement :

    Modèle Dimension
    Gecko propriétaire 768
    Gecko propriétaire réglé 768
    E5 Consultez Utiliser des modèles d'embedding OSS.

  4. Sélectionnez l'une des métriques de distance compatibles suivantes :

    • cosine
    • dotproduct
    • euclidean

  5. Facultatif : lorsque vous créez un index basé sur des pods, vous devez spécifier le file_id dans le champ pod.metadata_config.indexed. Pour en savoir plus, consultez Indexation sélective des métadonnées.

Créer votre clé API Pinecone

Le moteur RAG Vertex AI ne peut se connecter à votre index Pinecone qu'à l'aide de votre clé API pour l'authentification et l'autorisation. Vous devez suivre le guide officiel Pinecone pour configurer l'authentification basée sur une clé API dans votre projet Pinecone.

Stocker votre clé API dans Secret Manager

Une clé API contient des informations personnelles sensibles, qui sont soumises à des obligations légales. Si ces données sont compromises ou utilisées de manière abusive, une personne physique peut être exposée à des risques ou à des préjudices importants. Pour minimiser les risques encourus par une personne lors de l'utilisation du moteur RAG Vertex AI, ne stockez pas et ne gérez pas votre clé API, et évitez de partager la clé API non chiffrée.

Pour protéger les informations personnelles sensibles, vous devez effectuer les actions suivantes :

  1. Stockez votre clé API dans Secret Manager.

  2. Accordez à votre compte de service du moteur RAG Vertex AI les autorisations nécessaires pour vos secrets, et gérez le contrôle des accès au niveau de la ressource du secret.

    1. Accédez aux autorisations de votre projet.

    2. Activez l'option Inclure les attributions de rôles fournies par Google.

    3. Recherchez le compte de service, qui est au format suivant :

      service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

    4. Modifiez les comptes principaux du compte de service.

    5. Ajoutez le rôle Secret Manager Secret Accessor au compte de service.

  3. Lors de la création ou de la mise à jour du corpus RAG, transmettez le nom de la ressource de secret au moteur RAG Vertex AI, puis stockez le nom de la ressource de secret.

Lorsque vous envoyez des requêtes API à vos index Pinecone, le moteur RAG Vertex AI utilise chaque compte de service pour lire la clé API correspondant à vos ressources de secret dans Secret Manager à partir de vos projets.

Provisionner votre compte de service du moteur RAG Vertex AI

Lorsque vous créez le premier corpus RAG dans votre projet, le moteur RAG Vertex AI crée un compte de service dédié. Vous pouvez trouver votre compte de service sur la page Identity and Access Management de votre projet.

Le compte de service respecte le format fixe suivant :

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

Par exemple :

service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

Préparer votre corpus RAG

Pour utiliser votre index Pinecone avec le moteur RAG Vertex AI, vous devez l'associer à un corpus RAG lors de sa création. Une fois l'association effectuée, cette liaison est permanente pendant toute la durée de vie du corpus RAG. L'association peut être effectuée à l'aide de l'API CreateRagCorpus ou UpdateRagCorpus.

Pour que l'association soit considérée comme terminée, vous devez définir trois champs clés sur le corpus RAG :

  • rag_vector_db_config.pinecone : ce champ vous permet de choisir une base de données vectorielle à associer à votre corpus RAG. Il doit être défini lors de l'appel d'API CreateRagCorpus. S'il ne l'est pas, la base de données vectorielle par défaut RagManagedDb est attribuée à votre corpus RAG.

  • rag_vector_db_config.pinecone.index_name : nom servant à créer l'index Pinecone utilisé avec le corpus RAG. Vous pouvez définir le nom lors de l'appel de CreateRagCorpus ou spécifier le nom lorsque vous appelez l'API UpdateRagCorpus.

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version : nom complet de la ressource du secret stocké dans Secret Manager, qui contient votre clé API Pinecone. Vous pouvez définir le nom lors de l'appel de CreateRagCorpus ou spécifier le nom lorsque vous appelez l'API UpdateRagCorpus. Tant que vous n'avez pas spécifié ce champ, vous ne pouvez pas importer de données dans le corpus RAG.
    Ce champ doit avoir le format suivant :
    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Créer votre corpus RAG

Si vous avez accès au nom de votre index Pinecone et à celui de la ressource de secret avec votre ensemble d'autorisations, vous pouvez créer votre corpus RAG et l'associer à votre index Pinecone, comme illustré dans cet exemple de code.

Si vous créez un corpus RAG pour la première fois, vous ne disposez pas des informations du compte de service. Toutefois, les champs sont facultatifs et peuvent être associés au corpus RAG à l'aide de l'API UpdateRagCorpus.

Pour obtenir un exemple de création d'un corpus RAG sans fournir les informations du compte de service, consultez Créer un corpus RAG sans nom d'index ni clé API.

Python

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

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. 


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# pinecone_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
        publisher_model="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = rag.Pinecone(
    index_name=pinecone_index_name,
    api_key=pinecone_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    backend_config=rag.RagVectorDbConfig(
        rag_embedding_model_config=embedding_model_config,
        vector_db=vector_db,
    ),
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

REST

   # Set your project ID under which you want to create the corpus
   PROJECT_ID = "YOUR_PROJECT_ID"

   # Choose a display name for your corpus
   CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

   # Set your Pinecone index name
   PINECONE_INDEX_NAME=YOUR_INDEX_NAME

   # Set the full resource name of your secret. Follows the format
   # projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
   SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

   # Call CreateRagCorpus API with all the Vector DB information.
   # You can also add the embedding model choice or set other RAG corpus parameters on
   # this call per your choice.
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
         "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
         "rag_vector_db_config" : {
            "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
            "api_auth": {"api_key_config":
                  {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
            }
         }
      }'

   # To poll the status of your RAG corpus creation, get the operation_id returned in
   # response of your CreateRagCorpus call.
   OPERATION_ID="YOUR_OPERATION_ID"

   # Poll Operation status until done = true in the response.
   # The response to this call will contain the ID for your created RAG corpus
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

Créer un corpus RAG sans nom d'index ni clé API

Si vous créez votre premier corpus RAG et que vous n'avez pas accès aux informations de votre compte de service, ou si vous n'avez pas effectué la procédure de provisionnement pour votre index Pinecone, vous pouvez quand même créer votre corpus RAG. Vous pouvez ensuite associer le corpus RAG à une configuration Pinecone vide, puis ajouter les informations ultérieurement.

Vous devez prendre en compte les points suivants :

  • Si vous ne fournissez pas le nom de l'index et le nom du secret de clé API, les fichiers ne peuvent pas être importés dans le corpus RAG.
  • Si vous choisissez Pinecone comme base de données vectorielle pour votre corpus RAG, vous ne pourrez pas la remplacer ultérieurement par une autre base de données.

Cet exemple de code montre comment créer un corpus RAG avec Pinecone sans fournir de nom d'index Pinecone ni de nom de secret d'API. Utilisez l'API UpdateRagCorpus pour spécifier ultérieurement les informations manquantes.

Python 

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone()

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST 

# Set your project ID under which you want to create the corpus
PROJECT_ID = "YOUR_PROJECT_ID"

# Choose a display name for your corpus
CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

# Call CreateRagCorpus API with all the Vector DB information.
# You can also add the embedding model choice or set other RAG corpus parameters on
# this call per your choice.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "rag_vector_db_config" : {
         "pinecone": {}
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

Modifier votre corpus RAG

L'API UpdateRagCorpus vous permet de modifier la configuration de la base de données vectorielle. Si le nom de l'index Pinecone et la version du secret de la clé API n'ont pas été définis précédemment, vous pouvez utiliser l'API Pinecone pour mettre à jour les champs. Le choix de la base de données vectorielle est définitif. Le secret de la clé API est facultatif. Toutefois, si vous ne le spécifiez pas, vous pouvez importer des données dans le corpus RAG.

Champ Mutabilité Obligatoire ou facultatif
rag_vector_db_config.vector_db Immuable après sélection Obligatoire
rag_vector_db_config.pinecone.index_name Immuable une fois le champ défini sur le corpus RAG Obligatoire
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version Non immuable. Une fois la clé API définie, vous ne pouvez plus la supprimer. Facultatif

Python 

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone(index_name=)

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST 

# Set your project ID for the corpus that you want to create.
PROJECT_ID = "YOUR_PROJECT_ID"

# Set your Pinecone index name
PINECONE_INDEX_NAME=YOUR_INDEX_NAME

# Set the full resource name of your secret. Follows the format
# projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

# Call UpdateRagCorpus API with the Vector DB information.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "rag_vector_db_config" : {
         "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
         "api_auth": {"api_key_config":
               {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
         }
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

Étape suivante