Usar um banco de dados do Weaviate com o mecanismo RAG

Nesta página, mostramos como conectar seu corpus do RAG Engine ao banco de dados do Weaviate.

Você também pode acompanhar usando o notebook Mecanismo de RAG com o Weaviate.

É possível usar sua instância do banco de dados 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 trechos de texto semelhantes ao texto que você está procurando, o que requer o uso de um modelo de embedding. O modelo de embedding produz dados vetoriais para cada trecho de texto que está sendo comparado. A pesquisa de similaridade é usada para recuperar contextos semânticos para embasamento, de modo a retornar o conteúdo mais preciso do LLM.

Com o RAG Engine, você pode continuar usando sua instância de banco de dados de vetores totalmente gerenciada, que é responsável por provisionar. O mecanismo RAG usa o banco de dados vetorial para armazenamento, gerenciamento de índices e pesquisa.

Considerações

Considere as seguintes etapas antes de usar o banco de dados do Weaviate:

  1. É necessário 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 é compatível com o AuthN e o AuthZ baseados em chave de API, que se conectam ao banco de dados do Weaviate e são compatíveis com 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 Google Cloud Secret Manager.
    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 o recurso secreto usando sua conta de serviço.
  4. O corpus do mecanismo RAG e a coleção do Weaviate têm um mapeamento um para 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 de RAG é associado à coleção do banco de dados.
  5. Além das pesquisas semânticas baseadas em embeddings densos, a pesquisa híbrida também é compatível com o RAG Engine por meio de 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 mecanismo de RAG, faça o seguinte:

  1. Configurar e implantar sua instância de 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 sua 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, é possível usar o guia do Marketplace doGoogle Cloud , que é opcional.

É possível configurar a instância do Weaviate em qualquer lugar, desde que o endpoint do Weaviate esteja acessível para configuração e implantação no projeto. Em seguida, é possível gerenciar totalmente sua instância de 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 tráfego do banco de dados do mecanismo de RAG e do Weaviate use uma conexão HTTPS.

Criar sua coleção do Weaviate

Como o corpus do mecanismo RAG e a coleção do Weaviate têm um mapeamento um para um, é necessário criar uma coleção no banco de dados do Weaviate antes de associá-la ao corpus do mecanismo RAG. Essa associação única é feita quando você chama a API CreateRagCorpus ou 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 de API do Weaviate envolve as seguintes etapas:

  1. Crie a chave de API do Weaviate.
  2. Configure o Weaviate usando sua chave de API do Weaviate.
  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 do Weaviate para autenticação para configurar a autenticação baseada em chave de API na instância do banco de dados do Weaviate.

Se a criação da chave de API do Weaviate exigir informações de identidade para associar ao RAG Engine, crie seu primeiro corpus e use sua conta de serviço do RAG Engine como 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 de SPII forem comprometidos ou usados de maneira indevida, um indivíduo poderá sofrer um risco ou dano significativo. Para minimizar os riscos para um indivíduo ao usar o mecanismo RAG, não armazene nem gerencie sua chave de API e evite compartilhar a chave de API não criptografada.

Para proteger as SPII, faça o seguinte:

  1. Armazene sua chave de API no Secret Manager.
  2. Conceda à conta de serviço do RAG Engine as permissões para os secrets e gerencie o controle de acesso no nível do recurso do secret.
    1. Acesse 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 Acessador de secrets do Secret Manager à conta de serviço.
  3. Durante a criação ou atualização do corpus de RAG, transmita o nome do recurso do secret para o mecanismo de RAG e armazene o nome do recurso do secret.

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 que corresponde aos recursos de secret no Secret Manager dos seus projetos.

Provisionar sua 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. Encontre 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:

  • Use sua conta de serviço para gerar a chave de API do Weaviate para autenticação. Em alguns casos, a geração da chave de API não requer informações 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, sua conta de serviço não é obrigatória.
  • É possível armazenar o Secret Manager da chave de API no projeto e conceder permissões de 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. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  7. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.

  8. Instale ou atualize o SDK da Agent Platform para Python executando o seguinte comando:

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

Node.js

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  7. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.

  8. Instale ou atualize o SDK da Agent Platform para Node.js executando o seguinte comando:

    npm install @google-cloud/vertexai

Java

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  7. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.

  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 sem BoM

    Adicione o seguinte ao seu build.gradle:

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

Go

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  7. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.

  8. Analise os pacotes disponíveis da API Agent Platform 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 Agent Platform. 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 Agent Platform 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. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  7. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.

REST

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    6.

  6. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  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-3.5-flash"
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 de RAG

Para acessar dados do banco de dados do Weaviate, o mecanismo de RAG precisa ter acesso a um corpus de RAG. Nesta seção, mostramos as etapas para criar um único corpus de RAG e outros corpora de 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 vetorial é escolhida. A configuração do banco de dados vetorial 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 vetorial.
  • api_key_config.api_key_secret_version: o nome do recurso do secret armazenado no Secret Manager, que contém sua chave de API do Weaviate.

É possível criar e associar seu corpus de RAG à coleção do Weaviate na instância do banco de dados. No entanto, talvez você precise da conta de serviço para gerar a chave de 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 de 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 de RAG.

Caso seu banco de dados e sua chave não estejam prontos para serem associados ao corpus de 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 vetores associado.
    • Deixe os campos http_endpoint e collection_name em branco. Ambos os campos podem ser atualizados posteriormente.

  2. Se você não tiver sua 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 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 alterá-los, a menos que você exclua o corpus de RAG e o crie novamente. Outros campos, como o campo de chave de API, api_key_secret_version, podem ser atualizados.

  4. Ao chamar UpdateRagCorpus, é possível 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 Banco de dados gerenciado pela RAG, que é o padrão. Não é possível mudar essa opção ao chamar a API UpdateRagCorpus. Ao chamar UpdateRagCorpus e o campo vector_db estiver parcialmente definido, será possível atualizar os campos marcados como Alteráveis (também chamados de mutáveis).

Esta tabela lista os campos mutáveis e imutáveis de WeaviateConfig que são 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 de RAG

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

  1. Crie um corpus de RAG no mecanismo RAG com uma configuração vazia do Weaviate, que inicia o provisionamento do mecanismo RAG para criar uma conta de serviço.
  2. Escolha um nome para a conta de serviço do mecanismo RAG 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 seu projeto, que contém sua 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 de RAG

Quando a conta de serviço do mecanismo de RAG 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 do 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 seu projeto, que contém sua chave de API do Weaviate.
  5. Durante o provisionamento do Weaviate, receba as seguintes informações:
    • O endpoint HTTPS ou HTTP do Weaviate.
    • O nome da sua coleção do Weaviate.
  6. Crie um corpus de RAG no mecanismo de RAG e conecte-se à sua coleção do Weaviate seguindo um destes procedimentos:
    1. Faça uma chamada de API CreateRagCorpus para criar um corpus RAG com uma configuração do Weaviate preenchida, que é a opção preferida.
    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 do Weaviate
      • Chave de API

Exemplos

Nesta seção, apresentamos um exemplo de código que demonstra como configurar o banco de dados do Weaviate, o Secret Manager, o corpus de RAG e o arquivo de RAG. Também fornecemos exemplos de código para demonstrar como importar arquivos, recuperar 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 Agent Platform 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 do Secret Manager.

    Acessar o Secret Manager

  2. Clique em Criar secret.

  3. Insira o Nome do secret. Nomes de secrets podem conter apenas 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 o secret, clique em Procurar.
    2. Leia a política de replicação.
    3. Se você quiser gerenciar manualmente os locais do secret, marque Gerenciar manualmente os locais deste secret. Selecione pelo menos uma região.
    4. Selecione a opção de criptografia.
    5. Se você quiser definir manualmente o período de rotação, marque 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 secrets são destruídas quando solicitado. Para atrasar a destruição de versões de secrets, marque Definir duração para destruição com atraso.
    9. Se você quiser usar rótulos para organizar e categorizar seus secrets, clique em + Adicionar rótulo.
    10. Se você quiser usar anotações para anexar metadados sem identificação aos 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 este exemplo, siga as instruções de configuração do Python no Guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

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

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


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")
    """

    # 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

É preciso 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 este exemplo, siga as instruções de configuração do Python no Guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na Plataforma de Agentes, 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 este exemplo, siga as instruções de configuração do Python no Guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na Plataforma de Agentes, 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 Agent Platform 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 notebook 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 vetorial.

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 Agent Platform 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 este exemplo, siga as instruções de configuração do Python no Guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

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


import agentplatform
from agentplatform import types

# 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 Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

# Configure embedding model (Optional)
embedding_model_config = types.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=types.RagEmbeddingModelConfigVertexPredictionEndpoint(
        endpoint="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = types.RagVectorDbConfigWeaviate(
    http_endpoint=weaviate_http_endpoint,
    collection_name=weaviate_collection_name,
)

corpus = client.rag.create_corpus(
    rag_corpus=types.RagCorpus(
        display_name=display_name,
        description=description,
        rag_vector_db_config=types.RagVectorDbConfig(
            weaviate=vector_db,
            api_auth=types.ApiAuth(
                api_key_config=types.ApiAuthApiKeyConfig(
                    api_key_secret_version=weaviate_api_key_secret_manager_version
                )
            ),
            rag_embedding_model_config=embedding_model_config,
        ),
    )
)
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: .
  • 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/media: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/media: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/media: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. 


import agentplatform

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

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

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

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: .
  • 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 mecanismo RAG 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 mecanismo RAG 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. 


import agentplatform
from agentplatform import types

from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"
# paths = ["gs://my_bucket/my_files_dir/*"]

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

response = client.rag.import_files(
    name=corpus_name,
    import_config=types.ImportRagFilesConfig(
        gcs_source=genai_types.GcsSource(uris=paths),
        rag_file_transformation_config=types.RagFileTransformationConfig(
            rag_file_chunking_config=types.RagFileChunkingConfig(
                chunk_size=512,
                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: .
  • 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. 


import agentplatform

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

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

rag_file = client.rag.get_file(name=file_name)
print(rag_file)
# Example response:
# RagFile(name='projects/1234567890/locations/us-east5/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: .
  • 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. 


import agentplatform

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

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

files_response = client.rag.list_files(name=corpus_name)
for file in files_response.rag_files:
    print(file.display_name)
    print(file.name)
# Example response:
# g-drive_file.txt
# projects/1234567890/locations/us-east5/ragCorpora/111111111111/ragFiles/222222222222
# g_cloud_file.txt
# projects/1234567890/locations/us-east5/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: .
  • 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. 


import agentplatform

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

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

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

Recuperar contexto

Quando um usuário faz uma pergunta ou fornece um comando, 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: .
  • 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. 


import agentplatform

from agentplatform import types
from google.genai import types as genai_types

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

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

response = client.rag.retrieve_contexts(
    vertex_rag_store=genai_types.VertexRagStore(
        rag_resources=[
            genai_types.VertexRagStoreRagResource(
                rag_corpus=corpus_name,
                # Optional: supply IDs from `rag.list_files()`.
                # rag_file_ids=["rag-file-1", "rag-file-2", ...],
            )
        ],
    ),
    query=types.RagQuery(
        text="Hello World!",
        rag_retrieval_config=genai_types.RagRetrievalConfig(
            top_k=10,
            filter=genai_types.RagRetrievalConfigFilter(
                vector_distance_threshold=0.5
            ),
        ),
    )
)
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: .
  • LOCATION: a região para processar a solicitação.
  • MODEL_ID: modelo LLM para geração de conteúdo. Exemplo: gemini-3.5-flash
  • 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 google import genai
from google.genai import types as genai_types

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

rag_retrieval_tool = genai_types.Tool(
    retrieval=genai_types.Retrieval(
        vertex_rag_store=genai_types.VertexRagStore(
            rag_resources=[
                genai_types.VertexRagStoreRagResource(
                    rag_corpus=corpus_name
                )
            ],
            rag_retrieval_config=genai_types.RagRetrievalConfig(
                top_k=10,
                filter=genai_types.RagRetrievalConfigFilter(
                    vector_distance_threshold=0.5
                ),
            ),
        ),
    )
)

# Create a GenAI SDK client to make a generate_content request
genai_client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = genai_client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Why is the sky blue?",
    config=genai_types.GenerateContentConfig(
        tools=[rag_retrieval_tool]
    ),
)
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 Weaviate, que combina pesquisas semânticas e por palavras-chave para melhorar a relevância dos resultados da pesquisa. Durante a recuperação dos resultados da pesquisa, uma combinação de pontuações de similaridade da correspondência semântica (um vetor denso) e da correspondência de palavra-chave (um vetor esparso) 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 Agent Platform 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. 


import agentplatform

from agentplatform import types
from google.genai import types as genai_types

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

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

response = client.rag.retrieve_contexts(
    vertex_rag_store=genai_types.VertexRagStore(
        rag_resources=[
            genai_types.VertexRagStoreRagResource(
                rag_corpus=corpus_name,
                # Optional: supply IDs from `rag.list_files()`.
                # rag_file_ids=["rag-file-1", "rag-file-2", ...],
            )
        ],
    ),
    query=types.RagQuery(
        text="Hello World!",
        rag_retrieval_config=genai_types.RagRetrievalConfig(
            top_k=10,
            filter=genai_types.RagRetrievalConfigFilter(
                vector_distance_threshold=0.5
            ),
        ),
    )
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Usar a pesquisa híbrida e o mecanismo RAG para geração embasada

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

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 Agent Platform 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 google import genai
from google.genai import types as genai_types

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

rag_retrieval_tool = genai_types.Tool(
    retrieval=genai_types.Retrieval(
        vertex_rag_store=genai_types.VertexRagStore(
            rag_resources=[
                genai_types.VertexRagStoreRagResource(
                    rag_corpus=corpus_name
                )
            ],
            rag_retrieval_config=genai_types.RagRetrievalConfig(
                top_k=10,
                filter=genai_types.RagRetrievalConfigFilter(
                    vector_distance_threshold=0.5
                ),
            ),
        ),
    )
)

# Create a GenAI SDK client to make a generate_content request
genai_client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = genai_client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Why is the sky blue?",
    config=genai_types.GenerateContentConfig(
        tools=[rag_retrieval_tool]
    ),
)
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