Usar RagManagedDb com o mecanismo RAG na plataforma de agentes do Gemini Enterprise

Os controles de segurança do VPC-SC e a CMEK são compatíveis com o mecanismo RAG da plataforma de agentes. Os controles de segurança de residência de dados e AXT não são compatíveis.

A instância do Spanner gerenciada pelo mecanismo RAG é usada como um banco de dados vetorial e está em disponibilidade geral com o faturamento ativado. Para mais informações, consulte Faturamento do Mecanismo RAG na Gemini Enterprise Agent Platform.

Nesta página, mostramos como o Mecanismo RAG na Gemini Enterprise Agent Platform usa o RagManagedDb, que é um banco de dados de vetores pronto para empresas usado para armazenar e gerenciar representações vetoriais dos seus documentos. O banco de dados de vetores é usado para recuperar documentos relevantes com base na semelhança semântica do documento com uma determinada consulta.

Além disso, esta página mostra como implementar CMEKs.

Importante: o RagManagedDb é usado por padrão e utiliza o Spanner. Os clientes vão receber cobranças pelo uso de uma instância do Spanner gerenciada pelo Google que é provisionada em um projeto de locatário do Google usando SKUs padrão do Spanner.

Gerenciar sua estratégia de recuperação

O RagManagedDb oferece as seguintes estratégias de recuperação para dar suporte aos seus casos de uso de RAG:

Estratégia de recuperação	Descrição
k-vizinhos mais próximos (KNN) (padrão)	Encontra os vizinhos mais próximos exatos comparando todos os pontos de dados no seu corpus RAG. Se você não especificar uma estratégia durante a criação do corpus de RAG, a KNN será usada como estratégia de recuperação padrão.	Verifica o recall perfeito (1.0) durante a recuperação. Ótimo para aplicativos sensíveis ao recall. Ótimo para corpora de RAG de pequeno a médio porte, que armazenam menos de 10.000 arquivos de RAG. Exige a pesquisa em cada ponto de dados. Portanto, a latência aumenta com o número de arquivos RAG no corpus.
Vizinho mais próximo aproximado (ANN, na sigla em inglês)	Usa técnicas de aproximação para encontrar vizinhos semelhantes mais rapidamente do que a técnica KNN.	Reduz significativamente as latências de consulta em grandes corpora de RAG. O recall diminuiu um pouco devido às técnicas de aproximação usadas. Torna-se muito eficaz quando você tem grandes corpora de RAG, que é aproximadamente mais de 10.000 arquivos de RAG. A quantidade de perda de recall aceitável depende do caso de uso, mas, na maioria dos casos em grande escala, perder um pouco de recall em troca de um melhor desempenho de consulta é uma compensação aceitável.

Criar um corpus de RAG com KNN RagManagedDb

Este exemplo de código demonstra como criar um corpus RAG usando o 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

Substitua as seguintes variáveis:

• PROJECT_ID: o ID do projeto.
• LOCATION: a região para processar a solicitação.
• CORPUS_DISPLAY_NAME: o nome de exibição do 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": {}
        }
      }
    }'

Visualizar

Alguns dos recursos de RAG são produtos e recursos em pré-GA, sujeitos aos "Termos de ofertas pré-GA" dos Termos específicos de serviço do Google Cloud. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Além disso, as mudanças neles podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições da fase de lançamento. Ao usar a API Gemini na Gemini Enterprise Agent Platform, você concorda com os termos e condições do pré-lançamento da IA generativa (Termos de pré-lançamento).

Criar um corpus RAG com ANN RagManagedDb

Para oferecer o recurso de ANN, o RagManagedDb usa uma estrutura baseada em árvore para particionar dados e facilitar pesquisas mais rápidas. Para permitir o melhor recall e latência, a estrutura dessa árvore precisa ser configurada por experimentação para se adequar ao tamanho e à distribuição dos dados. O RagManagedDb permite configurar o tree_depth e o leaf_count da árvore.

O tree_depth determina o número de camadas ou níveis na árvore. Siga estas diretrizes:

• Se você tiver aproximadamente 10.000 arquivos RAG no corpus, defina o valor como 2.
• Se você tiver mais arquivos RAG do que isso, defina como 3.
• Se o tree_depth não for especificado, o RAG Engine vai atribuir um valor padrão de 2 para esse parâmetro.

O leaf_count determina o número de nós de folha na estrutura baseada em árvore. Cada nó folha contém grupos de vetores intimamente relacionados, além do centroide correspondente. Siga estas diretrizes:

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

• Se não for especificado, o RAG Engine vai atribuir um valor padrão de 500 para esse 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

Substitua as seguintes variáveis:

• PROJECT_ID: o ID do projeto.
• LOCATION: a região para processar a solicitação.
• CORPUS_DISPLAY_NAME: o nome de exibição do corpus de RAG.
• TREE_DEPTH: a profundidade da árvore.
• LEAF_COUNT: a contagem de folhas.

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

Visualizar

Alguns dos recursos de RAG são produtos e recursos em pré-GA, sujeitos aos "Termos de ofertas pré-GA" dos Termos específicos de serviço do Google Cloud. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Além disso, as mudanças neles podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições da fase de lançamento. Ao usar a API Gemini na Gemini Enterprise Agent Platform, você concorda com os termos e condições do pré-lançamento da IA generativa (Termos de pré-lançamento).

Como importar seus dados para a ANN RagManagedDb

É possível usar a API ImportRagFiles ou UploadRagFile para importar seus dados para a RagManagedDb de ANN. No entanto, ao contrário da estratégia de recuperação KNN, a abordagem ANN exige que o índice baseado em árvore seja recriado pelo menos uma vez e, opcionalmente, após a importação de quantidades significativas de dados para uma recuperação ideal. Para que o mecanismo RAG recrie seu índice de ANN, defina rebuild_ann_index como verdadeiro na solicitação de API ImportRagFiles.

Os seguintes pontos são importantes:

1. Antes de consultar o corpus de RAG, é necessário recriar o índice de ANN pelo menos uma vez.
2. Só é possível recriar um índice simultâneo em um projeto em cada local.

Para fazer upload do arquivo local para o corpus de RAG, consulte Fazer upload de um arquivo RAG. Para importar dados para seu corpus de RAG e acionar uma recriação de índice de ANN, consulte o exemplo de código a seguir, que demonstra como importar do Cloud Storage. Para saber mais sobre as fontes de dados compatíveis, consulte Fontes de dados compatíveis com 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}'
  }
}'

Gerenciar sua criptografia

O RAG Engine oferece opções robustas para gerenciar como seus dados em repouso são criptografados. Por padrão, todos os dados do usuário no RagManagedDb são criptografados usando uma Google-owned and Google-managed encryption key, que é a configuração padrão. Essa configuração padrão ajuda a verificar se os dados estão seguros sem exigir nenhuma configuração específica.

Se você precisar de mais controle sobre as chaves usadas para criptografia, o mecanismo RAG é compatível com chaves de criptografia gerenciadas pelo cliente (CMEK). Com as CMEKs, é possível usar suas chaves criptográficas, gerenciadas no Cloud Key Management Service (Cloud KMS), para proteger os dados do corpus de RAG.

Para informações sobre as limitações de CMEK para corpora de RAG, consulte Limitações de CMEK para o Mecanismo RAG na Gemini Enterprise Agent Platform.

Configurar a chave do Cloud KMS e conceder permissões

Antes de criar um corpus de RAG criptografado com CMEK, é necessário configurar uma chave criptográfica no Google Cloud KMS e conceder à conta de serviço do RAG Engine as permissões necessárias para usar essa chave.

Pré-requisitos

Para realizar as etapas de configuração a seguir, verifique se sua conta de usuário tem as permissões apropriadas do Identity and Access Management (IAM) no projeto do Google Cloud em que você pretende criar a chave do Cloud KMS e o corpus de RAG. Normalmente, é necessário um papel como o de administrador do Cloud KMS (roles/cloudkms.admin).

Ativar a API

Para ativar a API Cloud Key Management Service, faça o seguinte:

1. Acesse o console do Google Cloud .
2. Selecione o projeto em que você quer gerenciar suas chaves e crie seu corpus de RAG.
3. Na barra de pesquisa, digite "Gerenciamento de chaves" e selecione o serviço "Gerenciamento de chaves".
4. Se a API não estiver ativada, clique em Ativar. Talvez seja necessário aguardar alguns minutos para que a API seja totalmente provisionada.

Criar o keyring e a chave do Cloud KMS

Para criar um keyring, faça o seguinte:

1. Na seção Gerenciamento de chaves, clique em Criar keyring.

   Digite o seguinte:

   • Nome do keyring: insira um nome exclusivo para o keyring, como rag-engine-cmek-keys.
   • Tipo de local: selecione "Região". O keyring do Cloud KMS precisa estar na mesma região do endpoint da ferramenta RAG que você está usando ao criptografar um corpus de RAG com CMEK.
   • Local: escolha a região selecionada, como us-central1. O ideal é que essa região corresponda à região em que os recursos do mecanismo RAG vão residir.

2. Clique em Criar.

Para criar uma chave no keyring, faça o seguinte:

1. Depois que o keyring for criado, você vai receber uma solicitação ou poderá navegar até Criar chave.

   Digite o seguinte:

   • Nome da chave: insira um nome exclusivo para a chave, como my-rag-corpus-key.
   • Nível de proteção: escolha um nível de proteção (Software ou HSM). Se você precisar de chaves protegidas por hardware, selecione HSM.
   • Finalidade: selecione Criptografia/descriptografia simétrica. Isso é obrigatório para CMEK.
   • Origem do material da chave: selecione Chave gerada.
   • Período de rotação: opcional. Recomendado. Configure uma programação de rotação de chaves de acordo com as políticas de segurança da sua organização, como a cada 90 dias.

2. Clique em Criar.

Para copiar o nome do recurso de chave, faça o seguinte:

1. Depois que a chave for criada, acesse a página de detalhes dela.

2. Localize o nome do recurso. O formato é projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1.

   Importante: para o EncryptionSpec no corpus de RAG, use o nome do recurso de chave sem o número da versão.

3. Copie o nome do recurso e remova a parte /cryptoKeyVersions/VERSION_NUMBER. O nome do recurso formatado corretamente é projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME.

Conceder permissões ao agente de serviço do RAG Engine

Para que o mecanismo de RAG criptografe e descriptografe dados usando sua chave do Cloud KMS, o agente de serviço precisa das permissões adequadas nessa chave específica.

Para identificar o agente de serviço do mecanismo de RAG, faça o seguinte:

1. Acesse a página IAM e administrador > IAM no console do Google Cloud do seu projeto.

2. Na página do Identity and Access Management, marque a caixa de seleção Incluir concessões de papéis fornecidos pelo Google.

3. Na barra de filtro ou pesquisa da lista de principais, procure o agente de serviço do RAG Engine. Ele segue o padrão [e-mail].

   Substitua YOUR_PROJECT_NUMBER pelo número do projeto do Google Cloud .

Se o agente de serviço do RAG Engine ainda não estiver presente, faça o seguinte para acionar a criação do agente de serviço:

1. Ative a API Resource Manager.

2. Execute este comando no Cloud Shell ou na linha de comando:

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

   Como alternativa, envie a chamada de 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. Verifique se o agente de serviço do RAG Engine foi criado.

Para conceder permissões na chave do Cloud KMS, faça o seguinte:

1. Volte para o serviço do Cloud KMS no console do Google Cloud .

2. Selecione o keyring que contém a chave que você criou.

3. Selecione a chave específica que você criou.

4. Na página de detalhes da chave, acesse a guia Permissões.

5. Clique em Adicionar principal.

6. No campo Novos principais, digite o endereço de e-mail do agente de serviço do RAG Engine.

7. No menu suspenso Selecionar um papel, escolha o papel de criptografador/descriptografador de CryptoKey do Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter). Esse papel concede ao agente de serviço as permissões necessárias para usar a chave em operações de criptografia e descriptografia.

8. Clique em Salvar.

Criar um corpus de RAG com criptografia gerenciada pelo cliente

Este exemplo de código demonstra como criar um corpus RAG criptografado com chaves de criptografia gerenciadas pelo cliente (CMEK).

Substitua as variáveis nos seguintes exemplos 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}"\"'
      }
    }'

Cotas

Quando você usa CMEK com os serviços da Gemini Enterprise Agent Platform, como o mecanismo RAG na Gemini Enterprise Agent Platform, há uma cota para o número de chaves exclusivas do Cloud KMS que podem ser usadas por projeto e por região. Essa cota é rastreada pela métrica aiplatform.googleapis.com/in_use_customer_managed_encryption_keys.

Sempre que você usa uma chave nova e exclusiva do Cloud KMS para criar um recurso, como um corpus de RAG, em um projeto e uma região, a chave do Cloud KMS consome uma unidade dessa cota. Essa unidade de cota não é liberada mesmo que os recursos que usam essa chave específica sejam excluídos.

Se você precisar de mais chaves exclusivas do que o limite atual, solicite um aumento de cota para aiplatform.googleapis.com/in_use_customer_managed_encryption_keys na região selecionada.

Para mais informações sobre como solicitar um aumento de cota, consulte Ver e editar as cotas no console do Google Cloud .

A seguir

• Para saber mais sobre o RagManagedDb, consulte Modos de implantação.
• Para importar arquivos e pastas do Google Drive ou do Cloud Storage, consulte o exemplo de importação de arquivos RAG.
• Para listar arquivos RAG, consulte o exemplo de listagem de arquivos RAG.