Utilizzare RagManagedDb con il motore RAG di Vertex AI

Questa pagina mostra come Vertex AI RAG Engine utilizza RagManagedDb, un database vettoriale pronto per l'uso aziendale utilizzato per archiviare e gestire le rappresentazioni vettoriali dei tuoi documenti. Il database vettoriale viene quindi utilizzato per recuperare documenti pertinenti in base alla somiglianza semantica del documento con una determinata query.

Inoltre, questa pagina mostra come implementare CMEK.

Gestire la strategia di recupero

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

Crea un corpus RAG con KNN RagManagedDb

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

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Vertex AI 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))

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

Crea 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 migliore latenza, la struttura di questo albero deve essere configurata tramite sperimentazione in modo che si adatti 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 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, Vertex AI RAG Engine assegna un valore predefinito di 2 a questo parametro.

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

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

• Se non specificato, Vertex AI RAG Engine assegna a questo parametro un valore predefinito di 500.

from vertexai 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 Vertex AI 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))

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

Importazione dei dati in ANN RagManagedDb

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

Sono importanti i seguenti aspetti:

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

Per caricare il file locale nel corpus RAG, consulta Caricare un file RAG. Per importare i dati nel corpus RAG e attivare la ricompilazione 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.

from vertexai 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 Vertex AI 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()

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

Vertex AI RAG Engine offre opzioni solide per gestire la modalità di crittografia dei dati at-rest. Per impostazione predefinita, tutti i dati utente all'interno di RagManagedDb sono criptati utilizzando un Google-owned and Google-managed encryption key, che è l'impostazione predefinita. Questa impostazione predefinita ti consente di 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 di Vertex AI supporta la chiave di crittografia gestita dal cliente (CMEK). Con CMEK, puoi utilizzare le tue chiavi crittografiche, gestite in Cloud Key Management Service (KMS), per proteggere i dati del corpus RAG.

Per informazioni sulle limitazioni di CMEK per i corpus RAG, consulta la sezione Limitazioni di CMEK per Vertex AI RAG Engine.

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

Abilita l'API

Per abilitare l'API Cloud KMS:

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. Potresti dover attendere alcuni minuti per il provisioning completo dell'API.

Crea il keyring e la chiave KMS

Per creare un portachiavi:

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.
   • Località: scegli la regione selezionata, ad esempio us-central1. Questa regione deve corrispondere idealmente a quella in cui risiederanno le risorse del motore RAG.

2. Fai clic su Crea.

Per creare una chiave all'interno del portachiavi:

1. Dopo aver creato il keyring, ti verrà chiesto di creare una chiave oppure potrai andare su 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/decriptazione simmetrica. Questo è necessario per CMEK.
   • Origine materiale chiave: seleziona Chiave generata.
   • Periodo di rotazione: facoltativo. Consigliato. Configura una pianificazione rotazione della chiave in base ai criteri 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.

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 di Vertex AI

Affinché il motore RAG di Vertex AI possa criptare e decriptare i dati utilizzando la tua chiave KMS, il suo service agent deve disporre delle autorizzazioni appropriate per quella chiave specifica.

Per identificare l'agente di servizio Vertex AI RAG Engine, procedi nel seguente modo:

1. Vai alla pagina IAM e amministrazione > IAM nella console Google Cloud 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 dei filtri dell'elenco dei principal, cerca l'agente di servizio Vertex AI RAG Engine. Segue il pattern service-YOUR_PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.com.

Per concedere le autorizzazioni sulla chiave KMS:

1. Torna al servizio Key Management 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 di Vertex AI RAG Engine.

7. Nel menu a discesa Seleziona un ruolo, seleziona il ruolo Autore crittografia/decrittografia CryptoKey Cloud KMS (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 una chiave di crittografia gestita dal cliente (CMEK).

Sostituisci le variabili nei seguenti esempi di codice:

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

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

Passaggi successivi

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