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 ce notebook Moteur RAG Vertex AI avec Pinecone.

Vous pouvez utiliser votre instance de base de données Pinecone avec le moteur de RAG Vertex AI pour indexer et effectuer une recherche de similarité basée sur les vecteurs. Une recherche de similarité permet de trouver des morceaux de texte similaires au texte recherché, ce qui 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 Vertex AI RAG Engine, vous pouvez continuer à utiliser votre instance de base de données vectorielle entièrement gérée, pour laquelle vous êtes responsable du provisionnement. Le moteur de 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

Déterminez si l'utilisation de la base de données Pinecone est le meilleur choix pour votre application de classification des risques en examinant les points suivants:

  • Vous devez créer, configurer et gérer la mise à l'échelle 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 être modifié par rien d'autre.

  • Vous devez fournir une clé API Pinecone, qui permet au moteur de RAG Vertex AI d'interagir avec la base de données Pinecone. Le moteur RAG Vertex AI ne stocke pas et ne gère pas votre clé API Pinecone. Procédez plutôt comme suit:

    • 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'indice Pinecone présentent un mappage de type "un à un". Cette association est effectuée dans le cadre de l'appel d'API CreateRagCorpus ou de l'appel d'API UpdateRagCorpus.

Créer votre index Pinecone

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

  1. Consultez le guide de démarrage rapide de Pinecone pour obtenir les configurations d'index qui doivent être spécifiées 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 ou proche de celui où vous utilisez le moteur de RAG Vertex AI pour les raisons suivantes:

    • Vous souhaitez maintenir des latences réduites.
    • 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 indique les tailles de dimension ou l'emplacement des tailles de dimension:

    Modèle Taille de la dimension
    Gecko propriétaire 768
    Gecko propriétaire optimisé 768
    E5 Consultez Utiliser des modèles d'embedding Open Source.

  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 un pod, vous devez spécifier le file_id dans le champ pod.metadata_config.indexed. Pour en savoir plus, consultez la section Indexation sélective des métadonnées.

Créer votre clé API Pinecone

Le moteur RAG Vertex AI ne peut se connecter à votre indice Pinecone qu'à l'aide de votre clé API pour l'authentification et l'autorisation. Vous devez suivre le guide officiel de Pinecone sur l'authentification 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 à mauvais escient, 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, procédez comme suit:

  1. Stockez votre clé API dans Secret Manager.

  2. Accordez à votre compte de service 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 Vertex AI RAG 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 de 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 (IAM) 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 aide à choisir la base de données vectorielle que vous souhaitez associer à votre corpus RAG. Il doit être défini lors de l'appel de l'API CreateRagCorpus. Si elle n'est pas définie, la base de données de vecteurs par défaut RagManagedDb est attribuée à votre corpus RAG.

  • rag_vector_db_config.pinecone.index_name: nom utilisé pour créer l'index Pinecone utilisé avec le corpus RAG. Vous pouvez définir le nom lors de l'appel CreateRagCorpus ou le spécifier 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 CreateRagCorpus ou le spécifier 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 au nom de la ressource secrète avec vos autorisations définies, vous pouvez créer votre corpus RAG et l'associer à votre index Pinecone, comme illustré dans cet exemple de code.

Lorsque 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 savoir comment créer le 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

S'il s'agit de votre premier corpus RAG et que vous n'avez pas accès aux détails de votre compte de service, ou que vous n'avez pas terminé les étapes de provisionnement pour votre index Pinecone, vous pouvez toujours créer votre corpus RAG. Vous pouvez ensuite associer le corpus RAG à une configuration Pinecone vide, puis ajouter les détails ultérieurement.

Vous devez tenir compte des points suivants:

  • Lorsque vous ne fournissez pas le nom de l'index et le nom du secret de la 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 passer à une autre base de données plus tard.

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}

Mettre à jour votre corpus RAG

L'API UpdateRagCorpus vous permet de mettre à jour la configuration de la base de données vectorielle. Si le nom de l'index Pinecone et la version secrète de la clé API ne sont pas définis, vous pouvez utiliser l'API Pinecone pour mettre à jour les champs. Le choix d'une base de données vectorielle ne peut pas être modifié. Vous pouvez fournir le secret de la clé API de manière facultative. Toutefois, si vous ne spécifiez pas le secret de la clé API, vous pouvez importer des données dans le corpus RAG.

Champ Mutabilité Obligatoire ou facultatif
rag_vector_db_config.vector_db Une fois que vous avez fait votre choix, il est immuable. Obligatoire
rag_vector_db_config.pinecone.index_name Il est 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