Amazon Kendra企业智能搜索实战：从架构原理到部署调优-平芜编程栈

1. 项目概述：当企业搜索不再“大海捞针”

如果你在团队里负责过知识管理，或者自己尝试过在公司内部网、文档库、甚至是一堆产品手册里找过某个特定问题的答案，那你一定对那种“大海捞针”的无力感深有体会。传统的全文搜索，比如你丢个关键词进去，它给你返回一堆包含这个词的文档，至于哪个文档真正解决了你的问题，哪个文档只是提了一嘴，全靠你自己去一篇篇翻。更别提那些藏在PDF表格里、扫描图片里、或者邮件附件里的关键信息了，它们对传统搜索引擎来说，基本就是“隐形”的。

这就是为什么当我第一次深入了解Amazon Kendra时，感觉像是打开了一扇新世界的大门。它不是一个简单的关键词匹配工具，而是一个由机器学习驱动的智能企业搜索服务。你可以把它理解为你公司内部的“专家级研究助理”。这个助理不仅能听懂你的自然语言提问（比如“去年第三季度我们在华东区的销售策略是什么？”），还能理解你公司内部各种格式文档（Word、PDF、PPT、网页、甚至数据库表和聊天记录）的深层语义，然后从海量数据中精准地找出最相关、最权威的答案，并以清晰、可引用的方式呈现给你。

这个项目的核心，就是彻底拆解 Amazon Kendra 的“力量”从何而来。它凭什么能做到传统搜索做不到的事情？背后有哪些关键的技术组件在协同工作？从零开始搭建一个可用的 Kendra 搜索体验，需要经历哪些关键的配置步骤？在实际落地过程中，又会遇到哪些“坑”，以及如何绕过它们？这篇文章，就是我基于多次在企业内部部署和优化 Kendra 的经验，为你带来的一份深度实操指南。无论你是技术决策者、开发者，还是业务部门的负责人，都能从中看到 Kendra 如何将混乱的企业数据，转化为可直接驱动业务决策的智能资产。

2. 核心架构与工作原理拆解

要理解 Kendra 的强大，不能只看表面功能，必须深入到它的架构设计和工作原理。这就像了解一辆跑车，不能只看它跑得多快，还得知道它的引擎、传动系统和底盘是如何协同的。

2.1 从“关键词匹配”到“语义理解”的范式转变

传统搜索的核心是“词袋”模型和倒排索引。它把文档拆成一个个独立的词（Token），建立“词”到“文档”的映射。当你搜索“苹果”时，它会返回所有包含“苹果”这个词的文档，不管这个“苹果”指的是水果公司、手机，还是真的水果。它不理解上下文，也不理解同义词、近义词或问题的意图。

Kendra 则采用了完全不同的路径。它的核心是预训练的深度学习模型，特别是基于 Transformer 架构的模型（类似于 BERT、GPT 系列的思想，但经过了亚马逊针对搜索场景的专门优化和训练）。这些模型在训练时“阅读”了海量的文本数据，学会了词语之间的复杂关系、句子的语法结构，以及更重要的——语义。

举个例子：当你问“如何重置我的设备密码？”，传统搜索可能会匹配到标题里有“重置”、“设备”、“密码”的文档。但 Kendra 的模型能理解：

意图识别：这是一个“操作指南”类的问题，用户需要步骤。
实体识别：“设备”可能指代公司内部的笔记本电脑、门禁卡、或者某个特定软件。
语义关联：它知道“重置”和“恢复出厂设置”、“初始化”是相近的概念；“密码”和“PIN码”、“通行证”在特定上下文中相关。
上下文理解：如果这个提问来自公司的 IT 支持门户，那么“设备”更可能指公司配发的笔记本电脑。

基于这种理解，Kendra 会去寻找那些真正解释密码重置步骤的文档，哪怕文档里没有完整出现“如何重置我的设备密码”这个句子，只要语义高度相关，就会被优先返回。

2.2 Kendra 的核心组件三要素

一个完整的 Kendra 实现，主要由三个核心组件构成，它们分别对应数据处理的“输入-处理-输出”流程：

1. 数据源连接器这是 Kendra 的“数据触手”。Kendra 本身不生产数据，它连接你已有的数据仓库。亚马逊提供了数十种开箱即用的连接器，覆盖了绝大多数企业数据环境：

云存储：Amazon S3（最简单、最常用的数据源）、SharePoint Online、OneDrive、ServiceNow、Salesforce、Google Drive、Box、Dropbox等。
数据库：通过自定义连接器或间接方式（如将数据库查询结果导出到S3）接入。
网站：可以爬取公司内网、Confluence、Jira等网页内容。
自定义：通过 API 或 SDK，你可以编写连接器接入任何有API的系统。

关键点：连接器不仅仅是“拉取”数据。它们通常具备增量同步能力，只同步新增或修改的文档，这大大降低了持续运行的资源消耗和成本。同时，它们能处理文档的访问权限（ACL），确保搜索结果的安全性，用户只能看到自己有权限访问的内容。

2. 索引这是 Kendra 的“大脑”和“记忆库”。当连接器把数据摄取进来后，Kendra 会对其进行一系列复杂的处理：

文档解析与拆分：将PDF、Word等文件中的文本、表格、甚至图片中的文字（通过OCR）提取出来。对于长文档，它会智能地拆分成更小的、语义完整的“段落”或“块”，以便进行更精细的检索。
语义编码：使用前面提到的深度学习模型，将每一段文本转换成一个高维度的向量（一组数字）。这个向量就是这段文本的“语义指纹”。语义相近的文本，其向量在数学空间中的距离也更近。
元数据提取：自动提取或根据配置添加元数据，如文档作者、创建日期、来源系统、文档类型等。这些元数据是后续进行结果过滤和排序的重要依据。
向量存储与索引构建：将文本向量和元数据存储在一个高性能的向量数据库中，并构建起高效的索引结构，使得在毫秒级别内就能完成海量向量的相似度计算。

3. 查询与答案生成这是 Kendra 的“交互界面”。用户通过搜索框或API发起查询：

查询理解：Kendra 首先用同样的模型处理用户的查询语句，将其也转换为一个查询向量。
语义检索：在向量索引中，快速查找与查询向量最相似的文档段落向量。这个过程不是关键词匹配，而是“语义相似度”计算。
答案提取与生成：对于“事实型”问题（如“公司的年假政策是多少天？”），Kendra 会尝试从最相关的文档段落中，直接提取出答案片段，并高亮显示。这被称为“精确答案”。
相关性排序：Kendra 会综合语义相似度得分、文档的权威性（可配置，如官方手册比个人笔记权威性高）、新鲜度、用户反馈等多种信号，对结果进行排序，把最可能正确的答案排在前面。
结果呈现：返回的结果不仅包括文档链接和摘要，还可能包含提取的精确答案、相关的常见问题（FAQ）、以及用于进一步筛选的元数据分面（Facets）。

2.3 为什么是“智能”搜索？关键能力解析

基于上述架构，Kendra 提供了几个超越传统搜索的关键智能能力：

自然语言查询：用户可以用问问题的方式搜索，无需琢磨关键词。
精确答案提取：直接给出答案，而非仅仅一堆文档链接，极大提升效率。
动态上下文理解：通过持续的查询日志和用户反馈（如点击、答案有用性评分），模型会自我优化，更好地理解你公司内部的术语和上下文。
混合搜索模式：Kendra 实际上结合了“语义搜索”和“关键词搜索”。当语义搜索没有高置信度的结果时，它会自动 fallback 到关键词搜索，确保总有结果返回，兼顾了召回率。

理解了这个架构，你就明白了 Kendra 的“力量”源泉：它不是魔法，而是将先进的自然语言处理模型与成熟的云服务工程化能力相结合，封装成了一个企业可即取即用的服务。接下来，我们就看看如何亲手搭建它。

3. 从零开始：构建你的第一个 Kendra 索引

理论懂了，手会痒。这部分，我将带你一步步创建一个最小可用的 Kendra 搜索应用。我们选择最通用、最简单的场景：将一堆公司产品手册（PDF格式）上传到 Amazon S3，然后用 Kendra 为其建立智能搜索索引。

3.1 前期准备与环境配置

在开始点击控制台之前，有几件事需要先理清。

1. 权限与角色（IAM）安全是云上第一课。Kendra 需要权限去读取 S3 的数据、写入 CloudWatch 日志、调用其他服务等。最佳实践是创建一个专门的 IAM 角色。

创建角色：在 IAM 控制台，创建名为AmazonKendraS3DataSourceRole的角色。
信任实体：选择“AWS 服务” -> “Kendra”。
附加策略：需要附加两个策略：
- AmazonKendraFullAccess：授予 Kendra 服务必要的权限（谨慎起见，后期可根据需要缩小范围）。
- 一个自定义的内联策略，允许 Kendra 读取你特定的 S3 存储桶。策略 JSON 类似如下：
```
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::你的产品手册存储桶", "arn:aws:s3:::你的产品手册存储桶/*" ] } ] }
```
把这个角色记下来，创建索引时会用到。

2. 数据准备与 S3 存储桶

存储桶创建：在 S3 控制台创建一个新存储桶，名字全局唯一，例如company-product-manuals-2023。
文档上传：将你的 PDF、Word 等产品手册上传到该存储桶。建议保持清晰的文件夹结构，例如按产品线分类/ProductA/,/ProductB/。良好的结构有助于后期利用元数据进行筛选。
重要提示：确保文档中的文字是可选的。如果是扫描的图片 PDF，Kendra 内置的 OCR 功能可以处理，但处理时间和成本会略高。纯文本或由 Office 软件生成的 PDF 效果最佳。

3.2 在 AWS 控制台中创建索引

这是核心步骤，我们将在 AWS 管理控制台中完成。

进入 Kendra 服务：在 AWS 控制台搜索并进入 Amazon Kendra。
创建索引：点击“创建索引”。
基本信息：
- 索引名称：product-manuals-index。名称需在账户内唯一。
- 描述：可选，填写“用于搜索公司产品手册的智能索引”。
- IAM 角色：选择我们之前创建的AmazonKendraS3DataSourceRole。这一步至关重要，索引将代表这个角色去访问数据。
- 索引版本：选择“Kendra 企业版”。开发者版有功能和容量限制，用于企业生产环境，建议直接使用企业版。
配置索引容量：这里需要规划。
- 索引单位：这是 Kendra 的计费和容量单位。每个索引单位可以提供一定的查询量（QPS）和存储容量。对于初期测试，你可以先选择最小的1个索引单位。后期可以根据查询量和文档量进行扩展。
- 存储容量：系统会根据你选择的索引单位，显示预估可存储的文档数量（通常一个索引单位能存数万到数十万份文档，取决于文档复杂度）。上传文档后，可以在控制台监控实际使用量。
创建并等待：点击“创建”。索引的初始化需要20-30 分钟。你可以去喝杯咖啡。状态会从“创建中”变为“活跃”。

3.3 添加 S3 数据源并同步数据

索引是空的“大脑”，现在需要喂数据给它。

添加数据源：在索引创建完成后，进入该索引的详情页，选择“数据源”选项卡，点击“添加数据源”。
选择 S3：从列表中选择“Amazon S3”。
配置数据源：
- 名称：s3-product-manuals。
- 描述：可选。
- S3 存储桶：输入或浏览选择你之前创建的存储桶。
- 包含模式：如果你只想同步某个文件夹，可以指定前缀，如ProductA/。留空则同步整个桶。
- 排除模式：可以排除某些临时文件或日志，例如*.tmp。
- 文档元数据：这里可以配置如何从 S3 对象中提取元数据。一个非常有用的技巧是利用 S3 对象标签或自定义元数据。例如，你可以在上传文档时，为每个对象添加标签product=ProductA和doc_type=manual。Kendra 可以读取这些标签作为文档的元数据字段，后续搜索时可以用来筛选。
设置同步计划：
- 同步模式：选择“定期同步”。
- 频率：对于不常变动的产品手册，可以设置为每天一次，或在低峰时段运行。你也可以选择“按需运行”，手动触发同步。
- 增量同步：务必确保启用。这样后续同步只会处理新增或修改的文件，速度极快，成本也低。
IAM 角色：再次确认或选择之前创建的那个 IAM 角色。
创建并运行：点击“添加”。数据源创建后，你可以立即点击“立即同步”来触发第一次全量数据摄取。

实操心得：第一次全量同步的时间取决于文档的数量和大小。控制台会显示同步状态和进度。一定要有耐心，并去 CloudWatch 查看 Kendra 的日志流（日志组通常为/aws/kendra/index-id），里面会有详细的处理信息，包括哪些文档成功、哪些失败（例如，加密的文档、损坏的文件会失败）。这是排查问题的第一现场。

3.4 测试搜索与体验优化

数据同步完成后（状态显示“已完成”且没有错误），你的智能搜索引擎就准备好了！

使用控制台搜索栏测试：在索引的详情页顶部，就有一个搜索框。尝试用自然语言提问。
- 低级问题：“ProductA 的安装步骤”
- 高级问题：“如何解决 ProductB 在启动时报错‘内存不足’的问题？”
- 对比一下传统关键词搜索：“安装步骤 ProductA” 和自然语言提问的返回结果差异。
解读搜索结果：
- 答案片段：最相关的答案可能会被直接提取并显示在结果顶部。
- 文档结果：下方是相关的文档列表，包含标题、来源、一段摘要。
- 相关性分数：每个结果都有一个置信度分数（通常不直接显示，但排序依据它）。
- 元数据筛选器：如果配置了元数据（如产品线、文档类型），页面左侧会出现筛选面板，用户可以快速缩小范围。
初步优化：
- 调整答案置信度阈值：在索引设置中，可以调整“精确答案”的置信度阈值。如果发现它经常提取错误的答案片段，可以适当调高阈值，宁可少显示，也要保证准确。
- 查看搜索分析：Kendra 控制台提供了搜索分析面板，可以看到热门查询、零结果查询等。这是优化数据源和查询理解的重要依据。

至此，一个最基本但功能强大的企业智能搜索系统就搭建完成了。但这只是开始，要让它真正在生产环境发挥威力，还需要更深入的调优和问题处理。

4. 高级配置与性能调优实战

一个能用的搜索和一个好用的搜索之间，隔着无数细节的打磨。这部分，我们深入那些让 Kendra 从“不错”变得“卓越”的高级配置和调优技巧。

4.1 文档级权限与安全性集成

在企业中，搜索必须安全。你不能让一个普通员工搜到高管的薪酬文件。Kendra 通过访问控制列表（ACL）来实现文档级安全性。

原理：Kendra 在索引文档时，会同时索引该文档的“访问权限列表”。这个列表定义了哪些用户/组可以访问该文档。当用户执行搜索时，Kendra 会先根据用户的身份过滤掉所有他无权访问的文档，然后再在剩下的文档中进行语义检索和排序。
如何实现：
1. 数据源支持：并非所有数据源都支持 ACL。SharePoint Online、OneDrive、ServiceNow 等本身具有完善权限系统的数据源，其连接器可以自动同步 ACL 信息。对于S3，则需要通过自定义属性来手动实现。
2. S3 的 ACL 模拟：在配置 S3 数据源时，你可以创建一个“访问控制配置”。你需要提供一个 JSON 文件（通常也放在 S3），该文件定义了每个文档（S3 对象键）对应的允许访问的用户/组列表（通常用 LDAP 或 Cognito 中的组名表示）。
3. 查询时授权：在通过 Search API 查询时，你必须传入一个UserContext对象，其中包含当前用户的身份标识（如Token或UserId）。Kendra 会利用这个身份去匹配文档的 ACL。
注意事项：实现 ACL 会增加索引的复杂性和大小，并且要求你的前端应用能安全地获取和传递用户身份信息。对于内部应用，可以集成 AWS Cognito 或企业 SAML 身份提供商（如 Okta, Azure AD）。

4.2 自定义词典与同义词扩展

每个公司都有自己的“黑话”和缩写。Kendra 的默认模型可能不认识“FY23”、“K8s”、“我们内部的‘彩虹表’系统”。这时就需要自定义词典。

业务术语：在索引设置中，你可以上传一个 CSV 文件，定义业务术语及其解释。例如，FY23, 2023财年。这有助于 Kendra 在索引和查询时识别这些术语，提升相关性。
同义词：你可以定义同义词库。例如，将“笔记本”、“手提电脑”、“Laptop”定义为同义词。这样，无论用户搜索哪个词，都能找到相关的文档。这对于统一产品名称、部门别名等非常有效。
停用词：你可以添加公司特定的停用词，让 Kendra 忽略它们。但一般情况下，不建议过多修改，因为 Kendra 的语义模型已经能很好地处理常见停用词。

4.3 调整相关性排序：权威性与新鲜度

为什么官方发布的产品白皮书应该比某个工程师的个人博客排名更靠前？为什么上个月发布的故障排除指南应该比三年前的旧版本更相关？Kendra 允许你通过调整“权重”来影响排序。

文档权威性：你可以给不同的数据源、文档类型、甚至基于 URL 路径模式设置不同的权威性权重（例如 0-10）。例如：
- 官方产品文档网站 (docs.company.com)：权重 10
- 内部技术维基 (wiki.internal)：权重 7
- 员工个人博客目录 (blogs/)：权重 3 在排序时，权威性高的文档会获得加分。
新鲜度衰减：你可以设置一个时间衰减函数。例如，规定文档的相关性随着时间推移而缓慢下降。这样，一篇三年前和一篇上周关于“K8s 部署”的文档，即使语义相似度相同，新的那篇也会排名更高。这对于技术文档、新闻、政策类搜索至关重要。

4.4 利用查询增强提升意图理解

有时用户的查询很短、很模糊。例如，只搜索“错误”。Kendra 的“查询增强”功能可以自动或手动地扩展查询，以更好地理解意图。

同义词扩展：基于你配置的同义词库自动扩展。
时间范围感知：当查询中包含“上周”、“本季度”等词时，Kendra 可以自动将其转换为具体的日期范围，并用于筛选。
个性化（高级功能）：如果启用了个性化搜索，Kendra 可以根据用户的历史搜索和点击行为，微调其查询的表示，使其更符合该用户的兴趣和上下文。

调优是一个持续的过程。没有一劳永逸的“最佳配置”。你需要：

收集反馈：在搜索界面添加“结果是否有用？”的反馈按钮。
分析日志：定期查看 Kendra 的搜索分析仪表板，关注“零结果查询”和“低点击率查询”。
A/B 测试：对于重大的配置变更（如调整权威性权重），可以创建索引的副本进行测试，对比新老版本的效果。

5. 集成开发与 API 深度使用

控制台适合管理和测试，但真正的力量在于通过 API 将 Kendra 集成到你自己的应用程序中。无论是内部门户、聊天机器人还是移动应用，API 提供了最大的灵活性。

5.1 核心 API 操作概览

AWS 为 Kendra 提供了完善的 SDK（支持 Python、Java、JavaScript 等）。核心操作围绕两个端点：Query和Retrieve（以及管理索引的Index相关 API）。

QueryAPI：这是最常用的 API，用于执行搜索并返回结构化的结果，包括精确答案、文档列表、相关问题和分面信息。
RetrieveAPI：这是一个更底层的 API，它只返回与查询最相关的文档段落（块），而不进行复杂的答案提取和排序重排。适用于你希望自己处理结果排序和呈现的场景，或者用于构建检索增强生成（RAG）系统，将这些段落作为上下文提供给大语言模型（如 Amazon Bedrock 上的 Claude）。
SubmitFeedbackAPI：用于提交用户对搜索结果的反馈（相关/不相关），这些反馈数据会被 Kendra 用于改进模型。

5.2 使用 Python (Boto3) 进行查询集成示例

以下是一个简单的 Python 脚本，演示如何调用QueryAPI：

import boto3 import json # 初始化 Kendra 客户端 client = boto3.client('kendra', region_name='us-east-1') # 替换为你的区域 # 你的索引 ID index_id = 'YOUR_INDEX_ID' def search_kendra(query_text, user_context=None): """ 执行 Kendra 搜索 :param query_text: 用户查询字符串 :param user_context: 可选的用户上下文，用于 ACL 过滤 :return: 搜索结果 """ request_params = { 'IndexId': index_id, 'QueryText': query_text, 'PageNumber': 1, 'PageSize': 10 # 每页结果数 } # 如果启用了 ACL，必须传入 UserContext if user_context: request_params['UserContext'] = user_context # 可选：请求返回精确答案 request_params['AttributeFilter'] = { "AndAllFilters": [ { "EqualsTo": { "Key": "_language_code", "Value": {"StringValue": "zh"} # 假设我们主要处理中文文档 } } ] } # 注意：精确答案（`QueryResultType` 为 `ANSWER`）通常会自动返回，无需特别指定。 # 上面的 AttributeFilter 是一个示例，用于按元数据过滤。 try: response = client.query(**request_params) return response except Exception as e: print(f"搜索出错: {e}") return None # 示例查询 results = search_kendra("如何配置产品的自动备份功能？") if results: # 1. 处理精确答案 if 'ResultItems' in results: for item in results['ResultItems']: item_type = item.get('Type') if item_type == 'ANSWER': print(f"[精确答案] {item['DocumentExcerpt']['Text']}") print(f" 来源: {item['DocumentTitle']['Text']}") print(f" 置信度: {item.get('ScoreAttributes', {}).get('ScoreConfidence', 'N/A')}") elif item_type == 'DOCUMENT': print(f"[相关文档] {item['DocumentTitle']['Text']}") print(f" 摘要: {item['DocumentExcerpt']['Text'][:200]}...") # 截取部分摘要 print(f" 链接: {item.get('DocumentURI', 'N/A')}") # 2. 处理相关的问题建议（如果存在） if 'FeaturedResultsItems' in results: print("\n[相关问题]") for fr in results['FeaturedResultsItems']: print(f" - {fr.get('DocumentTitle', {}).get('Text')}")

5.3 构建一个简单的检索增强生成（RAG）流水线

这是当前最热门的应用模式之一：用 Kendra 作为“事实记忆库”，为大语言模型提供准确、最新的上下文，避免其“胡言乱语”。

用户提问：用户问：“我们公司最新的差旅报销标准是什么？”
检索：你的应用调用 Kendra 的RetrieveAPI，传入问题。Kendra 返回最相关的几个文档段落（例如，来自最新版《财务管理制度》PDF 的特定章节）。

构造提示词：将这些段落作为上下文，和用户问题一起，构造一个提示词给大语言模型（如通过 Bedrock 调用 Claude）：

请基于以下上下文信息回答问题。如果上下文信息不足以回答问题，请直接说“根据现有信息无法回答”。 上下文： 《财务管理制度-2023版》，第五章：...（此处插入Kendra返回的段落）... 《员工手册》，差旅部分：...（此处插入Kendra返回的段落）... 问题：我们公司最新的差旅报销标准是什么？

生成与返回：LLM 基于你提供的“事实”上下文生成答案，从而保证答案的准确性和时效性。你可以将生成的答案和 Kendra 返回的源文档一起呈现给用户，做到既有准确回答，又有据可查。

这种模式完美结合了 Kendra 的精准检索能力和 LLM 的强大语言生成能力，是构建企业级知识问答机器人的黄金组合。

6. 成本控制、监控与常见问题排查

将 Kendra 用于生产，必须关注其运行状态和成本。

6.1 成本构成与优化策略

Kendra 的成本主要来自三部分：

索引单元费用：这是固定成本，按小时计费。每个索引单元提供一定的存储容量和查询吞吐量。选择多少单元，取决于你的文档量和预期查询量。技巧：从小规模开始（1个单元），根据监控指标（存储使用率、查询延迟）逐步调整。
查询费用：按每次查询（Query API 调用）计费。优化点：
- 实现前端搜索框的防抖（Debounce），避免用户每输入一个字符就发起一次查询。
- 对常见问题，考虑使用缓存（如 Amazon ElastiCache 或简单的内存缓存），将热门问题的答案缓存一段时间。
存储与同步费用：存储文档向量和元数据需要费用。同步数据（尤其是全量同步）会产生少量的读写费用。优化点：
- 定期清理数据源中过期或无效的文档。
- 善用增量同步，避免不必要的全量同步。
- 对于 S3 数据源，注意 S3 本身的存储和请求费用。

6.2 关键监控指标与告警设置

在 Amazon CloudWatch 中监控 Kendra：

SuccessfulQueryCount/FailedQueryCount：查询成功/失败次数。失败激增可能意味着 API 调用错误或权限问题。
QueryLatency：查询延迟（P50, P90, P99）。延迟过高可能影响用户体验，可能需要增加索引单元。
StorageUtilization：索引存储使用率。接近100%时需要增加索引单元或清理数据。
数据源同步状态：在 Kendra 控制台直接查看同步历史，确保数据源同步成功，没有大量错误。

建议为FailedQueryCount和StorageUtilization设置 CloudWatch 告警，以便及时发现问题。

6.3 常见问题与排查清单

以下是我在项目中遇到的一些典型问题及解决方法：

问题现象	可能原因	排查步骤与解决方案
搜索返回零结果或结果不相关	1. 数据未成功同步。 2. 文档格式不支持或解析失败。 3. 查询语言与索引语言不匹配。 4. 查询太模糊。	1. 检查数据源同步状态和 CloudWatch 日志，看是否有处理错误。 2. 确认文档格式在Kendra支持列表中。对于复杂格式（如多层扫描PDF），可尝试先转换为纯文本。 3. 在创建索引时选择了主要语言（如中文），查询也应用中文。 4. 引导用户输入更具体的问题，或在后端尝试查询增强。
用户搜索时看到无权访问的文档	ACL 配置不正确或未在查询时传入`UserContext`。	1. 确认数据源连接器支持并正确配置了 ACL 同步（如 SharePoint）。 2. 对于 S3，检查访问控制配置 JSON 文件是否正确。 3. 确认调用 Query API 时，传入了正确的`UserContext`参数。
精确答案置信度低，经常提取错误	答案置信度阈值设置过低，或文档中答案表述不明确。	1. 在索引设置中调高“精确答案置信度”阈值。 2. 优化文档结构，确保关键信息（如 Q&A、步骤列表）格式清晰。
查询延迟很高（>1秒）	1. 索引单元容量不足。 2. 查询过于复杂或返回结果过多。 3. 网络延迟。	1. 监控`QueryLatency`和`StorageUtilization`，考虑增加索引单元。 2. 优化查询，鼓励用户使用更具体的词语。在 API 调用中合理设置`PageSize`。 3. 确保应用服务器和 Kendra 索引在同一 AWS 区域。
同步失败，大量文档错误	1. 文件损坏或加密。 2. 权限不足（IAM 角色策略错误）。 3. 不支持的字符编码或文件大小超限。	1. 查看 CloudWatch 日志中具体的错误信息，定位失败文档。 2. 仔细检查数据源 IAM 角色的策略，确保其对 S3 存储桶有`ListBucket`和`GetObject`权限。 3. 检查 Kendra 的服务配额和文件限制（如单个文件大小）。