注意：Vertex AI Search 即将更名为 Agent Search。我们正在更新内容，以反映新品牌。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

客户管理的加密密钥

默认情况下，Agent Search 会对静态客户内容进行加密。Agent Search 会为您处理加密，您无需执行任何其他操作。此选项称为“Google 默认加密”。

如果您想要控制加密密钥，则可以将 Cloud KMS 中客户管理的加密密钥 (CMEK) 与集成 CMEK 的服务（包括 Agent Search）搭配使用。使用 Cloud KMS 密钥时，您可以控制其保护级别、位置、轮替时间表、使用和访问权限以及加密边界。使用 Cloud KMS 还可让您跟踪密钥使用情况、查看审核日志以及控制密钥生命周期。这样您就可以在 Cloud KMS 中控制和管理用于保护数据的对称密钥加密密钥 (KEK)，而不是由 Google 拥有和管理这些密钥。

使用 CMEK 设置资源后，访问 Agent Search 资源的体验与使用 Google 默认加密功能类似。如需详细了解加密选项，请参阅客户管理的加密密钥 (CMEK)。

注册 CMEK 密钥后，Agent Search 会定期调用 Cloud KMS，以维护逻辑上隔离的数据实例。即使未将 CMEK 配置设置为默认配置，并且没有任何应用或数据连接器使用该配置，也会发生这种情况。使用量来自设置和运行实例，而不是来自数据量或访问实例的用户数量。请参阅 Cloud Key Management Service 价格。

Agent Search 中 Cloud KMS 的限制

以下限制适用于 Agent Search 中的 CMEK (Cloud KMS) 密钥：

已应用于应用或数据连接器的密钥无法更改，但可以轮替密钥版本。

您必须使用美国或欧盟多区域应用和数据存储区（而非全球）。如需详细了解多区域位置和数据驻留，包括使用非全球位置的相关限制，请参阅位置。

如果您需要为项目注册多个密钥，请与您的 Google 客户支持团队联系，申请增加 CMEK 配置的配额，并说明您需要多个密钥的原因。

将 EKM 或 HSM 与 CMEK 搭配使用时，存在以下限制：
- 用于加密和解密调用的 EKM 和 HSM 配额应至少有 1,000 QPM 的余量。如需了解如何查看配额，请参阅查看 Cloud KMS 配额。
- 如果使用 EKM，密钥必须在任何超过 30 秒的时间段内有 90% 以上的时间可访问。如果密钥在此时间段内无法访问，则可能会对编入索引和搜索新鲜度产生负面影响。
- 如果出现结算问题、持久性配额不足问题或持久性无法访问问题超过 12 小时，服务会自动关闭与 EKM 或 HSM 密钥相关的 CmekConfig。

在向项目注册密钥之前创建的应用或数据连接器无法受到该密钥的保护。

您无法为受密钥保护的应用和数据连接器调优搜索模型。

对于具有多个数据连接器的应用，如果一个数据连接器使用 CMEK 配置，则所有其他数据连接器也必须使用相同的 CMEK 配置。

如需使用代理搜索，您需要有企业版许可。如需了解企业版，请参阅高级功能简介。
第一方连接器不符合 CMEK 要求（适用于 BigQuery 和 Cloud Storage 的“一次性导入”和“定期”应用和数据连接器除外）。
医疗保健搜索应用和数据连接器以及第三方连接器与 CMEK 兼容。如需有关医疗保健应用和数据连接器的一般信息，请参阅创建医疗保健搜索应用或数据连接器。如需了解如何使第三方连接器与 CMEK 兼容，请参阅关于第三方连接器的单区域密钥。
密钥不适用于以下 RAG API，因为这些 API 不会存储静态内容：check grounding、grounded generation 和 ranking。

您可以使用 Terraform 为 Agent Search 配置 CMEK。请参阅 google_discovery_engine_cmek_config。

关于第三方连接器的单区域密钥

如果您使用第三方连接器，并希望使用自己的密钥来保护连接的数据，则除了多区域密钥之外，还需要创建三个补充的单区域密钥。有关创建密钥的命令，请参阅以下过程：注册 Cloud KMS 密钥。

需要为以下区域创建单个密钥：

多区域	单区域
`eu`	`europe-west1`	`europe-west4`	`europe-north1`
`us`	`us-east1`	`us-central1`	`us-west1`

准备工作

请确保您满足以下前提条件：

创建多区域对称 Cloud KMS 密钥。请参阅 Cloud KMS 文档中的创建密钥环和创建密钥。
- 将轮替周期设置为永不（手动轮替）。
- 在位置字段中，选择多区域，然后从下拉菜单中选择欧洲或美国。

已向 Discovery Engine 服务代理授予密钥的 CryptoKey Encrypter/Decrypter IAM 角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。服务代理账号的邮箱采用以下格式：service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com。如需查看如何向服务代理添加角色的一般说明，请参阅授予或撤销单个角色。
已向 Cloud Storage 服务代理授予密钥的 CryptoKey Encrypter/Decrypter IAM 角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。如果未授予此角色，则受 CMEK 保护的应用和数据连接器的数据导入会失败，因为 Discovery Engine 无法创建导入所需的受 CMEK 保护的临时存储桶和目录。
在完成本页面上的密钥注册说明之前，请勿创建任何您希望由密钥管理的应用或数据连接器。

应用已启用企业版功能。请参阅启用或停用企业版。

注册 Cloud KMS 密钥

如需使用 CMEK 加密数据，您必须注册多区域密钥。（可选）如果您的数据需要单区域密钥（例如，在使用第三方连接器时），您还需要注册单区域密钥。

准备工作

为此，您需要确保实现以下各项安排：

相应区域尚未受到密钥的保护。如果已通过 REST 命令为相应区域注册密钥，则以下过程会失败。如需确定代理搜索中是否存在某个位置的有效密钥，请参阅查看 Cloud KMS 密钥。

您拥有 Discovery Engine Admin (roles/discoveryengine.admin) 角色。

过程

REST

如需为 Agent Search 注册您自己的密钥，请按照以下步骤操作：

使用要注册的密钥调用 UpdateCmekConfig 方法。

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"kmsKey":"projects/KMS_PROJECT_ID/locations/KMS_LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"}' \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID?set_default=SET_DEFAULT"

替换以下内容：

KMS_PROJECT_ID：包含密钥的项目的 ID。项目编号无效。
KMS_LOCATION：密钥的多区域：us 或 europe。
KEY_RING：包含密钥的密钥环的名称。
KEY_NAME：密钥的名称。
PROJECT_ID：包含应用或数据连接器的项目的 ID。
LOCATION：应用或数据连接器的多区域：us 或 eu。
CMEK_CONFIG_ID：为 CmekConfig 资源设置唯一 ID，例如 default_cmek_config。
SET_DEFAULT：设置为 true 可将该密钥用作在多区域中创建的后续应用和数据连接器的默认密钥。

重要提示：需要使用 SET_DEFAULT 才能在后续资源上自动应用 CmekConfig。

命令和结果示例

$ curl -X PATCH
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-d '{"kmsKey":"projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"}'
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config?set_default=true"

{
 "name": "projects/my-ai-app-project-123/locations/us/operations/update-cmek-config-56789",
 "metadata": {
  "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateCmekConfigMetadata"
 }
}

可选：记录该方法返回的 name 值，然后按照获取长时间运行的操作的详细信息中的说明查看操作何时完成。

注册密钥通常需要几分钟的时间。

操作完成后，相应多区域中的新应用和数据连接器将受到该密钥的保护。如需大致了解如何创建应用，请参阅应用和数据存储区简介。
创建应用。如需了解相关说明，请参阅创建应用和应用和数据存储区简介。

控制台

过程

如需为 Agent Search 注册您自己的密钥，请按照以下步骤操作：

在 Google Cloud 控制台中，前往 AI Applications 页面。

AI Applications
点击设置，然后选择 CMEK 标签页。
点击 us 或 eu 位置对应的添加密钥。

点击“添加密钥”。
1. 点击选择 Cloud KMS 密钥下拉菜单，然后选择相应密钥。
  - 如果密钥位于其他项目中，请点击切换项目，点击您的项目名称，输入您创建的密钥的名称，然后选择该密钥。
  - 如果您知道密钥的资源名称，请点击手动输入，粘贴密钥资源名称，然后点击保存。
2. 依次点击确定 > 保存。
创建应用。如需查看相关说明，请参阅应用和数据存储区简介。

此操作会注册密钥，并创建一个名为 default_cmek_config 的 CmekResource。

注入的数据可能需要过几个小时才会显示在搜索结果中。

查看 Cloud KMS 密钥

如需查看代理搜索的注册密钥，请执行以下操作之一：

如果您有 CmekConfig 资源名称，请调用 GetCmekConfig 方法：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"

替换以下内容：

LOCATION：应用或数据连接器的多区域：us 或 eu。
PROJECT_ID：包含数据的项目的 ID。
CMEK_CONFIG_ID：CmekConfig 资源的 ID。如果您使用控制台注册了密钥，则 ID 为 default_cmek_config。

curl 调用和响应的示例如下所示：

$ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config"

{
  "name":
  "projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config",
  "kmsKey": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
  "state": "ACTIVE"
  "isDefault": true
}

如果您没有 CmekConfig 资源名称，请调用 ListCmekConfigs 方法：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs"

替换以下内容：

LOCATION：应用或数据连接器的多区域：us 或 eu。
PROJECT_ID：包含数据的项目的 ID。

curl 调用和响应的示例如下所示：

$ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs"

{
  "cmek_configs": [
    {
      "name":
      "projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config",
      "kmsKey": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
      "state": "ACTIVE"
      "isDefault": true
    }
  ]
}

取消注册 Cloud KMS 密钥

如需从 Agent Search 中取消注册密钥，请按照以下步骤操作：

使用您要取消注册的 CmekConfig 资源名称调用 DeleteCmekConfig 方法。

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"

替换以下内容：

LOCATION：应用或数据连接器的多区域：us 或 eu。
PROJECT_ID：包含应用或数据连接器的项目的 ID。
CMEK_CONFIG_ID：CmekConfig 资源的 ID。如果您使用控制台注册了密钥，则 ID 为 default_cmek_config。

curl 调用和响应的示例如下所示：

$ curl -X DELETE
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config"
 
{
 "name": "projects/my-ai-app-project-123/locations/us/operations/delete-cmek-config-56789",
 "metadata": {
  "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.DeleteCmekConfigMetadata"
 }
}

可选：记录该方法返回的 name 值，然后按照获取有关长时间运行的操作的详细信息中的说明查看操作何时完成。

删除 CmekConfig 是一项长时间运行的操作，可能需要几天时间才能完成。这是因为在移除 CmekConfig 之前，系统会先完全取消配置底层加密资源。

验证应用或数据连接器是否受密钥保护

在注册密钥后创建的应用和数据连接器会受到该密钥的保护。如果您想确认特定应用或数据连接器是否受密钥保护，请按照以下步骤操作：

使用 Google Cloud 控制台进行验证

您可以使用 Google Cloud 控制台检查是否已设置默认 CMEK 配置。

在 Google Cloud 控制台中，前往 AI Applications 页面。
点击设置，然后选择 CMEK 标签页。
检查您的位置信息的配置状态是否显示为有效，并显示您注册的密钥。

使用 CLI / API 进行验证

如需验证数据存储区，请执行以下操作：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID"

替换以下内容：

LOCATION：项目的多区域：us 或 eu。
PROJECT_ID：包含应用或数据连接器的项目的 ID。
DATA_STORE_ID：与您的应用或数据连接器关联的数据存储区的 ID。

curl 调用示例如下所示：

curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-H "x-goog-user-project: my-ai-app-project-123"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/dataStores/my-data-store-1"

如需验证应用，请执行以下操作：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/ENGINE_ID"

替换以下内容：

LOCATION：项目的多区域：us 或 eu。
PROJECT_ID：包含应用的项目的 ID。
ENGINE_ID：应用的 ID。

curl 调用示例如下所示：

curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-H "x-goog-user-project: my-ai-app-project-123"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/engines/my-app"

查看命令的输出：如果输出中包含 cmekConfig 字段，并且 kmsKey 字段显示的是您注册的密钥，则表示相应应用或数据连接器受该密钥保护。

数据存储区的响应示例如下所示：

{
 "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1",
 "displayName": "my-data-store-1",
 "industryVertical": "GENERIC",
 "createTime": "2023-09-05T21:20:21.520552Z",
 "solutionTypes": [
   "SOLUTION_TYPE_SEARCH"
 ],
 "defaultSchemaId": "default_schema",
 "cmekConfig": {
   "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/default_cmek_config",
   "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
 }
}

应用的示例回答如下所示：

{
  "name": "projects/969795412903/locations/us/collections/default_collection/engines/my-app",
  "displayName": "my-app",
  "dataStoreIds": [
    "my-data-store-1"
  ],
  "solutionType": "SOLUTION_TYPE_SEARCH",
  "searchEngineConfig": {
    "searchTier": "SEARCH_TIER_STANDARD"
  },
  "industryVertical": "GENERIC",
  "appType": "APP_TYPE_INTRANET",
  "cmekConfig": {
   "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/default_cmek_config",
   "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
 }
}

受 Cloud KMS 密钥保护的其他数据

除了应用和数据连接器中的数据外，您的密钥还可以保护 Agent Search 存储的其他类型的应用自有核心信息，例如在搜索并跟进期间生成的会话数据。如果应用和数据连接器受 CMEK 保护，则此类核心信息也会受到 CMEK 保护。

虽然您无法运行特定命令来验证会话是否受到保护，但可以验证应用是否受到保护。针对应用运行验证应用或数据连接器是否受密钥保护命令，以查看 cmekConfig 资源中的密钥。这样，您就知道会话数据受到了保护。

轮替 Cloud KMS 密钥

轮替密钥时，您会创建新的密钥版本，并将新版本设置为主版本。在停用原始版本的密钥之前，请先启用该密钥一段时间。这样，可能正在使用旧密钥的任何长时间运行的操作都有时间完成。

以下流程简要介绍了轮替代理搜索应用或数据连接器的密钥的步骤。如需了解有关轮替密钥的一般信息，请参阅 Cloud KMS 指南中的密钥轮替。

重要提示：请勿轮换与建议或任何需要分析的应用相关联的应用或数据连接器的密钥，也不要轮换用于第三方连接器的单区域密钥。请参阅代理搜索中的 Cloud KMS 限制。

重新注册密钥。为此，请重复注册 Cloud KMS 密钥的第 1 步。

注意：重新注册比注册快得多。您无需将重新注册监控为长时间运行的操作。
请参阅 Cloud KMS 指南的管理密钥部分中的说明，执行以下操作：
1. 创建新密钥版本，启用该版本并将其设为主密钥。
  
  将新密钥设为主密钥后，应用或数据连接器中的文档会使用新密钥重新加密，并且后续添加到应用或数据连接器中的所有文档都会使用新密钥加密。
2. 保持旧密钥版本处于启用状态。
3. 大约一周后，停用旧密钥版本，并确保一切正常运行。
4. 在稍后的某个日期，当您确定停用旧密钥版本未造成任何问题时，可以销毁旧密钥版本。

如果 Cloud KMS 密钥已停用或已撤销

如果密钥已停用或密钥的权限已撤消，则应用或数据连接器会在 15 分钟内停止注入数据和传送数据。您可以在 30 天内重新启用密钥，以在 CMEK 配置过期且所有关联数据被永久删除之前恢复操作。不过，重新启用密钥或恢复权限需要很长时间。应用或数据连接器最长可能需要 24 小时才能继续传送数据。

因此，除非必要，否则请勿停用密钥。停用和启用应用或数据连接器上的密钥是一项耗时的操作。例如，如果反复在停用和启用之间切换密钥，应用或数据连接器将需要很长时间才会达到受保护状态。停用密钥，之后立即重新启用密钥可能会导致停机数天，因为系统会先从应用或数据连接器停用密钥，然后再重新启用密钥。

问题排查：KMS 密钥项目未找到错误

症状：当您尝试使用 KMS 密钥创建应用或数据连接器时，收到类似于以下内容的错误：

KMS key projects/[...] not found for location: [...] and project number: [...]

问题：此错误消息可能具有误导性。这并不一定意味着密钥不存在。而是可能表示 KMS 密钥尚未在指定位置进行注册以用于 Agent Search。

解决方案：如需解决此问题，请按照注册 Cloud KMS 密钥中的步骤注册密钥。注册完成后，您可以创建受该密钥保护的应用或数据连接器。

客户管理的加密密钥 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Agent Search 中 Cloud KMS 的限制

关于第三方连接器的单区域密钥

准备工作

注册 Cloud KMS 密钥

准备工作

过程

REST

命令和结果示例

控制台

过程

查看 Cloud KMS 密钥

取消注册 Cloud KMS 密钥

验证应用或数据连接器是否受密钥保护

使用 Google Cloud 控制台进行验证

使用 CLI / API 进行验证

受 Cloud KMS 密钥保护的其他数据

轮替 Cloud KMS 密钥

如果 Cloud KMS 密钥已停用或已撤销

问题排查：KMS 密钥项目未找到错误

客户管理的加密密钥