Use o RagManagedDb com o Vertex AI RAG Engine

Os controlos de segurança do VPC-SC e a CMEK são suportados pelo Vertex AI RAG Engine. A residência dos dados e os controlos de segurança AXT não são suportados.

A instância do Spanner gerida pelo motor RAG da Vertex AI é usada como uma base de dados vetorial e está disponível para todos com a faturação ativada. Para mais informações, consulte o artigo Faturação do Vertex AI RAG Engine.

Esta página mostra como o Vertex AI RAG Engine usa o RagManagedDb, que é uma base de dados vetorial pronta para a empresa usada para armazenar e gerir representações vetoriais dos seus documentos. Em seguida, a base de dados vetorial é usada para obter documentos relevantes com base na semelhança semântica do documento com uma determinada consulta.

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

Importante: o RagManagedDb é usado por predefinição e usa o Spanner. Os clientes vão receber cobranças pela utilização de uma instância do Spanner gerida pela Google, aprovisionada num projeto de inquilino da Google, através de SKUs do Spanner padrão.

Faça a gestão da sua estratégia de obtenção

O RagManagedDb oferece as seguintes estratégias de obtenção para suportar os seus exemplos de utilização de RAG:

Estratégia de obtenção	Descrição
k-Nearest Neighbors (KNN) (predefinição)	Encontra os vizinhos mais próximos exatos comparando todos os pontos de dados no seu corpus de RAG. Se não especificar uma estratégia durante a criação do seu corpus de RAG, a KNN é a estratégia de obtenção predefinida usada.	Valida a recordação perfeita (1,0) durante a obtenção. Ideal para aplicações sensíveis à capacidade de memorização. Ideal para conjuntos de dados RAG pequenos a médios, que armazenam menos de 10 000 ficheiros RAG. Requer a pesquisa em todos os pontos de dados individuais. Por conseguinte, a latência aumenta com o número de ficheiros RAG no corpus.
Vizinhos mais próximos aproximados (ANN)	Usa técnicas de aproximação para encontrar vizinhos semelhantes mais rapidamente do que a técnica KNN.	Reduz significativamente as latências de consultas em grandes conjuntos de dados RAG. A capacidade de memorização foi ligeiramente reduzida devido às técnicas de aproximação usadas. Torna-se muito eficaz quando tem grandes conjuntos de dados RAG, que são aproximadamente mais de 10 000 ficheiros RAG. A quantidade de perda de recordação que considera aceitável depende do exemplo de utilização, mas, na maioria dos casos em grande escala, perder um pouco de recordação em troca de um desempenho de consulta melhorado é uma compensação aceitável.

Crie um corpus RAG com KNN RagManagedDb

Estes exemplos de código demonstram como criar um corpus RAG usando 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 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

Substitua as seguintes variáveis:

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

Pré-visualizar

Algumas das funcionalidades de RAG são ofertas de pré-visualização, sujeitas aos "Termos das Ofertas de Pré-DG" dos Termos Específicos do Serviço da Google Cloud. Os produtos e as funcionalidades de pré-DG podem ter apoio técnico limitado, e as alterações aos produtos e às funcionalidades de pré-DG podem não ser compatíveis com outras versões de pré-DG. Para mais informações, consulte as descrições das fases de lançamento. Além disso, ao usar a API Gemini na Vertex AI, aceita os termos e condições da pré-visualização da IA generativa(termos de pré-visualização).

Crie um corpus RAG com ANN RagManagedDb

Para oferecer a funcionalidade ANN, o RagManagedDb usa uma estrutura baseada em árvore para dividir os dados e facilitar as pesquisas mais rápidas. Para permitir a melhor capacidade de memorização e latência, a estrutura desta árvore deve ser configurada através de experiências para se ajustar ao tamanho e à distribuição dos seus dados. RagManagedDb permite-lhe configurar o tree_depth e o leaf_count da árvore.

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

• Se tiver aproximadamente 10 000 ficheiros RAG no corpus RAG, defina o valor como 2.
• Se tiver mais ficheiros RAG do que isso, defina este valor como 3.
• Se o tree_depth não for especificado, o motor RAG da Vertex AI atribui um valor predefinido de 2 a este parâmetro.

O leaf_count determina o número de nós folha na estrutura baseada em árvores. Cada nó folha contém grupos de vetores estreitamente relacionados, juntamente com o respetivo centroide. Siga estas diretrizes:

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

• Se não for especificado, o Vertex AI RAG Engine atribui um valor predefinido de 500 a 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 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

Substitua as seguintes variáveis:

• PROJECT_ID: o ID do seu projeto.
• LOCATION: a região para processar o pedido.
• CORPUS_DISPLAY_NAME: o nome a apresentar do corpus RAG.
• TREE_DEPTH: a profundidade da árvore.
• LEAF_COUNT: o número 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}"'
          }
        }
      }
    }'

Pré-visualizar

Algumas das funcionalidades de RAG são ofertas de pré-visualização, sujeitas aos "Termos das Ofertas de Pré-DG" dos Termos Específicos do Serviço da Google Cloud. Os produtos e as funcionalidades de pré-DG podem ter apoio técnico limitado, e as alterações aos produtos e às funcionalidades de pré-DG podem não ser compatíveis com outras versões de pré-DG. Para mais informações, consulte as descrições das fases de lançamento. Além disso, ao usar a API Gemini na Vertex AI, aceita os termos e condições da pré-visualização da IA generativa(termos de pré-visualização).

Importar os seus dados para a ANN RagManagedDb

Pode usar a API ImportRagFiles ou a API UploadRagFile para importar os seus dados para a RNA RagManagedDb. No entanto, ao contrário da estratégia de obtenção de KNN, a abordagem de ANN requer que o índice baseado em árvore subjacente seja reconstruído, pelo menos, uma vez e, opcionalmente, após a importação de quantidades significativas de dados para uma capacidade de memorização ideal. Para que o Vertex AI RAG Engine reconstrua o índice ANN, defina rebuild_ann_index como verdadeiro no seu pedido da API ImportRagFiles.

Os seguintes aspetos são importantes:

1. Antes de consultar o corpus RAG, tem de reconstruir o índice ANN, pelo menos, uma vez.
2. Apenas é suportada uma reconstrução de índice simultânea num projeto em cada localização.

Para carregar o ficheiro local para o seu corpus RAG, consulte o artigo Carregue um ficheiro RAG. Para importar dados para o seu corpus de RAG e acionar uma reconstrução do índice de ANN, consulte o seguinte exemplo de código que demonstra como importar a partir do Cloud Storage. Para saber mais sobre as origens de dados compatíveis, consulte o artigo Origens de dados compatíveis com a 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 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}'
  }
}'

Faça a gestão da encriptação

O motor RAG da Vertex AI oferece opções robustas para gerir a forma como os seus dados em repouso são encriptados. Por predefinição, todos os dados do utilizador em RagManagedDb são encriptados através de um Google-owned and Google-managed encryption key, que é a definição predefinida. Esta predefinição ajuda a verificar se os seus dados estão seguros sem precisar de uma configuração específica.

Se precisar de mais controlo sobre as chaves usadas para encriptação, o Vertex AI RAG Engine suporta a chave de encriptação gerida pelo cliente (CMEK). Com as CMEK, pode usar as suas chaves criptográficas, geridas no Cloud Key Management Service (KMS), para proteger os dados do seu corpus de RAG.

Para obter informações sobre as limitações da CMEK para conjuntos de dados RAG, consulte o artigo Limitações da CMEK para o motor RAG da Vertex AI.

Configure a chave do KMS e conceda autorizações

Antes de poder criar um corpus RAG encriptado com CMEK, tem de configurar uma chave criptográfica no Google Cloud KMS e conceder à conta de serviço do Vertex AI RAG Engine as autorizações necessárias para usar esta chave.

Pré-requisitos

Para realizar os passos de configuração seguintes, verifique se a sua conta de utilizador tem as autorizações de gestão de identidade e acesso (IAM) adequadas no Google Cloud projeto onde pretende criar a chave do KMS e o corpus de RAG. Normalmente, é necessária uma função como a função de administrador do Cloud KMS (roles/cloudkms.admin).

Ative a API

Para ativar a API Cloud KMS, faça o seguinte:

1. Navegue para a Google Cloud consola.
2. Selecione o projeto onde quer gerir as suas chaves e crie o seu corpus de RAG.
3. Na barra de pesquisa, escreva "Gestão de chaves" e selecione o serviço "Gestão de chaves".
4. Se a API não estiver ativada, clique em Ativar. Pode ter de aguardar alguns minutos para que a API seja totalmente aprovisionada.

Crie o conjunto de chaves e a chave do KMS

Para criar um conjunto de chaves, faça o seguinte:

1. Na secção Gestão de chaves, clique em Criar anel de chaves.

   Introduza os seguintes dados:

   • Nome do conjunto de chaves: introduza um nome exclusivo para o conjunto de chaves, como rag-engine-cmek-keys.
   • Tipo de localização: selecione Região. O conjunto de chaves do Cloud Key Management Service tem de estar na mesma região que o ponto final do Vertex AI RAG Engine que está a usar quando encripta um corpus RAG com CMEK.
   • Localização: escolha a região selecionada, como us-central1. Idealmente, esta região deve corresponder à região onde os recursos do motor RAG vão residir.

2. Clique em Criar.

Para criar uma chave no conjunto de chaves, faça o seguinte:

1. Depois de criar o conjunto de chaves, é-lhe pedido que navegue para Criar chave ou pode fazê-lo manualmente.

   Introduza os seguintes dados:

   • Nome da chave: introduza 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 precisar de chaves suportadas por hardware, selecione HSM.
   • Finalidade: selecione Encriptar/desencriptar simetricamente. Este campo é obrigatório para as CMEK.
   • Origem do material da chave: selecione Chave gerada.
   • Período de rotação: opcional. Recomendado. Configure uma agenda 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 principal, faça o seguinte:

1. Depois de criar a chave, navegue para a respetiva página de detalhes.

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 seu corpus de RAG, tem de usar o nome do recurso 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.

Conceda autorizações ao agente do serviço Vertex AI RAG Engine

Para que o motor RAG da Vertex AI encripte e desencripte dados através da sua chave do KMS, o respetivo agente do serviço precisa das autorizações adequadas nessa chave específica.

Para identificar o agente do serviço do Vertex AI RAG Engine, faça o seguinte:

1. Navegue para a página IAM e administração > IAM na Google Cloud consola do seu projeto.

2. Na página Identity and Access Management, selecione a caixa de verificação Incluir concessões de funções fornecidas pela Google.

3. Na barra de filtros ou de pesquisa da lista de responsáveis, pesquise o agente do serviço do Vertex AI RAG Engine. Segue o padrão [e-mail].

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

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

1. Ative a API Resource Manager.

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

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

   Em alternativa, envie a chamada da 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 motor RAG da Vertex AI foi criado.

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

1. Volte ao serviço de gestão de chaves na Google Cloud consola.

2. Selecione o conjunto de chaves que contém a chave que criou.

3. Selecione a chave específica que criou.

4. Na página de detalhes da chave, aceda ao separador Autorizações.

5. Clique em Adicionar diretor.

6. No campo Novos membros, introduza o endereço de email do agente de serviço do Vertex AI RAG Engine.

7. No menu pendente Selecionar uma função, selecione a função de encriptar/desencriptar do CryptoKey do Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter). Esta função concede ao agente de serviço as autorizações necessárias para usar a chave para operações de encriptação e desencriptação.

8. Clique em Guardar.

Crie um corpus RAG com encriptação gerida pelo cliente

Este exemplo de código demonstra como criar um corpus de RAG encriptado com uma chave encriptada gerida 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}"\"'
      }
    }'

Quotas

Quando usa a CMEK com os serviços do Vertex AI, como o Vertex AI RAG Engine, existe uma quota para o número de chaves do Cloud KMS únicas que podem estar em utilização por projeto e por região. Esta quota é monitorizada pela métrica aiplatform.googleapis.com/in_use_customer_managed_encryption_keys.

Cada vez que usa uma chave do KMS nova e exclusiva para criar um recurso, como um corpus RAG, num projeto e numa região, a chave do KMS consome uma unidade desta quota. Esta unidade de quota não é libertada, mesmo que os recursos que usam essa chave específica sejam eliminados.

Se precisar de mais chaves únicas do que o limite atual, tem de pedir um aumento da quota para aiplatform.googleapis.com/in_use_customer_managed_encryption_keys para a região selecionada.

Para mais informações sobre como pedir um aumento da quota, consulte o artigo Veja e edite as quotas na Google Cloud consola.

O que se segue?

• Para saber mais sobre a RagManagedDb, consulte o artigo Compreender a RagManagedDb.
• Para importar ficheiros e pastas do Google Drive ou do Cloud Storage, consulte o exemplo de importação de ficheiros RAG.
• Para listar ficheiros RAG, consulte o exemplo de como listar ficheiros RAG.