介绍文档级同步报告：增强Amazon Q Business中的数据同步可见性 机器学习博客

文档级同步报告的介绍：提升亚马逊Q商业数据同步可见性

作者：Aneesh Mohan 和 Ashwin Shukla，2024年8月14日在 Amazon Q 发表查看所有公告 查看生成AI相关内容

关键要点

新功能推出：文档级同步报告，提升数据源同步操作中对文档处理生命周期的可见性。该报告提供每份文档的详细索引状态、元数据和访问控制列表ACL。新增的SYNCRUNHISTORYREPORT日志流，方便故障排查和访问控制问题解决。

亚马逊Q商业是一个全面管理的生成式人工智能AI助手，旨在帮助企业解锁数据和知识的价值。通过亚马逊Q，用户可以快速找到问题答案、生成摘要和内容，并利用公司各种数据源和企业系统中的信息完成任务。这一能力的核心是原生数据源连接器，它们能够无缝集成并索引来自多个存储库的内容，形成统一索引。这使得亚马逊Q大语言模型LLM能够提取并提供准确、流畅的答案。数据源连接器充当桥梁，将来自Salesforce、Jira和SharePoint等多个不同系统的内容同步至中心化索引，从而增强自然语言理解和生成能力。

客户普遍希望亚马逊Q商业能够安全地连接超过40个数据源，并期待在数据源同步作业期间获取更好的文档处理生命周期可视化。他们希望了解每份文档的爬取和索引状态，能够排查某些文档未能返回预期答案的原因，并希望访问已被索引文档的元数据、时间戳和ACL访问控制列表。

我们很高兴地宣布，亚马逊Q商业推出了一项新功能，大幅提升数据源同步操作的可见性。此次更新引入了综合的文档级报告，包含在同步历史中，为管理员提供每份文档在数据源同步作业过程中处理的详细索引状态、元数据和ACL的详情。这一增强能让管理员迅速调查和解决在设置亚马逊Q商业应用时遇到的摄取或访问问题。详细的文档报告保存在新的SYNCRUNHISTORYREPORT日志流中，确保关键的同步作业细节在故障排查时随时可用。

文档在数据源同步运行作业中的生命周期

在这一部分，我们探讨文档在亚马逊Q商业中数据源同步时的生命周期。这为理解同步过程提供了价值。数据源同步包含三个关键阶段：爬取、同步和索引。

以下是同步运行作业的流程图：

爬取阶段

爬取阶段是第一阶段，连接器从数据源中爬取所有文档及其元数据。在此阶段，连接器还会比较文档的校验和checksum，判断某文档是否需要添加、修改或从索引中删除。此操作对应于同步运行历史报告中的CrawlAction字段。

如果文档没有修改，则标记为UNMODIFIED并跳过后续阶段。在爬取阶段出现故障例如，由于限制错误、内容损坏或文档大小过大时，相关文档在同步运行历史报告中会标记为FAILED，其CrawlStatus则为FAILED。如果由于验证错误而被跳过，状态为SKIPPED。所有成功的文档标记为SUCCESS并进入下一阶段。

我们在此阶段还捕获每份文档的ACL和元数据，以便将其添加至同步运行历史报告中。

同步阶段

在同步阶段，文档被发送至亚马逊Q商业摄取服务API，如BatchPutDocument和BatchDeleteDocument。提交至这些API的文档后，亚马逊Q商业会执行验证检查。如果任何文档在此检查中失败，其SyncStatus将标记为FAILED。若某文档发生无法恢复的错误，则会标记为SKIPPED，其他文档将继续前进。

索引阶段

在此步骤中，亚马逊Q商业解析文档，根据其内容类型进行处理，并将其持久化至索引中。如果文档未能成功持久化，则其IndexStatus将标记为FAILED；否则，记为SUCCESS。

所有阶段的状态被捕获后，我们将这些状态作为 Amazon CloudWatch 事件发送至客户的AWS账户。

新文档级报告的关键特点和好处

新文档级报告在亚马逊Q商业应用程序中提供以下关键特点和好处：

增强的同步运行历史页面 新增的Actions栏目，提供每个同步运行的文档级报告访问。

专用日志流 在亚马逊Q商业CloudWatch日志组中新增名为SYNCRUNHISTORYREPORT的日志流，包含文档级报告。

全面的文档信息 文档级报告为每份文档提供以下信息：文档ID 直接来自数据源或由客户在数据源字段映射中映射的文档ID。文档标题 文档标题来自数据源或客户在字段映射中映射的值。综合文档状态SUCCESS，FAILED或SKIPPED 文档的最终状态，标记为 SUCCESS FAILED或 SKIPPED。错误消息如果文档失败 失败文档的错误消息，包括任何由于限制或内部错误跳过的文档信息。爬取状态 表示文档是否成功从数据源中爬取。同步状态 表示文档是否成功发送至同步过程。索引状态 表示文档是否成功持久化于索引中。ACLs 包含从数据源爬取的每份文档的权限列表。元数据 包含来自数据源的元数据字段，及客户映射的额外元数据字段。哈希文档ID用于故障排查 为保护数据隐私，展示文档标识符的一次性哈希值。时间戳 表示文档状态在CloudWatch中记录的时间。

在接下来的部分中，我们将探讨此日志功能的不同用例。

解决“对不起，我未能找到相关信息”问题的日志功能

亚马逊Q商业中的新文档级日志功能可以帮助排查与“对不起，我未能找到相关信息来完成您的请求”响应相关的常见问题。

让我们探讨一个示例场景。一位共同基金经理使用亚马逊Q商业聊天，在企业数据存储中提取知识和洞察。当基金经理询问“多资产基金的年复合增长率CAGR是多少？”时，收到“对不起，我未能找到相关信息来完成您的请求”的响应。

作为管理亚马逊Q商业应用的管理员，您可以使用以下步骤利用新的日志功能进行故障排查。首先，您需要确认多资产基金文档是否已成功索引。接着，需要验证基金经理的用户账户是否具备读取多资产基金文档信息的权限。亚马逊Q商业执行数据源中配置的文档权限，可以通过此新功能确认文档ACL设置是否已同步至亚马逊Q商业应用的索引中。

您可以使用以下CloudWatch查询字符串检查文档ACL设置：

sqlfilter @logStream like SYNCRUNHISTORYREPORT/ and DocumentTitle = yourdocumenttitle fields DocumentTitle ConnectorDocumentStatusStatus Acl sort @timestamp desc limit 1

此查询过滤器使用每个文档级日志流SYNCRUNHISTORYREPORT，显示文档标题及其ACL设置。通过确认文档的索引和权限，您可以识别并消除可能导致“对不起，我未能找到相关信息”的问题。

以下截图显示了一个示例结果。

确定优化的最近文档提升时长

在生成准确答案时，您可能希望微调亚马逊Q对内容的优先级。例如，您可能希望优先考虑最近的文档，以确保使用最新的信息生成答案。为此，您可以利用亚马逊Q商业的相关性调优功能，根据最后更新日期属性进行文档优先级提升，指定提升时长。然而，在处理大量频繁更改的文档时，确定最佳提升周期可能很具挑战性。

现在，您可以使用每文档级报告获取文档的lastupdatedat元数据字段信息，以帮助您确定适当的提升周期。为此，您可以使用以下CloudWatch日志Insights查询来检索来自SYNCRUNHISTORYREPORT日志流的机器学习文档的lastupdatedat元数据属性：

sqlfilter @logStream like SYNCRUNHISTORYREPORT/ and Metadata like Machine Learning parse Metadata {keylastupdatedatvalue{dateValue}} as @lastupdatedat sort @lastupdatedat desc @timestamp desc dedup DocumentTitle

使用上述查询，您可以洞察文档的最后更新时间戳，从而便于决定最佳的提升周期。这种方法确保您在聊天响应中使用最新且相关的信息，提高亚马逊Q商业实现的整体准确性和有效性。

以下截图显示了一个示例结果。

常见文档索引可观察性和故障排查方法

在这一部分，我们探讨使用新文档级报告功能观察和故障排查文档索引的几项常见管理员任务。

列出数据源中所有成功索引的文档

要检索特定数据源成功索引的文档列表，您可以使用以下CloudWatch查询：

sqlfields DocumentTitle DocumentId @timestamp filter @logStream like SYNCRUNHISTORYREPORT/yourdatasourceid/and ConnectorDocumentStatusStatus = SUCCESS sort @timestamp desc dedup DocumentTitle DocumentId

以下截图显示了一个示例结果。

列出特定同步作业中成功索引的所有文档

要检索特定同步作业中成功索引的所有文档，您可以使用以下CloudWatch查询：

sqlfields DocumentTitle DocumentId ConnectorDocumentStatusStatus AS IndexStatus @timestamp filter @logStream like SYNCRUNHISTORYREPORT/yourdatasourceid/runidand ConnectorDocumentStatusStatus = SUCCESS sort DocumentTitle

以下截图显示了一个示例结果。

列出特定同步作业中所有未能索引的文档

要检索特定同步作业中未能索引的所有文档及其错误消息，您可以使用以下CloudWatch查询：

sqlfields DocumentTitle DocumentId ConnectorDocumentStatusStatus AS IndexStatus ErrorMsg @timestamp filter @logStream like SYNCRUNHISTORYREPORT/yourdatasourceid/runidand ConnectorDocumentStatusStatus = FAILED sort @timestamp desc

以下截图显示了一个示例结果。

列出亚马逊Q商业应用中特定用户名称的ACL权限的文档

要检索具有特定用户ACL权限的文档列表，您可以使用以下CloudWatch日志Insights查询：

sqlfilter @logStream like SYNCRUNHISTORYREPORT/ and Acl like aneesh@mydemoawsonmicrosoftcom display DocumentTitle SourceUri

以下截图显示了一个示例结果。

从同步作业中列出已索引文档的ACL

要检索特定索引文档的ACL信息，您可以使用以下CloudWatch日志Insights查询：

sqlfilter @logStream like SYNCRUNHISTORYREPORT/datasourceid/runid and DocumentTitle = yourdocumenttitle display DocumentTitle Acl

以下截图显示了一个示例结果。

从同步作业中列出已索引文档的元数据

要检索特定索引文档的元数据信息，您可以使用以下CloudWatch日志Insights查询：

sqlfilter @logStream like SYNCRUNHISTORYREPORT/datasourceid/runid and DocumentTitle = yourdocumenttitle display DocumentTitle Metadata

以下截图显示了一个示例结果。

结论

新推出的文档级报告在亚马逊Q商业中提升了文档处理生命周期的可见性和可观察性，满足客户对更好故障排查能力和详细信息访问的需求。该报告存储在SYNCRUNHISTORYREPORT的专用日志流中，包含每份文档的全面信息，包括文档ID、标题、整体文档同步状态、错误消息如有、ACL和从数据源获取的元数据信息。数据源同步运行历史页面现在新增了 Actions 栏，提供每个同步运行的文档级报告访问。这一功能显著增强了与文档摄取和访问控制相关的问题的故障排查能力，提高了有关与亚马逊Q索引同步文档的可见性。

如需开始使用亚马逊Q商业，请查阅入门指南。要了解关于数据源连接器和最佳实践的更多信息，请参阅配置亚马逊Q商业数据源连接器。

作者介绍

Aneesh Mohan 是亚马逊网络服务AWS的高级解决方案架构师，拥有二十年的业务关键工作负载解决方案开发经验。他热衷于技术，并喜欢与客户合作，构建卓越架构的解决方案，专注于金融服务行业、AI/ML、安全和数据技术。

Ashwin Shukla 是亚马逊Q商业和亚马逊Kendra工程团队的二级软件开发工程师，拥有六年的企业软件开发经验。在此角色中，他负责设计和开发亚马逊Q商业的基础性功能。

小黄鸭加速器免费3小时入口