亚马逊 Bedrock 托管知识库新增 AgentCore Memory 集成

关键要点

  • 亚马逊 Bedrock 托管知识库通过 memoryConfiguration 参数与 AgentCore 记忆集成,无需单独存储即可恢复对话历史并注入用户上下文。
  • 托管知识库使用启用了 ACL 的 S3 数据源,通过 IAM 条件键匹配经验证的 Cognito 邮箱和用户标识声明,强制实现用户级记忆隔离。
  • 长线记忆提取以异步方式进行,并具有最终一致性;记忆操作采用尽力而为机制,失败不会阻止知识库检索。

Amazon Bedrock Managed Knowledge Base 现已通过 AgenticRetrieveStream 请求中的 memoryConfiguration 参数与 Amazon Bedrock AgentCore memory 集成,使应用程序无需单独的对话存储即可恢复对话历史、提取长期有效的事实,并将相关用户上下文注入知识库查询。该集成为向后兼容的可选功能,可让多用户应用程序维护彼此隔离的用户记忆,同时执行文档访问控制列表(ACL)。

使用托管记忆的多用户应用程序架构

该集成将文档级访问控制与按用户划分的记忆命名空间相结合。托管知识库从启用了 ACL 的 Amazon S3 数据源同步文档,其中全局 ACL 文件将 S3 前缀映射到用户邮箱。一个 AgentCore memory 资源供所有用户使用,并通过命名空间路径中的 {actorId} 模板和 AWS Identity and Access Management (IAM) 条件键来确保用户之间相互隔离。服务会从之前的对话轮次恢复短期记忆,在规划器认为有帮助时搜索长期记忆,并根据配置的提取策略异步持久化每个新对话轮次。

应用程序通过 Amazon Cognito 对用户进行身份验证,并从经过验证的 ID 令牌中提取两个声明:sub(用户 ID)将作为 memory actorId 和命名空间标识符,经过验证的邮箱则作为 userContext.userId,用于知识库 ACL 筛选。借助这两个值,应用程序无需存储或管理对话历史即可构建 AgenticRetrieveStream 请求。

配置带有 ACL 的知识库数据源

创建托管知识库时,类型设为 MANAGED,embeddingModelType 设为 MANAGED,无需外部向量存储。数据源使用类型 MANAGED_KNOWLEDGE_BASE_CONNECTOR,且 connectorParameters.type 设为 S3。要启用 ACL 筛选,请将 aclEnabled 设为 True,并提供 globalAccessControlListS3Uri,指向同一个 S3 存储桶中的 JSON 文件。每个 ACL 条目都会将一个 S3 前缀映射到用户列表:例如,所有员工都可以读取 s3://BUCKET/docs/hr/ 和 s3://BUCKET/docs/it/,只有工程师可以读取 s3://BUCKET/docs/engineering/,只有销售人员可以读取 s3://BUCKET/docs/sales/。创建并同步数据源时,CreateDataSource 是异步操作;调用方必须等待状态变为 AVAILABLE,然后调用 StartIngestionJob 并等待其状态变为 COMPLETE。服务会扫描所有文档并为每份文档编制索引,同时附上其 ACL。没有匹配 ACL 条目的文档不会被摄取。邮箱与任何 ACL 条目都不匹配的用户,无法从相应前缀获得结果。

支持感知 ACL 的检索也适用于会从源系统爬取权限的连接器,例如 Microsoft SharePoint、Google Drive 和 Atlassian Confluence。知识库会实时根据源系统权限检查每条检索结果。应用程序代码无需更改:始终在 userContext 中传入用户的邮箱即可。

记忆资源设置与命名空间设计

一个记忆资源供所有员工使用。创建时,将 eventExpiryDuration 设为原始对话事件应保留的天数(例如 30 天)。配置两种提取策略:userPreferenceMemoryStrategy 使用 /anycompany/{actorId}/profile 下的命名空间,将用户明确表达的偏好提取为结构化记录;summaryMemoryStrategy 使用 /anycompany/{actorId}/summaries/{sessionId} 下的命名空间,对每段对话进行摘要并记录附带事实。在检索配置中使用命名空间路径 /anycompany/,即可访问特定用户的所有个人资料和对话摘要。等待记忆状态变为 ACTIVE。创建记忆时无需提供用户或 actorId,因此新用户会在首次查询时成为 actor。

Cognito 设置与 IAM 角色强制实施

创建 Cognito 用户池,并将邮箱设为必填、已验证且不可变的属性。设置 AutoVerifiedAttributes: ["email"],并在邮箱架构中将 Mutable 设为 False,以防用户在创建账户后更改邮箱。如果用户通过 Okta 或 Microsoft Entra ID 联合登录,请将身份提供方的邮箱映射到此属性,使其与知识库中的 ACL 条目相匹配。

应用程序在 IAM 角色下运行,并为每位用户单独担任该角色一次,设置会话标签 userId=,其值为 ID 令牌中的用户 sub。角色策略授予以下权限:作用范围限定为知识库 ARN 的 bedrock:AgenticRetrieveStream、bedrock:Retrieve、bedrock:GetDocumentContent;用于规划和生成的 bedrock:InvokeModelWithResponseStream;作用范围限定为记忆 ARN 的 bedrock-agentcore:GetMemory;以及对记忆操作的条件式访问。具体而言,仅当 bedrock-agentcore:actorId 与主体的会话标签 userId 匹配时,才允许调用 ListEvents、CreateEvent 和 ListSessions。仅当 bedrock-agentcore:namespacePath 与 /anycompany/${aws:PrincipalTag/userId}/* 匹配时,才允许调用 RetrieveMemoryRecords 和 ListMemoryRecords。这些 IAM 条件键强制措施构成第二道防线:如果应用程序代码意外将请求绑定到错误的 actorId,记忆操作将因 AccessDeniedException 而失败,请求也不会继续执行。

构建并执行请求

使用 Cognito 用户池的公钥验证 ID 令牌后,应用程序读取 sub 和经过验证的邮箱声明。sub 必须保持稳定,且绝不能在不同用户之间重复使用;Cognito 生成的 sub 符合此要求。随后,应用程序担任 IAM 角色,并设置 SourceIdentity= 为 sub,以及 Tags=[{"Key": "userId", "Value": principal.sub}]。应用程序会为每段对话生成一个新的 sessionId(例如 "conv-" + uuid4().hex),并在第一轮时将其返回给客户端;之后的对话轮次中,客户端会将其回传。

AgenticRetrieveStream 请求中的 messages 仅包含当前问题,不含之前的对话轮次,因为 sessionBinding 会自动恢复历史记录。userContext.userId 设为经过验证的邮箱。memoryConfiguration 包含记忆 ID、sessionBinding(其中 actorId 为用户的 sub,sessionId 为应用程序生成的值)、用于在生成后写入对话轮次的 persistenceMode: DEFAULT,以及一个 retrievalConfigs 条目,其中 namespacePath 解析为用户的命名空间(例如 /anycompany/a8e1b390-10f1-70d9-ee85-b68b610ee0c4)。请求还将知识库指定为检索器,并将 foundationModelType: MANAGED 和 rerankingModelType: MANAGED 用于规划器和生成器。

使用 persistenceMode: DEFAULT 时,每个对话轮次会作为一个事件写入,其中包含两个负载:用户的问题和生成的答案。应用程序随后可以直接通过 ListEvents 并传入用户的 actorId 和 sessionId 来读取对话历史,并根据 "conversational" 负载呈现清晰的对话记录。

追踪记忆与检索行为

每轮对话的追踪信息会显示是否使用了记忆。第一个追踪事件是 SessionHistoryLoad,其中会报告 _memory_event_count 和 _memory_message_count。新会话中,这两个值均为 0。SpeculativeRetrieval 会在规划前出现,其中包含知识库和记忆中的条目;记忆条目带有 memory* 元数据,但没有文本。如果规划器决定搜索记忆,追踪信息中会显示包含 actions[].memoryRetrieve 的 Planning 事件,其中会列出规划器生成的查询。之后会出现 retrievalType: BedrockAgentCoreMemory 的 Retrieval 事件,并报告 _memory_record_count;如果没有匹配记录,计数为 0 属于正常情况。

在新对话中,推测性检索会同时搜索知识库和长期记忆。在继续进行的会话中,推测性检索只查询知识库;只有当规划器生成 memoryRetrieve 操作时,才会访问长期记忆。长期记忆提取是异步的,会在对话轮次持久化后运行;记录可能在该轮次结束后 1–2 分钟或更晚出现,因此设计时应考虑最终一致性。

记忆操作在设计上采用尽力而为的方式。如果记忆调用失败或遭到拒绝,追踪信息中会显示带有失败消息的 FAILED 事件,而请求会继续仅使用知识库。生成的答案不会丢失;它会根据知识库以及成功检索到的任何记忆内容生成。

多用户隔离与安全性

感知 ACL 的检索属于筛选,而非授权。应用程序会对用户进行身份验证,并且只从 email_verified: true 的已验证 ID 令牌中读取邮箱。知识库会筛选文档:如果文档没有 ACL,或者用户邮箱与任何 ACL 条目都不匹配,就不会检索该文档。知识库采用默认拒绝策略,因此没有结果意味着权限问题,而非数据问题。如果某份文档本应可见却未显示,请检查令牌中的邮箱是否与 ACL 中的邮箱匹配。

记忆身份来自经过验证的令牌 sub。actorId 和命名空间绝不能来自客户端请求正文。如果应用程序错误导致 actorId 不匹配,IAM 会拦截:例如,代码意外将 Liam 的请求绑定到 Maya 的 actorId 时,SessionHistoryLoad 步骤会因 AccessDeniedException 而失败,不会向 Maya 的会话写入任何事件,Liam 的 sessionId 计数器也会保持不变。由于每位用户都在单独的 IAM 角色会话下运行,AWS CloudTrail 日志会显示每次调用对应的用户(SourceIdentity=)。

该记忆是客户拥有的资源,同一账户中的其他系统也可能向其中写入内容。应将其内容视为输入,并在需要时通过 policyConfiguration 为请求附加 Bedrock guardrail。应规划数据生命周期:原始事件会在 eventExpiryDuration 指定的时间后过期,但提取出的记录不会过期。删除用户的工作流必须针对该 actor 的所有会话调用 DeleteEvent,并针对该 actor 命名空间路径下的所有记录调用 DeleteMemoryRecord。

可观测性与性能注意事项

记录每轮对话的完整追踪信息,并附上关联 ID。规划器生成的子查询和最终结果一样值得审计。CloudWatch 指标 AWS/Bedrock/KnowledgeBases 会报告 Operation=AgenticRetrieveStream 时的 Invocations、ClientErrors 和 TotalIterationCount。AWS/Bedrock-AgentCore 会报告每种记忆操作的 Invocations、Latency、Errors、UserErrors,以及每种提取策略的 InputTokenUsage/OutputTokenUsage。

会话恢复会增加约 200 毫秒的延迟。在示例运行中,包含一个知识库、ACL 和记忆的完整对话轮次耗时 4–10 秒;大部分时间消耗在规划迭代上,而非记忆操作上。Agentic retrieval 按调用次数及底层检索次数计费;调用期间的记忆操作按 AgentCore memory 用量计费。应在整段对话期间使用稳定的 sessionId;每次请求都使用新 ID 会悄无声息地中断连续性,并导致每轮对话都生成一条摘要记录。

关键事实

  • Managed Knowledge Base 需要具有相应权限的服务角色;创建知识库时通过 roleArn 传入该角色 ARN。
  • 启用 ACL 的数据源使用 type MANAGED_KNOWLEDGE_BASE_CONNECTOR,connectorParameters.type 设为 S3,aclEnabled 设为 True。
  • 全局 ACL 文件将 S3 前缀映射到用户邮箱;没有 ACL 条目的文档不会被摄取。
  • 记忆资源使用 userPreferenceMemoryStrategy(命名空间:/anycompany/{actorId}/profile)和 summaryMemoryStrategy(命名空间:/anycompany/{actorId}/summaries/{sessionId})创建。
  • eventExpiryDuration 指定原始对话事件的保留天数;提取出的记录不会过期。
  • 带有 memoryConfiguration 的 AgenticRetrieveStream 请求中的 messages 仅包含当前问题。
  • userContext.userId 设为 ID 令牌中经过验证的邮箱;知识库会使用该值筛选 ACL。
  • memoryConfiguration.sessionBinding.actorId 设为 ID 令牌中经过验证的 sub;IAM 条件键会强制执行按用户隔离记忆。
  • persistenceMode: DEFAULT 会将问题和生成的答案作为一个事件写入;这需要 generateResponse: true。
  • persistenceMode: NONE 会恢复历史记录但不写入任何内容,适用于审计或回放视图。
  • IAM 策略授予条件式访问:仅当 bedrock-agentcore:actorId 与主体的会话标签匹配时,才允许调用 ListEvents、CreateEvent 和 ListSessions。
  • IAM 策略授予 RetrieveMemoryRecords 和 ListMemoryRecords 的权限,但仅当 bedrock-agentcore:namespacePath 与 /anycompany/${aws:PrincipalTag/userId}/* 匹配时才允许调用。
  • Cognito 邮箱必须为必填、已验证且不可变(Mutable: False),以防更改邮箱导致文档归属被重新分配。
  • 长期记忆提取是异步的,具有最终一致性;记录可能在一轮对话结束后 1–2 分钟才出现。
  • 记忆操作采用尽力而为的方式;失败会记录在追踪信息中,但不会阻止请求。
  • 一个请求最多可携带五个知识库;规划器会根据检索器描述路由子查询。
  • 会话恢复受到强制约束:使用 sessionBinding 时,请求不能携带包含之前对话轮次的 messages。
  • 该集成为可选功能且向后兼容;未配置 memoryConfiguration 的现有应用程序可继续照常运行。

常见问题

规划器如何决定搜索记忆还是知识库?

规划器可以查看知识库和记忆这两种检索来源。在新会话中,推测性检索会同时包含两者的条目,规划器可以检查这两组条目。在继续进行的会话中,推测性检索只查询知识库;只有当规划器生成 memoryRetrieve 操作,认为搜索记忆有助于回答用户问题时,才会访问记忆。如果搜索了记忆,追踪信息中的 Planning 事件会显示该决定,其中包含 actions[].memoryRetrieve;如果只使用知识库,则不会出现这一项。规划器可以根据用户的问题和目前的对话内容生成自己的记忆搜索查询。

如果文档没有 ACL 条目,或者用户邮箱与任何 ACL 条目都不匹配,会发生什么?

从数据源同步时,没有 ACL 条目的文档不会被摄取到知识库中。如果用户邮箱与某个前缀的任何 ACL 条目都不匹配,该用户从此类前缀检索时不会得到结果。知识库采用默认拒绝策略:缺少 ACL 或没有匹配项意味着结果更少,而非获得更多访问权限。如果本应可见的文档缺失,请确认用户邮箱与 ACL 文件中的邮箱完全匹配、ACL 条目中的 "Access": "ALLOW",并且文档位于该 ACL 条目涵盖的前缀下。大小写和空格都必须与 ACL 一致。

应用程序能否使用其他稳定用户 ID 代替 Cognito sub 来标识记忆用户?

可以。sub 必须保持稳定,绝不能在不同用户之间重复使用,也不能重新分配给其他人。如果组织有自己的稳定用户 ID(例如员工 ID),且符合这些条件,应用程序可以使用该 ID 作为 actorId 和命名空间标识符,代替 Cognito sub。用于知识库 ACL 筛选的 userContext.userId 可以独立设置——通常是用户邮箱,但如果 ACL 条目使用其他标识符,也可以使用该标识符。关键是,所选的记忆身份必须对每个人保持不可变,而所选的文档 ACL 身份必须与知识库 ACL 条目中记录的身份相匹配。

免责声明:本页面信息可能来自第三方,仅供参考,不代表 Gate 的观点或意见,亦不构成任何财务、投资或法律建议。数字资产交易风险较高,请勿仅依赖本页面信息作出决策。具体内容详见声明。
评论
0/400
暂无评论