Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

在 Gemini Enterprise Agent Platform 上将 RagManagedDb 与 RAG 引擎搭配使用

本页面介绍了 Gemini Enterprise Agent Platform 上的 RAG 引擎如何使用 RagManagedDb，这是一种适合企业的向量数据库，用于存储和管理文档的向量表示法。然后，向量数据库会根据文档与给定查询的语义相似度检索相关文档。

此外，本页面还介绍了如何实现 CMEK。

管理检索策略

RagManagedDb 提供以下检索策略来支持您的 RAG 应用场景：

检索策略	说明
k 最近邻 (KNN)（默认）	通过比较 RAG 语料库中的所有数据点来查找确切的最近邻。如果您在创建您的 RAG 语料库期间未指定策略，系统会默认使用 KNN 检索策略。	在检索期间验证完美召回率 (1.0)。非常适合对召回率敏感的应用。非常适合存储少于 10,000 个 RAG 文件的中小型 RAG 语料库。需要搜索每个数据点，因此，延迟时间会随着语料库中 RAG 文件数量的增加而增加。
近似最近邻 (ANN)	使用近似技术来查找相似的邻居，速度比 KNN 技术更快。	显著缩短了大型 RAG 语料库的查询延迟时间。由于使用了近似技术，召回率略有降低。当您拥有大型 RAG 语料库（大约超过 10,000 个 RAG 文件）时，此方法非常有效。您可以接受的召回率损失程度取决于具体应用场景，但在大多数大规模应用场景中，牺牲一点召回率来换取查询性能的提升是可接受的权衡。

使用 KNN `RagManagedDb` 创建 RAG 语料库

此代码示例演示了如何使用 KNN RagManagedDb 创建 RAG 语料库。

Python

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

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

vector_db = rag.RagManagedDb(retrieval_strategy=rag.KNN())
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

执行以下变量替换操作：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
CORPUS_DISPLAY_NAME：RAG 语料库的显示名称。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME

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}"\"',
      "vector_db_config": {
        "ragManagedDb": {
          "knn": {}
        }
      }
    }'

使用 ANN `RagManagedDb` 创建 RAG 语料库

为了提供 ANN 功能，RagManagedDb 使用基于树的结构对数据进行分区并帮助加快搜索速度。为了实现最佳召回率和延迟时间，应通过实验配置此树的结构，以适应您的数据大小和分布。RagManagedDb 可让您配置树的 tree_depth 和 leaf_count。

tree_depth 确定树中的层数或级别数。请遵循以下原则：

如果 RAG 语料库中大约有 10,000 个 RAG 文件，请将值设置为 2。
如果 RAG 文件数量超过此值，请将此值设置为 3。
如果未指定 tree_depth，RAG 引擎会为此参数分配默认值 2。

leaf_count 确定基于树的结构中的叶节点数量。每个叶节点都包含密切相关的向量组以及相应的形心。请遵循以下原则：

建议值为 10 * sqrt(num of RAG files in your RAG corpus)。
如果未指定，RAG 引擎会为此参数分配默认值 500。

Python

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
TREE_DEPTH = YOUR_TREE_DEPTH # Optional: Acceptable values are 2 or 3. Default is 2.
LEAF_COUNT = YOUR_LEAF_COUNT # Optional: Default is 500.

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

ann_config = rag.ANN(tree_depth=TREE_DEPTH, leaf_count=LEAF_COUNT)
vector_db = rag.RagManagedDb(retrieval_strategy=ann_config)
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

执行以下变量替换操作：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
CORPUS_DISPLAY_NAME：RAG 语料库的显示名称。
TREE_DEPTH：您的树深度。
LEAF_COUNT：您的叶数。

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME
TREE_DEPTH=TREE_DEPTH
LEAF_COUNT=LEAF_COUNT

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}"\"',
      "vector_db_config": {
        "ragManagedDb": {
          "ann": {
            "tree_depth": '"${TREE_DEPTH}"',
            "leaf_count": '"${LEAF_COUNT}"'
          }
        }
      }
    }'

将数据导入到 ANN `RagManagedDb` 中

您可以使用 ImportRagFiles API 或 UploadRagFile API 将数据导入到 ANN RagManagedDb 中。不过，与 KNN 检索策略不同，ANN 方法要求至少重建一次底层基于树的索引，并且可以选择在导入大量数据后重建索引，以实现最佳召回率。如需让 RAG 引擎重建您的 ANN 索引，请在 ImportRagFiles API 请求中将 rebuild_ann_index 设置为 true。

以下内容非常重要：

查询 RAG 语料库前，必须先重建一次 ANN 索引。
在每个位置，单个项目仅支持一个并发索引重建。

如需将本地文件上传到 RAG 语料库，请参阅上传 RAG 文件。如需将数据导入到 RAG 语料库并触发 ANN 索引重建，请参阅以下代码示例，该示例演示了如何从 Cloud Storage 导入数据。如需了解受支持的数据源，请参阅 RAG 支持的数据源。

Python

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
CORPUS_ID = YOUR_CORPUS_ID
PATHS = ["gs://my_bucket/my_files_dir"]
REBUILD_ANN_INDEX = REBUILD_ANN_INDEX # Choose true or false.

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

corpus_name = f"projects/{PROJECT_ID}/locations/{LOCATION}/ragCorpora/{CORPUS_ID}"
# This is a non blocking call.
response = await rag.import_files_async(
    corpus_name=corpus_name,
    paths=PATHS,
    rebuild_ann_index=REBUILD_ANN_INDEX
)

# Wait for the import to complete.
await response.result()

REST

GCS_URI=GCS_URI
REBUILD_ANN_INDEX=<true/false>

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/${CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URI}"\"',
      },
    "rebuild_ann_index": '${REBUILD_ANN_INDEX}'
  }
}'

管理加密

RAG 引擎提供了强大的选项来管理静态数据的加密方式。默认情况下，RagManagedDb 中的所有用户数据均使用 Google-owned and Google-managed encryption key进行加密，这是默认设置。此默认设置有助于您验证数据是否安全，而无需进行任何特定配置。

如果您需要更好地控制用于加密的密钥，RAG 引擎支持客户管理的加密密钥 (CMEK)。借助 CMEK，您可以使用在 Cloud Key Management Service (KMS) 中管理的加密密钥来保护 RAG 语料库数据。

如需了解 RAG 语料库的 CMEK 限制，请参阅 CMEK limitations for RAG Engine on Gemini Enterprise Agent Platform。

设置 KMS 密钥并授予权限

如需创建使用 CMEK 加密的 RAG 语料库，您必须先在 Google Cloud KMS 中设置加密密钥，并向 RAG 引擎服务帐号授予使用此密钥所需的权限。

前提条件

如需执行以下设置步骤，请验证您的用户账号在您打算在其中创建 KMS 密钥和 RAG 语料库的项目中是否拥有适当的 Identity and Access Management (IAM) 权限 Google Cloud 。通常，需要 Cloud KMS Admin 角色 (roles/cloudkms.admin) 等角色。

启用 API

如需启用 Cloud Key Management Service API，请执行以下操作：

前往 Google Cloud 控制台。
选择您要用于管理密钥的项目，然后创建 RAG 语料库。
在搜索栏中，输入“密钥管理”，然后选择“密钥管理”服务。
如果 API 未启用，请点击启用。您可能需要等待几分钟，API 才能完全预配。

创建 KMS 密钥环和密钥

如需创建密钥环，请执行以下操作：

在密钥管理 部分中，点击创建密钥环 。

输入以下内容：
- 密钥环名称：输入密钥环的唯一名称，例如 rag-engine-cmek-keys。
- 位置类型：选择“区域”。Cloud Key Management Service 密钥环必须与您在使用 CMEK 加密 RAG 语料库时使用的 RAG 引擎端点位于同一区域。
- 位置：选择所选区域，例如 us-central1。此区域最好与 RAG 引擎资源所在的区域一致。
点击创建。

如需在密钥环中创建密钥，请执行以下操作：

创建密钥环后，系统会提示您，或者您可以前往创建密钥 。

输入以下内容：
- 密钥名称：输入密钥的唯一名称，例如 my-rag-corpus-key。
- 保护级别：选择保护级别（软件或HSM）。如果您需要硬件支持的密钥，请选择 HSM。 HSM
- 用途：选择对称加密/解密。这是 CMEK 的必需项。
- 密钥材料来源：选择生成的密钥。
- 轮替周期：可选。推荐。根据组织的安全政策（例如每 90 天）配置密钥轮替时间表。
点击创建。

如需复制密钥资源名称，请执行以下操作：

创建密钥后，前往其详细信息页面。
找到资源名称。格式为 projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1。

**重要提示**：对于 RAG 语料库中的 EncryptionSpec，您必须使用不带版本号的密钥资源名称。
复制资源名称，并移除 /cryptoKeyVersions/VERSION_NUMBER 部分。格式正确的资源名称为 projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME。

向 RAG 引擎服务代理授予权限

如需让 RAG 引擎使用 KMS 密钥加密和解密数据，其服务代理需要对该特定密钥拥有适当的权限。

如需识别 RAG 引擎服务代理，请执行以下操作：

前往项目的控制台中的 IAM 和管理 > IAM 页面。 Google Cloud
在“Identity and Access Management”页面上，勾选包括 Google 提供的角色授权 复选框。
在主账号列表的过滤条件或搜索栏中，搜索 RAG 引擎服务代理。它遵循 service-YOUR_PROJECT_NUMBER@gcp-sa-vertex-rag.模式。

将 YOUR_PROJECT_NUMBER 替换为您的 Google Cloud 项目编号。

如果您的 RAG 引擎服务代理尚未存在，请执行以下操作以触发服务代理创建：

启用 Resource Manager API。

在 Cloud Shell 或命令行中执行以下命令：

gcloud beta services identity create --service=aiplatform.googleapis.com \
    --projects=PROJECT_ID

或者，发送 REST API 调用：

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json; charset=utf-8" -d "" "https://serviceusage.googleapis.com/v1beta1/projects/PROJECT_ID/services/aiplatform.googleapis.com:generateServiceIdentity"

验证 RAG 引擎服务代理是否已创建。

如需授予 KMS 密钥的权限，请执行以下操作：

返回 Google Cloud 控制台中的密钥管理服务。
选择包含您创建的密钥的密钥环。
选择您创建的特定密钥。
在密钥的详细信息页面中，前往权限标签页。
点击添加主账号 。
在新主账号 字段中，输入 RAG 引擎服务代理的电子邮件地址。
在选择角色 下拉列表中，选择 Cloud KMS CryptoKey Encrypter/Decrypter 角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。此角色会向服务代理授予使用密钥执行加密和解密操作所需的权限。
点击保存。

创建具有客户管理的加密功能的 RAG 语料库

此代码示例演示了如何创建使用客户管理的加密密钥 (CMEK) 加密的 RAG 语料库。

替换以下代码示例中的变量：

Python

import vertexai
from google.cloud import aiplatform
from vertexai import rag
from google.cloud.aiplatform_v1.types.encryption_spec import EncryptionSpec

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

vertexai.init(project=PROJECT_ID)

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, encryption_spec=EncryptionSpec(kms_key_name=KMS_KEY_NAME))

REST

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

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

配额

将 CMEK 与 Gemini Enterprise Agent Platform 服务（例如 Gemini Enterprise Agent Platform 上的 RAG 引擎）搭配使用时，每个项目在每个区域中可使用的唯一 Cloud KMS 密钥数量存在配额。此配额由指标 aiplatform.googleapis.com/in_use_customer_managed_encryption_keys 跟踪。

每次您使用新的唯一 KMS 密钥在项目和区域中创建资源（例如 RAG 语料库）时，KMS 密钥都会消耗此配额的一个单位。即使删除了使用该特定密钥的资源，此配额单位也不会释放。

如果您需要的唯一密钥数量超过当前限制，则必须针对所选区域为 aiplatform.googleapis.com/in_use_customer_managed_encryption_keys 申请增加配额。

如需详细了解如何申请增加配额，请参阅在控制台中查看和修改配额 Google Cloud 。

后续步骤

如需详细了解 RagManagedDb，请参阅部署模式。
如需从 Google 云端硬盘或 Cloud Storage 导入文件和文件夹，请参阅导入 RAG 文件示例。
如需列出 RAG 文件，请参阅列出 RAG 文件示例。

在 Gemini Enterprise Agent Platform 上将 RagManagedDb 与 RAG 引擎搭配使用 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

管理检索策略

使用 KNN RagManagedDb 创建 RAG 语料库

Python

REST

使用 ANN RagManagedDb 创建 RAG 语料库

Python

REST

将数据导入到 ANN RagManagedDb 中

Python

REST

管理加密

设置 KMS 密钥并授予权限

前提条件

启用 API

创建 KMS 密钥环和密钥

向 RAG 引擎服务代理授予权限

创建具有客户管理的加密功能的 RAG 语料库

Python

REST

配额

后续步骤

在 Gemini Enterprise Agent Platform 上将 RagManagedDb 与 RAG 引擎搭配使用

使用 KNN `RagManagedDb` 创建 RAG 语料库

使用 ANN `RagManagedDb` 创建 RAG 语料库

将数据导入到 ANN `RagManagedDb` 中