此页面由 Cloud Translation API 翻译。

将 RagManagedDb 与 Vertex AI RAG Engine 搭配使用

本页面介绍了 Vertex AI 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 的 RAG 语料库 `RagManagedDb`

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

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Vertex AI 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 的 RAG 语料库 `RagManagedDb`

为了提供 ANN 功能，RagManagedDb 使用基于树的结构来划分数据，从而加快搜索速度。为了实现最佳召回率和延迟时间，应通过实验配置此树的结构，使其适合您的数据大小和分布。RagManagedDb 可用于配置树的 tree_depth 和 leaf_count。

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

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

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

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

Python

from vertexai 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 Vertex AI 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 方法要求至少重建一次底层基于树的索引，并且可以选择在导入大量数据后重建索引，以实现最佳召回率。如需让 Vertex AI RAG 引擎重建 ANN 索引，请在 ImportRagFiles API 请求中将 rebuild_ann_index 设置为 true。

以下内容非常重要：

在查询 RAG 语料库之前，您必须至少重建一次 ANN 索引。
每个位置中的项目仅支持一次并发索引重建。

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

Python

from vertexai 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 Vertex AI 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}'
  }
}'

管理加密

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

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

如需了解 RAG 语料库的 CMEK 限制，请参阅 Vertex AI RAG Engine 的 CMEK 限制。

设置 KMS 密钥并授予权限

在创建使用 CMEK 加密的 RAG 语料库之前，您必须在 Google Cloud KMS 中设置加密密钥，并向 Vertex AI RAG Engine 服务账号授予使用此密钥的必要权限。

前提条件

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

启用 API

如需启用 Cloud KMS API，请执行以下操作：

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

创建 KMS 密钥环和密钥

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

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

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

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

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

输入以下内容：
- 密钥名称：为密钥输入一个唯一名称，例如 my-rag-corpus-key。
- 保护级别：选择保护级别（软件或 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。

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

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

如需确定 Vertex AI RAG Engine 服务代理，请执行以下操作：

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

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

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

启用 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"

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

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

返回 Google Cloud 控制台中的 Key Management 服务。
选择包含您创建的密钥的密钥环。
选择您创建的特定密钥。
在密钥的详细信息页面中，前往权限标签页。
点击添加主账号。
在新主账号字段中，输入 Vertex AI RAG Engine 服务代理的电子邮件地址。
在选择角色下拉菜单中，选择 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 与 Vertex AI 服务（例如 Vertex AI 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，请参阅了解 RagManagedDb。
如需从 Google 云端硬盘或 Cloud Storage 导入文件和文件夹，请参阅导入 RAG 文件示例。
如需列出 RAG 文件，请参阅列出 RAG 文件示例。

将 RagManagedDb 与 Vertex AI RAG Engine 搭配使用 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

管理检索策略

创建具有 KNN 的 RAG 语料库 RagManagedDb

Python

REST

创建具有 ANN 的 RAG 语料库 RagManagedDb

Python

REST

将数据导入到 ANN RagManagedDb

Python

REST

管理加密

设置 KMS 密钥并授予权限

前提条件

启用 API

创建 KMS 密钥环和密钥

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

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

Python

REST

配额

后续步骤

将 RagManagedDb 与 Vertex AI RAG Engine 搭配使用

创建具有 KNN 的 RAG 语料库 `RagManagedDb`

创建具有 ANN 的 RAG 语料库 `RagManagedDb`

将数据导入到 ANN `RagManagedDb`