Utilizzare Pinecone con il motore RAG della piattaforma agentica Gemini Enterprise

Questa pagina mostra come connettere il corpus RAG al database Pinecone.

Puoi anche seguire le istruzioni utilizzando questo notebook Motore RAG di Gemini Enterprise Agent Platform con Pinecone.

Puoi utilizzare l'istanza del database Pinecone con RAG Engine di Gemini Enterprise Agent Platform per indicizzare ed eseguire una ricerca di similarità basata su vettori. Una ricerca per similarità è un modo per trovare brani di testo simili a quello che stai cercando, il che richiede l'utilizzo di un modello di incorporamento. Il modello di embedding produce dati vettoriali per ogni parte di testo confrontata. La ricerca di somiglianze viene utilizzata per recuperare contesti semantici per il grounding, in modo da restituire i contenuti più accurati dal tuo LLM.

Con RAG Engine di Gemini Enterprise Agent Platform, puoi continuare a utilizzare l'istanza del database vettoriale completamente gestita, di cui sei responsabile del provisioning. Il motore RAG di Gemini Enterprise Agent Platform utilizza il tuo database vettoriale per l'archiviazione, la gestione degli indici e la ricerca.

Valuta se utilizzare Pinecone con il motore RAG di Gemini Enterprise Agent Platform

Valuta se l'utilizzo del database Pinecone è la scelta migliore per la tua applicazione RAG esaminando quanto segue:

  • Devi creare, configurare e gestire lo scaling dell'istanza del database Pinecone.

  • Il motore RAG di Gemini Enterprise Agent Platform utilizza lo spazio dei nomi predefinito nell'indice. Assicurati che questo spazio dei nomi non sia modificabile da altri elementi.

  • Devi fornire una chiave API Pinecone, che consente al motore RAG di Gemini Enterprise Agent Platform di interagire con il database Pinecone. Il motore RAG di Gemini Enterprise Agent Platform non archivia e gestisce la chiave API Pinecone. Devi invece procedere nel seguente modo:

    • Archivia la chiave in Google Cloud Secret Manager.
    • Concedi al account di servizio del tuo progetto le autorizzazioni per accedere al secret.
    • Fornisci all'engine RAG di Gemini Enterprise Agent Platform l'accesso al nome della risorsa del tuo secret.

    • Quando interagisci con il tuo corpus RAG, il motore RAG di Gemini Enterprise Agent Platform accede alla tua risorsa secret utilizzando il tuaccount di serviziont.

    • Il corpus RAG e l'indice Pinecone hanno una mappatura one-to-one. Questa associazione viene creata nell'ambito del metodo ragCorpora.create o del metodo ragCorpora.patch.

Crea l'indice Pinecone

Per creare l'indice Pinecone, devi seguire questi passaggi:

  1. Consulta la guida rapida di Pinecone per ottenere le configurazioni dell'indice che devono essere specificate nell'indice per renderlo compatibile con il corpus RAG.

  2. Per i seguenti motivi, vuoi assicurarti che la posizione dell'indice Pinecone sia la stessa o vicina a quella in cui utilizzi il motore RAG di Gemini Enterprise Agent Platform:

    • Vuoi mantenere latenze ridotte.
    • Vuoi soddisfare i requisiti di residenza dei dati stabiliti dalle leggi vigenti.

  3. Durante la creazione dell'indice Pinecone, specifica la dimensione dell'incorporamento da utilizzare con il motore RAG di Gemini Enterprise Agent Platform. Questa tabella fornisce le dimensioni delle dimensioni o la posizione delle dimensioni delle dimensioni:

    Modello Dimensione della dimensione
    Gecko proprietario 768
    Gecko proprietario ottimizzato 768
    E5 Vedi Utilizzare i modelli di incorporamento OSS.

  4. Scegli una delle seguenti metriche di distanza supportate:

    • cosine
    • dotproduct
    • euclidean

  5. (Facoltativo) Quando crei un indice basato su pod, devi specificare file_id nel campo pod.metadata_config.indexed. Per ulteriori informazioni, vedi Indicizzazione selettiva dei metadati.

Crea la chiave API Pinecone

Il motore RAG di Gemini Enterprise Agent Platform può connettersi al tuo indice Pinecone solo utilizzando la tua chiave API per l'autenticazione e l'autorizzazione. Per configurare l'autenticazione basata su chiave API nel tuo progetto Pinecone, devi seguire la guida ufficiale di Pinecone all'autenticazione.

Archivia la chiave API in Secret Manager

Una chiave API contiene informazioni sensibili che consentono l'identificazione personale (informazioni personali sensibili), che sono soggette a requisiti legali. Se i dati SPII vengono compromessi o utilizzati in modo improprio, un privato potrebbe subire un rischio o un danno significativo. Per ridurre al minimo i rischi per una persona durante l'utilizzo del motore RAG di Gemini Enterprise Agent Platform, non archiviare e gestire la chiave API ed evita di condividerla non criptata.

Per proteggere le informazioni personali sensibili, devi:

  1. Archivia la chiave API in Secret Manager.

  2. Concedi al tuo account di servizio RAG Engine di Gemini Enterprise Agent Platform le autorizzazioni per i tuoi secret e gestisci ilcontrollo dell'accessoo a livello di risorsa secret.

    1. Vai alle autorizzazioni del progetto.

    2. Attiva l'opzione Includi concessioni di ruoli fornite da Google.

    3. Trova il account di servizio, che ha il formato:

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

    4. Modifica le entità dell'account di servizio.

    5. Aggiungi il ruolo Secret Manager Secret Accessor al service account.

  3. Durante la creazione o l'aggiornamento del corpus RAG, passa il nome della risorsa secret al motore RAG di Gemini Enterprise Agent Platform e memorizza il nome della risorsa secret.

Quando effettua richieste API ai tuoi indici Pinecone, RAG Engine di Gemini Enterprise Agent Platform utilizza ogniaccount di serviziot per leggere la chiave API corrispondente alle tue risorse secret in Secret Manager dai tuoi progetti.

Esegui il provisioning dell'account di servizio del motore RAG di Gemini Enterprise Agent Platform

Quando crei il primo corpus RAG nel tuo progetto, il motore RAG di Gemini Enterprise Agent Platform crea un account di servizio dedicato. Puoi trovare il tuo account di servizio nella pagina Identity and Access Management del tuo progetto.

Il account di servizio segue questo formato fisso:

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

Ad esempio,

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

Prepara il corpus RAG

Per utilizzare l'indice Pinecone con il motore RAG di Gemini Enterprise Agent Platform, devi associare l'indice a un corpus RAG durante la fase di creazione. Una volta creata l'associazione, questo binding è permanente per tutta la durata del corpus RAG. L'associazione può essere eseguita utilizzando CreateRagCorpus o l'API UpdateRagCorpus.

Affinché l'associazione sia considerata completa, devi impostare tre campi chiave nel corpus RAG:

  • rag_vector_db_config.pinecone: questo campo ti consente di impostare la scelta di un database vettoriale che vuoi associare al tuo corpus RAG e deve essere impostato durante la chiamata API CreateRagCorpus. Se non è impostato, al corpus RAG viene assegnata la scelta predefinita del database vettoriale RagManagedDb.

  • rag_vector_db_config.pinecone.index_name: questo è il nome utilizzato per creare l'indice Pinecone utilizzato con il corpus RAG. Puoi impostare il nome durante la chiamata CreateRagCorpus oppure specificarlo quando chiami l'API UpdateRagCorpus.

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: Il nome completo della risorsa del secret archiviato in Secret Manager, che contiene la chiave API Pinecone. Puoi impostare il nome durante la chiamata CreateRagCorpus oppure specificarlo quando chiami l'API UpdateRagCorpus. Finché non specifichi questo campo, non puoi importare i dati nel corpus RAG.

    Questo campo deve avere il seguente formato:

    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Crea il corpus RAG

Se hai accesso al nome dell'indice Pinecone e al nome della risorsa segreta con le tue autorizzazioni impostate, puoi creare il tuo corpus RAG e associarlo al tuo indice Pinecone, come mostrato in questo codice campione.

Quando crei un corpus RAG per la prima volta, non avrai a disposizione le informazioni dell'account di servizio. Tuttavia, i campi sono facoltativi e possono essere associati al corpus RAG utilizzando l'API UpdateRagCorpus.

Per un esempio su come creare il corpus RAG senza fornire le informazioni del service account, consulta Crea il corpus RAG senza un nome indice o una chiave API.

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


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}

Crea un corpus RAG senza un nome indice o una chiave API

Se questo è il tuo primo corpus RAG e non hai accesso ai dettagli del tuo account di servizio o non hai completato i passaggi di provisioning per l'indice Pinecone, puoi comunque creare il tuo corpus RAG. Puoi quindi associare il corpus RAG a una configurazione Pinecone vuota e aggiungere i dettagli in un secondo momento.

Devono essere presi in considerazione i seguenti aspetti:

  • Se non fornisci il nome dell'indice e il nome del secret della chiave API, i file non possono essere importati nel corpus RAG.

  • Se scegli Pinecone come database vettoriale per il tuo corpus RAG, non puoi passare a un altro database in un secondo momento.

Questo esempio di codice mostra come creare un corpus RAG con Pinecone senza fornire un nome di indice Pinecone o un nome di segreto API. Utilizza l'API UpdateRagCorpus per specificare in un secondo momento le informazioni mancanti.

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}

Aggiorna il corpus RAG

L'API UpdateRagCorpus consente di aggiornare la configurazione del database vettoriale. Se il nome dell'indice Pinecone e la versione segreta della chiave API non sono stati impostati in precedenza, puoi utilizzare l'API Pinecone per aggiornare i campi. La scelta di un database vettoriale non può essere aggiornata. La fornitura del secret della chiave API è facoltativa. Tuttavia, se non specifichi il secret della chiave API, puoi importare i dati nel corpus RAG.

Campo Mutabilità Obbligatorio o facoltativo
rag_vector_db_config.vector_db Immutabile dopo la scelta. Obbligatorio
rag_vector_db_config.pinecone.index_name Immutabile dopo aver impostato il campo sul corpus RAG. Obbligatorio
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version Modificabile. Dopo aver impostato la chiave API, non puoi eliminarla. Facoltativo

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}

Passaggi successivi