AMAZON.KendraSearchIntent - Amazon Lex V1
IAM 策略使用请求和会话属性作为筛选器使用搜索响应使用 Lambda 函数管理请求和响应

如果您使用的是 Amazon Lex V2，请改为参阅 Amazon Lex V2 指南。

 

如果您使用的是 Amazon Lex V1，我们建议您将机器人升级到 Amazon Lex V2。我们不再向 V1 添加新功能，强烈建议使用 V2 以获得全新的机器人。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AMAZON.KendraSearchIntent

要搜索已使用 Amazon Kendra 编制索引的文档，请使用 AMAZON.KendraSearchIntent 意图。在与用户进行的对话中，如果 Amazon Lex 无法确定下一个操作，则会触发搜索意图。

AMAZON.KendraSearchIntent 仅适用于英语（美国）(en-US) 区域设置以及美国东部（弗吉尼亚州北部）、美国西部（俄勒冈州）和欧洲地区（爱尔兰）区域。

Amazon Kendra 是一种基于机器学习的搜索服务，可为自然语言文档（例如 PDF 文档或 Microsoft Word 文件）编制索引。它可以搜索已编制索引的文档并为问题返回以下类型的响应：

  • 答案

  • 可能是问题答案的常见问题解答条目

  • 与问题相关的文档

有关使用 AMAZON.KendraSearchIntent 的示例，请参阅示例：为 Amazon Kendra 索引创建常见问题机器人。

如果您为机器人配置了 AMAZON.KendraSearchIntent 意图，则 Amazon Lex 在无法确定插槽或意图的用户言语时，会调用该意图。例如，如果您的机器人引发名为“披萨配料”的插槽类型的响应，而用户问的是“什么是披萨？”，Amazon Lex 将调用 AMAZON.KendraSearchIntent 来处理此问题。如果没有来自 Amazon Kendra 的响应，则对话将按照机器人中的配置继续进行。

当您在同一机器人中同时使用 AMAZON.KendraSearchIntent 和 AMAZON.FallbackIntent 时，Amazon Lex 将按照以下方式使用意图：

  1. Amazon Lex 调用 AMAZON.KendraSearchIntent。该意图调用 Amazon Kendra Query 操作。

  2. 如果 Amazon Kendra 返回响应，则 Amazon Lex 向用户显示该结果。

  3. 如果没有来自 Amazon Kendra 的响应，则 Amazon Lex 将重新提示用户。下一个操作取决于用户的响应。

    • 如果用户的响应包含 Amazon Lex 可识别的言语（例如填充插槽值或确认意图），则与用户的对话将按照机器人的配置继续进行。

    • 如果用户的响应未包含 Amazon Lex 可识别的言语，则 Amazon Lex 将再次调用 Query 操作。

  4. 如果在配置的重试次数之后没有响应，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 开发人员指南》中的使用文档属性筛选查询。

要控制 Amazon Lex 发送到 Amazon Kendra 的查询，您可以在对话 Lambda 函数的 kendraQueryRequestPayload 字段中指定查询。如果查询无效，则 Amazon Lex 返回 InvalidLambdaResponseException 异常。有关更多信息，请参阅《Amazon Kendra 开发人员指南》中的查询操作。

有关如何使用 AMAZON.KendraSearchIntent 的示例，请参阅示例：为 Amazon Kendra 索引创建常见问题机器人。

Amazon Kendra 搜索的 IAM 策略

要使用 AMAZON.KendraSearchIntent 意图，您必须使用提供 AWS Identity and Access Management (IAM) 策略的角色，这些策略允许 Amazon Lex 代入有权限调用 Amazon Kendra Query 意图的运行时角色。您使用的 IAM 设置取决于您是使用 Amazon Lex 控制台还是使用 AWS SDK 或 AWS Command Line Interface (AWS CLI) 创建 AMAZON.KendraSearchIntent。使用控制台时，您可以选择向 Amazon Lex 服务相关角色添加调用 Amazon Kendra 的权限，或使用专门用于调用 Amazon Kendra Query 操作的角色。使用 AWS CLI 或软件开发工具包创建目的时，必须使用专门用于调用 Query 操作的角色。

附加权限

您可以使用控制台将访问 Amazon Kendra Query 操作的权限附加到默认 Amazon Lex 服务相关角色。当您将权限附加到服务相关角色时，无需专门创建和管理运行时角色即可连接到 Amazon Kendra 索引。

用于访问 Amazon Lex 控制台的用户、角色或组必须有权限管理角色策略。将以下 IAM 策略附加到控制台访问角色。当您授予这些权限时，角色将有权更改现有服务相关角色策略。

{
    "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 条件上下文键。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::account: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 的文档，向其中添加以下代码并保存

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kendra:Query"
            ],
            "Resource": [
                "arn:aws:kendra:region:account:index/index ID"
            ]
        }
    ]
}

  2. 在 AWS CLI 中，运行以下命令来创建用于运行 Amazon Kendra Query 操作的 IAM 策略。

    aws iam create-policy \
    --policy-name query-policy-name \
    --policy-document file://KendraQueryPolicy.json

  3. 将该策略附加到用于调用 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 角色。

为 AMAZON.KendraSearchIntent 指定运行时角色

  1. 登录 AWS Management Console，然后通过以下网址打开 Amazon Lex 控制台：https://console.aws.amazon.com/lex/。

  2. 选择要向其添加 AMAZON.KendraSearchIntent 的自动程序。

  3. 选择目的旁边的加号 (+)。

  4. 在添加目的中，选择搜索现有目的。

  5. 在搜索目的中，输入 AMAZON.KendraSearchIntent，然后选择添加。

  6. 在复制内置目的中，输入目的的名称，如 KendraSearchIntent，然后选择添加。

  7. 打开 Amazon Kendra 查询部分。

  8. 对于 IAM 角色，选择下列选项之一：

    • 要更新 Amazon Lex 服务相关角色以便机器人能够查询 Amazon Kendra 索引，请选择添加 Amazon Kendra 权限。

    • 要使用有权调用 Amazon Kendra Query 操作的角色，请选择使用现有角色。

使用请求和会话属性作为筛选器

要从来自 Amazon Kendra 的响应中筛选出与当前对话相关的项目，请在创建机器人时添加 queryFilterString 参数以使用会话和请求属性作为筛选条件。您可以在创建意图时指定属性的占位符，以便 Amazon Lex V2 在调用 Amazon Kendra 之前将其替换为值。有关请求属性的更多信息，请参阅设置请求属性。有关会话属性的更多信息，请参阅 设置会话属性。

以下是使用字符串来筛选 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 开发人员指南》中的使用文档属性筛选搜索结果。

与 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-<N> — 与搜索匹配的常见问题中的问题。

  • x-amz-lex:kendra-search-response-question_answer-answer-<N> — 与搜索匹配的常见问题中的答案。

  • x-amz-lex:kendra-search-response-document-<N> — 索引中与言语文本相关的文档摘录。

  • x-amz-lex:kendra-search-response-document-link-<N> — 索引中与言语文本相关的文档的 URL。

  • x-amz-lex:kendra-search-response-answer-<N> — 索引中能作为问题答案的文档摘录。

在 request 属性中返回响应。每个属性最多可以具有五个响应，编号为 1 到 5。有关响应的更多信息，请参阅《Amazon Kendra 开发人员指南》中的响应类型。

conclusion 语句必须具有一个或多个消息组。每个消息组都包含一条或多条消息。每条消息均可以包含一个或多个占位符变量，这些变量替换为来自 Amazon Kendra 的响应中的请求属性。消息组中必须至少有一条消息的所有变量都由运行时响应中的请求属性值替换，或者组中必须有一条没有占位符变量的消息。请求属性使用双括号（“((”“))”）进行设置。以下消息组消息与来自 Amazon Kendra 的任何响应匹配：

  • “I found a FAQ question for you: ((x-amz-lex:kendra-search-response-question_answer-question-1)), and the answer is ((x-amz-lex:kendra-search-response-question_answer-answer-1))”

  • “I found an excerpt from a helpful document: ((x-amz-lex:kendra-search-response-document-1))”

  • “I think the answer to your questions is ((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 开发人员指南》中的使用文档属性筛选查询。如果指定的筛选器字符串无效，则会出现 InvalidLambdaResponseException 异常。kendraQueryFilterString 字符串将覆盖为目的配置的 queryFilterString 中指定的任何查询字符串。

  • kendraQueryRequestPayload — 使用此字符串指定 Amazon Kendra 查询。您的查询可以使用 Amazon Kendra 的任何功能。如果您没有指定有效的查询，则会出现 InvalidLambdaResponseException 异常。有关更多信息，请参阅《Amazon Kendra 开发人员指南》中的查询。

创建筛选条件或查询字符串后，将响应发送到 Amazon Lex，并将响应的 dialogAction 字段设置为 delegate。Amazon Lex 将查询发送到 Amazon Kendra，然后将查询响应返回给履行代码挂钩。

对响应使用实现代码挂钩

在 Amazon Lex 将查询发送到 Amazon Kendra 后，查询响应将返回到 AMAZON.KendraSearchIntent 履行 Lambda 函数。代码挂钩的输入事件包含来自 Amazon Kendra 的完整响应。查询数据与 Amazon Kendra Query 操作返回的结构相同。有关更多信息，请参阅《Amazon Kendra 开发人员指南》中的查询响应语法。

实现代码挂钩是可选的。如果代码挂钩不存在，或者代码挂钩未在响应中返回消息，则 Amazon Lex 将对响应使用 conclusion 语句。