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 RAG de Agent Platform. No se admiten los controles de seguridad de residencia de datos ni AXT.

La instancia de Spanner administrada por el motor RAG se usa como una base de datos de vectores y está disponible de forma general con la facturación habilitada. Para obtener más información, consulta Facturación del motor RAG en Agent Platform de Gemini Enterprise billing.

En esta página, se muestra cómo el motor RAG en Gemini Enterprise Agent Platform 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, 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 CMEK.

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

Administra 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
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. Ideal para aplicaciones sensibles a la recuperación. Ideal para corpus de RAG de tamaño pequeño a mediano, que almacenan menos de 10,000 archivos RAG. Requiere buscar en cada punto de datos, por lo que la latencia aumenta con la cantidad de archivos 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 KNN.	Reduce significativamente las latencias de las consultas en corpus de RAG grandes. La recuperación se reduce ligeramente debido a las técnicas de aproximación que se usan. Se vuelve muy eficaz cuando tienes corpus de RAG grandes, que son aproximadamente más de 10,000 archivos 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 rendimiento mejorado 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: Es el 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 vista previa, 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 funciones anteriores a la disponibilidad general están disponibles "tal cual" y pueden tener asistencia limitada, y los cambios en estos productos y funciones 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 IA generativa (Términos de versión preliminar).

Crea un corpus de RAG con ANN RagManagedDb

Para ofrecer la función ANN, RagManagedDb usa una estructura basada en árbol para particionar 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 la experimentación para adaptarse al tamaño y la distribución de tus datos. RagManagedDb te permite configurar la tree_depth y la 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 RAG en el corpus de RAG, establece el valor en 2.
• Si tienes más archivos RAG que eso, establécelo en 3.
• Si no se especifica tree_depth, el motor 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 árbol. 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 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: Es el 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 el 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 vista previa, 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 funciones anteriores a la disponibilidad general están disponibles "tal cual" y pueden tener asistencia limitada, y los cambios en estos productos y funciones 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 IA generativa (Términos de versión preliminar).

Importa tus datos a ANN RagManagedDb

Puedes usar la API de ImportRagFiles o la API de UploadRagFile para importar tus datos a 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, de manera opcional, después de importar cantidades significativas de datos para una recuperación óptima. Para que el motor RAG vuelva a compilar tu índice de ANN, establece rebuild_ann_index en true en tu solicitud a la API de ImportRagFiles.

A continuación, se incluyen aspectos 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 a tu corpus de RAG, consulta Sube un archivo RAG file. Para importar datos a tu corpus de RAG y activar una recompilación de índice de ANN, consulta la siguiente muestra de código que muestra 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

El motor RAG proporciona opciones sólidas para administrar cómo se encriptan tus datos en reposo. De forma predeterminada, todos los datos del usuario dentro de RagManagedDb se encriptan con Google-owned and Google-managed encryption key, que es la configuración predeterminada. Esta configuración predeterminada te ayuda a verificar que tus datos estén protegidos sin requerir ninguna configuración específica.

Si necesitas más control sobre las claves que se usan para la encriptación, el motor RAG admite la clave de encriptación administrada por el cliente (CMEK). Con 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 corpus de RAG, consulta Limitaciones de CMEK para el motor RAG en Gemini Enterprise Agent Platform.

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 RAG 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 adecuados de Identity and Access Management (IAM) en el Google Cloud proyecto en el que deseas crear la clave de KMS y el corpus de RAG. Por lo general, se requiere un rol como el rol de administrador de Cloud KMS (roles/cloudkms.admin).

Habilita la API

Para habilitar la API de Cloud Key Management Service, haz lo siguiente:

1. Navega a la Google Cloud consola de.
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 “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 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. El llavero de claves de Cloud Key Management Service debe estar en la misma región que el extremo del motor 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 del motor RAG.

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 lo hagas o puedes navegar a Crear clave.

   Ingresa lo siguiente:

   • Nombre de la clave: Ingresa un nombre único para tu 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 CMEK.
   • Fuente de 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, como 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 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 del motor RAG

Para que el motor RAG 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 del motor RAG, haz lo siguiente:

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

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

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

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

Si tu agente de servicio del motor RAG 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 del motor RAG.

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

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

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 del motor RAG.

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 una clave encriptada administrada 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 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 realiza un seguimiento con la métrica aiplatform.googleapis.com/in_use_customer_managed_encryption_keys.

Cada vez que usas una clave de KMS nueva y única para crear un recurso como un corpus de RAG dentro de un proyecto y una región, la clave de 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 para la región seleccionada.

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

¿Qué sigue?

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