此页面由 Cloud Translation API 翻译。

RAG Engine API

本指南提供了 RAG 引擎的 API 参考文档。它涵盖以下主题：

参数列表：介绍了用于管理语料库、文件和项目的 API 参数。
语料库管理示例：提供有关创建、更新、列出和删除 RAG 语料库的示例。
文件管理示例：展示了如何在 RAG 语料库中上传、导入和管理文件。
检索和预测示例：包含检索上下文和生成有事实依据的回答的示例。
项目管理示例：说明如何为 RAG 引擎配置项目级设置。

Vertex AI RAG 引擎是 Vertex AI 平台的组成部分，有助于检索增强生成 (RAG)。RAG 引擎可让大语言模型 (LLM) 访问和整合外部知识源（例如文档和数据库）中的数据。通过使用 RAG，LLM 可以生成更准确、信息更丰富的回答。

参数列表

语料库管理参数

如需了解 RAG 语料库，请参阅语料库管理。

创建 RAG 语料库

下表列出了用于创建 RAG 语料库的参数。

正文请求

参数	说明
`corpus_type_config`	可选，不可变。`RagCorpus.CorpusTypeConfig` 用于指定语料库类型的配置。
`display_name`	必需。`string` RAG 语料库的显示名称。
`description`	可选。`string` RAG 语料库的说明。
`encryption_spec`	可选，不可变。`string` 用于加密与 RAG 语料库相关的静态数据的 CMEK 密钥名称。此键名仅适用于向量数据库的 `RagManaged` 选项。您可以在创建语料库时设置此字段，但之后无法更新或删除该字段。格式：`projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}`
`vector_db_config`	可选，不可变。`RagVectorDbConfig` 向量数据库的配置。
`vertex_ai_search_config.serving_config`	可选。`string` Vertex AI Search 的配置。格式：`projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config}` 或 `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/servingConfigs/{serving_config}`

CorpusTypeConfig

参数说明

参数	说明
`document_corpus`	`oneof` `RagCorpus.CorpusTypeConfig.DocumentCorpus` `corpus_type_config` 的默认值，表示基于文档的传统 RAG 语料库。
`memory_corpus`	`oneof` `RagCorpus.CorpusTypeConfig.MemoryCorpus` 如果您设置了此类型，则 RAG 语料库将成为 `MemoryCorpus`，可与 Gemini Live API 搭配用作记忆存储区。如需了解详情，请参阅将 Vertex AI RAG 引擎用作记忆存储区。
`memory_corpus.llm_parser`	`oneof` `RagFileParsingConfig.LlmParser` 用于解析和存储来自 Gemini Live API 的会话上下文的 LLM 解析器。您可以构建用于编入索引的记忆。

document_corpus

oneof RagCorpus.CorpusTypeConfig.DocumentCorpus

corpus_type_config 的默认值，表示基于文档的传统 RAG 语料库。

memory_corpus

oneof RagCorpus.CorpusTypeConfig.MemoryCorpus

如果您设置了此类型，则 RAG 语料库将成为 MemoryCorpus，可与 Gemini Live API 搭配用作记忆存储区。

如需了解详情，请参阅将 Vertex AI RAG 引擎用作记忆存储区。

memory_corpus.llm_parser

oneof RagFileParsingConfig.LlmParser

用于解析和存储来自 Gemini Live API 的会话上下文的 LLM 解析器。您可以构建用于编入索引的记忆。

RagVectorDbConfig

创建 RAG 语料库时，您可以从多个向量数据库选项中进行选择。下表提供了比较信息，可帮助您选择最适合自己使用情形的选项。

向量数据库选项	说明	使用场景
`rag_managed_db`	Google 提供的全代管式矢量数据库。	对于希望获得集成式解决方案但不想管理自己的数据库基础设施的用户。
`weaviate`	连接到自行管理的 Weaviate 实例。	对于已拥有或偏好使用 Weaviate 向量数据库的用户。
`pinecone`	连接到自行管理的 Pinecone 实例。	对于已拥有或偏好使用 Pinecone 向量数据库的用户。
`vertex_feature_store`	使用现有的 Vertex AI Feature Store 实例。	用于将 RAG 与 Vertex AI Feature Store 中的现有机器学习特征和数据集成。
`vertex_vector_search`	使用现有的 Vector Search 索引。	利用向量搜索的高级可伸缩性和性能来支持大规模应用。

如果您选择 rag_managed_db 选项，还必须选择检索策略。下表比较了可用的策略。

检索策略	说明	优点	缺点
`KNN`（K 近邻）	通过对所有数据点进行详尽搜索来查找精确的最近邻。	提供最准确、最相关的结果。	速度可能较慢，计算开销也可能较高，尤其是在处理大型数据集时。
`ANN`（近似最邻近）	查找可能最接近的邻居，以牺牲一定程度的准确性换取显著的速度提升。	查询性能大幅提升，延迟时间缩短。	结果是近似值，可能不是绝对最相关的。

参数	说明
`rag_managed_db`	`oneof` `vector_db`：`RagVectorDbConfig.RagManagedDb` 如果未指定向量数据库，则 `rag_managed_db` 是默认的向量数据库。
`rag_managed_db.knn`	`oneof` `retrieval_strategy`：`KNN` 这是默认的检索策略。通过比较 RAG 语料库中的所有数据点来查找确切的最近邻。如果您在创建 RAG 语料库时未指定策略，系统会使用 KNN。
`rag_managed_db.ann`	`oneof` `retrieval_strategy`：`ANN` tree_depth 确定树中的层数或级别数。如果 RAG 语料库中有 `O(10K)` 个 RAG 文件，请将此值设置为 2。如果需要更多层或级别，请将此值设置为 3。如果您未指定层数或级别数，Vertex AI RAG Engine 会分配默认值 2。 leaf_count 确定基于树的结构中的叶节点数量。建议值为 `10 * sqrt(num of RAG files in your RAG corpus)`。如果未指定，Vertex AI RAG 引擎会分配默认值 500。 rebuild_ann_index Vertex AI RAG 引擎会重建 ANN 索引。如需重建索引，请在 `ImportRagFiles` API 请求中将此参数设置为 `true`。在查询 RAG 语料库之前，您必须重建一次 ANN 索引。每个位置中的项目仅支持一次并发索引重建。
`weaviate`	`oneof` `vector_db`：`RagVectorDbConfig.Weaviate` 指定您的 Weaviate 实例。
`weaviate.http_endpoint`	`string` Weaviate 实例的 HTTP 端点。此值一经设置便无法更改。您可以在 `CreateRagCorpus` 请求中将此字段留空，稍后在 `UpdateRagCorpus` 请求中设置此字段。
`weaviate.collection_name`	`string` RAG 语料库映射到的 Weaviate 集合。此值一经设置便无法更改。您可以在 `CreateRagCorpus` 请求中将此字段留空，稍后在 `UpdateRagCorpus` 请求中设置此字段。
`pinecone`	`oneof` `vector_db`：`RagVectorDbConfig.Pinecone` 指定您的 Pinecone 实例。
`pinecone.index_name`	`string` 用于创建与 RAG 语料库搭配使用的 Pinecone 索引的名称。此值一经设置便无法更改。您可以在 `CreateRagCorpus` 请求中将此字段留空，稍后在 `UpdateRagCorpus` 请求中设置此字段。
`vertex_feature_store`	`oneof` `vector_db`：`RagVectorDbConfig.VertexFeatureStore` 指定您的 Vertex AI Feature Store 实例。
`vertex_feature_store.feature_view_resource_name`	`string` RAG 语料库映射到的 Vertex AI Feature Store `FeatureView`。格式：`projects/{project}/locations/{location}/featureOnlineStores/{feature_online_store}/featureViews/{feature_view}` 此值一经设置便无法更改。您可以在 `CreateRagCorpus` 请求中将此字段留空，稍后在 `UpdateRagCorpus` 请求中设置此字段。
`vertex_vector_search`	`oneof` `vector_db`：`RagVectorDbConfig.VertexVectorSearch` 指定您的 Vector Search 实例。
`vertex_vector_search.index`	`string` 与 RAG 语料库搭配使用的 Vector Search 索引的资源名称。格式：`projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}` 此值一经设置便无法更改。您可以在 `CreateRagCorpus` 请求中将此字段留空，稍后在 `UpdateRagCorpus` 请求中设置此字段。
`vertex_vector_search.index_endpoint`	`string` 与 RAG 语料库搭配使用的 Vector Search 索引端点的资源名称。格式：`projects/{project}/locations/{location}/indexes/{index}` 此值一经设置便无法更改。您可以在 `CreateRagCorpus` 请求中将此字段留空，稍后在 `UpdateRagCorpus` 请求中设置此字段。
`api_auth.api_key_config.api_key_secret_version`	`string` 这是存储在 Secret Manager 中的密文的完整资源名称，该密文包含 Weaviate 或 Pinecone 向量数据库的 API 密钥。格式：`projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}` 您可以在 `CreateRagCorpus` 请求中将此字段留空，稍后在 `UpdateRagCorpus` 请求中设置此字段。
`rag_embedding_model_config.vertex_prediction_endpoint.endpoint`	可选，不可变。`string` 要用于 RAG 语料库的嵌入模型。此值一经设置便无法更改。如果您将其留空，RAG 引擎会使用 text-embedding-005 作为嵌入模型。

更新 RAG 语料库

下表列出了用于更新 RAG 语料库的参数。

正文请求

参数	说明
`display_name`	可选。`string` RAG 语料库的显示名称。
`description`	可选。`string` RAG 语料库的说明。
`rag_vector_db.weaviate.http_endpoint`	`string` Weaviate 实例的 HTTP 端点。如果您使用 `Weaviate` 配置创建了 `RagCorpus`，并且尚未设置此字段，那么您可以更新 Weaviate 实例的 HTTP 端点。
`rag_vector_db.weaviate.collection_name`	`string` RAG 语料库映射到的 Weaviate 集合。如果您使用 `Weaviate` 配置创建了 `RagCorpus`，但尚未设置此字段，则可以更新 Weaviate 实例的集合名称。
`rag_vector_db.pinecone.index_name`	`string` 用于创建与 RAG 语料库搭配使用的 Pinecone 索引的名称。如果您使用 `Pinecone` 配置创建了 `RagCorpus`，并且尚未设置此字段，则可以更新 Pinecone 实例的索引名称。
`rag_vector_db.vertex_feature_store.feature_view_resource_name`	`string` RAG 语料库映射到的 Vertex AI Feature Store `FeatureView`。格式：`projects/{project}/locations/{location}/featureOnlineStores/{feature_online_store}/featureViews/{feature_view}` 如果您使用 `Vertex AI Feature Store` 配置创建了 `RagCorpus`，并且尚未设置此字段，则可以更新它。
`rag_vector_db.vertex_vector_search.index`	`string` 与 RAG 语料库搭配使用的 Vector Search 索引的资源名称。格式：`projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}` 如果您使用 `Vector Search` 配置创建了 `RagCorpus`，并且尚未设置此字段，则可以更新它。
`rag_vector_db.vertex_vector_search.index_endpoint`	`string` 与 RAG 语料库搭配使用的 Vector Search 索引端点的资源名称。格式：`projects/{project}/locations/{location}/indexes/{index}` 如果您使用 `Vector Search` 配置创建了 `RagCorpus`，并且尚未设置此字段，则可以更新它。
`rag_vector_db.api_auth.api_key_config.api_key_secret_version`	`string` 存储在 Secret Manager 中的密文的完整资源名称，该密文包含 Weaviate 或 Pinecone 向量数据库的 API 密钥。格式：`projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}`

列出 RAG 语料库

下表列出了用于列出 RAG 语料库的参数。

参数说明

参数	说明
`page_size`	可选。`int` 标准列表页面大小。
`page_token`	可选。`string` 您可以从之前的 `[VertexRagDataService.ListRagCorpora][]` 调用的 `[ListRagCorporaResponse.next_page_token][]` 中获取的页面令牌。

page_size

可选。int

标准列表页面大小。

page_token

可选。string

您可以从之前的 [VertexRagDataService.ListRagCorpora][] 调用的 [ListRagCorporaResponse.next_page_token][] 中获取的页面令牌。

获取 RAG 语料库

下表列出了用于获取 RAG 语料库的参数。

参数说明

参数	说明
`name`	必需。`string` `RagCorpus` 资源的名称。格式：`projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}`

name

必需。string

RagCorpus 资源的名称。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

删除 RAG 语料库

下表列出了用于删除 RAG 语料库的参数。

参数说明

参数	说明
`name`	必需。`string` `RagCorpus` 资源的名称。格式：`projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}`

name

必需。string

RagCorpus 资源的名称。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

文件管理参数

如需了解 RAG 文件，请参阅文件管理。

上传 RAG 文件

下表列出了用于上传 RAG 文件的参数。

正文请求

参数说明

参数	说明
`parent`	必需。`string` `RagCorpus` 资源的名称。格式：`projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}`
`rag_file`	必需。`RagFile` 要上传的文件。
`upload_rag_file_config`	必需。`UploadRagFileConfig` 要上传到 `RagCorpus` 的 `RagFile` 的配置。

parent

必需。string

RagCorpus 资源的名称。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

rag_file

必需。RagFile

要上传的文件。

upload_rag_file_config

必需。UploadRagFileConfig

要上传到 RagCorpus 的 RagFile 的配置。

RagFile 说明

`RagFile`	说明
`display_name`	必需。`string` RAG 文件的显示名称。
`description`	可选。`string` RAG 文件的说明。

display_name

必需。string

RAG 文件的显示名称。

description

可选。string

RAG 文件的说明。

UploadRagFileConfig 说明

`UploadRagFileConfig`	说明
`rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_size`	`int32` 每个分块中的令牌数量。
`rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_overlap`	`int32` 分块之间的重叠词元数。

rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_size

int32

每个分块中的令牌数量。

rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_overlap

int32

分块之间的重叠词元数。

导入 RAG 文件

下表列出了用于导入 RAG 文件的参数。

参数	说明
`parent`	必需。`string` `RagCorpus` 资源的名称。格式：`projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}`
`gcs_source`	`oneof` `import_source`：`GcsSource` Cloud Storage 位置。支持导入单个文件和整个 Cloud Storage 目录。
`gcs_source.uris`	`list`/`string` 包含上传文件的 Cloud Storage URI。
`google_drive_source`	`oneof` `import_source`：`GoogleDriveSource` Google 云端硬盘位置。支持导入单个文件和 Google 云端硬盘文件夹。
`slack_source`	`oneof` `import_source`：`SlackSource` 上传文件的 Slack 频道。
`jira_source`	`oneof` `import_source`：`JiraSource` 上传文件的 Jira 查询。
`share_point_sources`	`oneof` `import_source`：`SharePointSources` 上传文件的 SharePoint 来源。
`rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_size`	`int32` 每个分块中的令牌数量。
`rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_overlap`	`int32` 分块之间的重叠词元数。
`rag_file_parsing_config`	可选。`RagFileParsingConfig` 指定 `RagFiles` 的解析配置。如果您未设置此字段，RAG 会使用默认解析器。
`max_embedding_requests_per_min`	可选。`int32` 此作业可以对嵌入模型进行的每分钟查询次数 (QPM) 上限。此值仅适用于此作业，不会与其他导入作业共用。如需设置适当的值，请参阅项目的“配额”页面。如果您未指定值，则使用默认值 1,000 QPM。

GoogleDriveSource 说明

`GoogleDriveSource`	说明
`resource_ids.resource_id`	必需。`string` Google 云端硬盘资源的 ID。
`resource_ids.resource_type`	必需。`string` Google 云端硬盘资源的类型。

resource_ids.resource_id

必需。string

Google 云端硬盘资源的 ID。

resource_ids.resource_type

必需。string

Google 云端硬盘资源的类型。

`SlackSource`	说明
`channels.channels`	重复。`SlackSource.SlackChannels.SlackChannel` Slack 频道信息，包括要导入的 ID 和时间范围。
`channels.channels.channel_id`	必需。`string` Slack 频道 ID。
`channels.channels.start_time`	可选。`google.protobuf.Timestamp` 要导入的消息的起始时间戳。
`channels.channels.end_time`	可选。`google.protobuf.Timestamp` 要导入的消息的结束时间戳。
`channels.api_key_config.api_key_secret_version`	必需。`string` 存储在 Secret Manager 中的密文的完整资源名称，该密文包含可用于访问指定 Slack 频道 ID 的 Slack 频道访问令牌。请参阅：获取令牌。格式：`projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}`

`JiraSource`	说明
`jira_queries.projects`	重复。`string` 要完整导入的 Jira 项目的列表。
`jira_queries.custom_queries`	重复。`string` 要导入的自定义 Jira 查询的列表。如需详细了解 Jira 查询语言 (JQL)，请参阅 Jira 支持。
`jira_queries.email`	必需。`string` Jira 电子邮件地址。
`jira_queries.server_uri`	必需。`string` Jira 服务器 URI。
`jira_queries.api_key_config.api_key_secret_version`	必需。`string` 存储在 Secret Manager 中的密文的完整资源名称，该密文包含 Jira API 密钥。请参阅：管理 Atlassian 账号的 API 令牌。格式：`projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}`

`SharePointSources`	说明
`share_point_sources.sharepoint_folder_path`	`folder_source` 中的 `oneof`：`string` 要作为下载来源的 SharePoint 文件夹的路径。
`share_point_sources.sharepoint_folder_id`	`folder_source` 中的 `oneof`：`string` 要作为下载来源的 SharePoint 文件夹的 ID。
`share_point_sources.drive_name`	`drive_source` 中的 `oneof`：`string` 要作为下载来源的云端硬盘的名称。
`share_point_sources.drive_id`	`drive_source` 中的 `oneof`：`string` 要作为下载来源的云端硬盘的 ID。
`share_point_sources.client_id`	`string` 在 Microsoft Azure 门户中注册的应用的应用（客户端）ID。应用还必须配置以下 Microsoft Graph 权限：`Files.ReadAll`、`Sites.ReadAll` 和 `BrowserSiteLists.Read.All`。
`share_point_sources.client_secret.api_key_secret_version`	必需。`string` 存储在 Secret Manager 中的密文的完整资源名称，该密文包含在 Azure 中注册的应用的应用密文。格式：`projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}`
`share_point_sources.tenant_id`	`string` Azure Active Directory 实例的唯一标识符。
`share_point_sources.sharepoint_site_name`	`string` 要作为下载来源的 SharePoint 网站的名称。可以是网站名称，也可以是网站 ID。

解析器选项	说明	使用场景
`layout_parser`	使用 Document AI 解析文件，同时保留文档的结构和布局。	最适合结构化或半结构化文档，例如包含表格、列和复杂布局的 PDF。
`llm_parser`	使用大语言模型 (LLM) 解析文件，侧重于对内容的语义理解。	非常适合非结构化文本文档，这类文档中提取含义和上下文比保留原始视觉布局更重要。

`RagFileParsingConfig`	说明
`layout_parser`	`oneof` `parser`：`RagFileParsingConfig.LayoutParser` 要用于 `RagFile` 的布局解析器。
`layout_parser.processor_name`	`string` Document AI 处理器或处理器版本的完整资源名称。格式： `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` 作业每分钟可向 Document AI 处理器发出的请求数上限。请访问 https://cloud.google.com/document-ai/quotas 和项目的“配额”页面，在此处设置适当的值。如果未指定，则使用默认值 120 QPM。
`llm_parser`	`oneof` `parser`：`RagFileParsingConfig.LlmParser` 要用于 `RagFile` 的 LLM 解析器。
`llm_parser.model_name`	`string` LLM 模型的资源名称。格式： `projects/{project_id}/locations/{location}/publishers/{publisher}/models/{model}`
`llm_parser.max_parsing_requests_per_min`	`string` 作业每分钟可向 LLM 模型发出的请求数上限。如需为项目设置适当的值，请参阅模型配额部分和项目的“配额”页面，在此处设置适当的值。如果未指定，则使用默认值 5000 QPM。

获取 RAG 文件

下表列出了用于获取 RAG 文件的参数。

参数说明

参数	说明
`name`	必需。`string` `RagFile` 资源的名称。格式：`projects/{project}/locations/{location}/ragCorpora/{rag_file_id}`

name

必需。string

RagFile 资源的名称。格式：projects/{project}/locations/{location}/ragCorpora/{rag_file_id}

删除 RAG 文件

下表列出了用于删除 RAG 文件的参数。

参数说明

参数	说明
`name`	必需。`string` `RagFile` 资源的名称。格式：`projects/{project}/locations/{location}/ragCorpora/{rag_file_id}`

name

必需。string

RagFile 资源的名称。格式：projects/{project}/locations/{location}/ragCorpora/{rag_file_id}

检索和预测参数

本部分列出了检索和预测参数。

检索参数

下表列出了 retrieveContexts 方法的参数。

参数说明

参数	说明
`parent`	必需。`string` 要从中检索 `RagContexts` 的营业地点的资源名称。您必须有权在项目中进行调用。格式：`projects/{project}/locations/{location}`
`vertex_rag_store`	`VertexRagStore` Vertex RagStore 的数据源。
`query`	必需。`RagQuery` 单个 RAG 检索查询。

parent

必需。string

要从中检索 RagContexts 的营业地点的资源名称。
您必须有权在项目中进行调用。

格式：projects/{project}/locations/{location}

vertex_rag_store

VertexRagStore

Vertex RagStore 的数据源。

query

必需。RagQuery

单个 RAG 检索查询。

VertexRagStore

VertexRagStore 说明

`VertexRagStore`	说明
`rag_resources`	列表：`RagResource` RAG 来源。您可以指定单个语料库，也可以指定一个语料库中的多个 `RagFile`。
`rag_resources.rag_corpus`	可选。`string` `RagCorpora` 资源名称。格式：`projects/{project}/locations/{location}/ragCorpora/{rag_corpus}`
`rag_resources.rag_file_ids`	列表：`string` `RagFile` 资源的列表。格式：`projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file}`

rag_resources

列表：RagResource

RAG 来源。您可以指定单个语料库，也可以指定一个语料库中的多个 RagFile。

rag_resources.rag_corpus

可选。string

RagCorpora 资源名称。

格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}

rag_resources.rag_file_ids

列表：string

RagFile 资源的列表。

格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file}

RagQuery 说明

`RagQuery`	说明
`text`	`string` 要获取相关上下文的文本格式的查询。
`rag_retrieval_config`	可选。`RagRetrievalConfig` 用于查询的检索配置。

text

string

要获取相关上下文的文本格式的查询。

rag_retrieval_config

可选。RagRetrievalConfig

用于查询的检索配置。

`RagRetrievalConfig`	说明
`top_k`	可选。`int32` 要检索的上下文数量。
`hybrid_search.alpha`	可选。`float` 用于控制密集和稀疏向量搜索结果之间的权重。该值必须介于 0.0 到 1.0 之间。值为 0.0 表示仅进行稀疏向量搜索，值为 1.0 表示仅进行密集向量搜索。默认值为 0.5。混合搜索仅适用于 Weaviate。
`filter.vector_distance_threshold`	`oneof vector_db_threshold`：`double` 仅返回向量距离小于此阈值的上下文。
`filter.vector_similarity_threshold`	`oneof vector_db_threshold`：`double` 仅返回向量相似度大于此阈值的上下文。
`ranking.rank_service.model_name`	可选。`string` 排名服务的模型名称。示例：`semantic-ranker-512@latest`
`ranking.llm_ranker.model_name`	可选。`string` 用于排名的模型名称。示例：`gemini-2.5-flash`

预测参数

下表列出了预测参数。

GenerateContentRequest 说明

`GenerateContentRequest`	说明
`tools.retrieval.vertex_rag_store`	`VertexRagStore` 设置为使用由 Vertex AI RAG 存储空间提供支持的数据源。

tools.retrieval.vertex_rag_store

VertexRagStore

设置为使用由 Vertex AI RAG 存储空间提供支持的数据源。

如需了解详情，请参阅 VertexRagStore。

项目管理参数

下表列出了项目级参数。

使用 RagManagedDb 时，您可以选择最符合性能和费用要求的层级。下表比较了可用的层级。

层级	说明	使用场景
`scaled`	一种生产规模层级，具有自动扩缩功能，可处理高且可变的查询负载。	建议用于需要高可用性和高性能的生产应用。
`basic`	经济实惠、计算层级较低，适合小规模需求。	适用于开发、测试或流量较低且可预测的应用。
`unprovisioned`	取消预配受管理的数据库及其底层资源。	用于停用代管式数据库并停止产生相关费用。

RagEngineConfig

参数	说明
`RagManagedDbConfig.scaled`	此层级提供生产规模的性能，并具有自动扩缩功能。
`RagManagedDbConfig.basic`	此层级具有成本效益，计算层级较低。
`RagManagedDbConfig.unprovisioned`	此层级会取消预配 `RagManagedDb` 及其底层 Spanner 实例。

语料库管理示例

本部分举例说明了如何使用 API 管理 RAG 语料库。

创建 RAG 语料库示例

此示例演示了如何创建 RAG 语料库。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
CORPUS_DISPLAY_NAME：RagCorpus 的显示名称。
CORPUS_DESCRIPTION：RagCorpus 的说明。

HTTP 方法和网址：

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

请求 JSON 正文：

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

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

成功的请求会返回 2xx 状态代码。 <0x0A

更新 RAG 语料库示例

您可以更新 RAG 语料库的显示名称、说明和部分向量数据库配置。不过，您无法更改以下不可变的参数：

向量数据库类型。例如，您无法将向量数据库从 Weaviate 更改为 Vertex AI Feature Store。
如果您使用的是托管式数据库选项，则无法更新向量数据库配置。

此示例演示了如何更新 RAG 语料库。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
CORPUS_ID：RAG 语料库的语料库 ID。
CORPUS_DISPLAY_NAME：RagCorpus 的显示名称。
CORPUS_DESCRIPTION：RagCorpus 的说明。
INDEX_NAME：Vector Search Index 的资源名称。格式：projects/{project}/locations/{location}/indexes/{index}
INDEX_ENDPOINT_NAME：Vector Search Index Endpoint 的资源名称。格式：projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}

HTTP 方法和网址：

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

请求 JSON 正文：

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

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

成功的请求会返回 2xx 状态代码。 <0x0A

列出 RAG 语料库示例

此示例展示了如何列出项目中的所有 RAG 语料库。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
PAGE_SIZE：标准列表页面大小。您可以通过更新 page_size 参数来调整每页返回的 RagCorpora 数量。
PAGE_TOKEN：标准列表页面词元。从之前的 VertexRagDataService.ListRagCorpora 调用中的 ListRagCorporaResponse.next_page_token 获取此令牌。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

成功的请求会返回 2xx 状态代码以及指定项目的 RagCorpora 列表。

获取 RAG 语料库示例

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RagCorpus 资源的 ID。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

如果请求成功，则会返回指定的 RagCorpus 资源。

删除 RAG 语料库示例

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RagCorpus 资源的 ID。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

如果请求成功，将返回 DeleteOperationMetadata 资源。

文件管理示例

本部分举例说明了如何使用 API 管理 RAG 文件。

上传 RAG 文件示例

REST

在运行该命令之前，请替换以下变量：

  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.

如需发送请求，请使用以下命令：

  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"

导入 RAG 文件示例

您可以从云端硬盘或 Cloud Storage 导入文件和文件夹。

response.skipped_rag_files_count 是指导入期间跳过的文件数量。如果满足以下条件，系统会跳过某个文件：

该文件已导入。
该文件未更改。
该文件的分块配置未更改。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RagCorpus 资源的 ID。
GCS_URIS：Cloud Storage 位置列表。示例：gs://my-bucket1, gs://my-bucket2。
CHUNK_SIZE（可选）：每个分块应具有的词元数。
CHUNK_OVERLAP（可选）：分块之间重叠的 token 数。

HTTP 方法和网址：

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

请求 JSON 正文：

{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": "GCS_URIS"
    },
    "rag_file_chunking_config": {
      "chunk_size": CHUNK_SIZE,
      "chunk_overlap": CHUNK_OVERLAP
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

如果请求成功，则返回 ImportRagFilesOperationMetadata 资源。 <0x0A

以下示例演示了如何从 Cloud Storage 导入文件。使用 max_embedding_requests_per_min 控制字段限制 RAG 引擎在 ImportRagFiles 索引编制过程中调用嵌入模型的速率。该字段的默认值为每分钟 1000 次调用。

  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

以下示例演示了如何从云端硬盘导入文件。使用 max_embedding_requests_per_min 控制字段限制 RAG 引擎在 ImportRagFiles 索引编制过程中调用嵌入模型的速率。该字段的默认值为每分钟 1000 次调用。

  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

列出 RAG 文件示例

此示例演示了如何列出 RAG 文件。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RagCorpus 资源的 ID。
PAGE_SIZE：标准列表页面大小。您可以通过更新 page_size 参数来调整每页返回的 RagFiles 数量。
PAGE_TOKEN：标准列表页面词元。从之前的 VertexRagDataService.ListRagFiles 调用中的 ListRagFilesResponse.next_page_token 获取此令牌。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

成功的请求会返回 2xx 状态代码以及指定 RAG_CORPUS_ID 的 RagFiles 列表。

获取 RAG 文件示例

此示例演示了如何获取 RAG 文件。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RagCorpus 资源的 ID。
RAG_FILE_ID：RagFile 资源的 ID。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

如果请求成功，则会返回指定的 RagFile 资源。

删除 RAG 文件示例

此示例演示了如何删除 RAG 文件。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RagCorpus 资源的 ID。
RAG_FILE_ID：RagFile 资源的 ID。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file_id}。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

如果请求成功，将返回 DeleteOperationMetadata 资源。

检索和预测示例

检索查询示例

当您提供查询时，RAG 中的检索组件会搜索其知识库，以查找相关信息。

REST

在使用任何请求数据之前，请先进行以下替换：

LOCATION：处理请求的区域。
PROJECT_ID：您的项目 ID。
RAG_CORPUS_RESOURCE：RagCorpus 资源的名称。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}。
VECTOR_DISTANCE_THRESHOLD：仅返回向量距离小于阈值的上下文。
TEXT：要获取相关上下文的查询文本。
SIMILARITY_TOP_K：要检索的热门上下文数量。

HTTP 方法和网址：

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

请求 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

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

成功的请求会返回 2xx 状态代码以及相关RagFiles 的列表。

生成示例

LLM 使用检索到的上下文生成有依据的回答。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
MODEL_ID：用于内容生成的 LLM 模型。示例：gemini-2.5-flash
GENERATION_METHOD：用于生成内容的 LLM 方法。选项：generateContent、streamGenerateContent
INPUT_PROMPT：发送到 LLM 用于生成内容的文本。尝试使用与上传的 RAG 文件相关的问题。
RAG_CORPUS_RESOURCE：RagCorpus 资源的名称。格式：projects/{project}/locations/{location}/ragCorpora/{rag_corpus}。
SIMILARITY_TOP_K（可选）：要检索的热门上下文数量。
VECTOR_DISTANCE_THRESHOLD（可选）：返回向量距离小于阈值的上下文。

HTTP 方法和网址：

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

请求 JSON 正文：

{
 "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
   }
  }
 }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

成功的请求会返回生成的内容以及引用。 <0

项目管理示例

层级是项目级设置，可在 RagEngineConfig 资源下找到，会影响使用 RagManagedDb 的 RAG 语料库。如需获取层级配置，请使用 GetRagEngineConfig。如需更新层级配置，请使用 UpdateRagEngineConfig。

如需详细了解如何管理层级配置，请参阅管理层级。

获取项目配置

以下示例演示了如何读取 RagEngineConfig：

控制台

在 Google Cloud 控制台中，前往 RAG 引擎页面。
前往 RAG 引擎
选择 RAG Engine 运行的区域。您的 RAG 语料库列表已更新。
点击配置 RAG 引擎。系统随即会显示配置 RAG 引擎窗格。您可以查看为 RAG Engine 选择的层级。
点击取消。

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/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig

更新项目配置

本部分提供了有关如何更改会员等级的示例。

将 RagEngineConfig 更新为“按用量付费”层级

以下示例演示了如何将 RagEngineConfig 设置为“缩放”层级：

控制台

在 Google Cloud 控制台中，前往 RAG 引擎页面。
前往 RAG 引擎
选择 RAG Engine 运行的区域。您的 RAG 语料库列表已更新。
点击配置 RAG 引擎。系统随即会显示配置 RAG 引擎窗格。
选择要运行 RAG 引擎的层级。
点击保存。

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/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'scaled': {}}}"

将您的 RagEngineConfig 更新为基本层级

以下示例演示了如何将 RagEngineConfig 设置为基本层级：

如果您在 RAG 语料库的 RagManagedDb 中有大量数据，则由于计算和存储容量不足，降级到基本层级可能会失败。

控制台

在 Google Cloud 控制台中，前往 RAG 引擎页面。
前往 RAG 引擎
选择 RAG Engine 运行的区域。您的 RAG 语料库列表已更新。
点击配置 RAG 引擎。系统随即会显示配置 RAG 引擎窗格。
选择要运行 RAG 引擎的层级。
点击保存。

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/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'basic': {}}}"

将 RagEngineConfig 更新为未配置层级

以下示例演示了如何将 RagEngineConfig 设置为“未配置”层级：

控制台

在 Google Cloud 控制台中，前往 RAG 引擎页面。
前往 RAG 引擎
选择 RAG Engine 运行的区域。您的 RAG 语料库列表已更新。
点击配置 RAG 引擎。系统随即会显示配置 RAG 引擎窗格。
点击删除 RAG 引擎。此时会显示一个确认对话框。
输入 delete，确认您即将删除 RAG 引擎中的数据，然后点击确认。
点击保存。

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/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'unprovisioned': {}}}"

后续步骤

如需详细了解支持的生成模型，请参阅支持 RAG 的生成式 AI 模型。
如需详细了解支持的嵌入模型，请参阅嵌入模型。
如需详细了解开放模型，请参阅开放模型。
如需详细了解 RAG 引擎，请参阅 RAG 引擎概览。

RAG Engine API 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

参数列表

语料库管理参数

文件管理参数

检索和预测参数

项目管理参数

语料库管理示例

创建 RAG 语料库示例

REST

curl

PowerShell

更新 RAG 语料库示例

REST

curl

PowerShell

列出 RAG 语料库示例

REST

curl

PowerShell

获取 RAG 语料库示例

REST

curl

PowerShell

删除 RAG 语料库示例

REST

curl

PowerShell

文件管理示例

上传 RAG 文件示例

REST

导入 RAG 文件示例

REST

curl

PowerShell

列出 RAG 文件示例

REST

curl

PowerShell

获取 RAG 文件示例

REST

curl

PowerShell

删除 RAG 文件示例

REST

curl

PowerShell

检索和预测示例

检索查询示例

REST

curl

PowerShell

生成示例

REST

curl

PowerShell

项目管理示例

获取项目配置

控制台

Python

REST

更新项目配置

控制台

Python

REST

控制台

Python

REST

控制台

Python

REST

后续步骤

RAG Engine API