API RAG Engine

O mecanismo RAG da Vertex AI é um componente da plataforma Vertex AI, que facilita a geração aumentada por recuperação (RAG, na sigla em inglês). O mecanismo RAG permite que os 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 recuperação e previsão.	Consulte Exemplo de consulta de recuperação.
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
`corpus_type_config`	Opcional: imutável. `RagCorpus.CorpusTypeConfig` A configuração para especificar o tipo de corpus.
`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 é 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: `RagVectorDbConfig` A configuração dos 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}`

`CorpusTypeConfig`

Parâmetros

Parâmetros
`document_corpus`	`oneof` `RagCorpus.CorpusTypeConfig.DocumentCorpus` O valor padrão de `corpus_type_config`, que representa um corpus de RAG convencional baseado em documentos.
`memory_corpus`	`oneof` `RagCorpus.CorpusTypeConfig.MemoryCorpus` Se você definir esse tipo, o corpus de RAG será um `MemoryCorpus` que poderá ser usado com a API Gemini Live como um repositório de memória. Para mais informações, consulte Usar o Mecanismo RAG da Vertex AI como o repositório de memória.
`memory_corpus.llm_parser`	`oneof` `RagFileParsingConfig.LlmParser` O analisador de LLM usado para analisar e armazenar contextos de sessão da API Gemini Live. Você pode criar recordações para indexação.

document_corpus

oneof RagCorpus.CorpusTypeConfig.DocumentCorpus

O valor padrão de corpus_type_config, que representa um corpus de RAG convencional baseado em documentos.

memory_corpus

oneof RagCorpus.CorpusTypeConfig.MemoryCorpus

Se você definir esse tipo, o corpus de RAG será um MemoryCorpus que poderá ser usado com a API Gemini Live como um repositório de memória.

Para mais informações, consulte Usar o Mecanismo RAG da Vertex AI como o repositório de memória.

memory_corpus.llm_parser

oneof RagFileParsingConfig.LlmParser

O analisador de LLM usado para analisar e armazenar contextos de sessão da API Gemini Live. Você pode criar recordações para indexação.

`RagVectorDbConfig`

Parâmetros
`rag_managed_db`	`oneof` `vector_db`: `RagVectorDbConfig.RagManagedDb` Se nenhum banco de dados de vetores for especificado, `rag_managed_db` será o padrão.
`rag_managed_db.knn`	`oneof` `retrieval_strategy`: `KNN` Padrão. Encontra os vizinhos mais próximos exatos comparando todos os pontos de dados no seu corpus RAG. Se você não especificar uma estratégia durante a criação do corpus de RAG, a KNN será a estratégia de recuperação padrão usada.
`rag_managed_db.ann`	`oneof` `retrieval_strategy`: `ANN` `tree_depth` Determina o número de camadas ou níveis na árvore. Se você tiver `O(10K)` arquivos RAG no corpus, defina esse valor como 2. Se forem necessárias mais camadas ou níveis, defina esse valor como 3. Se o número de camadas ou níveis não for especificado, o Vertex AI RAG Engine vai atribuir um valor padrão de 2 a esse parâmetro. `leaf_count` Determina o número de nós folha na estrutura baseada em árvore. O valor recomendado é `10 * sqrt(num of RAG files in your RAG corpus)`. Se não for especificado, o mecanismo RAG da Vertex AI vai atribuir um valor padrão de 500 a esse parâmetro. `rebuild_ann_index` O mecanismo de RAG da Vertex AI recria seu índice ANN. Defina como `true` na sua solicitação de API `ImportRagFiles`. Antes de consultar o corpus de RAG, é necessário recriar o índice ANN uma vez. Apenas uma recriação de índice simultânea é aceita em um projeto em cada local.
`weaviate`	`oneof` `vector_db`: `RagVectorDbConfig.Weaviate` Especifica sua instância do Weaviate.
`weaviate.http_endpoint`	`string` O endpoint HTTP da instância do Weaviate. 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.
`weaviate.collection_name`	`string` A coleção do Weaviate com que o corpus RAG é mapeado. 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.
`pinecone`	`oneof` `vector_db`: `RagVectorDbConfig.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_feature_store`	`oneof` `vector_db`: `RagVectorDbConfig.VertexFeatureStore` Especifica sua instância do Vertex AI Feature Store.
`vertex_feature_store.feature_view_resource_name`	`string` O `FeatureView` da Vertex AI Feature Store com o qual o corpus de RAG é mapeado. Formato: `projects/{project}/locations/{location}/featureOnlineStores/{feature_online_store}/featureViews/{feature_view}` 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`: `RagVectorDbConfig.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 Weaviate ou do Pinecone, dependendo do banco de dados de vetores escolhido. 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.weaviate.http_endpoint`	`string` O endpoint HTTP da instância do Weaviate. Se o `RagCorpus` foi criado com uma configuração `Weaviate` e esse campo nunca foi definido antes, é possível atualizar o endpoint HTTP da instância do Weaviate.
`rag_vector_db.weaviate.collection_name`	`string` A coleção do Weaviate com que o corpus RAG é mapeado. Se o `RagCorpus` foi criado com uma configuração de `Weaviate` e esse campo nunca foi definido antes, é possível atualizar o nome da coleção da instância do Weaviate.
`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_feature_store.feature_view_resource_name`	`string` O `FeatureView` da Vertex AI Feature Store com o qual o corpus de RAG é mapeado. Formato: `projects/{project}/locations/{location}/featureOnlineStores/{feature_online_store}/featureViews/{feature_view}` Se o `RagCorpus` foi criado com uma configuração `Vertex AI Feature Store` e esse campo nunca foi definido antes, é possível atualizá-lo.
`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 Weaviate ou do Pinecone, depende do banco de dados de vetores escolhido. 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

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.

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

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

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

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

name

string

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

Criar esquemas de metadados em lote

Esta tabela lista os parâmetros usados para criar em lote esquemas de metadados para um corpus RAG.

Solicitação de corpo

Parâmetros

Parâmetros
`requests`	Obrigatório: lista de `CreateRagDataSchemaRequest` As mensagens de solicitação para `CreateRagDataSchema`.

requests

Obrigatório: lista de CreateRagDataSchemaRequest

As mensagens de solicitação para CreateRagDataSchema.

`CreateRagDataSchemaRequest`

Parâmetros

Parâmetros
`rag_data_schema`	Obrigatório: `RagDataSchema` O esquema de metadados a ser criado.

rag_data_schema

Obrigatório: RagDataSchema

O esquema de metadados a ser criado.

`RagDataSchema`

Parâmetros

Parâmetros
`key`	Obrigatório: `string` A chave do esquema de metadados.
`schema_details`	`RagMetadataSchemaDetails` Os detalhes do esquema de metadados.

key

Obrigatório: string

A chave do esquema de metadados.

schema_details

RagMetadataSchemaDetails

Os detalhes do esquema de metadados.

`RagMetadataSchemaDetails`

Parâmetros

Parâmetros
`type`	`DataType` O tipo de dados do esquema de metadados. Opções: `INTEGER`, `FLOAT`, `STRING`, `DATETIME`, `BOOLEAN`, `LIST`.

type

DataType

O tipo de dados do esquema de metadados. Opções: INTEGER, FLOAT, STRING, DATETIME, BOOLEAN, LIST.

Listar esquemas de metadados

Esta tabela lista os parâmetros usados para listar esquemas de metadados.

Parâmetros Descrição

Parâmetros	Descrição
`parent`	Obrigatório: `string` O nome do recurso do `RagCorpus`. Formato: `projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}`

parent

Obrigatório: string

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

Excluir em lote esquemas de metadados

Esta tabela lista os parâmetros usados para excluir em lote esquemas de metadados.

Parâmetros

Parâmetros
`names`	Obrigatório: lista de `string` Os nomes de recursos dos `RagDataSchema` a serem excluídos. Formato: `projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}/ragDataSchemas/{rag_data_schema_id}`

names

Obrigatório: lista de string

Os nomes de recursos dos RagDataSchema a serem excluídos. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}/ragDataSchemas/{rag_data_schema_id}

Parâmetros de gerenciamento de arquivos

Para informações sobre um arquivo RAG e os metadados dele, 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

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

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 Descrição

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

display_name

Obrigatório: string

O nome de exibição do arquivo RAG.

description

Opcional: string

A descrição do arquivo RAG.

UploadRagFileConfig Descrição

`UploadRagFileConfig`	Descrição
`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_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. É possível importar 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 este 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

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

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 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 do site ou o ID do site.

`RagFileParsingConfig`
`layout_parser`	`oneof` `parser`: `RagFileParsingConfig.LayoutParser` O analisador de layouts a ser usado para `RagFile`s.
`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 `RagFile`s.
`llm_parser.model_name`	`string` O nome do recurso de um modelo de LLM. Formato: `{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

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

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

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

name

string

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

Criar metadados em lote

Esta tabela lista os parâmetros usados para criar em lote metadados de um arquivo RAG.

Solicitação de corpo

Parâmetros

Parâmetros
`requests`	Obrigatório: lista de `CreateRagMetadataRequest` As mensagens de solicitação para `CreateRagMetadata`.

requests

Obrigatório: lista de CreateRagMetadataRequest

As mensagens de solicitação para CreateRagMetadata.

`CreateRagMetadataRequest`

Parâmetros

Parâmetros
`rag_metadata`	Obrigatório: `RagMetadata` Os metadados a serem criados.
`rag_metadata_id`	Opcional: `string` O ID a ser usado nos metadados, que se tornará o componente final do nome do recurso dos metadados.

rag_metadata

Obrigatório: RagMetadata

Os metadados a serem criados.

rag_metadata_id

Opcional: string

O ID a ser usado nos metadados, que se tornará o componente final do nome do recurso dos metadados.

`RagMetadata`

Parâmetros

Parâmetros
`user_specified_metadata`	`UserSpecifiedMetadata` Os metadados fornecidos pelos usuários.

user_specified_metadata

UserSpecifiedMetadata

Os metadados fornecidos pelos usuários.

`UserSpecifiedMetadata`

Parâmetros

Parâmetros
`key`	Obrigatório: `string` A chave dos metadados. A chave precisa corresponder a uma chave definida em um `RagDataSchema`.
`value`	`MetadataValue` O valor dos metadados.

key

Obrigatório: string

A chave dos metadados. A chave precisa corresponder a uma chave definida em um RagDataSchema.

value

MetadataValue

O valor dos metadados.

`MetadataValue`

Parâmetros
`int_value`	`oneof value`: `int64`
`float_value`	`oneof value`: `float`
`str_value`	`oneof value`: `string`
`datetime_value`	`oneof value`: `string`
`bool_value`	`oneof value`: `boolean`
`list_value`	`oneof value`: `MetadataList`

Metadados da lista

Esta tabela lista os parâmetros usados para listar metadados de um arquivo RAG.

Parâmetros

Parâmetros
`parent`	Obrigatório: `string` O nome do recurso do `RagFile`. Formato: `projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}`

parent

Obrigatório: string

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

Atualizar metadados

Esta tabela lista os parâmetros usados para atualizar metadados.

Parâmetros

Parâmetros
`rag_metadata`	Obrigatório: `RagMetadata` O `RagMetadata` que substitui o recurso no servidor.

rag_metadata

Obrigatório: RagMetadata

O RagMetadata que substitui o recurso no servidor.

Excluir metadados em lote

Esta tabela lista os parâmetros usados para excluir metadados em lote.

Parâmetros

Parâmetros
`names`	Obrigatório: lista de `string` Os nomes de recursos dos `RagMetadata` a serem excluídos. Formato: `projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}/ragMetadata/{rag_metadata_id}`

names

Obrigatório: lista de string

Os nomes de recursos dos RagMetadata a serem excluídos. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}/ragMetadata/{rag_metadata_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

Parâmetros
`parent`	Obrigatório: `string` O nome do recurso do local para realizar a recuperação. 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.

parent

Obrigatório: string

O nome do recurso do local para realizar a recuperação.
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

`VertexRagStore`
`rag_resources`	lista: `RagResource` A representação da origem RAG. Ele pode ser usado para especificar apenas o corpus ou `RagFile`s. Aceita apenas 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}`

rag_resources

lista: RagResource

A representação da origem RAG. Ele pode ser usado para especificar apenas o corpus ou RagFiles. Aceita apenas 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.

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.
`hybrid_search.alpha`	Opcional: `float` O valor Alfa controla o peso entre os resultados da pesquisa vetorial densa e esparsa. O intervalo é [0, 1], em que 0 significa apenas pesquisa vetorial esparsa e 1 significa apenas pesquisa vetorial densa. O valor padrão é 0,5, que equilibra igualmente a pesquisa de vetores esparsos e densos. A pesquisa híbrida está disponível apenas para o Weaviate.
`filter.vector_distance_threshold`	`oneof vector_db_threshold`: `double` Só retorna contextos com uma distância vetorial menor que o limite.
`filter.metadata_filter`	Opcional: `string` O filtro de metadados a ser aplicado durante a recuperação, usando a Common Expression Language (CEL). Para mais informações, consulte [Pesquisa de metadados](/vertex-ai/generative-ai/docs/rag-engine/use-metadata-search). Exemplo: `author == "Shakespeare" && page_number == 42`
`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 recuperação assíncrona

Esta tabela lista os parâmetros da API asyncRetrieveContexts.

Parâmetros

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}`
`query`	Obrigatório: `RagQuery` Consulta única de recuperação de RAG.
`tools`	Opcional: lista de `Tool` As ferramentas a serem usadas para recuperação. As ferramentas compatíveis incluem `retrieval`, que especifica o `vertex_rag_store`.

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}

query

Obrigatório: RagQuery

Consulta única de recuperação de RAG.

tools

Opcional: lista de Tool

As ferramentas a serem usadas para recuperação. As ferramentas compatíveis incluem retrieval, que especifica o vertex_rag_store.

Parâmetros de contexto de solicitação

Esta tabela lista os parâmetros da API askContexts.

Parâmetros

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}`
`query`	Obrigatório: `RagQuery` Consulta única de recuperação de RAG.
`tools`	Opcional: lista de `Tool` As ferramentas a serem usadas para recuperação. As ferramentas compatíveis incluem `retrieval`, que especifica o `vertex_rag_store`.

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}

query

Obrigatório: RagQuery

Consulta única de recuperação de RAG.

tools

Opcional: lista de Tool

As ferramentas a serem usadas para recuperação. As ferramentas compatíveis incluem retrieval, que especifica o vertex_rag_store.

Parâmetros de Prediction

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

GenerateContentRequest

`GenerateContentRequest`
`tools.retrieval.vertex_rag_store`	`VertexRagStore` Definido para usar uma fonte de dados com tecnologia do repositório de RAG da Vertex AI.

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 para envolvidos no projeto.

`RagEngineConfig`

Parâmetros
`RagManagedDbConfig.serverless`	Define/muda o modo de implantação para sem servidor, fornecendo um banco de dados totalmente gerenciado e altamente escalonável para fazer backup dos recursos do mecanismo RAG.
`RagManagedDbConfig.spanner`	Define/muda o modo de implantação para o Spanner, com suporte de uma instância do Spanner pronta para produção.
`RagManagedDbConfig.spanner.scaled`	Esse nível oferece desempenho em escala de produção e funcionalidade de escalonamento automático no modo Spanner.
`RagManagedDbConfig.spanner.basic`	Esse nível oferece uma opção econômica e de baixa computação no modo Spanner.
`RagManagedDbConfig.spanner.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

Este exemplo de código demonstra como criar um corpus RAG.

REST

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

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

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/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ê tenha feito login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login ou usando o Cloud Shell, que faz login automaticamente na gcloud CLI. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

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

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora"

PowerShell

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

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

$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/v1beta1/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.

  PROJECT_ID: Your project ID.
  LOCATION: The region to process the request.
  CORPUS_DISPLAY_NAME: The display name of the <code>RagCorpus</code>.

    // 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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora \
    -d '{
          "display_name" : "CORPUS_DISPLAY_NAME"
      }'

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 Vertex AI Feature Store.
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 abaixo, 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 RagCorpus.
CORPUS_DESCRIPTION: a descrição do RagCorpus.
INDEX_NAME: o nome do recurso do Vector Search Index. Formato: projects/{project}/locations/{location}/indexes/{index}
INDEX_ENDPOINT_NAME: o nome do recurso do Vector Search Index Endpoint. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "display_name" : "CORPUS_DISPLAY_NAME",
  "description": "CORPUS_DESCRIPTION",
  "rag_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 com o nome request.json e execute o comando abaixo:

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID"

PowerShell

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

$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/v1beta1/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

Este exemplo de código demonstra como listar todos os corpora RAG.

REST

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

PROJECT_ID: o ID do projeto.
LOCATION: a região para processar a solicitação.
PAGE_SIZE: tamanho de página de lista padrão. É possível ajustar o número de RagCorpora 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/v1beta1/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 o seguinte comando:

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

PowerShell

Execute o seguinte comando:

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/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 RagCorpora no PROJECT_ID especificado.

Acessar um exemplo de corpus RAG

REST

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

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

Método HTTP e URL:

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

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

curl

Execute o seguinte comando:

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

PowerShell

Execute o seguinte comando:

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

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

// 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/v1beta1/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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/

Excluir um exemplo de corpus RAG

REST

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

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

Método HTTP e URL:

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

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

curl

Execute o seguinte comando:

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

PowerShell

Execute o seguinte comando:

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

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

Uma resposta bem-sucedida retornará DeleteOperationMetadata.

Exemplo de criação em lote de esquemas de metadados

Este exemplo de código demonstra como criar em lote esquemas de metadados para um corpus de RAG.

REST

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

PROJECT_ID: o ID do projeto.
LOCATION: a região para processar a solicitação.
RAG_CORPUS_ID: o ID do recurso RagCorpus.
SCHEMA_KEY_1: a chave do primeiro esquema de metadados.
SCHEMA_TYPE_1: o tipo de dados do primeiro esquema de metadados (por exemplo, INTEGER).
SCHEMA_KEY_2: a chave do segundo esquema de metadados.
SCHEMA_TYPE_2: o tipo de dados do segundo esquema de metadados (por exemplo, STRING).

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "requests": [
    {
      "rag_data_schema": {
        "key": "SCHEMA_KEY_1",
        "schema_details": {"type": "SCHEMA_TYPE_1"}
      }
    },
    {
      "rag_data_schema": {
        "key": "SCHEMA_KEY_2",
        "schema_details": {"type": "SCHEMA_TYPE_2"}
      }
    }
  ]
}

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

curl

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

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragDataSchemas:batchCreate"

PowerShell

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

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragDataSchemas:batchCreate" | Select-Object -Expand Content

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

Exemplo de listagem de esquemas de metadados

Este exemplo de código demonstra como listar esquemas de metadados para um corpus RAG.

REST

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

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

Método HTTP e URL:

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

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

curl

Execute o seguinte comando:

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

PowerShell

Execute o seguinte comando:

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

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

Uma resposta bem-sucedida retorna uma lista de recursos RagDataSchema.

Exemplo de exclusão em lote de esquemas de metadados

Este exemplo de código demonstra como excluir esquemas de metadados em lote.

REST

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

PROJECT_ID: o ID do projeto.
LOCATION: a região para processar a solicitação.
RAG_CORPUS_ID: o ID do recurso RagCorpus.
SCHEMA_ID_1: o ID do primeiro esquema de metadados a ser excluído.
SCHEMA_ID_2: o ID do segundo esquema de metadados a ser excluído.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "names": [
    "projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragDataSchemas/SCHEMA_ID_1",
    "projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragDataSchemas/SCHEMA_ID_2"
  ]
}

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

curl

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

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragDataSchemas:batchDelete"

PowerShell

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

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragDataSchemas:batchDelete" | Select-Object -Expand Content

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

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

REST

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

  PROJECT_ID: Your project ID.
  LOCATION: The region to process the request.
  RAG_CORPUS_ID: The corpus ID of your RAG corpus.
  LOCAL_FILE_PATH: The local path to the file to be uploaded.
  DISPLAY_NAME: The display name of the RAG file.
  DESCRIPTION: The description of the RAG file.

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload"

Exemplo de importação de arquivos RAG

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

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:

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

REST

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

PROJECT_ID: o ID do projeto.
LOCATION: a região para processar a solicitação.
RAG_CORPUS_ID: o ID do recurso RagCorpus.
GCS_URIS: uma lista de locais do Cloud Storage. Exemplo: gs://my-bucket1, gs://my-bucket2.
CHUNK_SIZE (opcional): número de tokens que cada bloco precisa ter.
CHUNK_OVERLAP (opcional): número de tokens sobrepostos entre blocos.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": "GCS_URIS"
    },
    "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 com o nome request.json e execute o comando abaixo:

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"

PowerShell

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

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import" | Select-Object -Expand Content

Uma resposta bem-sucedida retorna o recurso ImportRagFilesOperationMetadata.

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

  PROJECT_ID: Your project ID.
  LOCATION: The region to process the request.
  RAG_CORPUS_ID: The corpus ID of your RAG corpus.
  GCS_URIS: A list of Cloud Storage locations. Example: gs://my-bucket1.
  CHUNK_SIZE: Number of tokens each chunk should have.
  CHUNK_OVERLAP: Number of tokens overlap between chunks.
  EMBEDDING_MODEL_QPM_RATE: The QPM rate to limit RAGs access to your embedding model. Example: 1000.

// 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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": "GCS_URIS"
    },
    "rag_file_chunking_config": {
      "chunk_size": CHUNK_SIZE,
      "chunk_overlap": CHUNK_OVERLAP
    },
    "max_embedding_requests_per_min": EMBEDDING_MODEL_QPM_RATE
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID: The operation ID you get from the response of the previous command.
poll_op_wait OPERATION_ID

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

  PROJECT_ID: Your project ID.
  LOCATION: The region to process the request.
  RAG_CORPUS_ID: The corpus ID of your RAG corpus.
  FOLDER_RESOURCE_ID: The resource ID of your Google Drive folder.
  CHUNK_SIZE: Number of tokens each chunk should have.
  CHUNK_OVERLAP: Number of tokens overlap between chunks.
  EMBEDDING_MODEL_QPM_RATE: The QPM rate to limit RAGs access to your embedding model. Example: 1000.

// 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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "google_drive_source": {
      "resource_ids": {
        "resource_id": "FOLDER_RESOURCE_ID",
        "resource_type": "RESOURCE_TYPE_FOLDER"
      }
    },
    "max_embedding_requests_per_min": EMBEDDING_MODEL_QPM_RATE
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID: The operation ID you get from the response of the previous command.
poll_op_wait OPERATION_ID

Exemplo de listagem de arquivos RAG

Este exemplo de código demonstra como listar arquivos RAG.

REST

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

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

Método HTTP e URL:

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

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

curl

Execute o seguinte comando:

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

PowerShell

Execute o seguinte comando:

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

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

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

Exemplo de como acessar um arquivo RAG

Este exemplo de código demonstra como obter um arquivo RAG.

REST

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

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

Método HTTP e URL:

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

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

curl

Execute o seguinte comando:

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

PowerShell

Execute o seguinte comando:

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

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

Uma resposta bem-sucedida retorna o recurso RagFile.

Excluir um exemplo de arquivo RAG

Este exemplo de código demonstra como excluir um arquivo RAG.

REST

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

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

Método HTTP e URL:

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

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

curl

Execute o seguinte comando:

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

PowerShell

Execute o seguinte comando:

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

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

Uma resposta bem-sucedida retorna o recurso DeleteOperationMetadata.

Exemplo de criação de metadados em lote

Este exemplo de código demonstra como criar metadados em lote para um arquivo RAG.

REST

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

PROJECT_ID: o ID do projeto.
LOCATION: a região para processar a solicitação.
RAG_CORPUS_ID: o ID do recurso RagCorpus.
RAG_FILE_ID: o ID do recurso RagFile.
METADATA_KEY_1: a chave da primeira entrada de metadados.
VALUE_TYPE_1: o campo de tipo de valor para a primeira entrada de metadados (por exemplo, int_value).
METADATA_VALUE_1: o valor da primeira entrada de metadados.
METADATA_KEY_2: a chave da segunda entrada de metadados.
VALUE_TYPE_2: o campo de tipo de valor para a segunda entrada de metadados (por exemplo, str_value).
METADATA_VALUE_2: o valor da segunda entrada de metadados.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "requests": [
    {
      "rag_metadata": {
        "user_specified_metadata": {
          "key": "METADATA_KEY_1",
          "value": { "VALUE_TYPE_1": METADATA_VALUE_1 }
        }
      }
    },
    {
      "rag_metadata": {
        "user_specified_metadata": {
          "key": "METADATA_KEY_2",
          "value": { "VALUE_TYPE_2": "METADATA_VALUE_2" }
        }
      }
    }
  ]
}

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

curl

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

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID/ragMetadata:batchCreate"

PowerShell

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

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID/ragMetadata:batchCreate" | Select-Object -Expand Content

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

Exemplo de metadados da lista

Este exemplo de código demonstra como listar metadados de um arquivo RAG.

REST

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

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

Método HTTP e URL:

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

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

curl

Execute o seguinte comando:

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

PowerShell

Execute o seguinte comando:

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

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

Uma resposta bem-sucedida retorna uma lista de recursos RagMetadata.

Exemplo de atualização de metadados

Este exemplo de código demonstra como atualizar os metadados de um arquivo RAG.

REST

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

PROJECT_ID: o ID do projeto.
LOCATION: a região para processar a solicitação.
RAG_CORPUS_ID: o ID do recurso RagCorpus.
RAG_FILE_ID: o ID do recurso RagFile.
METADATA_ID: o ID da entrada de metadados a ser atualizada.
METADATA_KEY: a chave da entrada de metadados.
VALUE_TYPE: o campo de tipo de valor (por exemplo, int_value).
METADATA_VALUE: o novo valor da entrada de metadados.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "user_specified_metadata": {
    "key": "METADATA_KEY",
    "value": { "VALUE_TYPE": METADATA_VALUE }
  }
}

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

curl

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

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID/ragMetadata/METADATA_ID"

PowerShell

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

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID/ragMetadata/METADATA_ID" | Select-Object -Expand Content

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

Exemplo de exclusão de metadados em lote

Este exemplo de código demonstra como excluir em lote entradas de metadados de um arquivo RAG.

REST

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

PROJECT_ID: o ID do projeto.
LOCATION: a região para processar a solicitação.
RAG_CORPUS_ID: o ID do recurso RagCorpus.
RAG_FILE_ID: o ID do recurso RagFile.
METADATA_ID_1: o ID da primeira entrada de metadados a ser excluída.
METADATA_ID_2: o ID da segunda entrada de metadados a ser excluída.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "names": [
    "projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID/ragMetadata/METADATA_ID_1",
    "projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID/ragMetadata/METADATA_ID_2"
  ]
}

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

curl

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

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID/ragMetadata:batchDelete"

PowerShell

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

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID/ragMetadata:batchDelete" | Select-Object -Expand Content

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

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.

REST

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

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

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "vertex_rag_store": {
    "rag_resources": [
      {
        "rag_corpus": "RAG_CORPUS_RESOURCE"
      }
    ]
  },
  "query": {
    "text": "TEXT",
    "rag_retrieval_config": {
      "top_k": TOP_K,
      "filter": {
        "vector_distance_threshold": VECTOR_DISTANCE_THRESHOLD,
        "metadata_filter": "METADATA_FILTER"
      }
    }
  }
}

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

curl

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

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/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"

PowerShell

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

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" | Select-Object -Expand Content

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

Exemplo de geração

O LLM gera uma resposta embasada usando os contextos recuperados.

REST

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

PROJECT_ID: o ID do projeto.
LOCATION: a região para processar a solicitação.
MODEL_ID: modelo LLM para geração de conteúdo. Exemplo: gemini-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}.
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.
METADATA_FILTER: opcional: o filtro de metadados a ser aplicado durante a recuperação.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "contents": {
    "role": "user",
    "parts": {
      "text": "INPUT_PROMPT"
    }
  },
  "tools": {
    "retrieval": {
      "disable_attribution": false,
      "vertex_rag_store": {
        "rag_resources": [
          {
            "rag_corpus": "RAG_CORPUS_RESOURCE"
          }
        ],
        "rag_retrieval_config": {
          "top_k": TOP_K,
          "filter": {
            "vector_distance_threshold": VECTOR_DISTANCE_THRESHOLD,
            "metadata_filter": "METADATA_FILTER"
          }
        }
      }
    }
  }
}

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

curl

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

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD"

PowerShell

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

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD" | Select-Object -Expand Content

Uma resposta bem-sucedida retornará o conteúdo gerado com citações.

Exemplos de gerenciamento de projetos

O modo e o nível de implantação são uma configuração para envolvidos no projeto disponível no recurso RagEngineConfig e afetam os corpus de RAG que usam RagManagedDb. Para conferir a configuração atual, use GetRagEngineConfig. Para atualizar a configuração, use UpdateRagEngineConfig.

Para mais informações sobre como gerenciar a configuração de modo e nível, consulte Modos de implantação no RAG Engine.

Ler seu RagEngineConfig atual

Os exemplos de código a seguir mostram como ler seu RagEngineConfig para ver qual modo e nível estão selecionados no momento:

Console

No console do Google Cloud , acesse a página Mecanismo RAG.
Acessar o mecanismo RAG
Selecione a região em que o mecanismo RAG está sendo executado. Sua lista de corpora de RAG é atualizada.
Clique em Configurar o mecanismo RAG. O painel Configurar o mecanismo RAG é exibido. Você pode conferir o nível selecionado para seu mecanismo de RAG.
Clique em Cancelar.

REST

PROJECT_ID: Your project ID.
LOCATION: The region to process the request.

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

Python

from vertexai.preview 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)

Mudar para o modo sem servidor

Os exemplos de código a seguir mostram como mudar seu RagEngineConfig para o modo sem servidor:

Console

No console do Google Cloud , acesse a página Mecanismo RAG.
Acessar o mecanismo RAG
Selecione a região em que o Mecanismo RAG da Vertex AI está sendo executado.
Clique no botão Mudar para sem servidor. Esse botão pode não aparecer se você já estiver no modo sem servidor. Você pode verificar seu modo atual no rótulo no canto superior direito da página.

REST

PROJECT_ID: Your project ID.
LOCATION: The region to process the request.

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

Python

from vertexai.preview 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(mode=rag.Serverless()),
)

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

print(updated_rag_engine_config)

Mudar para o modo Spanner

Os exemplos de código a seguir mostram como mudar seu RagEngineConfig para o modo do Spanner. Se você já usou o modo do Spanner e escolheu um nível, não é mais necessário informá-lo explicitamente ao mudar. Caso contrário, consulte os exemplos de código abaixo sobre como mudar para o modo do Spanner ao fornecer um nível.

Console

No console do Google Cloud , acesse a página Mecanismo RAG.
Acessar o mecanismo RAG
Selecione a região em que o Mecanismo RAG da Vertex AI está sendo executado.
Clique no botão Mudar para o Spanner. Esse botão pode não aparecer se você já estiver no modo Spanner. Você pode verificar seu modo atual no rótulo no canto superior direito da página.

REST

PROJECT_ID: Your project ID.
LOCATION: The region to process the request.

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

Python

from vertexai.preview 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(mode=rag.Spanner()),
)

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

print(updated_rag_engine_config)

Atualizar seu `RagEngineConfig` para o nível escalonado do modo Spanner

Os exemplos de código a seguir demonstram como definir o RagEngineConfig para o modo do Spanner com o nível escalonado:

Console

No console do Google Cloud , acesse a página Mecanismo RAG.
Acessar o mecanismo RAG
Selecione a região em que o Mecanismo RAG da Vertex AI está sendo executado.
Clique no botão Mudar para o Spanner se ainda não estiver no modo Spanner.
Clique em Configurar o mecanismo RAG. O painel Configurar o mecanismo RAG é exibido.
Selecione a camada em que você quer executar o mecanismo de RAG.
Clique em Salvar.

REST

PROJECT_ID: Your project ID.
LOCATION: The region to process the request.

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

Python

from vertexai.preview 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(mode=rag.Spanner(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)

Atualizar seu `RagEngineConfig` para o modo do Spanner com o nível Básico

Os exemplos de código a seguir demonstram como definir o RagEngineConfig para o modo do Spanner com o nível básico:

Console

No console do Google Cloud , acesse a página Mecanismo RAG.
Acessar o mecanismo RAG
Selecione a região em que o Mecanismo RAG da Vertex AI está sendo executado.
Clique no botão Mudar para o Spanner se ainda não estiver no modo Spanner.
Clique em Configurar o mecanismo RAG. O painel Configurar o mecanismo RAG é exibido.
Selecione a camada em que você quer executar o mecanismo de RAG.
Clique em Salvar.

REST

PROJECT_ID: Your project ID.
LOCATION: The region to process the request.

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

Python

from vertexai.preview 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(mode=rag.Spanner(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)

Atualizar seu `RagEngineConfig` para o nível não provisionado

Os exemplos de código a seguir demonstram como definir o RagEngineConfig para o modo do Spanner com o nível não provisionado. Isso vai excluir permanentemente todos os dados do seu modo de implantação do Spanner e interromper as despesas de faturamento decorrentes dele.

Console

No console do Google Cloud , acesse a página Mecanismo RAG.
Acessar o mecanismo RAG
Selecione a região em que o Mecanismo RAG da Vertex AI está sendo executado.
Clique no botão Mudar para o Spanner se ainda não estiver no modo Spanner.
Clique em Excluir mecanismo RAG. Uma caixa de diálogo de confirmação é exibida.
Verifique se você está prestes a excluir seus dados no mecanismo de RAG da Vertex AI digitando "delete" e clique em Confirmar.
Clique em Salvar.

REST

PROJECT_ID: Your project ID.
LOCATION: The region to process the request.

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

Python

from vertexai.preview 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(mode=rag.Spanner(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)

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 Visão geral do mecanismo RAG.

API RAG Engine Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Lista de parâmetros

Parâmetros de gerenciamento do corpus

Criar um corpus RAG

Solicitação de corpo

CorpusTypeConfig

RagVectorDbConfig

Atualizar um corpus RAG

Solicitação de corpo

Listar corpus da RAG

Acessar um corpus RAG

Excluir um corpus RAG

Criar esquemas de metadados em lote

Solicitação de corpo

CreateRagDataSchemaRequest

RagDataSchema

RagMetadataSchemaDetails

Listar esquemas de metadados

Excluir em lote esquemas de metadados

Parâmetros de gerenciamento de arquivos

Fazer upload de um arquivo RAG

Solicitação de corpo

Importar arquivos RAG

Acessar um arquivo RAG

Excluir um arquivo RAG

Criar metadados em lote

Solicitação de corpo

CreateRagMetadataRequest

RagMetadata

UserSpecifiedMetadata

MetadataValue

Metadados da lista

Atualizar metadados

Excluir metadados em lote

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

Parâmetros de recuperação

VertexRagStore

Parâmetros de recuperação assíncrona

Parâmetros de contexto de solicitação

Parâmetros de Prediction

Parâmetros de gerenciamento de projetos

RagEngineConfig

Exemplos de gerenciamento do corpus

Criar um exemplo de corpus RAG

REST

curl

PowerShell

Atualizar um exemplo de corpus RAG

REST

curl

PowerShell

Exemplo de lista de corpora de RAG

REST

curl

PowerShell

Acessar um exemplo de corpus RAG

REST

curl

PowerShell

Excluir um exemplo de corpus RAG

REST

curl

PowerShell

Exemplo de criação em lote de esquemas de metadados

REST

curl

PowerShell

Exemplo de listagem de esquemas de metadados

REST

curl

PowerShell

Exemplo de exclusão em lote de esquemas de metadados

REST

curl

PowerShell

Exemplos de gerenciamento de arquivos

Fazer upload de um exemplo de arquivo RAG

REST

Exemplo de importação de arquivos RAG

REST

API RAG Engine

`CorpusTypeConfig`

`RagVectorDbConfig`

`CreateRagDataSchemaRequest`

`RagDataSchema`

`RagMetadataSchemaDetails`

`CreateRagMetadataRequest`

`RagMetadata`

`UserSpecifiedMetadata`

`MetadataValue`

`VertexRagStore`

`RagEngineConfig`

Atualizar seu `RagEngineConfig` para o nível escalonado do modo Spanner

Atualizar seu `RagEngineConfig` para o modo do Spanner com o nível Básico

Atualizar seu `RagEngineConfig` para o nível não provisionado