Utilizzare RagManagedDb con il motore RAG su Gemini Enterprise Agent Platform

I controlli di sicurezza VPC-SC e CMEK sono supportati da RAG Engine di Agent Platform. I controlli di sicurezza di residenza dei dati e AXT non sono supportati.

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

Questa pagina mostra come RAG Engine su Gemini Enterprise Agent Platform utilizza RagManagedDb, un database vettoriale di livello enterprise utilizzato per archiviare e gestire le rappresentazioni vettoriali dei documenti. Il database vettoriale viene quindi utilizzato per recuperare i documenti pertinenti in base alla similarità 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 con tenant Google utilizzando gli SKU Spanner standard.

Gestire la strategia di recupero

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

Strategia di recupero	Descrizione
K-Nearest Neighbors (KNN) (predefinita)	Trova i vicini più prossimi esatti confrontando tutti i punti dati nel tuo 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 i corpus RAG di piccole e medie dimensioni, che archiviano 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 i vicini simili più velocemente rispetto a la tecnica KNN.	Riduce significativamente le latenze delle query sui corpus RAG di grandi dimensioni. Richiamo leggermente ridotto a causa delle tecniche di approssimazione utilizzate. Diventa molto efficace quando hai corpus 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 prestazioni delle query migliorate è un compromesso accettabile.

Creare 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: l'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 specifici di servizio di 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 saperne di più, consulta le descrizioni della fase di lancio. Utilizzando l'API Gemini su Gemini Enterprise Agent Platform, accetti i termini e condizioni dell'anteprima dell'AI generativa (Termini dell'anteprima ).

Creare un corpus RAG con ANN RagManagedDb

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

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

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

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

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

• Se non specificato, RAG Engine assegna un valore predefinito di 500 a 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: l'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 foglie.

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 specifici di servizio di 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 saperne di più, consulta le descrizioni della fase di lancio. Utilizzando l'API Gemini su Gemini Enterprise Agent Platform, accetti i termini e condizioni dell'anteprima dell'AI generativa (Termini dell'anteprima ).

Importare i dati in ANN RagManagedDb

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

Di seguito sono riportati alcuni aspetti importanti:

1. Prima di eseguire query sul corpus RAG, devi ricompilare l'indice ANN almeno una volta.
2. In ogni località è supportata una sola ricompilazione simultanea dell'indice in un progetto.

Per caricare il file locale nel corpus RAG, consulta Caricare un file RAG. Per importare i dati nel corpus RAG e attivare una ricompilazione dell'indice ANN, consulta l'esempio di codice seguente 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}'
  }
}'

Gestire la crittografia

RAG Engine offre opzioni robuste per la gestione della crittografia dei dati at-rest. Per impostazione predefinita, tutti i dati utente in RagManagedDb vengono criptati utilizzando a 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, RAG Engine supporta la chiave di crittografia gestita dal cliente (CMEK). Con CMEK, puoi utilizzare le chiavi di crittografia, gestite all'interno di Cloud Key Management Service (KMS), per proteggere i dati del corpus RAG.

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

Configurare la chiave KMS e concedere 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 di 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 di Identity and Access Management (IAM) appropriate nel Google Cloud progetto in cui intendi creare la chiave KMS e il corpus RAG. In genere è richiesto un ruolo come il ruolo Cloud KMS Admin (roles/cloudkms.admin).

Abilitare l'API

Per abilitare l'API Cloud Key Management Service:

1. Vai alla Google Cloud console.
2. Seleziona il progetto in cui vuoi gestire le chiavi e crea il corpus RAG.
3. Nella barra di ricerca, digita "Gestione chiavi" e seleziona il servizio "Gestione chiavi".
4. Se l'API non è abilitata, fai clic su Abilita. Potresti dover attendere qualche minuto prima che l'API venga completamente sottoposta a provisioning.

Creare il keyring e la chiave KMS

Per creare un keyring:

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

   Inserisci quanto segue:

   • Nome keyring: inserisci un nome univoco per il keyring, ad esempio rag-engine-cmek-keys.
   • Tipo di località: seleziona Regione. Il keyring di Cloud Key Management Service deve trovarsi nella stessa regione dell'endpoint di RAG Engine che stai utilizzando quando cripti un corpus RAG con CMEK.
   • Località: scegli la regione selezionata, ad esempio us-central1. Idealmente, questa regione dovrebbe corrispondere alla regione in cui risiederanno le risorse di RAG Engine.

2. Fai clic su Crea.

Per creare una chiave all'interno del keyring:

1. Una volta creato il keyring, ti verrà chiesto di creare una chiave oppure puoi 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 supportate dall'hardware, seleziona HSM.
   • Finalità: seleziona Crittografia/decrittografia simmetrica. Questo è obbligatorio per CMEK.
   • Origine del materiale della chiave: seleziona Chiave generata.
   • Periodo di rotazione: facoltativo. Consigliato. 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:

1. Una volta creata la chiave, vai alla 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 chiave senza il numero di versione.

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

Concedere le autorizzazioni al service agent di RAG Engine

Affinché RAG Engine possa criptare e decriptare i dati utilizzando la chiave KMS, il relativo service agent deve disporre delle autorizzazioni appropriate per quella chiave specifica.

Per identificare il service agent di RAG Engine:

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

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

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

   Sostituisci YOUR_PROJECT_NUMBER con il numero del tuo Google Cloud progetto.

Se il service agent di RAG Engine non è ancora presente, segui questi passaggi per attivare la creazione del service agent:

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 il service agent di RAG Engine sia stato creato.

Per concedere le autorizzazioni per la chiave KMS:

1. Torna al servizio Gestione chiavi nella Google Cloud console.

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 del service agent di RAG Engine.

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

8. Fai clic su Salva.

Creare un corpus RAG con crittografia gestita dal cliente

Questo esempio di codice mostra come creare un corpus RAG criptato con una chiave di crittografia gestita dal cliente (CMEK).

Sostituisci le variabili negli esempi di codice seguenti:

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 di Gemini Enterprise Agent Platform, come RAG Engine su Gemini Enterprise Agent Platform, esiste una quota sul numero di chiavi Cloud KMS univoche che possono essere in uso per progetto per regione. Questa quota viene monitorata dalla metrica aiplatform.googleapis.com/in_use_customer_managed_encryption_keys.

Ogni volta che utilizzi una nuova chiave KMS univoca per creare una risorsa come un corpus RAG all'interno di un progetto e di una regione, la chiave KMS consuma un'unità di questa quota. Questa unità di quota non viene rilasciata anche se le risorse che utilizzano quella 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 Visualizzare e modificare le quote nella Google Cloud console.

Passaggi successivi

• Per saperne 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.