Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

Esta página mostra como o mecanismo RAG na plataforma de agentes do Gemini Enterprise 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 similaridade semântica do documento com uma determinada consulta.

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

Gerenciar sua estratégia de recuperação

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

Estratégia de recuperação	Descrição
Vizinhos mais próximos exatos (KNN, na sigla em inglês) (padrão)	Encontra os vizinhos mais próximos exatos comparando todos os pontos de dados no seu RAG corpus. Se você não especificar uma estratégia durante a criação do seu corpus RAG, o KNN será a estratégia de recuperação padrão usada.	Verifica o recall perfeito (1,0) durante a recuperação. Ótimo para aplicativos sensíveis ao recall. Ótimo para corpora RAG pequenos a médios, que armazenam menos de 10.000 arquivos RAG. Exige a pesquisa em todos os pontos de dados. Portanto, a latência aumenta com o número de arquivos RAG no corpus.
Vizinhos mais próximos aproximados (ANN, na sigla em inglês)	Usa técnicas de aproximação para encontrar vizinhos semelhantes mais rápido do que a técnica KNN.	Reduz significativamente as latências de consulta em corpora RAG grandes. O recall é ligeiramente reduzido devido às técnicas de aproximação usadas. Torna-se muito eficaz quando você tem corpora RAG grandes, que são aproximadamente mais de 10.000 arquivos 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 desempenho de consulta aprimorado é uma compensação aceitável.

Criar um corpus 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 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": {}
        }
      }
    }'

Criar um corpus RAG com ANN `RagManagedDb`

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

A tree_depth determina o número de camadas ou níveis na árvore. Siga as seguintes diretrizes:

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

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

O valor recomendado é 10 * sqrt(num of RAG files in your RAG corpus).
Se não for especificado, o mecanismo RAG vai atribuir um valor padrão de 500 a 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 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}"'
          }
        }
      }
    }'

Importar seus dados para o ANN `RagManagedDb`

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

O seguinte é importante:

Antes de consultar o corpus RAG, é necessário recriar o índice ANN pelo menos uma vez.
Apenas uma recriação de índice simultânea é aceita em um projeto em cada local.

Para fazer upload do arquivo local para o corpus RAG, consulte Fazer upload de um arquivo RAG. Para importar dados para o corpus RAG e acionar uma recriação do índice ANN, consulte o exemplo de código a seguir, que demonstra como importar do Cloud Storage. Para saber mais sobre as fontes de dados aceitas, consulte Fontes de dados aceitas para 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 mecanismo RAG oferece opções robustas para gerenciar como os dados em repouso são criptografados. Por padrão, todos os dados do usuário em RagManagedDb são criptografados usando um 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 oferece suporte à chave de criptografia gerenciada pelo cliente (CMEK). Com a CMEK, você pode usar suas chaves criptográficas, gerenciadas no Cloud Key Management Service (KMS), para proteger os dados do corpus RAG.

Para informações sobre as limitações da CMEK para corpora RAG, consulte Limitações da CMEK para o mecanismo RAG na plataforma de agentes do Gemini Enterprise.

Configurar a chave do KMS e conceder permissões

Antes de criar um corpus RAG criptografado com a CMEK, é necessário configurar uma chave criptográfica no Google Cloud KMS e conceder à conta de serviço do mecanismo RAG 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 Google Cloud projeto em que você pretende criar a chave do KMS e o corpus RAG. Normalmente, um papel como o de administrador do Cloud KMS (roles/cloudkms.admin) é necessário.

Ativar a API

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

Navegue até o Google Cloud console.
Selecione o projeto em que você quer gerenciar as chaves e criar o corpus RAG.
Na barra de pesquisa, digite "Gerenciamento de chaves" e selecione o serviço "Gerenciamento de chaves".
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 KMS

Para criar um keyring, faça o seguinte:

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 Key Management Service precisa estar na mesma região que o endpoint do mecanismo RAG que você está usando ao criptografar um corpus RAG com a CMEK.
- Local: escolha a região selecionada, como us-central1. Essa região precisa corresponder à região em que os recursos do mecanismo RAG vão residir.
Clique em Criar.

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

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 com suporte de hardware, selecione HSM.
- Finalidade: selecione Criptografia/descriptografia simétrica. Isso é necessário para a CMEK.
- Fonte 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.
Clique em Criar.

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

Depois que a chave for criada, navegue até a página de detalhes dela.
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 RAG, use o nome do recurso da chave sem o número da versão.
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 mecanismo RAG

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

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

Navegue até a página IAM e administrador > IAM no Google Cloud console do seu projeto.
Na página "Identity and Access Management", marque a caixa de seleção Incluir concessões de papéis fornecidos pelo Google.
Na barra de filtro ou pesquisa da lista de principais, procure o agente de serviço do mecanismo RAG. Ele segue o padrão service-YOUR_PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.com.

Substitua YOUR_PROJECT_NUMBER pelo seu Google Cloud projeto número.

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

Ative a API Resource Manager.

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"

Verifique se o agente de serviço do mecanismo RAG foi criado.

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

Volte ao serviço de gerenciamento de chaves no Google Cloud console.
Selecione o keyring que contém a chave criada.
Selecione a chave específica que você criou.
Na página de detalhes da chave, acesse a guia Permissões.
Clique em Adicionar principal.
No campo Novos principais, digite o endereço de e-mail do agente de serviço do mecanismo RAG.
Na lista suspensa Selecionar um papel, escolha o papel de criptografador/descriptografador do Cloud KMS CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter). Esse papel concede ao agente de serviço as permissões necessárias para usar a chave para operações de criptografia e descriptografia.
Clique em Salvar.

Criar um corpus RAG com criptografia gerenciada pelo cliente

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

Substitua as variáveis nos exemplos de código a seguir:

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

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

Cada vez que você usa uma chave KMS nova e exclusiva para criar um recurso, como um corpus RAG, em um projeto e região, a chave 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 para a região selecionada.

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

A seguir

Para saber mais sobre o RagManagedDb, consulte Noções básicas sobre o RagManagedDb.
Para importar arquivos e pastas do Google Drive ou do Cloud Storage, consulte Exemplo de importação de arquivos RAG exemplo.
Para listar arquivos RAG, consulte Listar arquivos RAG exemplo.

Usar RagManagedDb com o mecanismo RAG na plataforma de agentes do Gemini Enterprise Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Gerenciar sua estratégia de recuperação

Criar um corpus RAG com KNN RagManagedDb

Python

REST

Criar um corpus RAG com ANN RagManagedDb

Python

REST

Importar seus dados para o ANN RagManagedDb

Python

REST

Gerenciar sua criptografia

Configurar a chave do KMS e conceder permissões

Pré-requisitos

Ativar a API

Criar o keyring e a chave do KMS

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

Criar um corpus RAG com criptografia gerenciada pelo cliente

Python

REST

Cotas

A seguir

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

Criar um corpus RAG com KNN `RagManagedDb`

Criar um corpus RAG com ANN `RagManagedDb`

Importar seus dados para o ANN `RagManagedDb`