如何将编码智能体迁移至 Amazon Bedrock Managed Knowledge Base

使用 Amazon Bedrock 上的客户自主管理的知识库时，你需要自行预置和扩展向量存储、调整嵌入模型和索引设置，并为每个新数据源规划容量。AWS Agent Toolkit 中的迁移指南可帮助你迁移到 Amazon Bedrock 托管式知识库。托管式知识库会接手这些工作，并新增检索功能，同时你的团队仍然掌控内容以及使用内容的应用程序。

迁移生产环境的知识库意味着你的团队需要梳理其配置、创建替代方案、摄取内容、更新应用程序的检索调用，并在切换流量之前验证检索结果。为此，我们在 Agent Toolkit for AWS 的 amazon-bedrock 技能中添加了知识库迁移指南。该指南为你的编程智能体提供了与你共同规划迁移所需的上下文，首先进行只读发现，并生成一份供你逐行审查的计划。经你批准后，智能体会在原有知识库旁创建新知识库及其数据源，或者为你的流水线编写迁移后的基础设施即代码（IaC）模板。内容摄取和更新应用程序的 Retrieve 调用仍由你负责，你的智能体可以逐步引导你完成这两项工作。

在本文中，我们将说明为什么推荐进行这一迁移以及迁移指南的工作原理，介绍先决条件，安装技能，规划迁移，更新应用程序的检索调用，并在切换前验证检索结果。

为什么要迁移到托管式知识库

我们推荐托管式知识库，因为它在易用性、检索准确性和成本之间取得了平衡。

由 AWS 运行存储

使用托管式知识库，Amazon Bedrock 会处理内容摄取、存储、索引和检索，并且存储会随内容的增长自动扩展。混合搜索（结合关键词与语义匹配）始终开启，无需配置索引。知识库包含托管式嵌入模型、托管式重排序模型，以及针对多模态文件类型的内置解析器。

你仍然可以在创建知识库时自带 Amazon Bedrock 嵌入模型。在每次检索请求中，你可以选择托管式重排序器、某个 Amazon Bedrock 重排序模型，或不使用重排序。托管式重排序器需要使用托管式嵌入模型。

内置功能

托管式知识库包含你原本需要自行构建的功能：

• 原生连接器可直接从 Amazon Simple Storage Service（Amazon S3）、Microsoft SharePoint 和 Atlassian Confluence 等来源摄取内容。有关当前列表，请参阅支持的连接器。首次完整同步后，后续同步只会获取变更内容，可按需进行或按计划进行。托管式知识库包含删除保护机制，有助于防止意外批量删除已索引的内容。
• 访问控制列表（ACL）感知会在摄取内容的同时摄取文档权限，因此检索只会返回登录用户有权访问的内容。对于支持该功能的连接器（如 Microsoft SharePoint 和 Atlassian Confluence），还会针对源系统进行实时检查，以捕捉自上次同步以来的权限变更。ACL 感知不会对用户进行身份验证，因此你的应用程序必须验证并传递用户的身份。
• 智能体检索可以回答单次搜索无法回答的问题，它能够处理多部分问题并进行迭代式检索。它还可以在单个请求中搜索多个知识库。
• 与 AgentCore Gateway 集成，这是 Amazon Bedrock AgentCore 的一项功能，可将您的知识库公开为一个目标。任何支持模型上下文协议（MCP）的客户端都可以查询该知识库，网关负责处理身份验证。
• 基于资源的策略允许其他 AWS 账户中的应用程序使用某个团队的知识库。将每项策略的范围限定为调用知识库的特定角色，并仅授予它们所使用的操作，例如 bedrock:Retrieve。

智能体检索、AgentCore Gateway 集成和基于资源的策略在客户自管知识库上不可用。有关托管知识库可用的 AWS 区域，以及 AWS GovCloud（美国西部）不支持的功能，请参阅 支持的 AWS 区域。

更高的配额

截至撰写本文时，更高的默认配额改变了您组织内容的方式。每个知识库可拥有 200 个数据源，您可以在一个知识库中对相关内容进行分组。每个账户、每个区域可拥有 10,000 个知识库，每个团队或产品线都可以使用单独的知识库。

有关当前数值，请参阅 Amazon Bedrock 端点和配额以及 托管知识库的服务配额。

为您存储和检索的内容付费

成本是团队在考虑此举时权衡的三个因素之一，另外两个因素是可定制性以及对向量存储的直接控制。在客户自管知识库上，您需要自行选择、配置、扩展和更新向量与文本存储，并为您选择的基础设施单独付费。在托管知识库上，这些环节都是服务的一部分，存储和检索直接按用量计费。

定价模式也可能不同。使用客户自管知识库时，存储和检索费用取决于您选择的向量存储。有些存储按预置容量或最低容量收费，而另一些存储（如 Amazon S3 Vectors，Amazon S3 的一项功能）只按实际使用量收费。托管知识库按您存储和检索的内容定价，因此成本与实际使用量保持一致。基于用量的定价非常适合利用率较低的企业问答、政策和支持类知识库。有关当前费率，请参阅 Amazon Bedrock 定价。有关客户自管知识库可用的解析器及其计费方式，请参阅 数据源的解析选项。

费率只是总拥有成本的一部分。在客户自管的知识库上，你的团队需要将每个阶段作为独立资源进行预置、扩展和运维。托管知识库（Managed Knowledge Base）将它们整合为一个资源，默认带有嵌入模型、基础模型和重排序器，并默认按知识库设置速率限制。你只需管理内容以及使用内容的应用程序，而由 Amazon Bedrock 负责运维托管存储、嵌入模型、基础模型和重排序器

解决方案概述

客户自管的知识库使用 VECTOR 类型，并使用你配置的向量存储。托管知识库使用 MANAGED 类型。迁移指南会引导你的智能体在原有知识库旁边创建一个新的 MANAGED 知识库，且在迁移期间不修改或删除原有知识库。按照指南的映射，你的智能体会编写一份计划，列出哪些设置保持不变、哪些由托管版以不同方式处理，以及你需要进行哪些应用侧更改。如图 1 所示，在团队摄取内容、验证并切换期间，原有知识库会持续响应每一个请求

图 1：在原有知识库旁边创建托管知识库或迁移后的模板，然后在切换前进行验证

迁移指南的工作方式

该指南将规划与实施分开。在探索（Explore）模式下，你的智能体会回答有关托管知识库的问题，并可通过只读调用检查你的配置，从而帮助你估算工作量。在迁移（Migration）模式下，指南会带领你的智能体完成以下检查点：

1. 介绍与选择。你的智能体会说明它将涉及和不涉及的内容。选择模式（实时知识库或 IaC 源）以及普通（默认）或技术性的解释风格
2. 识别。确认账户和 AWS 区域。你的智能体会标记权限过宽的凭证，询问你是否需要成本分析，并创建输出目录
3. 发现。你的智能体通过只读调用读取知识库和数据源，或读取你的模板文件
4. 规划。审查计划和应用侧更改。默认情况下，你的智能体会在此停止
5. 实施（如有要求）。对于实时构建，批准预置脚本的确切预览；若脚本有更改，需再次批准。对于 IaC，你的智能体会编写迁移后的模板，并报告运行了哪些架构检查
6. 交接。审查生成的成果以及团队剩余的步骤

如图 2 所示，资源创建与摄取和切换保持分离。

图 2：迁移检查点。实现是可选的，由你的团队执行摄取和切换。

查看配置映射

该指南将每个设置进行映射，以便在托管类型使用不同配置时保留你的数据源、筛选器和分块行为。该计划会对每个设置进行分类：

• 1:1。新知识库使用相同的设置。
• 已调整。托管版使用不同的设置来实现相同结果，计划会应用相应的替换。
• 受阻。目前没有托管路径。你的智能体会在构建中排除该知识库，解释原因，并指引你联系 AWS Support。同一运行中的其他知识库可以继续进行。

在验证时，请对你自己的内容比较分块效果。

查看权限和生成的更改

发现、规划以及整个 IaC 路径只需要只读凭证。对于实际构建，该指南会指示你的智能体提出一个范围受限的策略，明确拒绝对原始知识库的更改，并且绝不请求管理员或完全访问权限。它还会指示你的智能体仅更改其创建的资源、通过 Amazon Resource Name (ARN) 引用密钥，并忽略其读取的数据中包含的指令。在你批准运行之前，请审查生成的 AWS Identity and Access Management (IAM) 策略和预配脚本。构建完成后，在保留 90 天管理事件的 AWS CloudTrail 事件历史记录中检查智能体的操作。每个事件都会记录 API 调用，例如 CreateKnowledgeBase，以及执行该调用的身份。

对于可选的成本分析，你的智能体会使用当前 AWS 价格，将当前支出与托管知识库的估算值进行比较。它使用只读输入，包括 Amazon CloudWatch 指标、Amazon S3 对象大小和 AWS Cost Explorer。每个数字都标记为实测值、你提供的值或估算值。

先决条件

使用单独的凭证进行规划以及任何经批准的资源创建。

• 一个兼容的开发环境，并配备 Agent Toolkit for AWS。
• AWS Command Line Interface (AWS CLI)，配置了最小权限的只读配置文件。
• 访问原始知识库配置或其 IaC 文件。
• For the optional live build:
  • 一个范围受限的构建配置文件，使用该指南推荐的策略。
  • 新知识库的 IAM 服务角色。该指南会为你的智能体提供信任策略和权限来帮助你创建它。
  • Python 3 和 boto3，用于生成的预配脚本。

Agent Toolkit for AWS 可与兼容的开发环境配合使用，其 GitHub 上的仓库列出了可用的技能。本文中的示例使用 AWS CLI 2.37 和 boto3 1.43.32。

安装技能

按照 Agent Toolkit for AWS 入门说明针对你的编码智能体进行操作。add-skill 命令会将 amazon-bedrock 技能安装到它检测到的编码智能体中。添加 --agent 可以指定目标，例如 --agent kiro。

aws agent-toolkit add-skill \
    --skill-name amazon-bedrock

安装后，当你描述迁移任务时，你的智能体会加载迁移指南。以下提示词是示意性输入，并非实际记录。

规划迁移

选择与你维护源的方式相匹配的路径。

要开始探索模式，请提出一个问题：

What would change if I moved knowledge base <your-kb-name>
in <your-region> to a Managed Knowledge Base? Use Explore mode.

准备就绪后，选择实时路径或 IaC 路径。

迁移一个实时知识库

在授权创建资源之前，先要求提供计划：

Plan a migration of knowledge base <your-kb-name> in <your-region>
to a Managed Knowledge Base. Stop after the plan.

确认账户和区域，然后审阅计划中的映射和应用变更。默认情况下，新知识库会采用原名称并附加 -managed 后缀。要构建它，请确认服务角色存在，切换到构建配置文件，检查预置脚本及其预览，并进行批准。你的智能体会运行该脚本，创建知识库和数据源，并报告它们的状态。

迁移基础设施即代码

将你的智能体指向源模板或配置：

Review <path-to-source-template> and plan a migration to a
Managed Knowledge Base.

你的智能体会将迁移后的文件写入输出目录，不部署任何内容，并向你显示差异。要保留该差异，请让智能体将其保存。在部署之前运行 terraform init -backend=false 和 terraform validate。你的智能体可以引导你完成这两个命令，但本指南将这些检查留给你，因为 terraform init 会下载较大的 AWS 提供程序。在应用部署计划之前，请检查它是否保留了回滚所需的原始资源。

对话示例

迁移以对话形式进行。在阅读任何内容之前，你的智能体会说明其范围并询问如何继续：

It never changes or deletes <your-kb-id>, never starts ingestion,
and never cuts your application over; every AWS change is shown to
you and approved first. Nothing has run against your KB yet.

1. Mode: Explore (read-only Q&A about Managed KBs and your KB, no
   plan or build) or Migration (run the phases: identify, discover,
   plan, and optionally build)?
2. Target type, if Migration: migrate the live KB <your-kb-id> (kb
   path, which can build a new Managed KB on approval), or migrate
   the Terraform/CloudFormation that defines it (iac path, which
   only emits a migrated file and provisions nothing)?
3. Explanation style: plain or technical. I'll use plain unless
   you say otherwise.

计划摘要会显示每个映射、调用方变更，以及你需要做出的决策：

Phase 3, Plan: written (plan.md)
- Mapping:
  - Vector store becomes auto-provisioned (adjusted, Yes).
  - SEMANTIC chunking is dropped for the managed default
    (adjusted, Partly).
  - Parsing becomes SMART_PARSING (adjusted, Yes).
  - The S3 prefix and metadata sidecars carry over 1:1.
- Changes for callers:
  - New KB id.
  - managedSearchConfiguration replaces vectorSearchConfiguration.
  - overrideSearchType: SEMANTIC can't be sent; search is hybrid.
Your input needed before this can go further.
- D1 embeddingModelType: MANAGED (recommended): keeps the managed
  reranker. CUSTOM Titan v2 1024/FLOAT32: turns off the managed
  reranker.
- D2 aclEnabled: recommend false, since the source has no ACLs.
  On S3 this can't be changed after create.
- Next step: stop with this plan (the default), or opt into Phase 4?

对于实时构建，你的智能体会在预览处停止，且批准命令需要计划的哈希值：

If you approve, the command to run is the following. It is MUTATING:
  AWS_PROFILE=build-profile AWS_REGION=<your-region> \
    python3 provision_managed_kb.py --execute \
    --expect-plan-sha256 <plan-sha256>
--execute refuses to start unless it is given --expect-plan-sha256
and the hash matches.
What the preview would create:
- Knowledge base (CreateKnowledgeBase, MANAGED): support-docs-managed
- Data source (CreateDataSource, managed connector, deletion
  protection ENABLED/15): support-docs-s3-managed
The script never calls StartIngestionJob, Retrieve, Update*,
Delete*, or a standalone TagResource.

示例对话经过轻度编辑，标识符已被替换。

更新应用程序的检索调用

你的应用程序对两种类型使用相同的 Retrieve 操作。托管请求指向新的知识库 ID，并将 vectorSearchConfiguration 替换为 managedSearchConfiguration。向托管知识库传递 vectorSearchConfiguration 会返回验证错误。托管检索始终使用混合搜索，因此托管请求结构中没有 overrideSearchType 字段。元数据筛选器保持相同的语法，只是托管知识库不支持 startsWith 和 stringContains 运算符。完整语法请参阅 Retrieve API 参考。

本示例假定两个知识库都包含筛选器所使用的 locale 元数据。

# Illustrative: the managed request shape was checked with boto3 1.43.32; adapt the IDs and filter to your knowledge base.
import boto3

client = boto3.client("bedrock-agent-runtime")
query = {"text": "How do I return an online order?"}
locale_filter = {"equals": {"key": "locale", "value": "en-US"}}

# Customer-managed (VECTOR) knowledge base.
original_response = client.retrieve(
    knowledgeBaseId="<original-kb-id>",
    retrievalQuery=query,
    retrievalConfiguration={
        "vectorSearchConfiguration": {
            "numberOfResults": 5,
            "overrideSearchType": "SEMANTIC",
            "filter": locale_filter,
        }
    },
)

# Managed target: different ID and search configuration.
managed_response = client.retrieve(
    knowledgeBaseId="<managed-kb-id>",
    retrievalQuery=query,
    retrievalConfiguration={
        "managedSearchConfiguration": {
            "numberOfResults": 5,
            "filter": locale_filter,
        }
    },
)

验证检索并完成切换

在应用程序仍使用原有知识库的同时评估新知识库。

1. 如果使用 IaC，请通过你的流水线审阅并部署目标配置。
2. 同步每个数据源并查看是否有失败。参见 Sync your data。
3. 为应用程序的运行时 IAM 角色授予对新知识库 ARN 的 bedrock:Retrieve 权限，同时保留其对原有知识库的访问权限，以便你可以回滚。
4. 使用该角色，通过 Retrieve 对两个知识库运行具有代表性的查询。两种类型使用不同的评分标准。托管评分还取决于 rerankingModelType，使用托管嵌入模型时默认为 MANAGED，使用自定义模型时默认为 NONE。请按模式分别调整阈值，并在比较时保持模式不变。
5. 在使用的位置测试元数据筛选器和权限感知检索，包括登录用户不应接收的内容。在启用了 ACL 的数据源上，不带 userContext.userId（用户电子邮件）的请求不会返回任何结果。
6. 获得接受后，部署新的知识库 ID 和请求格式。在整个回滚期内保留原始知识库（内容保持不变）以及应用程序配置。

对于每个查询，检查两者是否返回相同的顶部文档，以及结果的重叠程度。用一个简短的脚本，对照诸如“至少 90% 的查询顶部文档匹配”和“托管知识库上没有零结果查询”等标准，报告通过或失败。根据你的工作负载调整该阈值。有关其他检索质量指标（如上下文相关性和上下文覆盖率），请参阅 Use metrics to understand RAG system performance。

比较结果时请注意以下差异：

• 在比较之前先规范化源位置。客户自主管理的知识库可能在 location.s3Location.uri 中返回 s3://bucket/key，而托管知识库可能返回 https:// URL。请按对象键进行比较。
• 比较顶部结果，而不是假设结果数量相等。两种知识库类型可以返回不同数量的结果，并且 numberOfResults 设定的是上限而非保证。比较顶部文档，并逐一审查其发生变化的查询。详情请参阅 Configure and customize queries for managed knowledge bases。
• 映射已重命名的系统元数据键。例如，在比较代码中将 x-amz-bedrock-kb-data-source-id 替换为 _data_source_id。你自己的元数据属性名称保持不变。详情请参阅 Configure and customize queries for managed knowledge bases。

清理

如果你完成了迁移，只有在回滚期结束并完成依赖项审查之后，才可停用原始资源。保留托管知识库摄取来源的源文档和存储桶，以及其他工作负载使用的存储。通过各自的所有者模板清理 IaC 管理的资源。

如果你改为终止评估，请保留原始资源，并按以下顺序删除你创建的内容：

1. 删除每个托管数据源，并等待其删除完成。
2. 删除托管知识库，并等待其删除完成。
3. 如果该服务角色仅为本次评估而创建，请先删除其内联策略，然后再删除该角色。
4. 如果使用了客户自主管理的密钥，请检查 aws kms list-grants 中由 Amazon Bedrock 创建的授权，这些授权可能在知识库删除后仍然存在。
5. 保留仍被其他知识库读取的任何 S3 存储桶。

托管数据源上的删除保护限制的是同步可删除的内容量，而不是你是否能删除数据源本身。删除原始知识库并不会删除其向量存储，向量存储会持续产生费用，直到你将其移除。请参阅 Delete an Amazon Bedrock knowledge base。

结论

借助 Amazon Bedrock Managed Knowledge Base，你的团队不再需要运行向量存储或管理底层检索基础设施。借助 amazon-bedrock 技能中的迁移指南，你可以向你的智能体索取一个计划，审查它，并只批准你希望构建的资源。

要开始使用，请设置 Agent Toolkit for AWS，并让你的智能体对知识库进行只读评估。迁移完成后，可以探索智能体检索以处理多部分问题。要了解更多信息，请参阅 AWS Machine Learning Blog 上的 Build enterprise search for agents with Amazon Bedrock Managed Knowledge Base。

关于作者