API RAG Engine

O mecanismo de RAG da Vertex AI é um componente da plataforma Vertex AI para geração aumentada de recuperação (RAG). Com o mecanismo RAG, os modelos de linguagem grandes (LLMs) podem acessar e usar dados de fontes de conhecimento externas, como documentos e bancos de dados, para gerar respostas mais precisas e informativas.

Este documento fornece informações e exemplos de uso da API RAG Engine e aborda os seguintes tópicos:

  • Gerenciamento de corpus:descreve os parâmetros da API para gerenciar corpus e fornece exemplos de como criar, atualizar, listar, receber e excluir um corpus RAG.
  • Gerenciamento de arquivos:descreve os parâmetros da API para gerenciar arquivos e fornece exemplos de upload, importação e gerenciamento de arquivos em um corpus RAG.
  • Recuperação e geração:descreve os parâmetros da API para recuperar contextos e gerar respostas embasadas, com exemplos.
  • Gerenciamento de projetos:explica como configurar as definições no nível do projeto para o mecanismo RAG, com exemplos.

O diagrama a seguir resume o fluxo de trabalho geral para usar a API RAG Engine:

Parâmetros de gerenciamento do corpus

Nesta seção, descrevemos os parâmetros para gerenciar um corpus RAG. Para mais informações, consulte Gerenciamento de corpus.

Criar um corpus RAG

As tabelas a seguir descrevem os parâmetros usados para criar um corpus RAG.

Opções de banco de dados vetorial

Você pode escolher uma das seguintes opções de banco de dados de vetores para seu corpus de RAG.

Opção de banco de dados de vetores Descrição Caso de uso
rag_managed_db Um banco de dados vetorial totalmente gerenciado e sem servidor fornecido pela Vertex AI. Essa é a opção padrão. Recomendado se você quiser uma solução simples e integrada sem gerenciar sua própria infraestrutura de banco de dados de vetores.
pinecone Integração com um banco de dados de vetores do Pinecone autogerenciado. É necessário informar o nome do índice e a chave de API do Pinecone. Use essa opção se você já tiver uma configuração do Pinecone ou preferir os recursos específicos dele.
vertex_vector_search Integração com a Pesquisa vetorial. Exige o fornecimento dos nomes de recursos do índice e do endpoint do índice. Use essa opção se precisar de uma solução de pesquisa vetorial escalonável e de alta performance no ecossistema do Google Cloud.

Corpo da solicitação

Parâmetros
display_name

Obrigatório: string

O nome de exibição do corpus de RAG.

description

Opcional: string

A descrição do corpus RAG.

encryption_spec

Opcional: imutável: string

O nome da chave CMEK usada para criptografar dados em repouso relacionados ao corpus de RAG. Essa chave só é aplicável à opção RagManaged para o banco de dados vetorial. Esse campo só pode ser definido durante a criação do corpus.

Formato: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}

vector_db_config

Opcional: imutável: vectorDbConfig

A configuração do banco de dados de vetores. Esse campo é um objeto oneof. Escolha uma destas opções:

  • rag_managed_db: o banco de dados vetorial padrão totalmente gerenciado.
  • pinecone: especifica a instância do Pinecone.
    • index_name (string): o nome do índice do Pinecone. Isso pode ser definido mais tarde com uma chamada UpdateRagCorpus.
    • api_auth.api_key_config.api_key_secret_version (string): o nome completo do recurso do secret no Secret Manager que contém sua chave de API do Pinecone. Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}. Isso pode ser definido mais tarde.
  • vertex_vector_search: especifica sua instância da Pesquisa de vetores.
    • index (string): o nome do recurso do índice de pesquisa vetorial. Formato: projects/{project}/locations/{location}/indexes/{index}. Isso pode ser definido mais tarde.
    • index_endpoint (string): o nome do recurso do endpoint do índice de pesquisa de vetores. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}. Isso pode ser definido mais tarde.
vertex_ai_search_config.serving_config

Opcional: string

A configuração da Vertex AI para Pesquisa.

Formato: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config} ou projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/servingConfigs/{serving_config}

rag_embedding_model_config.vertex_prediction_endpoint.endpoint

Opcional: imutável: string

O modelo de embedding a ser usado para o corpus RAG. Esse valor não pode ser mudado depois de definido. Se você deixar em branco, text-embedding-005 será usado como o modelo de embedding padrão.

Atualizar um corpus RAG

Esta tabela lista os parâmetros usados para atualizar um corpus de RAG.

Corpo da solicitação

Parâmetros
display_name

Opcional: string

O novo nome de exibição do corpus RAG.

description

Opcional: string

A nova descrição do corpus RAG.

rag_vector_db.pinecone.index_name

string

O nome do índice do Pinecone. É possível definir esse campo se o RagCorpus foi criado com uma configuração Pinecone e o nome do índice não foi definido antes.

rag_vector_db.vertex_vector_search.index

string

O nome do recurso do índice da Pesquisa de vetor. Você pode definir esse campo se o RagCorpus foi criado com uma configuração Vector Search e o índice não foi definido antes.

Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}

rag_vector_db.vertex_vector_search.index_endpoint

string

O nome do recurso do endpoint do índice da Pesquisa de vetor. É possível definir esse campo se o RagCorpus foi criado com uma configuração Vector Search e o endpoint do índice não foi definido antes.

Formato: projects/{project}/locations/{location}/indexes/{index}

rag_vector_db.api_auth.api_key_config.api_key_secret_version

string

O nome completo do recurso do secret no Secret Manager que contém sua chave de API do Pinecone.

Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Listar corpus da RAG

Esta tabela lista os parâmetros usados para listar corpora de RAG.

Parâmetros

page_size

Opcional: int

O número máximo de corpora a serem retornados por página.

page_token

Opcional: string

O token de página de lista padrão. Normalmente recebido de [ListRagCorporaResponse.next_page_token][] da chamada [VertexRagDataService.ListRagCorpora][] anterior.

Acessar um corpus RAG

Esta tabela lista o parâmetro usado para extrair um corpus RAG.

Parâmetros
name

Obrigatório: string

RagCorpus: o nome do recurso. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

Excluir um corpus RAG

Esta tabela lista o parâmetro usado para excluir um corpus RAG.

Parâmetros
name

Obrigatório: string

O nome do recurso RagCorpus a ser excluído. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

Parâmetros de gerenciamento de arquivos

Nesta seção, descrevemos os parâmetros para gerenciar arquivos em um corpus de RAG. Para mais informações, consulte Gerenciamento de arquivos.

Fazer upload de um arquivo RAG

Esta tabela lista os parâmetros usados para fazer upload de um arquivo RAG.

Corpo da solicitação

Parâmetros
parent

Obrigatório: string

O nome do recurso RagCorpus para fazer upload do arquivo. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

rag_file

Obrigatório: RagFile

O arquivo a ser enviado. Contém os seguintes campos:

  • display_name (obrigatório, string): o nome de exibição do arquivo RAG.
  • description (opcional, string): a descrição do arquivo RAG.
upload_rag_file_config

Obrigatório: UploadRagFileConfig

A configuração do RagFile. Contém os seguintes campos:

  • rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_size (int32): o número de tokens em cada bloco.
  • rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_overlap (int32): a sobreposição de tokens entre blocos.

Importar arquivos RAG

Esta tabela lista os parâmetros usados para importar um arquivo RAG.

Parâmetros

parent

Obrigatório: string

RagCorpus: o nome do recurso.

Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

gcs_source

oneof import_source: GcsSource

Local do Cloud Storage.

Permite importar arquivos individuais e diretórios inteiros do Cloud Storage.

gcs_source.uris

list de string

URI do Cloud Storage que contém o arquivo de upload

google_drive_source

oneof import_source: GoogleDriveSource

Local do Google Drive.

Suporta a importação de arquivos individuais e pastas do Google Drive.

slack_source

oneof import_source: SlackSource

O canal do Slack em que o arquivo foi enviado.

jira_source

oneof import_source: JiraSource

A consulta do Jira em que o arquivo é enviado.

share_point_sources

oneof import_source: SharePointSources

As fontes do SharePoint em que o arquivo é enviado.

rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_size

int32

O número de tokens que cada bloco tem.

rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_overlap

int32

A sobreposição entre os blocos.

rag_file_parsing_config

Opcional: RagFileParsingConfig

Especifica a configuração de análise para RagFiles.

Se esse campo não for definido, a RAG vai usar o analisador padrão.

max_embedding_requests_per_min

Opcional: int32

O número máximo de consultas por minuto que este job pode fazer para o modelo de embedding especificado no corpus. Esse valor é específico para esse job e não é compartilhado com outros jobs de importação. Consulte a página "Cotas" no projeto para definir um valor adequado.

Se não for especificado, um valor padrão de 1.000 QPM será usado.

GoogleDriveSource

resource_ids.resource_id

Obrigatório: string

O o ID do recurso do Google Drive.

resource_ids.resource_type

Obrigatório: string

O tipo do recurso do Google Drive.

SlackSource

channels.channels

Repetido: SlackSource.SlackChannels.SlackChannel

Informações do canal do Slack, incluindo ID e período a ser importado.

channels.channels.channel_id

Obrigatório: string

O ID do canal do Slack.

channels.channels.start_time

Opcional: google.protobuf.Timestamp

O carimbo de data/hora inicial das mensagens a serem importadas.

channels.channels.end_time

Opcional: google.protobuf.Timestamp

O carimbo de data/hora final das mensagens a serem importadas.

channels.api_key_config.api_key_secret_version

Obrigatório: string

O nome completo do recurso do secret armazenado no Secret Manager, que contém um token de acesso ao canal do Slack com acesso aos IDs dos canais do Slack.
Acesse: https://api.slack.com/tutorials/tracks/getting-a-token.

Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

JiraSource

jira_queries.projects

Repetido: string

Uma lista de projetos do Jira para importar por completo.

jira_queries.custom_queries

Repetido: string

Uma lista de consultas personalizadas do Jira para importar. Para informações sobre a JQL (linguagem de consulta do Jira), consulte
Suporte do Jira

jira_queries.email

Obrigatório: string

O endereço de e-mail do Jira.

jira_queries.server_uri

Obrigatório: string

O URI do servidor do Jira.

jira_queries.api_key_config.api_key_secret_version

Obrigatório: string

O nome completo do recurso do secret armazenado no Secret Manager, que contém a chave de API do Jira com acesso aos IDs dos canais do Slack.
Acesse: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/

Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

SharePointSources

share_point_sources.sharepoint_folder_path

oneof em folder_source: string

O caminho da pasta do SharePoint para fazer o download.

share_point_sources.sharepoint_folder_id

oneof em folder_source: string

O ID da pasta do SharePoint de onde será feito o download.

share_point_sources.drive_name

oneof em drive_source: string

O nome da unidade de onde fazer o download.

share_point_sources.drive_id

oneof em drive_source: string

O ID da unidade de onde fazer o download.

share_point_sources.client_id

string

O ID do aplicativo registrado no portal do Microsoft Azure.
O aplicativo também precisa ser configurado com as permissões do MS Graph "Files.ReadAll", "Sites.ReadAll" e BrowserSiteLists.Read.All.

share_point_sources.client_secret.api_key_secret_version

Obrigatório: string

O nome completo do recurso do secret armazenado no Secret Manager, que contém o secret do aplicativo registrado no Azure.

Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

share_point_sources.tenant_id

string

Identificador exclusivo da instância do Azure Active Directory.

share_point_sources.sharepoint_site_name

string

O nome do site do SharePoint de onde fazer o download. Pode ser o nome ou o ID do site.

RagFileParsingConfig

layout_parser

oneof parser: RagFileParsingConfig.LayoutParser

O analisador de layout a ser usado para RagFiles.

layout_parser.processor_name

string

O nome completo do recurso de um processador ou uma versão do processador da Document AI.

Formato:
projects/{project_id}/locations/{location}/processors/{processor_id}
projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}

layout_parser.max_parsing_requests_per_min

string

O número máximo de solicitações que o job pode fazer ao processador da Document AI por minuto.

Consulte https://cloud.google.com/document-ai/quotas e a página "Cota" do seu projeto para definir um valor adequado aqui. Se não for especificado, um valor padrão de 120 QPM será usado.

llm_parser

oneof parser: RagFileParsingConfig.LlmParser

O analisador de LLM a ser usado para RagFiles.

llm_parser.model_name

string

O nome do recurso de um modelo de LLM.

Formato:
projects/{project_id}/locations/{location}/publishers/{publisher}/models/{model}

llm_parser.max_parsing_requests_per_min

string

O número máximo de solicitações que o job pode fazer para o modelo de LLM por minuto.

Para definir um valor adequado para seu projeto, consulte a seção de cota de modelo e a página "Cota" do projeto. Se não for especificado, um valor padrão de 5.000 QPM será usado.

Acessar um arquivo RAG

Esta tabela lista o parâmetro usado para receber um arquivo RAG.

Parâmetros
name

Obrigatório: string

RagFile: o nome do recurso. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_file_id}

Excluir um arquivo RAG

Esta tabela lista o parâmetro usado para excluir um arquivo RAG.

Parâmetros
name

Obrigatório: string

O nome do recurso RagFile a ser excluído. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_file_id}

Parâmetros de recuperação e previsão

Esta seção lista os parâmetros de recuperação e previsão.

Parâmetros de recuperação

Esta tabela lista os parâmetros da API retrieveContexts.

Parâmetros

parent

Obrigatório: string

O nome do recurso do local a ser recuperado RagContexts.
Os usuários precisam ter permissão para fazer uma chamada no projeto.

Formato: projects/{project}/locations/{location}

vertex_rag_store

VertexRagStore

A fonte de dados da Vertex RagStore.

query

Obrigatório: RagQuery

Consulta única de recuperação de RAG.

VertexRagStore
VertexRagStore

rag_resources

lista: RagResource

A representação da origem RAG. Ele pode ser usado para especificar apenas o corpus ou RagFiles. Só é possível usar um corpus ou vários arquivos de um corpus.

rag_resources.rag_corpus

Opcional: string

Nome do recurso RagCorpora.

Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}

rag_resources.rag_file_ids

lista: string

Uma lista de recursos RagFile.

Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file}

RagQuery

text

string

A consulta em formato de texto para receber contextos relevantes.

rag_retrieval_config

Opcional: RagRetrievalConfig

A configuração de recuperação da consulta.

RagRetrievalConfig

top_k

Opcional: int32

O número de contextos a serem recuperados.

filter.vector_distance_threshold

oneof vector_db_threshold: double

Só retorna contextos com uma distância vetorial menor que o limite.

filter.vector_similarity_threshold

oneof vector_db_threshold: double

Só retorna contextos com similaridade vetorial maior que o limite.

ranking.rank_service.model_name

Opcional: string

O nome do modelo do serviço de classificação.

Exemplo: semantic-ranker-512@latest

ranking.llm_ranker.model_name

Opcional: string

O nome do modelo usado para classificação.

Exemplo: gemini-2.5-flash

Parâmetros de Prediction

Esta tabela lista os parâmetros de previsão.

GenerateContentRequest

tools.retrieval.vertex_rag_store

VertexRagStore

Definido para usar uma fonte de dados com tecnologia do repositório de RAG da Vertex AI.

Consulte VertexRagStore para mais detalhes.

Parâmetros de gerenciamento de projetos

Esta tabela lista as configurações de nível do projeto para o banco de dados gerenciado do mecanismo RAG.

Nível Descrição Caso de uso
RagManagedDbConfig.scaled Um nível de produção que oferece alto desempenho e recursos de escalonamento automático para seu banco de dados vetorial gerenciado. Recomendado para aplicativos de produção com cargas de consultas altas ou grandes volumes de dados.
RagManagedDbConfig.basic Um nível de computação baixo e econômico para o banco de dados vetorial gerenciado. Use para desenvolvimento, testes ou aplicativos de pequena escala com pouco tráfego.
RagManagedDbConfig.unprovisioned Exclui o banco de dados de vetores gerenciado e os recursos dele. Isso desativa efetivamente o banco de dados gerenciado para o projeto. Use para desativar a infraestrutura de banco de dados gerenciado quando ela não for mais necessária para ajudar a gerenciar os custos.

Exemplos de gerenciamento de corpus

Nesta seção, apresentamos exemplos de como usar a API para gerenciar seu corpus RAG.

Criar um exemplo de corpus RAG

Estes exemplos de código demonstram como criar um corpus RAG.

REST

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

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • CORPUS_DISPLAY_NAME: o nome de exibição do corpus RAG.
  • CORPUS_DESCRIPTION: a descrição do corpus RAG.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora

Corpo JSON da solicitação:

{
  "display_name" : "CORPUS_DISPLAY_NAME",
  "description": "CORPUS_DESCRIPTION",
}

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

curl

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

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora"

Powershell

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

  $cred = gcloud auth print-access-token
  $headers = @{ "Authorization" = "Bearer $cred" }

  Invoke-WebRequest `
      -Method POST `
      -Headers $headers `
      -ContentType: "application/json; charset=utf-8" `
      -InFile request.json `
      -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora" | Select-Object -Expand Content

Você receberá um código de status de sucesso (2xx).

O exemplo a seguir demonstra como criar um corpus RAG usando a API REST.

  // CreateRagCorpus
  // Input: LOCATION, PROJECT_ID, CORPUS_DISPLAY_NAME
  // Output: CreateRagCorpusOperationMetadata
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora \
  -d '{
        "display_name" : "CORPUS_DISPLAY_NAME"
    }'

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 import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# display_name = "test_corpus"
# description = "Corpus Description"

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

# Configure backend_config
backend_config = rag.RagVectorDbConfig(
    rag_embedding_model_config=rag.RagEmbeddingModelConfig(
        vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
            publisher_model="publishers/google/models/text-embedding-005"
        )
    )
)

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

Atualizar um exemplo de corpus RAG

É possível atualizar o nome de exibição, a descrição e a configuração do banco de dados de vetores de um corpus de RAG. No entanto, não é possível mudar os seguintes parâmetros imutáveis no seu corpus de RAG:

  • O tipo de banco de dados de vetores. Por exemplo, não é possível mudar o banco de dados de vetores do Pinecone para a Pesquisa vetorial.
  • Se você estiver usando a opção de banco de dados gerenciado, não será possível atualizar a configuração do banco de dados de vetores.

Estes exemplos demonstram como atualizar um corpus RAG.

REST

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

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • CORPUS_ID: o ID do corpus da RAG.
  • CORPUS_DISPLAY_NAME: o nome de exibição do corpus RAG.
  • CORPUS_DESCRIPTION: a descrição do corpus RAG.
  • INDEX_NAME: o nome do recurso do índice de pesquisa vetorial. Formato: projects/{project}/locations/{location}/indexes/{index}.
  • INDEX_ENDPOINT_NAME: o nome do recurso do endpoint do índice de pesquisa vetorial. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}.

Método HTTP e URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID

Corpo JSON da solicitação:

{
  "display_name" : "CORPUS_DISPLAY_NAME",
  "description": "CORPUS_DESCRIPTION",
  "vector_db_config": {
    "vertex_vector_search": {
        "index": "INDEX_NAME",
        "index_endpoint": "INDEX_ENDPOINT_NAME",
    }
  }
}

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

curl

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

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID"

Powershell

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID" | Select-Object -Expand Content

Uma solicitação bem-sucedida retorna um código de status 2xx.

Exemplo de lista de corpora de RAG

Estes exemplos de código demonstram como listar todos os seus corpora RAG.

REST

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

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • PAGE_SIZE: o número máximo de corpora de RAG a serem retornados por página.
  • PAGE_TOKEN: um token de página de uma resposta ListRagCorpora anterior para recuperar a próxima página de resultados.

Método HTTP e URL:

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

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

curl

Execute este comando:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

Powershell

Execute este comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content

Uma solicitação bem-sucedida retorna um código de status 2xx e uma lista de corpora de RAG para o projeto 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 import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"

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

corpora = rag.list_corpora()
print(corpora)
# Example response:
# ListRagCorporaPager<rag_corpora {
#   name: "projects/[PROJECT_ID]/locations/us-central1/ragCorpora/2305843009213693952"
#   display_name: "test_corpus"
#   create_time {
# ...

Acessar um exemplo de corpus RAG

Estes exemplos de código demonstram como receber um corpus RAG.

REST

Antes de usar os dados da solicitação, 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 de corpus RAG.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID

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

curl

Execute este comando:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID"

Powershell

Execute este comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID" | Select-Object -Expand Content

Uma resposta bem-sucedida retorna o recurso RagCorpus.

Os comandos get e list são usados em um exemplo para demonstrar como RagCorpus usa o campo rag_embedding_model_config em vector_db_config, que aponta para o modelo de embedding escolhido.

    PROJECT_ID: Your project ID.
    LOCATION: The region to process the request.
    RAG_CORPUS_ID: The corpus ID of your RAG corpus.
  ```

```sh
  // GetRagCorpus
  // Input: LOCATION, PROJECT_ID, RAG_CORPUS_ID
  // Output: RagCorpus
  curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID

  // ListRagCorpora
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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 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")

corpus = rag.get_corpus(name=corpus_name)
print(corpus)
# Example response:
# RagCorpus(name='projects/[PROJECT_ID]/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description',
# ...

Excluir um exemplo de corpus RAG

Estes exemplos de código demonstram como excluir um corpus RAG.

REST

Antes de usar os dados da solicitação, 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.

Método HTTP e URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID

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

curl

Execute este comando:

curl -X DELETE \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID"

Powershell

Execute este comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID" | Select-Object -Expand Content

Uma resposta bem-sucedida retornará 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 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")

rag.delete_corpus(name=corpus_name)
print(f"Corpus {corpus_name} deleted.")
# Example response:
# Successfully deleted the RagCorpus.
# Corpus projects/[PROJECT_ID]/locations/us-central1/ragCorpora/123456789012345 deleted.

Exemplos de gerenciamento de arquivos

Nesta seção, apresentamos exemplos de como usar a API para gerenciar arquivos RAG.

Fazer upload de um exemplo de arquivo RAG

Estes exemplos de código demonstram como fazer upload de um arquivo RAG.

REST

Antes de usar os dados da solicitação, 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 corpus da RAG.
  • LOCAL_FILE_PATH: o caminho local para o arquivo a ser enviado.
  • DISPLAY_NAME: o nome de exibição do arquivo RAG.
  • DESCRIPTION: a descrição do arquivo RAG.

Para enviar sua solicitação, use o seguinte comando:

curl -X POST \
-H "X-Goog-Upload-Protocol: multipart" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-F metadata="{'rag_file': {'display_name':' DISPLAY_NAME', 'description':'DESCRIPTION'}}" \
-F file=@LOCAL_FILE_PATH \
"https://LOCATION-aiplatform.googleapis.com/upload/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload"

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

Exemplo de importação de arquivos RAG

É possível importar arquivos e pastas do Drive ou do Cloud Storage. Use response.metadata para conferir falhas parciais, tempo de solicitação e tempo de resposta no objeto response do SDK.

O campo response.skipped_rag_files_count contém o número de arquivos que foram ignorados durante a importação. O serviço vai ignorar um arquivo se as seguintes condições forem atendidas:

  1. O arquivo já foi importado.
  2. O arquivo não foi alterado.
  3. A configuração de divisão em blocos do arquivo não foi alterada.

Python

from vertexai 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 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,
    transformation_config=rag.TransformationConfig(
        rag.ChunkingConfig(chunk_size=1024, chunk_overlap=256)
    ),
    import_result_sink="gs://sample-existing-folder/sample_import_result_unique.ndjson",  # Optional: This must be an existing Cloud Storage bucket folder, and the filename must be unique (non-existent).
    llm_parser=rag.LlmParserConfig(
      model_name="gemini-2.5-pro-preview-05-06",
      max_parsing_requests_per_min=100,
    ),  # Optional
    max_embedding_requests_per_min=900,  # Optional
)
print(f"Imported {response.imported_rag_files_count} files.")

REST

Antes de usar os dados da solicitação, 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 corpus da RAG.
  • FOLDER_RESOURCE_ID: o ID do recurso da sua pasta do Drive.
  • GCS_URIS: uma lista de locais do Cloud Storage. Exemplo: gs://my-bucket1.
  • CHUNK_SIZE: número de tokens que cada bloco precisa ter.
  • CHUNK_OVERLAP: número de tokens sobrepostos entre blocos.
  • EMBEDDING_MODEL_QPM_RATE: a taxa de QPM para limitar o acesso da RAG ao seu modelo de embedding. Exemplo: 1.000.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/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"
    },
    "rag_file_chunking_config": {
      "chunk_size": "CHUNK_SIZE",
      "chunk_overlap": "CHUNK_OVERLAP"
    }
  }
}

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

curl

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

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"

Powershell

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/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 de 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.

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do corpus da RAG.
  • GCS_URIS: uma lista de locais do Cloud Storage. Exemplo: gs://my-bucket1.
  • CHUNK_SIZE: número de tokens que cada bloco precisa ter.
  • CHUNK_OVERLAP: número de tokens sobrepostos entre blocos.
  • EMBEDDING_MODEL_QPM_RATE: a taxa de QPM para limitar o acesso das RAGs ao seu modelo de embedding. Exemplo: 1.000.
// ImportRagFiles
// Import a single Cloud Storage file or all files in a Cloud Storage bucket.
// Input: LOCATION, 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://LOCATION-aiplatform.googleapis.com/v1/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": CHUNK_SIZE,
      "chunk_overlap": CHUNK_OVERLAP
    },
    "max_embedding_requests_per_min": EMBEDDING_MODEL_QPM_RATE
  }
}'

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 de 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.

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do corpus da RAG.
  • FOLDER_RESOURCE_ID: o ID do recurso da sua pasta do Drive.
  • CHUNK_SIZE: número de tokens que cada bloco precisa ter.
  • CHUNK_OVERLAP: número de tokens sobrepostos entre blocos.
  • EMBEDDING_MODEL_QPM_RATE: a taxa de QPM para limitar o acesso da RAG ao seu modelo de embedding. Exemplo: 1.000.
// ImportRagFiles
// Import all files in a Google Drive folder.
// Input: LOCATION, 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://LOCATION-aiplatform.googleapis.com/v1/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
  }
}'

Exemplo de listagem de arquivos RAG

Estes exemplos de código demonstram como listar arquivos RAG.

REST

Antes de usar os dados da solicitação, 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: o número máximo de RagFiles a serem retornados por página.
  • PAGE_TOKEN: um token de página de uma resposta ListRagFiles anterior para recuperar a próxima página de resultados.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/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 este comando:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

Powershell

Execute este comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content

Uma solicitação bem-sucedida retorna um código de status 2xx e uma lista de RagFiles para o 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 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

Acessar um exemplo de arquivo RAG

Estes exemplos de código demonstram como obter um arquivo RAG.

REST

Antes de usar os dados da solicitação, 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/v1/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 este comando:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

Powershell

Execute este comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/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 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')

Excluir um exemplo de arquivo RAG

Estes exemplos de código demonstram como excluir um arquivo RAG.

REST

Antes de usar os dados da solicitação, 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/v1/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 este comando:

curl -X DELETE \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

Powershell

Execute este comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content

Uma resposta bem-sucedida retornará 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 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.

Exemplo de consulta de recuperação

Quando você faz uma consulta, o componente de recuperação na RAG pesquisa na base de conhecimento para encontrar informações relevantes.

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 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!",
    rag_retrieval_config=rag.RagRetrievalConfig(
        top_k=10,
        filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
    ),
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

REST

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

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • 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/v1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts

Solicitar corpo JSON:

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

curl

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

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"

Powershell

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" | Select-Object -Expand Content

Uma solicitação bem-sucedida retorna um código de status 2xx e uma lista de contextos relacionados.

Exemplo de geração

O LLM gera uma resposta embasada usando os contextos recuperados.

REST

Antes de usar os dados da solicitação, 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-2.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.
  • USER: seu nome de usuário.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/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 chamado request.json e execute o comando a seguir:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD"

Powershell

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/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 import rag
from vertexai.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", ...],
                )
            ],
            rag_retrieval_config=rag.RagRetrievalConfig(
                top_k=10,
                filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
            ),
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-2.0-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....
#   ...

Exemplos de gerenciamento de projetos

O nível é uma configuração no nível do projeto no recurso RagEngineConfig que afeta os corpus de RAG que usam RagManagedDb. Para receber a configuração do nível, use GetRagEngineConfig. Para atualizar a configuração de nível, use UpdateRagEngineConfig.

Para mais informações sobre como gerenciar a configuração de níveis, consulte Gerenciar níveis.

Receber configuração do projeto

Os exemplos de código a seguir mostram como ler seu RagEngineConfig:

Console

  1. No console do Google Cloud , acesse a página RAG Engine.

    Acessar o mecanismo RAG

  2. Selecione a região em que o mecanismo RAG está sendo executado. Sua lista de corpora de RAG é atualizada.
  3. Clique em Configurar o mecanismo RAG. O painel Configurar o mecanismo RAG é exibido. É possível conferir o nível selecionado para seu mecanismo RAG.
  4. Clique em Cancelar.

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

rag_engine_config = rag.rag_data.get_rag_engine_config(
    name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"
)

print(rag_engine_config)

REST

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig

Atualizar a configuração do projeto

Esta seção fornece exemplos de código para demonstrar como mudar sua configuração para um nível escalonado, básico ou não provisionado.

Atualizar seu RagEngineConfig para o nível escalonado

Os exemplos de código a seguir mostram como definir o RagEngineConfig como o nível escalonado:

Console

  1. No console do Google Cloud , acesse a página RAG Engine.

    Acessar o mecanismo RAG

  2. Selecione a região em que o mecanismo RAG está sendo executado. Sua lista de corpora de RAG é atualizada.
  3. Clique em Configurar o mecanismo RAG. O painel Configurar o mecanismo RAG é exibido.
  4. Selecione o nível em que você quer executar o mecanismo RAG.
  5. Clique em Salvar.

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

rag_engine_config_name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"

new_rag_engine_config = rag.RagEngineConfig(
name=rag_engine_config_name,
rag_managed_db_config=rag.RagManagedDbConfig(tier=rag.Scaled()),
)

updated_rag_engine_config = rag.rag_data.update_rag_engine_config(
rag_engine_config=new_rag_engine_config
)

print(updated_rag_engine_config)

REST

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'scaled': {}}}"

Atualizar seu RagEngineConfig para o nível Basic

Os exemplos de código a seguir mostram como definir o RagEngineConfig para o nível básico:

Console

  1. No console do Google Cloud , acesse a página RAG Engine.

    Acessar o mecanismo RAG

  2. Selecione a região em que o mecanismo RAG está sendo executado. Sua lista de corpora de RAG é atualizada.
  3. Clique em Configurar o mecanismo RAG. O painel Configurar o mecanismo RAG é exibido.
  4. Selecione o nível em que você quer executar o mecanismo RAG.
  5. Clique em Salvar.

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

rag_engine_config_name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"

new_rag_engine_config = rag.RagEngineConfig(
name=rag_engine_config_name,
rag_managed_db_config=rag.RagManagedDbConfig(tier=rag.Basic()),
)

updated_rag_engine_config = rag.rag_data.update_rag_engine_config(
rag_engine_config=new_rag_engine_config
)

print(updated_rag_engine_config)

REST

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'basic': {}}}"

Atualize seu RagEngineConfig para o nível não provisionado

Os exemplos de código a seguir mostram como definir o RagEngineConfig como o nível não provisionado:

Console

  1. No console do Google Cloud , acesse a página RAG Engine.

    Acessar o mecanismo RAG

  2. Selecione a região em que o mecanismo RAG está sendo executado. Sua lista de corpora de RAG é atualizada.
  3. Clique em Configurar o mecanismo RAG. O painel Configurar o mecanismo RAG é exibido.
  4. Clique em Excluir mecanismo RAG. Uma caixa de diálogo de confirmação é exibida.
  5. Verifique se você está prestes a excluir seus dados no RAG Engine digitando delete e clique em Confirmar.
  6. Clique em Salvar.

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

rag_engine_config_name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"

new_rag_engine_config = rag.RagEngineConfig(
  name=rag_engine_config_name,
  rag_managed_db_config=rag.RagManagedDbConfig(tier=rag.Unprovisioned()),
)

updated_rag_engine_config = rag.rag_data.update_rag_engine_config(
  rag_engine_config=new_rag_engine_config
)

print(updated_rag_engine_config)

REST

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'unprovisioned': {}}}"

A seguir