终止支持通知：2025年9月15日， AWS 我们将停止对Amazon Lex V1的支持。2025 年 9 月 15 日之后，您将无法再访问 Amazon Lex V1 控制台或 Amazon Lex V1 资源。如果您使用的是 Amazon Lex V2，请改为参阅 [Amazon Lex V2 指南](https://docs.aws.amazon.com/lexv2/latest/dg/what-is.html)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AMAZON.KendraSearchIntent
要搜索已使用 Amazon Kendra 编制索引的文档，请使用 `AMAZON.KendraSearchIntent` 意图。在与用户进行的对话中，如果 Amazon Lex 无法确定下一个操作，则会触发搜索意图。
`AMAZON.KendraSearchIntent` 仅适用于英语（美国）(en-US) 区域设置以及美国东部（弗吉尼亚州北部）、美国西部（俄勒冈州）和欧洲地区（爱尔兰）区域。
Amazon Kendra 是一项 machine-learning-based搜索服务，用于索引 PDF 文档或微软 Word 文件等自然语言文档。它可以搜索已编制索引的文档并为问题返回以下类型的响应：
+ 答案
+ 可能是问题答案的常见问题解答条目
+ 与问题相关的文档
有关使用 `AMAZON.KendraSearchIntent` 的示例，请参阅[示例：为 Amazon Kendra 索引创建常见问题机器人](faq-bot-kendra-search.md)。
如果您为机器人配置了 `AMAZON.KendraSearchIntent` 意图，则 Amazon Lex 在无法确定插槽或意图的用户言语时，会调用该意图。例如，如果您的机器人引发名为“披萨配料”的插槽类型的响应，而用户问的是“什么是披萨？”，Amazon Lex 将调用 `AMAZON.KendraSearchIntent` 来处理此问题。如果没有来自 Amazon Kendra 的响应，则对话将按照机器人中的配置继续进行。
当您在同一机器人中同时使用 `AMAZON.KendraSearchIntent` 和 `AMAZON.FallbackIntent` 时，Amazon Lex 将按照以下方式使用意图：
1. Amazon Lex 调用 `AMAZON.KendraSearchIntent`。该意图调用 Amazon Kendra `Query` 操作。
1. 如果 Amazon Kendra 返回响应，则 Amazon Lex 向用户显示该结果。
1. 如果没有来自 Amazon Kendra 的响应，则 Amazon Lex 将重新提示用户。下一个操作取决于用户的响应。
+ 如果用户的响应包含 Amazon Lex 可识别的言语（例如填充插槽值或确认意图），则与用户的对话将按照机器人的配置继续进行。
+ 如果用户的响应未包含 Amazon Lex 可识别的言语，则 Amazon Lex 将再次调用 `Query` 操作。
1. 如果在配置的重试次数之后没有响应，Amazon Lex 将调用 `AMAZON.FallbackIntent` 并结束与用户的对话。
有三种方法可以使用 `AMAZON.KendraSearchIntent` 向 Amazon Kendra 发出请求：
+ 让搜索意图为您提出请求。Amazon Lex 以用户的言语作为搜索字符串调用 Amazon Kendra。在创建意图时，您可以定义限制 Amazon Kendra 返回的响应数的查询筛选条件字符串。Amazon Lex 使用查询请求中的筛选条件。
+ 使用您的对话 Lambda 函数向请求添加其他查询参数以缩小搜索结果范围。您将包含 Amazon Kendra 查询参数的 `kendraQueryFilterString` 字段添加到 `delegate` 对话操作。使用 Lambda 函数向请求添加查询参数时，这些查询参数将优先于您在创建意图时定义的查询筛选条件。
+ 使用对话 Lambda 函数创建新查询。您可以创建 Amazon Lex 发送的完整 Amazon Kendra 查询请求。您可以在 `delegate` 对话操作的 `kendraQueryRequestPayload` 字段中指定查询。`kendraQueryRequestPayload` 字段优先于 `kendraQueryFilterString` 字段。
要在创建机器人时指定 `queryFilterString` 参数，或者在对话 Lambda 函数中调用 `delegate` 操作时指定 `kendraQueryFilterString` 字段，请指定用作 Amazon Kendra 查询的属性筛选条件的字符串。如果字符串不是有效的属性筛选器，您将在运行时收到 `InvalidBotConfigException` 异常。有关属性筛选条件的更多信息，请参阅《Amazon Kendra 开发人员指南》**中的[使用文档属性筛选查询](https://docs.aws.amazon.com/kendra/latest/dg/filtering.html#search-filtering)。
要控制 Amazon Lex 发送到 Amazon Kendra 的查询，您可以在对话 Lambda 函数的 `kendraQueryRequestPayload` 字段中指定查询。如果查询无效，则 Amazon Lex 返回 `InvalidLambdaResponseException` 异常。有关更多信息，请参阅《Amazon Kendra 开发人员指南》**中的[查询操作](https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html)。
有关如何使用 `AMAZON.KendraSearchIntent` 的示例，请参阅[示例：为 Amazon Kendra 索引创建常见问题机器人](faq-bot-kendra-search.md)。
## Amazon Kendra 搜索的 IAM 策略
要使用该`AMAZON.KendraSearchIntent`意图，您必须使用能够提供 AWS Identity and Access Management (IAM) 策略的角色，这些策略允许 Amazon Lex 担任有权调用 Amazon Kendra `Query` 意图的运行时角色。您使用的 IAM 设置取决于您是使用 Amazon Lex 控制台创建，还是使用 AWS 开发工具包或 AWS Command Line Interface (AWS CLI) 创建。`AMAZON.KendraSearchIntent`使用控制台时，您可以选择向 Amazon Lex 服务相关角色添加调用 Amazon Kendra 的权限，或使用专门用于调用 Amazon Kendra `Query` 操作的角色。使用 AWS CLI 或 SDK 创建 Intent 时，必须使用专门用于调用`Query`操作的角色。
### 附加权限
您可以使用控制台将访问 Amazon Kendra `Query` 操作的权限附加到默认 Amazon Lex 服务相关角色。当您将权限附加到服务相关角色时，无需专门创建和管理运行时角色即可连接到 Amazon Kendra 索引。
用于访问 Amazon Lex 控制台的用户、角色或组必须有权限管理角色策略。将以下 IAM 策略附加到控制台访问角色。当您授予这些权限时，角色将有权更改现有服务相关角色策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:PutRolePolicy",
"iam:GetRolePolicy"
],
"Resource": "arn:aws:iam::*:role/aws-service-role/lex.amazonaws.com/AWSServiceRoleForLexBots"
},
{
"Effect": "Allow",
"Action": "iam:ListRoles",
"Resource": "*"
}
]
}
```
------
### 指定角色
您可以使用控制台 AWS CLI、或 API 来指定在调用 Amazon Kendra `Query` 操作时要使用的运行时角色。
用于指定运行时角色的用户、角色或组必须具有 `iam:PassRole` 权限。以下策略定义权限。您可以使用 `iam:AssociatedResourceArn` 和 `iam:PassedToService` 条件上下文键进一步限制权限的范围。有关更多信息，请参阅*AWS Identity and Access Management 用户指南*[中的 IAM 和 AWS STS 条件上下文密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::{{111122223333}}:role/{{role}}"
}
]
}
```
------
Amazon Lex 调用 Amazon Kendra 时所需使用的运行时角色必须具有 `kendra:Query` 权限。当您使用现有 IAM 角色获取调用 Amazon Kendra `Query` 操作的权限时，该角色必须附加以下策略。
您可以使用 IAM 控制台、IAM API 或 AWS CLI 创建策略并将其附加到角色。这些说明使用 AWS CLI 创建角色和策略。
**注意**
以下代码针对 Linux 和 macOS 编排了格式。对于 Windows，将 Linux 行继续符（\\）替换为脱字号（^）。
**向角色添加 Query 操作权限**
1. 在当前目录中创建一个名为 **KendraQueryPolicy.json** 的文档，向其中添加以下代码并保存
1. 在中 AWS CLI，运行以下命令来创建用于运行 Amazon Kendra `Query` 操作的 IAM 策略。
```
aws iam create-policy \
--policy-name {{query-policy-name}} \
--policy-document file://KendraQueryPolicy.json
```
1. 将该策略附加到用于调用 `Query` 操作的 IAM 角色。
```
aws iam attach-role-policy \
--policy-arn arn:aws:iam::{{account-id}}:policy/{{query-policy-name}}
--role-name {{role-name}}
```
您可以选择更新 Amazon Lex 服务相关角色或使用您在为机器人创建 `AMAZON.KendraSearchIntent` 时所创建的角色。以下过程演示如何选择要使用的 IAM 角色。
**为亚马逊指定运行时角色。 KendraSearchIntent**
1. 登录 AWS 管理控制台 并打开 Amazon Lex 控制台，网址为[https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/)。
1. 选择要向其添加 `AMAZON.KendraSearchIntent` 的自动程序。
1. 选择**意图**旁边的加号（\+）。
1. 在**添加意图**中，选择**搜索现有意图**。
1. 在**搜索意图**中，输入 **AMAZON.KendraSearchIntent**，然后选择**添加**。
1. 在**复制内置意图**中，输入意图的名称，如 **KendraSearchIntent**，然后选择**添加**。
1. 打开 **Amazon Kendra 查询**部分。
1. 对于 **IAM 角色**，选择下列选项之一：
+ 要更新 Amazon Lex 服务相关角色以便机器人能够查询 Amazon Kendra 索引，请选择**添加 Amazon Kendra 权限**。
+ 要使用有权调用 Amazon Kendra `Query` 操作的角色，请选择**使用现有角色**。
## 使用请求和会话属性作为筛选器
要从来自 Amazon Kendra 的响应中筛选出与当前对话相关的项目，请在创建机器人时添加 `queryFilterString` 参数以使用会话和请求属性作为筛选条件。您可以在创建意图时指定属性的占位符，以便 Amazon Lex V2 在调用 Amazon Kendra 之前将其替换为值。有关请求属性的更多信息，请参阅[设置请求属性](context-mgmt-request-attribs.md)。有关会话属性的更多信息，请参阅 [设置会话属性](context-mgmt-session-attribs.md)。
以下是使用字符串来筛选 Amazon Kendra 查询的 `queryFilterString` 参数示例。
```
"{"equalsTo": {"key": "City", "value": {"stringValue": "Seattle"}}}"
```
以下是使用名为 `"SourceURI"` 的会话属性来筛选 Amazon Kendra 查询的 `queryFilterString` 参数示例。
```
"{"equalsTo": {"key": "SourceURI","value": {"stringValue": "[FileURL]"}}}"
```
以下是使用名为 `"DepartmentName"` 的请求属性来筛选 Amazon Kendra 查询的 `queryFilterString` 参数示例。
```
"{"equalsTo": {"key": "Department","value": {"stringValue": "((DepartmentName))"}}}"
```
`AMAZON.KendraSearchInteng` 筛选条件使用的格式与 Amazon Kendra 搜索筛选条件的格式相同。有关更多信息，请参阅《Amazon Kendra 开发人员指南》**中的[使用文档属性筛选搜索结果](https://docs.aws.amazon.com/kendra/latest/dg/filtering.html#search-filtering)。
与 `AMAZON.KendraSearchIntent` 一起使用的查询筛选条件字符串必须确保每个筛选条件的首字母为小写字母。例如，以下是 `AMAZON.KendraSearchIntent` 的有效查询筛选条件。
```
{
"andAllFilters": [
{
"equalsTo": {
"key": "City",
"value": {
"stringValue": "Seattle"
}
}
},
{
"equalsTo": {
"key": "State",
"value": {
"stringValue": "Washington"
}
}
}
]
}
```
## 使用搜索响应
Amazon Kendra 在意图的 `conclusion` 语句中返回搜索的响应。除非履行 Lambda 函数生成结论消息，否则意图必须具有 `conclusion` 语句。
Amazon Kendra 有四种类型的响应。
+ `x-amz-lex:kendra-search-response-question_answer-question-` — 与搜索匹配的常见问题中的问题。
+ `x-amz-lex:kendra-search-response-question_answer-answer-` — 与搜索匹配的常见问题中的答案。
+ `x-amz-lex:kendra-search-response-document-` — 索引中与言语文本相关的文档摘录。
+ `x-amz-lex:kendra-search-response-document-link-` — 索引中与言语文本相关的文档的 URL。
+ `x-amz-lex:kendra-search-response-answer-` — 索引中能作为问题答案的文档摘录。
在 `request` 属性中返回响应。每个属性最多可以具有五个响应，编号为 1 到 5。有关响应的更多信息，请参阅《Amazon Kendra 开发人员指南》**中的[响应类型](https://docs.aws.amazon.com/kendra/latest/dg/response-types.html)。
`conclusion` 语句必须具有一个或多个消息组。每个消息组都包含一条或多条消息。每条消息均可以包含一个或多个占位符变量，这些变量替换为来自 Amazon Kendra 的响应中的请求属性。消息组中必须至少有一条消息的所有变量都由运行时响应中的请求属性值替换，或者组中必须有一条没有占位符变量的消息。请求属性使用双括号（“（（”“））”）进行设置。以下消息组消息与来自 Amazon Kendra 的任何响应匹配：
+ “我为你找到了一个常见问题解答问题：((x-amz-lex: kendra-search-response-question \_answer-question-1))，答案是 ((: \_answer-answer-answer-1))” x-amz-lex kendra-search-response-question
+ “我找到了一份有用的文档的摘录：((x-amz-lex: kendra-search-response-document -1))”
+ “我想你的问题的答案是 ((x-amz-lex: kendra-search-response-answer -1))”
## 使用 Lambda 函数管理请求和响应
`AMAZON.KendraSearchIntent` 意图可以使用您的对话代码挂钩和履行代码挂钩来管理对 Amazon Kendra 的请求和响应。当您想要修改发送到 Amazon Kendra 的查询时，请使用对话代码挂钩 Lambda 函数；当您想要修改响应时，请使用履行代码挂钩 Lambda 函数。
### 使用对话代码挂钩创建查询
您可以使用对话代码挂钩创建要发送到 Amazon Kendra 的查询。使用对话代码挂钩是可选的。如果您未指定对话代码挂钩，则 Amazon Lex 会根据用户言语来构造查询并使用您在配置意图时提供的 `queryFilterString`（如有）。
您可以在对话代码挂钩响应中使用两个字段来修改对 Amazon Kendra 的请求：
+ `kendraQueryFilterString` — 使用此字符串为 Amazon Kendra 请求指定属性筛选条件。您可以使用索引中定义的任何索引字段筛选查询。有关筛选字符串的结构，请参阅《Amazon Kendra 开发人员指南》**中的[使用文档属性筛选查询](https://docs.aws.amazon.com/kendra/latest/dg/filtering.html#search-filtering)。如果指定的筛选器字符串无效，则会出现 `InvalidLambdaResponseException` 异常。`kendraQueryFilterString` 字符串将覆盖为意图配置的 `queryFilterString` 中指定的任何查询字符串。
+ `kendraQueryRequestPayload` — 使用此字符串指定 Amazon Kendra 查询。您的查询可以使用 Amazon Kendra 的任何功能。如果您没有指定有效的查询，则会出现 `InvalidLambdaResponseException` 异常。有关更多信息，请参阅《Amazon Kendra 开发人员指南》**中的[查询](https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html)。
创建筛选条件或查询字符串后，将响应发送到 Amazon Lex，并将响应的 `dialogAction` 字段设置为 `delegate`。Amazon Lex 将查询发送到 Amazon Kendra，然后将查询响应返回给履行代码挂钩。
### 对响应使用实现代码挂钩
在 Amazon Lex 将查询发送到 Amazon Kendra 后，查询响应将返回到 `AMAZON.KendraSearchIntent` 履行 Lambda 函数。代码挂钩的输入事件包含来自 Amazon Kendra 的完整响应。查询数据与 Amazon Kendra `Query` 操作返回的结构相同。有关更多信息，请参阅《Amazon Kendra 开发人员指南》**中的[查询响应语法](https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html#API_Query_ResponseSyntax)。
实现代码挂钩是可选的。如果代码挂钩不存在，或者代码挂钩未在响应中返回消息，则 Amazon Lex 将对响应使用 `conclusion` 语句。