Usa RagManagedDb con el motor RAG en Gemini Enterprise Agent Platform

Los controles de seguridad de VPC-SC y CMEK son compatibles con el motor de RAG de Agent Platform. No se admiten la residencia de datos ni los controles de seguridad de AXT.

La instancia de Spanner administrada por RAG Engine se usa como base de datos de vectores y está en DG con la facturación habilitada. Para obtener más información, consulta Facturación de RAG Engine en Gemini Enterprise Agent Platform.

En esta página, se muestra cómo RAG Engine en Gemini Enterprise Agent Platform usa RagManagedDb, que es una base de datos de vectores lista para empresas que se usa para almacenar y administrar representaciones vectoriales de tus documentos. Luego, la base de datos de vectores se usa para recuperar documentos relevantes en función de su similitud semántica con una consulta determinada.

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

Importante: RagManagedDb se usa de forma predeterminada y utiliza Spanner. Se les cobrará a los clientes por el uso de una instancia de Spanner administrada por Google que se aprovisiona en un proyecto de usuario de Google con los SKU estándar de Spanner.

Administra tu estrategia de recuperación

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

Estrategia de recuperación	Descripción
k-vecinos más cercanos (KNN) (predeterminado)	Encuentra 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, KNN es la estrategia de recuperación predeterminada que se usa.	Verifica la recuperación perfecta (1.0) durante la recuperación. Es ideal para aplicaciones sensibles a la recuperación. Es ideal para corpus de RAG de tamaño pequeño a mediano, que almacenan menos de 10,000 archivos de RAG. Requiere buscar en cada punto de datos, por lo que la latencia aumenta con la cantidad de archivos de RAG en el 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 de KNN.	Reduce significativamente las latencias de las consultas en corpus de RAG grandes. La recuperación se redujo ligeramente debido a las técnicas de aproximación utilizadas. Se vuelve muy eficaz cuando tienes corpus de RAG grandes, que son aproximadamente más de 10,000 archivos de RAG. La cantidad de pérdida de recuperación que es aceptable para ti depende del caso de uso, pero en la mayoría de los casos a gran escala, perder un poco de recuperación a cambio de un mejor rendimiento de las consultas es una compensación aceptable.

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.

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

Reemplaza las siguientes variables:

• PROJECT_ID: ID del proyecto.
• LOCATION: Es la región para procesar la solicitud.
• CORPUS_DISPLAY_NAME: Es 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": {}
        }
      }
    }'

Vista previa

Algunas de las funciones de RAG son ofertas de versión preliminar, sujetas a las "Condiciones de las ofertas de la fase previa a la DG" de las Condiciones específicas del servicio de Google Cloud. Los productos y las características anteriores a la DG están disponibles "tal cual" y pueden tener asistencia limitada, y los cambios en estos productos y características podrían no ser compatibles con otras versiones de la fase previa a la DG. Para obtener más información, consulta las descripciones de la etapa de lanzamiento. Si usas la API de Gemini en Gemini Enterprise Agent Platform, aceptas los Términos y Condiciones de la versión preliminar de la IA generativa (Términos de la versión preliminar).

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 se debe configurar mediante la experimentación para que se ajuste al tamaño y la distribución de tus datos. RagManagedDb te permite configurar el tree_depth y el leaf_count del árbol.

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

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

El 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 asigna un valor predeterminado de 500 para este parámetro.

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

Reemplaza las siguientes variables:

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

Vista previa

Algunas de las funciones de RAG son ofertas de versión preliminar, sujetas a las "Condiciones de las ofertas de la fase previa a la DG" de las Condiciones específicas del servicio de Google Cloud. Los productos y las características anteriores a la DG están disponibles "tal cual" y pueden tener asistencia limitada, y los cambios en estos productos y características podrían no ser compatibles con otras versiones de la fase previa a la DG. Para obtener más información, consulta las descripciones de la etapa de lanzamiento. Si usas la API de Gemini en Gemini Enterprise Agent Platform, aceptas los Términos y Condiciones de la versión preliminar de la IA generativa (Términos de la versión preliminar).

Importa tus datos a 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 basado en árboles subyacente se vuelva a compilar al menos una vez y, de forma opcional, después de importar cantidades significativas de datos para obtener una recuperación óptima. Para que RAG Engine vuelva a compilar tu índice de ANN, establece rebuild_ann_index en 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 reconstrucción de índice simultánea en un proyecto en cada ubicación.

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

Administra tu encriptación

RAG Engine 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 una 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 seguros sin necesidad de realizar ninguna configuración específica.

Si necesitas más control sobre las claves que usas para la encriptación, el motor de RAG admite claves de encriptación administradas por el cliente (CMEK). Con CMEK, puedes usar tus claves criptográficas, administradas en Cloud Key Management Service (Cloud 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 RAG Engine en Gemini Enterprise Agent Platform.

Configura tu clave de Cloud 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 de RAG Engine 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 de Google Cloud en el que pretendes crear la clave de Cloud 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 Key Management Service, sigue estos pasos:

1. Navega a la consola de Google Cloud .
2. Selecciona el proyecto en el que deseas administrar tus claves y crea tu corpus de RAG.
3. En la barra de búsqueda, escribe "Administración de claves" y selecciona el servicio "Administración de claves".
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 Cloud 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. El llavero de claves de Cloud KMS debe estar en la misma región que el extremo del motor de RAG que usas cuando encriptas 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 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 indicará 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 guardadas en hardware, selecciona HSM.
   • Propósito: Selecciona Encriptación/desencriptación simétrica. Esto es obligatorio para las 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 clave, haz lo siguiente:

1. Después de crear la clave, navega 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.

   Importante: Para la EncryptionSpec en tu corpus de RAG, debes usar el nombre del recurso de clave sin el número de versión.

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 RAG Engine

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

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

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

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

3. En la barra de filtro o búsqueda de la lista de principales, busca el agente de servicio de RAG Engine. Sigue el patrón [e-mail].

   Reemplaza YOUR_PROJECT_NUMBER por el número del proyecto de Google Cloud .

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

1. Habilita la API de 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
   

   Como alternativa, envía la llamada a la API de 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 RAG Engine.

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

1. Regresa al servicio de Cloud KMS 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 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 las 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 claves de encriptación administradas por el cliente (CMEK).

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

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 los servicios de Gemini Enterprise Agent Platform, como el motor de RAG en Gemini Enterprise Agent Platform, hay una cuota para la cantidad de claves de Cloud KMS únicas que se pueden usar por proyecto y por región. Esta cuota se supervisa con la métrica aiplatform.googleapis.com/in_use_customer_managed_encryption_keys.

Cada vez que usas una clave de Cloud KMS nueva y única para crear un recurso, como un corpus de RAG, dentro de un proyecto y una región, la clave de Cloud KMS consume una unidad de esta cuota. Esta unidad de cuota no se libera, incluso si se borran 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 cuota, consulta Visualiza y edita las cuotas en la consola de Google Cloud .

¿Qué sigue?

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