Usa RagManagedDb con el motor de RAG de Vertex AI

En esta página, se muestra cómo Vertex AI RAG Engine usa RagManagedDb, que es una base de datos de vectores lista para la empresa que se usa para almacenar y administrar representaciones vectoriales de tus documentos. Luego, se usa la base de datos de vectores para recuperar documentos relevantes en función de la similitud semántica del documento con una búsqueda determinada.

Además, en esta página, se muestra cómo implementar la CMEK.

Administra tu estrategia de recuperación

RagManagedDb ofrece las siguientes estrategias de recuperación para admitir tus casos de uso de RAG:

Crea un corpus de RAG con KNN RagManagedDb

En esta muestra de código, se muestra cómo crear un corpus de RAG con 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 de RAG con ANN RagManagedDb

Para ofrecer la función de ANN, RagManagedDb usa una estructura basada en árboles para particionar los datos y facilitar búsquedas más rápidas. Para habilitar la mejor recuperación y latencia, la estructura de este árbol debe configurarse mediante experimentación para que se ajuste al tamaño y la distribución de tus datos. RagManagedDb te permite configurar tree_depth y leaf_count del árbol.

El parámetro tree_depth determina la cantidad de capas o niveles del árbol. Para ello, sigue estos lineamientos:

• Si tienes aproximadamente 10,000 archivos RAG en el corpus de RAG, establece el valor en 2.
• Si tienes más archivos RAG, establece este valor en 3.
• Si no se especifica tree_depth, Vertex AI RAG Engine asigna un valor predeterminado de 2 a este parámetro.

El parámetro leaf_count determina la cantidad de nodos hoja en la estructura basada en árboles. Cada nodo hoja contiene grupos de vectores estrechamente relacionados junto con su centroide correspondiente. Para ello, sigue estos lineamientos:

• El valor recomendado es 10 * sqrt(num of RAG files in your RAG corpus).

• Si no se especifica, el motor de RAG de Vertex AI asigna un valor predeterminado de 500 para este parámetro.

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

Cómo importar tus datos a la ANN RagManagedDb

Puedes usar la API de ImportRagFiles o la API de UploadRagFile para importar tus datos al RagManagedDb de ANN. Sin embargo, a diferencia de la estrategia de recuperación de KNN, el enfoque de ANN requiere que el índice subyacente basado en árboles se vuelva a compilar al menos una vez y, de manera opcional, después de importar cantidades significativas de datos para lograr una recuperación óptima. Para que el motor de RAG de Vertex AI vuelva a compilar tu índice de ANN, establece rebuild_ann_index como verdadero en tu solicitud a la API de ImportRagFiles.

Los siguientes son importantes:

1. Antes de consultar el corpus de RAG, debes volver a compilar el índice de ANN al menos una vez.
2. Solo se admite una recompilación de índice simultánea en un proyecto en cada ubicación.

Para subir tu archivo local al corpus de RAG, consulta Sube un archivo RAG. Para importar datos a tu corpus de RAG y activar una recompilación del índice de ANN, consulta la siguiente muestra de código que demuestra cómo importar desde Cloud Storage. Para obtener información sobre las fuentes de datos compatibles, consulta Fuentes de datos compatibles con 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}'
  }
}'

Administra tu encriptación

El motor de RAG de Vertex AI proporciona opciones sólidas para administrar cómo se encriptan tus datos en reposo. De forma predeterminada, todos los datos del usuario en RagManagedDb se encriptan con un Google-owned and Google-managed encryption key, que es el parámetro de configuración predeterminado. Este parámetro de configuración predeterminado te ayuda a verificar que tus datos estén protegidos sin necesidad de realizar ninguna configuración específica.

Si necesitas más control sobre las claves que se usan para la encriptación, el motor de RAG de Vertex AI admite la clave de encriptación administrada por el cliente (CMEK). Con las CMEK, puedes usar tus claves criptográficas, administradas dentro de Cloud Key Management Service (KMS), para proteger los datos de tu corpus de RAG.

Para obtener información sobre las limitaciones de CMEK para los corpus de RAG, consulta Limitaciones de CMEK para el motor de RAG de Vertex AI.

Configura tu clave de KMS y otorga permisos

Antes de crear un corpus de RAG encriptado con CMEK, debes configurar una clave criptográfica en Google Cloud KMS y otorgar a la cuenta de servicio del motor de RAG de Vertex AI los permisos necesarios para usar esta clave.

Requisitos previos

Para realizar los siguientes pasos de configuración, verifica que tu cuenta de usuario tenga los permisos de Identity and Access Management (IAM) adecuados en el proyecto Google Cloud en el que deseas crear la clave del KMS y el corpus de RAG. Por lo general, se requiere un rol como el de administrador de Cloud KMS (roles/cloudkms.admin).

Habilita la API

Para habilitar la API de Cloud KMS, haz lo siguiente:

1. Navega a la consola de Google Cloud .
2. Selecciona el proyecto en el que deseas administrar tus claves y crear tu corpus de RAG.
3. En la barra de búsqueda, escribe “Key Management” y selecciona el servicio “Key Management”.
4. Si la API no está habilitada, haz clic en Habilitar. Es posible que debas esperar unos minutos para que la API se aprovisione por completo.

Crea tu llavero de claves y tu clave de KMS

Para crear un llavero de claves, haz lo siguiente:

1. En la sección Administración de claves, haz clic en Crear llavero de claves.

   Ingresa lo siguiente:

   • Nombre del llavero de claves: Ingresa un nombre único para tu llavero de claves, como rag-engine-cmek-keys.
   • Tipo de ubicación: Selecciona Región.
   • Ubicación: Elige la región seleccionada, como us-central1. Lo ideal es que esta región coincida con la región en la que residirán tus recursos de RAG Engine.

2. Haz clic en Crear.

Para crear una clave dentro del llavero de claves, haz lo siguiente:

1. Después de crear el llavero de claves, se te solicitará que crees una clave o puedes navegar a Crear clave.

   Ingresa lo siguiente:

   • Nombre de la clave: Ingresa un nombre único para la clave, como my-rag-corpus-key.
   • Nivel de protección: Elige un nivel de protección (Software o HSM). Si necesitas claves respaldadas por hardware, selecciona HSM.
   • Propósito: Selecciona Encriptación/desencriptación simétrica. Esto es obligatorio para la CMEK.
   • Fuente del material de clave: Selecciona Clave generada.
   • Período de rotación: Opcional. (recomendado) Configura un programa de rotación de claves según las políticas de seguridad de tu organización, por ejemplo, cada 90 días.

2. Haz clic en Crear.

Para copiar el nombre del recurso de la clave, haz lo siguiente:

1. Después de crear la clave, navega a su página de detalles.

2. Ubica el nombre del recurso. El formato es projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1.

3. Copia el nombre del recurso y quita la parte /cryptoKeyVersions/VERSION_NUMBER. El nombre del recurso con el formato correcto es projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME.

Otorga permisos al agente de servicio de Vertex AI RAG Engine

Para que el motor de RAG de Vertex AI encripte y desencripte datos con tu clave de KMS, su agente de servicio necesita los permisos adecuados en esa clave específica.

Para identificar tu agente de servicio de Vertex AI RAG Engine, haz lo siguiente:

1. Navega a la página IAM y administración > IAM en la consola de Google Cloud tu proyecto.

2. En la página de Identity and Access Management, habilita la casilla de verificación Incluir asignaciones de roles proporcionadas por Google.

3. En la barra de búsqueda o filtro de la lista de principales, busca el agente de servicio de Vertex AI RAG Engine. Sigue el patrón service-YOUR_PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.com.

Para otorgar permisos en la clave de KMS, haz lo siguiente:

1. Vuelve al servicio de administración de claves en la consola de Google Cloud .

2. Selecciona el llavero de claves que contiene la clave que creaste.

3. Selecciona la clave específica que creaste.

4. En la página de detalles de la clave, ve a la pestaña Permisos.

5. Haz clic en Agregar principal.

6. En el campo Principales nuevas, escribe la dirección de correo electrónico del agente de servicio de Vertex AI RAG Engine.

7. En el menú desplegable Seleccionar un rol, selecciona el rol de encriptador/desencriptador de CryptoKey de Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter). Este rol otorga al agente de servicio los permisos necesarios para usar la clave en operaciones de encriptación y desencriptación.

8. Haz clic en Guardar.

Crea un corpus de RAG con encriptación administrada por el cliente

En esta muestra de código, se muestra cómo crear un corpus de RAG encriptado con una clave de encriptación administrada por el cliente (CMEK).

Reemplaza las variables en las siguientes muestras de código:

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

¿Qué sigue?

• Para obtener más información sobre RagManagedDb, consulta Understanding RagManagedDb.
• Para importar archivos y carpetas desde Google Drive o Cloud Storage, consulta el ejemplo de importación de archivos RAG.
• Para enumerar archivos RAG, consulta el ejemplo de enumeración de archivos RAG.