API RAG Engine

O mecanismo de RAG da Vertex AI é um componente da plataforma Vertex AI, que facilita a geração aumentada de recuperação (RAG, na sigla em inglês). O mecanismo RAG permite que modelos de linguagem grandes (LLMs) acessem e incorporem dados de fontes de conhecimento externas, como documentos e bancos de dados. Ao usar a RAG, os LLMs podem gerar respostas mais precisas e informativas.

Lista de parâmetros

Esta seção lista:

Parâmetros	Exemplos
Consulte Parâmetros de gerenciamento de corpus.	Confira exemplos de gerenciamento de corpus.
Consulte Parâmetros de gerenciamento de arquivos.	Consulte Exemplos de gerenciamento de arquivos.
Consulte Parâmetros de gerenciamento de projetos.	Consulte Exemplos de gerenciamento de projetos.

Parâmetros de gerenciamento do corpus

Para informações sobre um corpus RAG, consulte Gerenciamento de corpus.

Criar um corpus RAG

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

Solicitação de corpo

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 da CMEK é usado para criptografar dados em repouso relacionados ao corpus de RAG. O nome da chave só é aplicável à opção RagManaged para o banco de dados de vetores. Quando o corpus é criado, esse campo pode ser definido e não pode ser atualizado ou excluído. Formato: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}
vector_db_config	Opcional: imutável: vectorDbConfig A configuração para os bancos de dados de vetores.
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}

vectorDbConfig

Parâmetros
rag_managed_db	oneof vector_db: vectorDbConfig.RagManagedDb Se nenhum banco de dados de vetores for especificado, rag_managed_db será o padrão.
pinecone	oneof vector_db: vectorDbConfig.Pinecone Especifica sua instância do Pinecone.
pinecone.index_name	string Esse é o nome usado para criar o índice do Pinecone que é usado com o corpus RAG. Esse valor não pode ser mudado depois de definido. Você pode deixar em branco na chamada de API CreateRagCorpus e definir com um valor não vazio em uma chamada de API UpdateRagCorpus subsequente.
vertex_vector_search	oneof vector_db: vectorDbConfig.VertexVectorSearch Especifica sua instância do Vertex Vector Search.
vertex_vector_search.index	string Esse é o nome do recurso do índice da Pesquisa Vetorial usado com o corpus de RAG. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint} Esse valor não pode ser mudado depois de definido. Você pode deixar em branco na chamada de API CreateRagCorpus e definir com um valor não vazio em uma chamada de API UpdateRagCorpus subsequente.
vertex_vector_search.index_endpoint	string Esse é o nome do recurso do endpoint do índice da Pesquisa Vetorial usado com o corpus de RAG. Formato: projects/{project}/locations/{location}/indexes/{index} Esse valor não pode ser mudado depois de definido. Você pode deixar em branco na chamada de API CreateRagCorpus e definir com um valor não vazio em uma chamada de API UpdateRagCorpus subsequente.
api_auth.api_key_config.api_key_secret_version	string Esse é o nome completo do recurso do secret armazenado no Secret Manager, que contém sua chave de API do Pinecone. Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID} Você pode deixar em branco na chamada de API CreateRagCorpus e definir com um valor não vazio em uma chamada de API UpdateRagCorpus subsequente.
rag_embedding_model_config.vertex_prediction_endpoint.endpoint	Opcional: imutável: string O modelo de embedding a ser usado para o corpus de RAG. Esse valor não pode ser mudado depois de definido. Se você deixar em branco, vamos usar text-embedding-005 como o modelo de embedding.

Atualizar um corpus RAG

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

Solicitação de corpo

Parâmetros
display_name	Opcional: string O nome de exibição do corpus de RAG.
description	Opcional: string A descrição do corpus RAG.
rag_vector_db.pinecone.index_name	string Esse é o nome usado para criar o índice do Pinecone que é usado com o corpus RAG. Se o RagCorpus foi criado com uma configuração Pinecone e esse campo nunca foi definido antes, é possível atualizar o nome do índice da instância do Pinecone.
rag_vector_db.vertex_vector_search.index	string Esse é o nome do recurso do índice da Pesquisa Vetorial usado com o corpus de RAG. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint} Se o RagCorpus foi criado com uma configuração Vector Search e esse campo nunca foi definido antes, é possível atualizá-lo.
rag_vector_db.vertex_vector_search.index_endpoint	string Esse é o nome do recurso do endpoint do índice da Pesquisa Vetorial usado com o corpus de RAG. Formato: projects/{project}/locations/{location}/indexes/{index} Se o RagCorpus foi criado com uma configuração Vector Search e esse campo nunca foi definido antes, é possível atualizá-lo.
rag_vector_db.api_auth.api_key_config.api_key_secret_version	string O nome completo do recurso do secret armazenado 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 tamanho de página de lista padrão.
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 os parâmetros usados para conseguir um corpus RAG.

Parâmetros
name	string RagCorpus: o nome do recurso. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

Excluir um corpus RAG

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

Parâmetros
name	string RagCorpus: o nome do recurso. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

Parâmetros de gerenciamento de arquivos

Para informações sobre um arquivo RAG, consulte Gerenciamento de arquivos.

Fazer upload de um arquivo RAG

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

Solicitação de corpo

Parâmetros
parent	string RagCorpus: o nome do recurso. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}
rag_file	Obrigatório: RagFile O arquivo a ser enviado.
upload_rag_file_config	Obrigatório: UploadRagFileConfig A configuração do RagFile a ser enviado para o RagCorpus.

RagFile
display_name	Obrigatório: string O nome de exibição do arquivo RAG.
description	Opcional: string A descrição do arquivo RAG.

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

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 a chave secreta 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 os parâmetros usados para receber um arquivo RAG.

Parâmetros
name	string RagFile: o nome do recurso. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_file_id}

Excluir um arquivo RAG

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

Parâmetros
name	string RagFile: o nome do recurso. 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 previsão

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 os parâmetros no nível do projeto.

RagEngineConfig

Parâmetros
RagManagedDbConfig.scaled	Esse nível oferece desempenho em escala de produção e funcionalidade de escalonamento automático.
RagManagedDbConfig.basic	Esse nível oferece uma opção econômica e de baixa computação.
RagManagedDbConfig.unprovisioned	Esse nível exclui o RagManagedDb e a instância do Spanner subjacente.

Exemplos de gerenciamento do corpus

Nesta seção, apresentamos exemplos de como usar a API para gerenciar seu corpus de 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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa executando gcloud CLI auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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 corpus de RAG com um novo nome de exibição, descrição e configuração de banco de dados de vetores. No entanto, não é possível mudar os seguintes parâmetros 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 Weaviate para o Feature Store da Vertex AI.
• 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

Observação: o comando a seguir pressupõe que você fez login na CLI do Google Cloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI do gcloud . É possível verificar a conta ativa executando a CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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

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

Exemplo de lista de corpora de RAG

Estes exemplos de código demonstram como listar todos os 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 tamanho da página de lista padrão. É possível ajustar o número de corpora de RAG 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 ListRagCorporaResponse.next_page_token da chamada VertexRagDataService.ListRagCorpora anterior.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa executando CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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

Você vai receber um código de status bem-sucedido (2xx) e uma lista de corpus da RAG no PROJECT_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"

# 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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa executando CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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 com 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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa executando CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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 response.skipped_rag_files_count se refere ao número de arquivos que foram ignorados durante a importação. Um arquivo é ignorado quando as seguintes condições são 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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa executando CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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 tamanho da 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 usando ListRagFilesResponse.next_page_token da chamada VertexRagDataService.ListRagFiles anterior.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa executando CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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

Você vai receber um código de status bem-sucedido (2xx) e uma lista de RagFiles no RAG_CORPUS_ID especificado.

Python

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

from vertexai 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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa executando CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa executando CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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

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 um usuário faz uma pergunta ou fornece uma solicitação, o componente de recuperação no RAG pesquisa em sua base de conhecimento para encontrar informações relevantes para a consulta.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa executando CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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

Você vai receber um código de status (2xx) e uma lista de RagFiles relacionadas.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud . É possível verificar a conta ativa executando CLI gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud CLI init ou gcloud CLI auth login. Para verificar a conta ativa, execute a CLI gcloud auth list.

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 disponível no recurso RagEngineConfig e afeta os corpora da 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 para 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:

Observação: se você tiver uma grande quantidade de dados no RagManagedDb em todos os seus corpus de RAG, o downgrade para um nível Basic poderá falhar devido à capacidade insuficiente de computação e armazenamento.

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

• Para saber mais sobre os modelos de geração aceitos, consulte Modelos de IA generativa que oferecem suporte à RAG.
• Para saber mais sobre os modelos de embedding aceitos, consulte Modelos de embedding.
• Para saber mais sobre modelos abertos, consulte Modelos abertos.
• Para saber mais sobre o mecanismo RAG, consulte a visão geral do mecanismo RAG.