Utilizza Pinecone con RAG Engine

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

Puoi utilizzare l'istanza del database Pinecone con RAG Engine per eseguire l'indicizzazione e una ricerca di similarità basata su vettori. Una ricerca di similarità è un modo per trovare frammenti di testo simili a quelli che stai cercando, il che richiede l'utilizzo di un modello di embedding. Il modello di embedding produce dati vettoriali per ogni testo confrontato. La ricerca di somiglianze viene utilizzata per recuperare i contesti semantici per l'ancoraggio in modo da restituire i contenuti più accurati dell'LLM.

Con RAG Engine, puoi continuare a utilizzare l'istanza del database di vettori completamente gestito di cui sei responsabile del provisioning. RAG Engine utilizza vettoriale per l'archiviazione, la gestione degli indici e la ricerca.

Valuta se utilizzare Pinecone con RAG Engine

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

  • Devi creare, configurare e gestire il ridimensionamento dell'istanza del database Pinecone.

  • RAG Engine utilizza lo spazio dei nomi predefinito nell'indice. Assicurati che dello spazio dei nomi non può essere modificato da nessun altro.

  • Devi fornire una chiave API Pinecone, che consente a RAG Engine di interagire con il database Pinecone. RAG Engine non memorizza e gestisce la chiave API Pinecone. Devi invece procedere nel seguente modo:

    • Memorizza la chiave in Secret Manager di Google Cloud.
    • Concedi all'account di servizio del progetto le autorizzazioni per accedere al secret.
    • Fornisci a RAG Engine l'accesso al nome della risorsa del tuo secret.
    • Quando interagisci con il corpus RAG, RAG Engine accede al tuo utilizzando il tuo account di servizio.

  • Il corpus RAG e l'indice Pinecone hanno una mappatura uno a uno. Questo viene effettuata nell'ambito dell'API CreateRagCorpus o il Chiamata API UpdateRagCorpus.

Creare l'indice Pinecone

Per creare il tuo indice della pigna, devi seguire questi passaggi:

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

  2. Vuoi assicurarti che la posizione del Pinecone di Google Cloud è uguale o vicino al punto in cui utilizzi RAG Engine per i seguenti motivi:

    • Vuoi mantenere la latenza ridotta.
    • Vuoi soddisfare i requisiti di residenza dei dati stabiliti dalle legge vigenti.

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

    Modello Dimensioni
    Gecko proprietario 768
    Gecko proprietario ottimizzato 768
    E5 Consulta 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 Metadati selettivi indicizzazione.

Crea la tua chiave API Pinecone

RAG Engine 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 progetto Pinecone, devi seguire la guida ufficiale di Pinecone sull'autenticazione.

Memorizza la chiave API in Secret Manager

Una chiave API contiene informazioni sensibili che consentono l'identificazione personale (informazioni personali sensibili), ovvero soggetti a requisiti legali. Se i dati relativi alle informazioni personali sensibili vengono compromessi o utilizzati in modo improprio, un privato potrebbe essere esposto a un rischio o a un danno significativo. Per ridurre al minimo i rischi per un singolo utente durante l'utilizzo di RAG Engine, non memorizzare e gestire la chiave API ed evita di condividerla non criptata.

Per proteggere le informazioni sensibili relative alla privacy, devi:

  1. Archivia la chiave API in Secret Manager.

  2. Concedi all'account di servizio RAG Engine le autorizzazioni per i tuoi secret e gestisci il controllo dell'accesso a livello di risorsa secret.

    1. Accedi alle autorizzazioni del progetto.

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

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

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

    4. Modifica gli amministratori dell'account di servizio.

    5. Aggiungi il ruolo Secret Manager Secret Accessor all'account di servizio.

  3. Durante la creazione o l'aggiornamento del corpus RAG, passa il nome della risorsa secret a RAG Engine e memorizzalo.

Quando invii richieste API ai tuoi indici Pinecone, RAG Engine utilizza ogni account di servizio per leggere la chiave API corrispondente alle risorse segrete in Secret Manager dai tuoi progetti.

Esegui il provisioning dell'account di servizio RAG Engine

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

L'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 RAG Engine, devi associarlo a un corpus RAG durante la fase di creazione. Una volta creata l'associazione, l'associazione è permanente per tutta la durata del corpus RAG. L'associazione può essere utilizzando l'API CreateRagCorpus o UpdateRagCorpus.

Affinché l'associazione venga considerata completa, devi impostare tre campi chiave: il corpus di RAG:

  • rag_vector_db_config.pinecone: questo campo ti aiuta a impostare la scelta di un database di vettori da associare al tuo corpus RAG e deve essere impostato durante la chiamata dell'API CreateRagCorpus. Se non è impostato, la scelta del database vettoriale predefinita RagManagedDb è assegnata alla tua RAG corpus.

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

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: si tratta del nome completo della risorsa del segreto memorizzato in Secret Manager, che contiene la chiave API Pinecone. Puoi impostare nome durante la chiamata CreateRagCorpus oppure puoi specificare il nome quando chiama l'API UpdateRagCorpus. Finché non specifichi questo campo, non puoi importare nel corpus RAG.
    Questo campo deve avere il seguente formato:
    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Crea il tuo corpus RAG

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

Se è la prima volta che crei un corpus RAG, non avrai a disposizione i dati dell'account servizio. Tuttavia, i campi sono facoltativi e possono essere associati al corpus RAG utilizzando l'API UpdateRagCorpus.

Ad esempio su come creare il corpus RAG senza fornire il servizio informazioni sull'account, consulta Creare un corpus RAG senza un nome di indice o un'API chiave.

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
PINECONE_INDEX_NAME = "YOUR_PINECONE_INDEX_NAME"
API_KEY = "YOUR_SECRET_RESOURCE_NAME"
vector_db = rag.Pinecone(index_name=PINECONE_INDEX_NAME, api_key=API_KEY)

# 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

# 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 il corpus RAG senza un nome di indice o una chiave API

Se questo è il tuo primo corpus RAG e non hai accesso ai dettagli del tuo account 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.

È necessario tenere conto di quanto segue:

  • Se non fornisci il nome dell'indice e il nome segreto della chiave API, i file non possono essere importati nel corpus RAG.
  • Se scegli Pinecone come database di vettori per il tuo corpus RAG, non potrai successivamente passare a un altro database.

Questo esempio di codice mostra come creare un corpus RAG con Pigna senza fornendo un nome indice o un nome API secret della Pigna. Usa UpdateRagCorpus per specificare in seguito 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}

Aggiornare il corpus RAG

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

Campo Modificabilità Obbligatorio o facoltativo
rag_vector_db_config.vector_db Immutabile dopo aver effettuato una scelta. Obbligatorio
rag_vector_db_config.pinecone.index_name Immutabile dopo l'impostazione del campo nel 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