Utilizzare RagManagedDb con il motore RAG su Gemini Enterprise Agent Platform

I controlli di sicurezza dei Controlli di servizio VPC e CMEK sono supportati dal motore RAG della piattaforma dell'agente. I controlli di sicurezza della residenza dei dati e di AXT non sono supportati.

L'istanza Spanner gestita da RAG Engine viene utilizzata come database vettoriale ed è in disponibilità generale con la fatturazione abilitata. Per saperne di più, consulta Fatturazione di RAG Engine su Gemini Enterprise Agent Platform.

Questa pagina mostra come il motore RAG su Gemini Enterprise Agent Platform utilizza RagManagedDb, un database vettoriale di livello enterprise utilizzato per archiviare e gestire le rappresentazioni vettoriali dei tuoi documenti. Il database vettoriale viene quindi utilizzato per recuperare i documenti pertinenti in base alla somiglianza semantica del documento con una determinata query.

Inoltre, questa pagina mostra come implementare CMEK.

Importante: RagManagedDb viene utilizzato per impostazione predefinita e utilizza Spanner. Ai clienti verrà addebitato l'utilizzo di un'istanza Spanner gestita da Google di cui è stato eseguito il provisioning in un progetto tenant di Google utilizzando gli SKU Spanner standard.

Gestisci la strategia di recupero

RagManagedDb offre le seguenti strategie di recupero per supportare i tuoi casi d'uso RAG:

Strategia di recupero	Descrizione
k-Nearest Neighbors (KNN) (predefinito)	Trova i vicini più prossimi esatti confrontando tutti i punti dati nel corpus RAG. Se non specifichi una strategia durante la creazione del corpus RAG, KNN è la strategia di recupero predefinita utilizzata.	Verifica il richiamo perfetto (1.0) durante il recupero. Ideale per le applicazioni sensibili al richiamo. Ideale per corpora RAG di piccole e medie dimensioni, che memorizzano meno di 10.000 file RAG. Richiede la ricerca in ogni singolo punto dati, pertanto la latenza aumenta con il numero di file RAG nel corpus.
Approximate Nearest Neighbors (ANN)	Utilizza tecniche di approssimazione per trovare vicini simili più velocemente rispetto alla tecnica KNN.	Riduce significativamente le latenze delle query su corpora RAG di grandi dimensioni. Il richiamo è leggermente inferiore a causa delle tecniche di approssimazione utilizzate. Diventa molto efficace quando hai corpora RAG di grandi dimensioni, ovvero circa più di 10.000 file RAG. La quantità di perdita di richiamo accettabile dipende dal caso d'uso, ma nella maggior parte dei casi su larga scala, perdere un po' di richiamo in cambio di un miglioramento delle prestazioni delle query è un compromesso accettabile.

Crea un corpus RAG con KNN RagManagedDb

Questo esempio di codice mostra come creare un corpus RAG utilizzando KNN RagManagedDb.

Python

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Agent Platform 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))

REST

Sostituisci le seguenti variabili:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• CORPUS_DISPLAY_NAME: il nome visualizzato del corpus RAG.

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

Anteprima

Alcune delle funzionalità RAG sono offerte in anteprima, soggette ai "Termini dell'offerta pre-GA" dei Termini di servizio specifici per Google Cloud. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Inoltre, le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Per ulteriori informazioni, consulta le descrizioni della fase di lancio. Utilizzando l'API Gemini su Gemini Enterprise Agent Platform, accetti i termini e condizioni dell'AI generativa in anteprima (Termini di anteprima).

Crea un corpus RAG con ANN RagManagedDb

Per offrire la funzionalità ANN, RagManagedDb utilizza una struttura ad albero per partizionare i dati e facilitare ricerche più rapide. Per ottenere il miglior richiamo e la migliore latenza, la struttura di questo albero deve essere configurata tramite sperimentazione per adattarsi alle dimensioni e alla distribuzione dei dati. RagManagedDb ti consente di configurare tree_depth e leaf_count dell'albero.

tree_depth determina il numero di strati o livelli nell'albero. Segui queste linee guida:

• Se nel corpus RAG sono presenti circa 10.000 file RAG, imposta il valore su 2.
• Se hai più file RAG, imposta questo valore su 3.
• Se tree_depth non è specificato, il motore RAG assegna un valore predefinito pari a 2 per questo parametro.

leaf_count determina il numero di nodi foglia nella struttura basata su albero. Ogni nodo foglia contiene gruppi di vettori strettamente correlati insieme al relativo centroide corrispondente. Segui queste linee guida:

• Il valore consigliato è 10 * sqrt(num of RAG files in your RAG corpus).

• Se non specificato, il motore RAG assegna un valore predefinito di 500 per questo parametro.

Python

from vertexai.preview 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 Agent Platform 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))

REST

Sostituisci le seguenti variabili:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• CORPUS_DISPLAY_NAME: il nome visualizzato del corpus RAG.
• TREE_DEPTH: la profondità dell'albero.
• LEAF_COUNT: il numero di Foglioline.

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

Anteprima

Alcune delle funzionalità RAG sono offerte in anteprima, soggette ai "Termini dell'offerta pre-GA" dei Termini di servizio specifici per Google Cloud. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Inoltre, le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Per ulteriori informazioni, consulta le descrizioni della fase di lancio. Utilizzando l'API Gemini su Gemini Enterprise Agent Platform, accetti i termini e condizioni dell'AI generativa in anteprima (Termini di anteprima).

Importazione dei dati in ANN RagManagedDb

Puoi utilizzare l'API ImportRagFiles o l'API UploadRagFile per importare i dati nell'ANN RagManagedDb. Tuttavia, a differenza della strategia di recupero KNN, l'approccio ANN richiede la ricostruzione dell'indice basato su albero sottostante almeno una volta e, facoltativamente, dopo l'importazione di quantità significative di dati per un richiamo ottimale. Per fare in modo che RAG Engine ricostruisca l'indice ANN, imposta rebuild_ann_index su true nella richiesta API ImportRagFiles.

I seguenti sono importanti:

1. Prima di eseguire una query sul corpus RAG, devi ricreare l'indice ANN almeno una volta.
2. È supportata una sola ricostruzione dell'indice simultanea per un progetto in ogni località.

Per caricare il file locale nel corpus RAG, consulta Carica un file RAG. Per importare i dati nel corpus RAG e attivare la ricostruzione dell'indice ANN, consulta il seguente esempio di codice che mostra come importare da Cloud Storage. Per scoprire di più sulle origini dati supportate, consulta Origini dati supportate per RAG.

Python

from vertexai.preview 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 Agent Platform 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()

REST

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

Gestisci la crittografia

RAG Engine offre opzioni efficaci per gestire la crittografia dei dati at-rest. Per impostazione predefinita, tutti i dati utente all'interno di RagManagedDb vengono criptati utilizzando una Google-owned and Google-managed encryption key, che è l'impostazione predefinita. Questa impostazione predefinita ti aiuta a verificare che i tuoi dati siano protetti senza richiedere alcuna configurazione specifica.

Se hai bisogno di un maggiore controllo sulle chiavi utilizzate per la crittografia, il motore RAG supporta le chiavi di crittografia gestite dal cliente (CMEK). Con CMEK, puoi utilizzare le tue chiavi di crittografia, gestite all'interno di Cloud Key Management Service (Cloud KMS), per proteggere i dati del corpus RAG.

Per informazioni sulle limitazioni CMEK per i corpus RAG, consulta Limitazioni CMEK per il motore RAG su Gemini Enterprise Agent Platform.

Configura la chiave Cloud KMS e concedi le autorizzazioni

Prima di poter creare un corpus RAG criptato con CMEK, devi configurare una chiave di crittografia in Google Cloud KMS e concedere al account di servizio RAG Engine le autorizzazioni necessarie per utilizzare questa chiave.

Prerequisiti

Per eseguire i seguenti passaggi di configurazione, verifica che il tuo account utente disponga delle autorizzazioni Identity and Access Management (IAM) appropriate nel progetto Google Cloud in cui intendi creare la chiave Cloud KMS e il corpus RAG. In genere, è richiesto un ruolo come il ruolo Cloud KMS Admin (roles/cloudkms.admin).

Abilita l'API

Per abilitare l'API Cloud Key Management Service, segui questi passaggi:

1. Vai alla console Google Cloud .
2. Seleziona il progetto in cui vuoi gestire le chiavi e crea il corpus RAG.
3. Nella barra di ricerca, digita "Key Management" e seleziona il servizio "Key Management".
4. Se l'API non è abilitata, fai clic su Abilita. Potrebbe essere necessario attendere alcuni minuti per il provisioning completo dell'API.

Crea la chiave automatizzata e la chiave Cloud KMS

Per creare un keyring, segui questi passaggi:

1. Nella sezione Gestione chiavi, fai clic su Crea chiavi automatizzate.

   Inserisci quanto segue:

   • Nome chiavi automatizzate: inserisci un nome univoco per le chiavi automatizzate, ad esempio rag-engine-cmek-keys.
   • Tipo di località: seleziona Regione. Il keyring Cloud KMS deve trovarsi nella stessa regione dell'endpoint RAG Engine che utilizzi quando cripti un corpus RAG con CMEK.
   • Località: scegli la regione selezionata, ad esempio us-central1. Questa regione dovrebbe idealmente corrispondere a quella in cui risiederanno le risorse di RAG Engine.

2. Fai clic su Crea.

Per creare una chiave all'interno delle chiavi automatizzate, segui questi passaggi:

1. Dopo aver creato il keyring, ti verrà chiesto di andare o potrai andare a Crea chiave.

   Inserisci quanto segue:

   • Nome chiave: inserisci un nome univoco per la chiave, ad esempio my-rag-corpus-key.
   • Livello di protezione: scegli un livello di protezione (Software o HSM). Se hai bisogno di chiavi con integrazione hardware, seleziona HSM.
   • Scopo: seleziona Crittografia/decrittografia simmetrica. Questo è obbligatorio per CMEK.
   • Origine del materiale della chiave: seleziona Chiave generata.
   • Periodo di rotazione: facoltativo. Consigliata. Configura una pianificazione rotazione della chiave in base alle policy di sicurezza della tua organizzazione, ad esempio ogni 90 giorni.

2. Fai clic su Crea.

Per copiare il nome della risorsa chiave, segui questi passaggi:

1. Una volta creata la chiave, vai alla relativa pagina dei dettagli.

2. Individua il nome della risorsa. Il formato è projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1.

   Importante: per EncryptionSpec nel corpus RAG, devi utilizzare il nome della risorsa della chiave senza il numero di versione.

3. Copia il nome della risorsa e rimuovi la parte /cryptoKeyVersions/VERSION_NUMBER. Il nome della risorsa formattato correttamente è projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME.

Concedi le autorizzazioni all'agente di servizio del motore RAG

Affinché il motore RAG possa criptare e decriptare i dati utilizzando la tua chiave Cloud KMS, il relativo agente di servizio deve disporre delle autorizzazioni appropriate su quella chiave specifica.

Per identificare l'agente di servizio RAG Engine, segui questi passaggi:

1. Vai alla pagina IAM e amministrazione > IAM nella console Google Cloud per il tuo progetto.

2. Nella pagina Identity and Access Management, attiva la casella di controllo Includi concessioni di ruoli fornite da Google.

3. Nella barra di filtro o di ricerca dell'elenco delle entità, cerca l'agente di servizio RAG Engine. Segue il pattern [e-mail].

   Sostituisci YOUR_PROJECT_NUMBER con il numero di progetto Google Cloud .

Se l'agente di servizio RAG Engine non è ancora presente, segui questi passaggi per attivare la creazione dell'agente di servizio:

1. Abilita l'API Resource Manager.

2. Esegui questo comando in Cloud Shell o nella riga di comando:

   gcloud beta services identity create --service=aiplatform.googleapis.com \
       --projects=PROJECT_ID
   

   In alternativa, invia la chiamata API REST:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json; charset=utf-8" -d "" "https://serviceusage.googleapis.com/v1beta1/projects/PROJECT_ID/services/aiplatform.googleapis.com:generateServiceIdentity"
   

3. Verifica che l'agente di servizio del motore RAG sia stato creato.

Per concedere le autorizzazioni per la chiave Cloud KMS, segui questi passaggi:

1. Torna al servizio Cloud KMS nella console Google Cloud .

2. Seleziona il keyring contenente la chiave che hai creato.

3. Seleziona la chiave specifica che hai creato.

4. Nella pagina dei dettagli della chiave, vai alla scheda Autorizzazioni.

5. Fai clic su Aggiungi entità.

6. Nel campo Nuove entità, digita l'indirizzo email dell'agente di servizio del motore RAG.

7. Nel menu a discesa Seleziona un ruolo, seleziona il ruolo Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter). Questo ruolo concede all'agente di servizio le autorizzazioni necessarie per utilizzare la chiave per le operazioni di crittografia e decrittografia.

8. Fai clic su Salva.

Crea un corpus RAG con crittografia gestita dal cliente

Questo esempio di codice mostra come creare un corpus RAG criptato con chiavi di crittografia gestite dal cliente (CMEK).

Sostituisci le variabili nei seguenti esempi di codice:

Python

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

REST

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

Quote

Quando utilizzi CMEK con i servizi Gemini Enterprise Agent Platform, come il motore RAG su Gemini Enterprise Agent Platform, esiste una quota sul numero di chiavi Cloud KMS univoche che possono essere utilizzate per progetto per regione. Questa quota è monitorata dalla metrica aiplatform.googleapis.com/in_use_customer_managed_encryption_keys.

Ogni volta che utilizzi una nuova chiave Cloud KMS univoca per creare una risorsa come un corpus RAG all'interno di un progetto e di una regione, la chiave Cloud KMS consuma un'unità di questa quota. Questa unità di quota non viene rilasciata anche se le risorse che utilizzano la chiave specifica vengono eliminate.

Se hai bisogno di più chiavi univoche rispetto al limite attuale, devi richiedere un aumento della quota per aiplatform.googleapis.com/in_use_customer_managed_encryption_keys per la regione selezionata.

Per saperne di più su come richiedere un aumento della quota, consulta Visualizza e modifica le quote nella console Google Cloud .

Passaggi successivi

• Per scoprire di più su RagManagedDb, consulta Modalità di deployment.
• Per importare file e cartelle da Google Drive o Cloud Storage, consulta l'esempio di importazione di file RAG.
• Per elencare i file RAG, consulta l'esempio di elenco dei file RAG.