Usar um banco de dados do Weaviate com o RAG Engine

Esta página mostra como conectar o corpus do RAG Engine ao banco de dados do Weaviate.

Você também pode acompanhar este notebook RAG Engine com Weaviate.

É possível usar a instância do banco de dados do Weaviate, que é um banco de dados de código aberto, com o mecanismo RAG para indexar e realizar uma pesquisa de similaridade baseada em vetores. Uma pesquisa de similaridade é uma maneira de encontrar partes de texto semelhantes ao texto que você está procurando, o que exige o uso de um modelo de embedding. O modelo de embedding produz dados vetoriais para cada parte do texto que está sendo comparado. A pesquisa de similaridade é usada para extrair contextos semânticos para agrupamento e retornar o conteúdo mais preciso do seu LLM.

Com o RAG Engine, você pode continuar usando a instância de banco de dados de vetor totalmente gerenciada, que é sua responsabilidade provisionar. O RAG Engine usa o banco de dados de vetores para armazenamento, gerenciamento de índices e pesquisa.

Considerações

Siga estas etapas antes de usar o banco de dados do Weaviate:

  1. Você precisa criar, configurar e implantar a instância e a coleção do banco de dados do Weaviate. Siga as instruções em Criar sua coleção do Weaviate para configurar uma coleção com base no seu esquema.
  2. É necessário fornecer uma chave de API do Weaviate, que permite que o RAG Engine interaja com o banco de dados do Weaviate. O RAG Engine oferece suporte a AuthN e AuthZ com base na chave da API, que se conecta ao seu banco de dados do Weaviate e oferece suporte a uma conexão HTTPS.
  3. O RAG Engine não armazena nem gerencia sua chave de API do Weaviate. Em vez disso, faça o seguinte:
    1. Armazene sua chave no Secret Manager do Google Cloud.
    2. Conceda permissões à conta de serviço do projeto para acessar o secret.
    3. Forneça ao RAG Engine acesso ao nome do recurso do secret.
    4. Quando você interage com o banco de dados do Weaviate, o RAG Engine acessa seu recurso secreto usando sua conta de serviço.
  4. O corpus do RAG Engine e a coleção do Weaviate têm um mapeamento um a um. Os arquivos RAG são armazenados em uma coleção de banco de dados do Weaviate. Quando uma chamada é feita para a API CreateRagCorpus ou UpdateRagCorpus, o corpus RAG é associado à coleção do banco de dados.
  5. Além das pesquisas semânticas densas baseadas em embeddings, a pesquisa híbrida também é aceita pelo RAG Engine em um banco de dados do Weaviate. Também é possível ajustar o peso entre a similaridade de vetores densos e esparsos em uma pesquisa híbrida.

Provisionar o banco de dados do Weaviate

Antes de usar o banco de dados do Weaviate com o RAG Engine, faça o seguinte:

  1. Configure e implante sua instância do banco de dados do Weaviate.
  2. Prepare o endpoint HTTPS.
  3. Crie sua coleção do Weaviate.
  4. Use sua chave de API para provisionar o Weaviate usando AuthN e AuthZ.
  5. Provisione a conta de serviço do RAG Engine.

Configurar e implantar a instância do banco de dados do Weaviate

Siga o guia de início rápido oficial do Weaviate. No entanto, você pode usar o guia do Google Cloud Marketplace, que é opcional.

É possível configurar a instância do Weaviate em qualquer lugar, desde que o endpoint do Weaviate seja acessível para configuração e implantação no projeto. Depois, você pode gerenciar totalmente a instância do banco de dados do Weaviate.

Como o RAG Engine não está envolvido em nenhuma etapa do ciclo de vida da instância do banco de dados do Weaviate, é sua responsabilidade conceder permissões ao RAG Engine para que ele possa armazenar e pesquisar dados no banco de dados do Weaviate. Também é sua responsabilidade garantir que os dados no seu banco de dados possam ser usados pelo RAG Engine. Por exemplo, se você mudar seus dados, o RAG Engine não será responsável por comportamentos inesperados devido a essas mudanças.

Preparar o endpoint HTTPS

Durante o provisionamento do Weaviate, crie um endpoint HTTPS. Embora as conexões HTTP sejam compatíveis, preferimos que o RAG Engine e o tráfego do banco de dados do Weaviate usem uma conexão HTTPS.

Criar sua coleção do Weaviate

Como o corpus do RAG Engine e a coleção do Weaviate têm um mapeamento um a um, é necessário criar uma coleção no banco de dados do Weaviate antes de associá-la ao corpus do RAG Engine. Essa associação única é feita quando você chama a API CreateRagCorpus ou a UpdateRagCorpus.

Ao criar uma coleção no Weaviate, use o seguinte esquema:

Nome da propriedade Tipo de dado
fileId text
corpusId text
chunkId text
chunkDataType text
chunkData text
fileOriginalUri text

Use sua chave de API para provisionar o Weaviate usando AuthN e AuthZ

O provisionamento da chave da API Weaviate envolve as seguintes etapas:

  1. Crie a chave da API Weaviate.
  2. Configure o Weaviate usando sua chave de API.
  3. Armazene sua chave de API do Weaviate no Secret Manager.

Criar a chave de API

O RAG Engine só pode se conectar às instâncias do banco de dados do Weaviate usando sua chave de API para autenticação e autorização. Siga o guia oficial de autenticação do Weaviate para configurar a autenticação baseada em chave de API na sua instância de banco de dados do Weaviate.

Se a criação da chave de API do Weaviate exigir informações de identidade para se associar às informações do RAG Engine, crie seu primeiro corpus e use sua conta de serviço do RAG Engine como uma identidade.

Armazenar a chave de API no Secret Manager

Uma chave de API contém informações sensíveis de identificação pessoal (SPII, na sigla em inglês), que estão sujeitas a requisitos legais. Se os dados do SPII forem comprometidos ou usados indevidamente, um indivíduo poderá sofrer um risco ou dano significativo. Para minimizar os riscos a um indivíduo ao usar o RAG Engine, não armazene e gerencie sua chave de API e evite compartilhar a chave de API não criptografada.

Para proteger o SPII, faça o seguinte:

  1. Armazene a chave de API no Secret Manager.
  2. Conceda à sua conta de serviço do RAG Engine as permissões para os segredos e gerencie o controle de acesso no nível do recurso secreto.
    1. Navegue até as permissões do projeto.
    2. Ative a opção Incluir concessões de papel fornecidas pelo Google.
    3. Encontre a conta de serviço, que tem o formato

      service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

    4. Edite os principais da conta de serviço.
    5. Adicione o papel de Acessador de secrets do Secret Manager à conta de serviço.
  3. Durante a criação ou atualização do corpus do RAG, transmita o nome do recurso secreto para o RAG Engine e armazene o nome do recurso secreto.

Quando você faz solicitações de API para as instâncias do banco de dados do Weaviate, o RAG Engine usa cada conta de serviço para ler a chave de API correspondente aos recursos secretos no Secret Manager dos seus projetos.

Provisionar a conta de serviço do RAG Engine

Quando você cria o primeiro recurso no projeto, o RAG Engine cria uma conta de serviço dedicada. É possível encontrar sua conta de serviço na página do IAM do projeto. A conta de serviço segue este formato:

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

Por exemplo, service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

Ao integrar com o banco de dados do Weaviate, sua conta de serviço é usada nos seguintes cenários:

  • Você pode usar sua conta de serviço para gerar a chave da API Weaviate para autenticação. Em alguns casos, a geração da chave de API não exige nenhuma informação do usuário, o que significa que uma conta de serviço não é necessária ao gerar a chave de API.
  • É possível vincular sua conta de serviço à chave de API no banco de dados do Weaviate para configurar a autenticação (AuthN) e a autorização (AuthZ). No entanto, a conta de serviço não é obrigatória.
  • É possível armazenar a chave de API do Secret Manager no projeto e conceder permissões da conta de serviço a esses recursos secretos.
  • O RAG Engine usa contas de serviço para acessar a chave de API do Secret Manager nos seus projetos.

Configurar o ambiente do console do Google Cloud

Clique para aprender a configurar seu ambiente

Saiba como configurar seu ambiente selecionando uma das guias a seguir:

Python

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

  8. Instale ou atualize o SDK da Vertex AI para Python executando o seguinte comando:

    pip3 install --upgrade "google-cloud-aiplatform>=1.38"

Node.js

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

  8. Instalar ou atualizar o SDK da Vertex AI para Node.js executando o seguinte comando:

    npm install @google-cloud/vertexai

Java

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

  8. Para adicionar google-cloud-vertexai como uma dependência, adicione o código apropriado para seu ambiente:

    Maven com BoM

    Adicione o seguinte HTML a seu pom.xml:

    <dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.32.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-vertexai</artifactId>
  </dependency>
</dependencies>

    Maven sem BOM

    Adicione o seguinte HTML a seu pom.xml:

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-vertexai</artifactId>
  <version>0.4.0</version>
</dependency>

    Gradle without BOM

    Add the following to your build.gradle

    implementation 'com.google.cloud:google-cloud-vertexai:0.4.0'

Go

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

  8. Analise os pacotes disponíveis da API Vertex AI para Go para determinar qual deles atende melhor às necessidades do seu projeto:

    • Pacote cloud.google.com/go/vertexai (recomendado)

      vertexai é um pacote criado por humanos que fornece acesso a recursos e capabilities comuns.

      Esse pacote é recomendado como ponto de partida para a maioria dos desenvolvedores que criam usando a API Vertex AI. Para acessar recursos e capabilities ainda não cobertos por esse pacote, use o aiplatform gerado automaticamente.

    • Pacote cloud.google.com/go/aiplatform

      aiplatform é um pacote gerado automaticamente.

      Esse pacote é destinado a projetos que exigem acesso a recursos e capabilities da API Vertex AI ainda não fornecidos pelo pacote vertexai criado por humanos.

  9. Instale o pacote Go desejado com base nas necessidades do seu projeto executando um dos seguintes comandos:

    # Human authored package. Recommended for most developers.
go get cloud.google.com/go/vertexai
    
    
# Auto-generated package.
go get cloud.google.com/go/aiplatform

C#

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

REST

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. Insira o comando abaixo para configurar as variáveis de ambiente. Substitua PROJECT_ID pelo ID do seu projeto do Google Cloud. 
    MODEL_ID="gemini-1.5-flash-002"
PROJECT_ID="PROJECT_ID"
  8. Provisione o endpoint: 
    gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_ID}

  9. Opcional: se você estiver usando o Cloud Shell e for solicitado a autorizá-lo, clique em Autorizar.

Preparar o corpus RAG

Para acessar dados do seu banco de dados do Weaviate, o RAG Engine precisa ter acesso a um corpus de RAG. Esta seção mostra as etapas para criar um único corpus RAG e outros corpora RAG.

Usar as APIs CreateRagCorpus e UpdateRagCorpus

É necessário especificar os seguintes campos ao chamar as APIs CreateRagCorpus e UpdateRagCorpus:

  • rag_vector_db_config.weaviate: depois de chamar a API CreateRagCorpus, a configuração do banco de dados de vetor é escolhida. A configuração do banco de dados de vetores contém todos os campos de configuração. Se o campo rag_vector_db_config.weaviate não estiver definido, rag_vector_db_config.rag_managed_db será definido por padrão.
  • weaviate.http_endpoint: o endpoint HTTPS ou HTTP do Weaviate é criado durante o provisionamento da instância do banco de dados do Weaviate.
  • weaviate.collection_name: o nome da coleção criada durante o provisionamento da instância do Weaviate. O nome precisa começar com uma letra maiúscula.
  • api_auth.api_key_config: a configuração especifica o uso de uma chave de API para autorizar seu acesso ao banco de dados de vetores.
  • api_key_config.api_key_secret_version: o nome do recurso do secret armazenado no Secret Manager, que contém a chave da API Weaviate.

Você pode criar e associar seu corpus RAG à coleção do Weaviate na sua instância de banco de dados. No entanto, talvez você precise da conta de serviço para gerar a chave da API e configurar a instância do banco de dados do Weaviate. Quando você cria seu primeiro corpus de RAG, a conta de serviço é gerada. Depois de criar seu primeiro corpus RAG, a associação entre o banco de dados do Weaviate e a chave de API pode não estar pronta para uso na criação de outro corpus RAG.

Caso o banco de dados e a chave não estejam prontos para serem associados ao corpus RAG, faça o seguinte:

  1. Defina o campo weaviate em rag_vector_db_config.

    • Não é possível mudar o banco de dados de vetor associado.
    • Deixe os campos http_endpoint e collection_name vazios. Ambos os campos podem ser atualizados mais tarde.

  2. Se você não tiver a chave de API armazenada no Secret Manager, deixe o campo api_auth vazio. Ao chamar a API UpdateRagCorpus, é possível atualizar o campo api_auth. O Weaviate exige que o seguinte seja feito:

    1. Defina o api_key_config no campo api_auth.

    2. Defina o api_key_secret_version da chave de API do Weaviate no Secret Manager. O campo api_key_secret_version usa o seguinte formato:

      projects/{project}/secrets/{secret}/versions/{version}

  3. Se você especificar campos que só podem ser definidos uma vez, como http_endpoint ou collection_name, não será possível fazer alterações, a menos que você exclua e crie o corpus RAG novamente. Outros campos, como o da chave de API, api_key_secret_version, podem ser atualizados.

  4. Ao chamar UpdateRagCorpus, você pode definir o campo vector_db. O vector_db precisa ser definido como weaviate pela chamada de API CreateRagCorpus. Caso contrário, o sistema escolhe a opção RAG Managed Database, que é o padrão. Essa opção não pode ser alterada quando você chama a API UpdateRagCorpus. Quando você chama UpdateRagCorpus e o campo vector_db está parcialmente definido, é possível atualizar os campos marcados como Mutáveis (também chamados de mutáveis).

Esta tabela lista os campos mutáveis e imutáveis WeaviateConfig usados no código.

Nome do campo Mutável ou imutável
http_endpoint Imutável depois de definido
collection_name Imutável depois de definido
api_key_authentication Mutável

Criar o primeiro corpus RAG

Quando a conta de serviço do RAG Engine não existir, faça o seguinte:

  1. Crie um corpus RAG no RAG Engine com uma configuração vazia do Weaviate, que inicia o provisionamento do RAG Engine para criar uma conta de serviço.
  2. Escolha um nome para sua conta de serviço do RAG Engine que siga este formato:

    service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

    Por exemplo, service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

  3. Usando sua conta de serviço, acesse o secret armazenado no Secret Manager do projeto, que contém a chave de API do Weaviate.
  4. Receba as seguintes informações após a conclusão do provisionamento do Weaviate:
    • Seu endpoint HTTPS ou HTTP do Weaviate.
    • O nome da sua coleção do Weaviate.
  5. Chame a API CreateRagCorpus para criar um corpus de RAG com uma configuração vazia do Weaviate e chame a API UpdateRagCorpus para atualizar o corpus de RAG com as seguintes informações:
    • Seu endpoint HTTPS ou HTTP do Weaviate.
    • O nome da sua coleção do Weaviate.
    • O nome do recurso da chave de API.

Criar outro corpus RAG

Quando a conta de serviço do RAG Engine existir, faça o seguinte:

  1. Acesse a conta de serviço do RAG Engine nas permissões do projeto.
  2. Ative a opção "Incluir concessões de papel fornecidas pelo Google".
  3. Escolha um nome para sua conta de serviço do RAG Engine que siga este formato:

    service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

  4. Usando sua conta de serviço, acesse o secret armazenado no Secret Manager do projeto, que contém a chave da API Weaviate.
  5. Durante o provisionamento do Weaviate, confira as seguintes informações:
    • O endpoint HTTPS ou HTTP do Weaviate.
    • O nome da sua coleção do Weaviate.
  6. Crie um corpus RAG no RAG Engine e conecte-se à sua coleção do Weaviate fazendo uma das seguintes ações:
    1. Faça uma chamada de API CreateRagCorpus para criar um corpus RAG com uma configuração Weaviate preenchida, que é a opção preferencial.
    2. Faça uma chamada de API CreateRagCorpus para criar um corpus RAG com uma configuração vazia do Weaviate e faça uma chamada de API UpdateRagCorpus para atualizar o corpus RAG com as seguintes informações:
      • Endpoint HTTP do banco de dados do Weaviate
      • Nome da coleção da Weaviate
      • Chave de API

Exemplos

Esta seção apresenta um exemplo de código que demonstra como configurar o banco de dados do Weaviate, o Secret Manager, o corpus RAG e o arquivo RAG. Também há um exemplo de código para demonstrar como importar arquivos, recuperar o contexto, gerar conteúdo e excluir o corpus e os arquivos RAG.

Para usar o notebook da API RAG do Model Garden, consulte Usar o Weaviate com o Llama 3.

Configurar o banco de dados do Weaviate

Este exemplo de código demonstra como configurar os dados do Weaviate e o Secret Manager.

REST

# TODO(developer): Update the variables.
# The HTTPS/HTTP Weaviate endpoint you created during provisioning.
HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"

# Select your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
# For example, "MyCollectionName"
# Note that the first letter needs to be capitalized.
# Otherwise, Weavaite will capitalize it for you.
WEAVIATE_COLLECTION_NAME="MyCollectionName"

# Create a collection in Weaviate which includes the required schema fields shown below.
echo '{
  "class": "'${WEAVIATE_COLLECTION_NAME}'",
  "properties": [
    { "name": "fileId", "dataType": [ "string" ] },
    { "name": "corpusId", "dataType": [ "string" ] },
    { "name": "chunkId", "dataType": [ "string" ] },
    { "name": "chunkDataType", "dataType": [ "string" ] },
    { "name": "chunkData", "dataType": [ "string" ] },
    { "name": "fileOriginalUri", "dataType": [ "string" ] }
  ]
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer "${WEAVIATE_API_KEY} \
    -d @- \
    ${HTTP_ENDPOINT_NAME}/v1/schema

Configurar o Secret Manager

Para configurar o Secret Manager, você precisa ativá-lo e definir as permissões.

Criar Secret

Para ativar o Secret Manager, faça o seguinte:

Console

  1. Acesse a página Secret Manager.

    Acessar o Secret Manager

  2. Clique em Criar secret.

  3. Insira o Nome do secret. Os nomes de secret só podem conter letras em inglês (A-Z), números (0-9), traços (-) e sublinhados (_).

  4. A especificação dos seguintes campos é opcional:

    1. Para fazer upload do arquivo com seu secret, clique em Procurar.
    2. Leia a política de replicação.
    3. Se você quiser gerenciar os locais do secret manualmente, marque a opção Gerenciar locais manualmente para este secret. Pelo menos uma região precisa ser selecionada.
    4. Selecione a opção de criptografia.
    5. Se você quiser definir o período de rotação manualmente, marque a opção Definir período de rotação.
    6. Se você quiser especificar tópicos de publicação ou assinatura para receber notificações de eventos, clique em Adicionar tópicos.
    7. Por padrão, o secret nunca expira. Se você quiser definir uma data de validade, marque Definir data de validade.
    8. Por padrão, as versões de segredos são destruídas quando solicitadas. Para atrasar a destruição de versões secretas, marque a opção Definir duração para destruição atrasada.
    9. Se você quiser usar rótulos para organizar e categorizar seus segredos, clique em + Adicionar rótulo.
    10. Se você quiser usar anotações para anexar metadados sem identificação aos seus secrets, clique em + Adicionar anotação.

  5. Clique em Criar secret.

REST

# Create a secret in SecretManager.
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets?secretId=${SECRET_NAME}" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"replication\": {\"automatic\": {}}}"

Python

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

def create_secret(
    project_id: str, secret_id: str, ttl: Optional[str] = None
) -> secretmanager.Secret:
    """
    Create a new secret with the given name. A secret is a logical wrapper
    around a collection of secret versions. Secret versions hold the actual
    secret material.

     Args:
        project_id (str): The project ID where the secret is to be created.
        secret_id (str): The ID to assign to the new secret. This ID must be unique within the project.
        ttl (Optional[str]): An optional string that specifies the secret's time-to-live in seconds with
                             format (e.g., "900s" for 15 minutes). If specified, the secret
                             versions will be automatically deleted upon reaching the end of the TTL period.

    Returns:
        secretmanager.Secret: An object representing the newly created secret, containing details like the
                              secret's name, replication settings, and optionally its TTL.

    Example:
        # Create a secret with automatic replication and no TTL
        new_secret = create_secret("my-project", "my-new-secret")

        # Create a secret with a TTL of 30 days
        new_secret_with_ttl = create_secret("my-project", "my-timed-secret", "7776000s")
    """

    # Import the Secret Manager client library.
    from google.cloud import secretmanager

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent project.
    parent = f"projects/{project_id}"

    # Create the secret.
    response = client.create_secret(
        request={
            "parent": parent,
            "secret_id": secret_id,
            "secret": {"replication": {"automatic": {}}, "ttl": ttl},
        }
    )

    # Print the new secret name.
    print(f"Created secret: {response.name}")

Definir permissões

É necessário conceder permissões do Secret Manager à sua conta de serviço.

Console

  1. Na seção IAM e administrador do console do Google Cloud, encontre sua conta de serviço e clique no ícone de lápis para editar.

  2. No campo Papel, selecione Acessador de secrets do Secret Manager.

Python

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

def iam_grant_access(
    project_id: str, secret_id: str, member: str
) -> iam_policy_pb2.SetIamPolicyRequest:
    """
    Grant the given member access to a secret.
    """

    # Import the Secret Manager client library.
    from google.cloud import secretmanager

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret.
    name = client.secret_path(project_id, secret_id)

    # Get the current IAM policy.
    policy = client.get_iam_policy(request={"resource": name})

    # Add the given member with access permissions.
    policy.bindings.add(role="roles/secretmanager.secretAccessor", members=[member])

    # Update the IAM Policy.
    new_policy = client.set_iam_policy(request={"resource": name, "policy": policy})

    # Print data about the secret.
    print(f"Updated IAM policy on {secret_id}")

Adicionar versão do secret

REST

# TODO(developer): Update the variables.
# Select a resource name for your Secret, which contains your API Key.
SECRET_NAME="MyWeaviateApiKeySecret"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"
# Encode your WEAVIATE_API_KEY using base 64.
SECRET_DATA=$(echo ${WEAVIATE_API_KEY} | base64)

# Create a new version of your secret which uses SECRET_DATA as payload
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets/${SECRET_NAME}:addVersion" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"payload\": {\"data\": \"${SECRET_DATA}\"}}"

Python

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import secretmanager
import google_crc32c  # type: ignore


def add_secret_version(
    project_id: str, secret_id: str, payload: str
) -> secretmanager.SecretVersion:
    """
    Add a new secret version to the given secret with the provided payload.
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent secret.
    parent = client.secret_path(project_id, secret_id)

    # Convert the string payload into a bytes. This step can be omitted if you
    # pass in bytes instead of a str for the payload argument.
    payload_bytes = payload.encode("UTF-8")

    # Calculate payload checksum. Passing a checksum in add-version request
    # is optional.
    crc32c = google_crc32c.Checksum()
    crc32c.update(payload_bytes)

    # Add the secret version.
    response = client.add_secret_version(
        request={
            "parent": parent,
            "payload": {
                "data": payload_bytes,
                "data_crc32c": int(crc32c.hexdigest(), 16),
            },
        }
    )

    # Print the new secret version name.
    print(f"Added secret version: {response.name}")

Usar o Weaviate com o Llama 3

O notebook da API RAG do Model Garden demonstra como usar o SDK da Vertex AI para Python com um corpus do Weaviate e um modelo Llama 3. Para usar o notebook, faça o seguinte:

  1. Configure o banco de dados do Weaviate.

  2. Configure o Secret Manager.

  3. Use o bloco de notas da API RAG do Model Garden.

Para mais exemplos, consulte Exemplos.

Criar um corpus RAG

Este exemplo de código demonstra como criar um corpus RAG e define a instância do Weaviate como o banco de dados de vetores.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# weaviate_http_endpoint = "weaviate-http-endpoint"
# weaviate_collection_name = "weaviate-collection-name"
# weaviate_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.EmbeddingModelConfig(
    publisher_model="publishers/google/models/text-embedding-004"
)

# Configure Vector DB
vector_db = rag.Weaviate(
    weaviate_http_endpoint=weaviate_http_endpoint,
    collection_name=weaviate_collection_name,
    api_key=weaviate_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    embedding_model_config=embedding_model_config,
    vector_db=vector_db,
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

Usar o arquivo RAG

A API RAG processa o upload, a importação, a listagem e a exclusão de arquivos.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do recurso RagCorpus.
  • INPUT_FILE: o caminho de um arquivo local.
  • FILE_DISPLAY_NAME: o nome de exibição do RagFile.
  • RAG_FILE_DESCRIPTION: a descrição do RagFile.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload

Corpo JSON da solicitação:

{
 "rag_file": {
  "display_name": "FILE_DISPLAY_NAME",
  "description": "RAG_FILE_DESCRIPTION"
 }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome INPUT_FILE e execute o comando a seguir: 

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @INPUT_FILE \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome INPUT_FILE e execute o comando a seguir: 

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile INPUT_FILE `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload" | Select-Object -Expand Content
Uma resposta bem-sucedida retorna o recurso RagFile. O último componente do campo RagFile.name é o rag_file_id gerado pelo servidor.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"
# path = "path/to/local/file.txt"
# display_name = "file_display_name"
# description = "file description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_file = rag.upload_file(
    corpus_name=corpus_name,
    path=path,
    display_name=display_name,
    description=description,
)
print(rag_file)
# RagFile(name='projects/[PROJECT_ID]/locations/us-central1/ragCorpora/1234567890/ragFiles/09876543',
#  display_name='file_display_name', description='file description')

Importar arquivos RAG

É possível importar arquivos e pastas do Drive ou do Cloud Storage.

REST

Use response.metadata para conferir falhas parciais, tempo de solicitação e tempo de resposta no objeto response do SDK.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do recurso RagCorpus.
  • GCS_URIS: uma lista de locais do Cloud Storage. Exemplo: gs://my-bucket1, gs://my-bucket2.
  • DRIVE_RESOURCE_ID: o ID do recurso do Drive. Exemplos:
    • https://drive.google.com/file/d/ABCDE
    • https://drive.google.com/corp/drive/u/0/folders/ABCDEFG
  • DRIVE_RESOURCE_TYPE: tipo do recurso do Drive. Opções:
    • RESOURCE_TYPE_FILE - Arquivo
    • RESOURCE_TYPE_FOLDER - Pasta
  • CHUNK_SIZE (opcional): número de tokens que cada bloco precisa ter.
  • CHUNK_OVERLAP (opcional): número de tokens sobrepostos entre blocos.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import

Corpo JSON da solicitação:

{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": GCS_URIS
    },
    "google_drive_source": {
      "resource_ids": {
        "resource_id": DRIVE_RESOURCE_ID,
        "resource_type": DRIVE_RESOURCE_TYPE
      },
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import" | Select-Object -Expand Content
Uma resposta bem-sucedida retorna o recurso ImportRagFilesOperationMetadata.

O exemplo a seguir demonstra como importar um arquivo do Cloud Storage. Use o campo de controle max_embedding_requests_per_min para limitar a taxa em que o RAG Engine chama o modelo de embedding durante o processo de indexação ImportRagFiles. O campo tem um valor padrão de 1000 chamadas por minuto.

// Cloud Storage bucket/file location.
// Such as "gs://rag-e2e-test/"
GCS_URIS=YOUR_GCS_LOCATION

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import a single Cloud Storage file or all files in a Cloud Storage bucket.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, GCS_URIS
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URIS}"\"'
    },
    "rag_file_chunking_config": {
      "chunk_size": 512
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

O exemplo a seguir demonstra como importar um arquivo do Drive. Use o campo de controle max_embedding_requests_per_min para limitar a taxa em que o RAG Engine chama o modelo de embedding durante o processo de indexação ImportRagFiles. O campo tem um valor padrão de 1000 chamadas por minuto.

// Google Drive folder location.
FOLDER_RESOURCE_ID=YOUR_GOOGLE_DRIVE_FOLDER_RESOURCE_ID

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import all files in a Google Drive folder.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, FOLDER_RESOURCE_ID
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "google_drive_source": {
      "resource_ids": {
        "resource_id": '\""${FOLDER_RESOURCE_ID}"\"',
        "resource_type": "RESOURCE_TYPE_FOLDER"
      }
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"
# paths = ["https://drive.google.com/file/123", "gs://my_bucket/my_files_dir"]  # Supports Google Cloud Storage and Google Drive Links

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.import_files(
    corpus_name=corpus_name,
    paths=paths,
    chunk_size=512,  # Optional
    chunk_overlap=100,  # Optional
    max_embedding_requests_per_min=900,  # Optional
)
print(f"Imported {response.imported_rag_files_count} files.")
# Example response:
# Imported 2 files.

Acessar um arquivo RAG

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do recurso RagCorpus.
  • RAG_FILE_ID: o ID do recurso RagFile.

Método HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte comando: 

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

execute o seguinte comando: 

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content
Uma resposta bem-sucedida retorna o recurso RagFile.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_file = rag.get_file(name=file_name)
print(rag_file)
# Example response:
# RagFile(name='projects/1234567890/locations/us-central1/ragCorpora/11111111111/ragFiles/22222222222',
# display_name='file_display_name', description='file description')

Listar arquivos RAG

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do recurso RagCorpus.
  • PAGE_SIZE: tamanho de página de lista padrão. É possível ajustar o número de RagFiles a serem retornados por página atualizando o parâmetro page_size.
  • PAGE_TOKEN: o token de página de lista padrão. Extraído normalmente usando o ListRagFilesResponse.next_page_token da chamada VertexRagDataService.ListRagFiles anterior.

Método HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte comando: 

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

PowerShell

execute o seguinte comando: 

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content
Você receberá um código de status bem-sucedido (2xx) junto com uma lista de RagFiles no RAG_CORPUS_ID especificado.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

files = rag.list_files(corpus_name=corpus_name)
for file in files:
    print(file.display_name)
    print(file.name)
# Example response:
# g-drive_file.txt
# projects/1234567890/locations/us-central1/ragCorpora/111111111111/ragFiles/222222222222
# g_cloud_file.txt
# projects/1234567890/locations/us-central1/ragCorpora/111111111111/ragFiles/333333333333

Excluir um arquivo RAG

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do recurso RagCorpus.
  • RAG_FILE_ID: o ID do recurso RagFile. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file_id}.

Método HTTP e URL: 

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte comando: 

curl -X DELETE \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

execute o seguinte comando: 

$headers = @{  }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content
Uma resposta bem-sucedida retorna o recurso DeleteOperationMetadata.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag.delete_file(name=file_name)
print(f"File {file_name} deleted.")
# Example response:
# Successfully deleted the RagFile.
# File projects/1234567890/locations/us-central1/ragCorpora/1111111111/ragFiles/2222222222 deleted.

Recuperar contexto

Quando um usuário faz uma pergunta ou fornece uma solicitação, o componente de recuperação na RAG pesquisa na base de conhecimento para encontrar informações relevantes para a consulta.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: a região para processar a solicitação.
  • PROJECT_ID: o ID do projeto.
  • RAG_CORPUS_RESOURCE: o nome do recurso RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
  • VECTOR_DISTANCE_THRESHOLD: somente contextos com uma distância vetorial menor que o limite são retornados.
  • TEXT: o texto da consulta para receber contextos relevantes.
  • SIMILARITY_TOP_K: o número dos principais contextos a serem recuperados.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts

Corpo JSON da solicitação:

{
 "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "vector_distance_threshold": 0.8
  },
  "query": {
   "text": "TEXT",
   "similarity_top_k": SIMILARITY_TOP_K
  }
 }

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" | Select-Object -Expand Content
Você vai receber um código de status (2xx) e uma lista de RagFiles relacionadas.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-central1/ragCorpora/[rag_corpus_id]"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.retrieval_query(
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus_name,
            # Optional: supply IDs from `rag.list_files()`.
            # rag_file_ids=["rag-file-1", "rag-file-2", ...],
        )
    ],
    text="Hello World!",
    similarity_top_k=10,  # Optional
    vector_distance_threshold=0.5,  # Optional
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Gera conteúdo

Uma previsão controla o método LLM que gera conteúdo.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • MODEL_ID: modelo LLM para geração de conteúdo. Exemplo: gemini-1.5-pro-002
  • GENERATION_METHOD: método LLM para geração de conteúdo. Opções: generateContent, streamGenerateContent
  • INPUT_PROMPT: o texto enviado ao LLM para geração de conteúdo. Tente usar um comando relevante para os arquivos de Rag enviados.
  • RAG_CORPUS_RESOURCE: o nome do recurso RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
  • SIMILARITY_TOP_K (opcional): o número dos principais contextos a serem recuperados.
  • VECTOR_DISTANCE_THRESHOLD (opcional): os contextos com uma distância vetorial menor que o limite são retornados.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD

Corpo JSON da solicitação:

{
 "contents": {
  "role": "user",
  "parts": {
    "text": "INPUT_PROMPT"
  }
 },
 "tools": {
  "retrieval": {
   "disable_attribution": false,
   "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "similarity_top_k": SIMILARITY_TOP_K,
    "vector_distance_threshold": VECTOR_DISTANCE_THRESHOLD
   }
  }
 }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD" | Select-Object -Expand Content
Uma resposta bem-sucedida retornará o conteúdo gerado com citações.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 


from vertexai.preview import rag
from vertexai.preview.generative_models import GenerativeModel, Tool
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_retrieval_tool = Tool.from_retrieval(
    retrieval=rag.Retrieval(
        source=rag.VertexRagStore(
            rag_resources=[
                rag.RagResource(
                    rag_corpus=corpus_name,
                    # Optional: supply IDs from `rag.list_files()`.
                    # rag_file_ids=["rag-file-1", "rag-file-2", ...],
                )
            ],
            similarity_top_k=3,  # Optional
            vector_distance_threshold=0.5,  # Optional
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-1.5-flash-001", tools=[rag_retrieval_tool]
)
response = rag_model.generate_content("Why is the sky blue?")
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

A pesquisa híbrida é compatível com o banco de dados do Weaviate, que combina pesquisas semânticas e de palavras-chave para melhorar a relevância dos resultados. Durante a recuperação dos resultados da pesquisa, uma combinação de pontuações de similaridade da semântica (um vetor denso) e da correspondência de palavras-chave (um vetor disperso) produz os resultados finais classificados.

Pesquisa híbrida usando a API de recuperação do mecanismo RAG

Este é um exemplo de como ativar uma pesquisa híbrida usando a API de recuperação do mecanismo RAG.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-central1/ragCorpora/[rag_corpus_id]"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.retrieval_query(
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus_name,
            # Optional: supply IDs from `rag.list_files()`.
            # rag_file_ids=["rag-file-1", "rag-file-2", ...],
        )
    ],
    text="Hello World!",
    similarity_top_k=10,  # Optional
    vector_distance_threshold=0.5,  # Optional
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Usar a pesquisa híbrida e o RAG Engine para geração de embasamento

Este é um exemplo de como usar a pesquisa híbrida e o mecanismo RAG para geração com base em dados.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python. 


from vertexai.preview import rag
from vertexai.preview.generative_models import GenerativeModel, Tool
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_retrieval_tool = Tool.from_retrieval(
    retrieval=rag.Retrieval(
        source=rag.VertexRagStore(
            rag_resources=[
                rag.RagResource(
                    rag_corpus=corpus_name,
                    # Optional: supply IDs from `rag.list_files()`.
                    # rag_file_ids=["rag-file-1", "rag-file-2", ...],
                )
            ],
            similarity_top_k=3,  # Optional
            vector_distance_threshold=0.5,  # Optional
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-1.5-flash-001", tools=[rag_retrieval_tool]
)
response = rag_model.generate_content("Why is the sky blue?")
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

A seguir