Usar RagManagedDb con el motor de RAG de Vertex AI

En esta página se muestra cómo usa Vertex AI RAG Engine RagManagedDb, que es una base de datos de vectores preparada para empresas que se usa para almacenar y gestionar representaciones vectoriales de tus documentos. A continuación, la base de datos vectorial se usa para recuperar documentos relevantes en función de la similitud semántica del documento con una consulta determinada.

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

Gestionar tu estrategia de recuperación

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

Estrategia de recuperación Descripción
Vecinos más cercanos (KNN) (predeterminado) Busca los vecinos más cercanos exactos comparando todos los puntos de datos de tu corpus de RAG. Si no especificas una estrategia durante la creación de tu corpus de RAG, se usará KNN como estrategia de recuperación predeterminada.
  • Verifica la recuperación perfecta (1.0) durante la recuperación.
  • Ideal para aplicaciones sensibles a la retirada.
  • Ideal para corpus de RAG de tamaño pequeño o mediano, que almacena menos de 10.000 archivos de RAG.
  • Requiere buscar en todos los puntos de datos, por lo que la latencia aumenta con el número de archivos RAG del corpus.
Vecinos más cercanos aproximados (ANN) Usa técnicas de aproximación para encontrar vecinos similares más rápido que la técnica KNN.
  • Reduce significativamente la latencia de las consultas en grandes conjuntos de datos de RAG.
  • El recall se ha reducido ligeramente debido a las técnicas de aproximación utilizadas.
  • Se vuelve muy eficaz cuando tienes grandes conjuntos de datos de RAG, que son aproximadamente más de 10.000 archivos de RAG.
  • La cantidad de pérdida de memoria que puedes aceptar depende del caso de uso, pero en la mayoría de los casos a gran escala, perder un poco de memoria a cambio de un mejor rendimiento de las consultas es una solución aceptable.

Crear un corpus de RAG con KNN RagManagedDb

En este ejemplo de código se muestra cómo crear un corpus de RAG mediante KNN RagManagedDb.

Python 

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

REST

Sustituye las siguientes variables:

  • PROJECT_ID: tu ID de proyecto.
  • LOCATION: la región en la que se procesará la solicitud.
  • CORPUS_DISPLAY_NAME: el nombre visible del corpus de 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": {}
        }
      }
    }'

Crear un corpus de RAG con ANN RagManagedDb

Para ofrecer la función de ANN, RagManagedDb usa una estructura basada en árbol para particionar los datos y facilitar las búsquedas. Para conseguir la mejor latencia y la mayor capacidad de recuperación, la estructura de este árbol debe configurarse mediante experimentación para adaptarse al tamaño y la distribución de tus datos. RagManagedDb te permite configurar el tree_depth y el leaf_count del árbol.

El tree_depth determina el número de capas o niveles del árbol. Sigue estas directrices:

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

El leaf_count determina el número de nodos hoja de la estructura basada en árbol. Cada nodo hoja contiene grupos de vectores estrechamente relacionados junto con su centroide correspondiente. Sigue estas directrices:

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

  • Si no se especifica ningún valor, el motor de RAG de Vertex AI asigna el valor predeterminado de 500 a este parámetro.

Python 

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

REST

Sustituye las siguientes variables:

  • PROJECT_ID: tu ID de proyecto.
  • LOCATION: la región en la que se procesará la solicitud.
  • CORPUS_DISPLAY_NAME: el nombre visible del corpus de RAG.
  • TREE_DEPTH: la profundidad de tu árbol.
  • LEAF_COUNT: número de hojas.
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}"'
          }
        }
      }
    }'

Importar tus datos a la ANN RagManagedDb

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

Es importante tener en cuenta lo siguiente:

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

Para subir un archivo local a tu corpus de RAG, consulta Subir un archivo de RAG. Para importar datos en tu corpus de RAG y activar una recompilación del índice ANN, consulta el siguiente ejemplo de código, que muestra cómo importar datos de Cloud Storage. Para obtener información sobre las fuentes de datos admitidas, consulta Fuentes de datos admitidas para RAG.

Python 

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

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

Gestionar el cifrado

Vertex AI RAG Engine ofrece opciones sólidas para gestionar cómo se cifran tus datos en reposo. De forma predeterminada, todos los datos de usuario de RagManagedDb se cifran con Google-owned and Google-managed encryption key, que es el ajuste predeterminado. Este ajuste predeterminado le ayuda a verificar que sus datos están protegidos sin necesidad de realizar ninguna configuración específica.

Si necesitas más control sobre las claves que usas para el cifrado, el motor RAG de Vertex AI admite claves de cifrado gestionadas por el cliente (CMEK). Con las CMEK, puedes usar tus claves criptográficas, gestionadas en Cloud Key Management Service (KMS), para proteger tus datos del corpus de RAG.

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

Configurar la clave de KMS y conceder permisos

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

Requisitos previos

Para llevar a cabo los siguientes pasos de configuración, comprueba que tu cuenta de usuario tenga los permisos de gestión de identidades y accesos (IAM) adecuados en el Google Cloud proyecto en el que quieras crear la clave de KMS y el corpus de RAG. Normalmente, se requiere un rol como el de administrador de Cloud KMS (roles/cloudkms.admin).

Activar la API

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

  1. Ve a la Google Cloud consola.
  2. Selecciona el proyecto en el que quieras gestionar tus claves y crea tu corpus de RAG.
  3. En la barra de búsqueda, escribe "Gestión de claves" y selecciona el servicio "Gestión de claves".
  4. Si la API no está habilitada, haz clic en Habilitar. Es posible que tengas que esperar unos minutos para que la API se aprovisione por completo.

Crea tu conjunto de claves y tu clave de KMS

Para crear un conjunto de claves, sigue estos pasos:

  1. En la sección Gestión de claves, haz clic en Crear conjunto de claves.

    Introduce lo siguiente:

    • Nombre del conjunto de claves: introduce un nombre único para el conjunto de claves, como rag-engine-cmek-keys.
    • Tipo de ubicación: selecciona Región. El conjunto de claves de Cloud Key Management Service debe estar en la misma región que el endpoint de Vertex AI RAG Engine que utilices al cifrar un corpus de RAG con CMEK.
    • 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 se ubicarán los recursos de tu RAG Engine.

  2. Haz clic en Crear.

Para crear una clave en el conjunto de claves, sigue estos pasos:

  1. Una vez creado el conjunto de claves, se te pedirá que crees una clave o puedes ir a Crear clave.

    Introduce lo siguiente:

    • Nombre de la clave: introduce 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.
    • Finalidad: selecciona Encriptado y desencriptado simétrico. Este campo es obligatorio para usar CMEK.
    • Fuente del material de la clave: seleccione Clave generada.
    • Periodo de rotación: opcional. Recommended. Configura una programación de rotación de claves de acuerdo con 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 clave, sigue estos pasos:

  1. Una vez creada la clave, vaya a su página de detalles.

  2. Busca 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 elimina la parte /cryptoKeyVersions/VERSION_NUMBER. El nombre de recurso con el formato correcto es projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME.

Conceder permisos al agente de servicio del motor de RAG de Vertex AI

Para que el motor RAG de Vertex AI pueda cifrar y descifrar 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. En la Google Cloud consola de tu proyecto, ve a la página IAM y administración > IAM.

  2. En la página Gestión de Identidades y Accesos, marca la casilla Incluir concesiones de roles proporcionadas por Google.

  3. En la barra de filtro o de búsqueda 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.

    Sustituye YOUR_PROJECT_NUMBER por el Google Cloud número de tu proyecto.

Si tu agente de servicio de Vertex AI RAG Engine aún no está presente, haz lo siguiente para activar la creación del agente de servicio:

  1. Habilita la API Resource Manager.

  2. Ejecuta este comando en Cloud Shell o en la línea de comandos:

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

    También puedes enviar la llamada a la 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 que se haya creado el agente de servicio de Vertex AI RAG Engine.

Para conceder permisos en la clave KMS, sigue estos pasos:

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

  2. Selecciona el conjunto de claves que contiene la clave que has creado.

  3. Selecciona la clave específica que has creado.

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

  5. Haz clic en Añadir principal.

  6. En el campo Nuevos principales, escribe la dirección de correo del agente de servicio de Vertex AI RAG Engine.

  7. En el menú desplegable Seleccionar un rol, selecciona el rol Encargado del encriptado y desencriptado de la clave criptográfica Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter). Este rol concede al agente de servicio los permisos necesarios para usar la clave en operaciones de encriptado y desencriptado.

  8. Haz clic en Guardar.

Crear un corpus de RAG con cifrado gestionado por el cliente

Este código de ejemplo muestra cómo crear un corpus de RAG cifrado con una clave de cifrado gestionada por el cliente (CMEK).

Sustituye las variables de los siguientes códigos de ejemplo:

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

Cuotas

Cuando usas CMEK con servicios de Vertex AI, como Vertex AI RAG Engine, hay una cuota sobre el número de claves de Cloud KMS únicas que se pueden usar por proyecto y región. Esta cuota se monitoriza con la métrica aiplatform.googleapis.com/in_use_customer_managed_encryption_keys.

Cada vez que uses una clave de KMS nueva y única para crear un recurso, como un corpus de RAG, en un proyecto y una región, la clave de KMS consumirá una unidad de esta cuota. Esta unidad de cuota no se libera aunque se eliminen los recursos que usan esa clave específica.

Si necesitas más claves únicas que el límite actual, debes solicitar un aumento de cuota para aiplatform.googleapis.com/in_use_customer_managed_encryption_keys en la región seleccionada.

Para obtener más información sobre cómo solicitar un aumento de la cuota, consulta Ver y editar las cuotas en la consola Google Cloud .

Siguientes pasos