使用 API 进行分析 - Amazon Lex
筛选结果检索机器人的指标在机器人中检索会话和言语的元数据检索意图路径分析数据查看 Lex V2 对话中的言语统计数据

使用 API 进行分析

本节介绍用于检索机器人分析的 API 操作。

注意

要使用 ListUtteranceMetrics 和 ListUtteranceAnalyticsData，您的 IAM 角色必须拥有执行 ListAggregatedUtterances 操作的权限，以便提供对言语相关分析的访问权限。有关详细信息以及适用于 IAM 角色的 IAM 策略，请参阅查看 Lex V2 对话中的言语统计数据。

筛选结果

您需要针对 Analytics API 请求来指定 startTime 和 endTime。API 将返回在 startTime 之后开始并在 endTime 之前结束的会话、意图、意图阶段或言语。

filters 是 Analytics API 请求中的可选字段。该字段映射到 AnalyticsSessionFilter、AnalyticsIntentFilter、AnalyticsIntentStageFilter 或 AnalyticsUtteranceFilter 对象的列表。在每个对象中，使用字段创建表达式以作为筛选条件。例如，如果您将以下筛选条件添加到列表中，则机器人将搜索时长超过 30 秒的对话。

{
    "name": "Duration",
    "operator": "GT",
    "value": "30 sec",
}

检索机器人的指标

使用 ListSessionMetrics、ListIntentMetrics、ListIntentStageMetrics 和 ListUtteranceMetrics 操作来检索会话、意图、意图阶段和言语的摘要指标。

对于这些操作，请填写以下必填字段：

  • 提供 startTime 和 endTime 以定义要检索结果的时间范围。

  • 在 metrics 中指定要计算的指标，即 AnalyticsSessionMetric、AnalyticsIntentMetric、AnalyticsIntentStageMetric 或 AnalyticsUtteranceMetric 对象的列表。在每个对象中，使用 name 字段指定要计算的指标，使用 statistic 字段指定计算的是 Sum、Average 或 Max 数，并且使用 order 字段指定结果的排序方式是 Ascending 还是 Descending。

    注意

    metrics 和 binBy 对象均包含 order 字段。您只能在这两个对象中的一个对象中指定排序 order。

该请求中的其余字段为可选字段。您可以通过以下方式筛选和整理结果：

  • 筛选结果：使用 filters 字段来筛选结果。有关更多信息，请参阅筛选结果。

  • 按类别对结果进行分组：指定 groupBy 字段，即包含单个 AnalyticsSessionResult、AnalyticsIntentResult、AnalyticsIntentStageResult 或 AnalyticsUtteranceResult 对象的列表。在对象中，指定要以其为基础对结果进行分组的类别的 name 字段。

    如果您在请求中指定 groupBy 字段，则响应中的 results 对象将包含 groupByKeys，即 AnalyticsSessionGroupByKey、AnalyticsIntentGroupByKey、AnalyticsIntentStageGroupByKey 或 AnalyticsUtteranceGroupByKey 对象的列表，每个对象的 value 字段中均有您在请求中指定的 name 以及该类别的成员。

  • 按时间对结果进行分箱：指定 binBy 字段，即包含单个 AnalyticsBinBySpecification 对象的列表。在对象中，将 name 字段指定为 ConversationStartTime 以便按对话开始的时间对结果进行分箱，或者指定为 UtteranceTimestamp 以便按言语发生的时间对结果进行分箱。在 interval 字段中指定要对结果进行分箱的时间间隔，并且在 order 字段中指定排序是 Ascending 还是 Descending。

    如果您在请求中指定 binBy 字段，则响应中的 results 对象将包含 binKeys，即 AnalyticsBinKey 对象列表，每个对象的 value 字段中均包含您在请求中指定的 name 以及定义该分箱的时间间隔。

    注意

    metrics 和 binBy 对象均包含 order 字段。您只能在这两个对象中的一个对象中指定排序 order。

使用以下字段来处理响应的显示：

  • 在 maxResults 字段中指定一个介于 1 到 1,000 之间的数字，以限制单个响应中返回的结果数。

  • 如果结果数大于您在 maxResults 字段中指定的数字，则响应中包含 nextToken。再次发出请求，但使用 nextToken 字段中的值以便返回下一批结果。

如果使用 ListUtteranceMetrics，则可以在 attributes 字段中指定要返回的属性。此字段映射到包含单个 AnalyticsUtteranceAttribute 对象的列表。在 name 字段中指定 LastUsedIntent，以返回 Amazon Lex V2 在言语时使用的意图。

在响应中，results 字段映射到 AnalyticsSessionResult、AnalyticsIntentResult、AnalyticsIntentStageResult 或 AnalyticsUtteranceResult 对象的列表。每个对象均包含 metrics 字段，以返回您所请求的指标的汇总统计数据以及使用您指定的方法创建的任何数据分箱或组。

在机器人中检索会话和言语的元数据

使用 ListSessionAnalyticsData 和 ListUtteranceAnalyticsData 操作来检索关于单个会话和言语的元数据。

填写必填的 startTime 和 endTime 字段以定义要检索结果的时间范围。

该请求中的其余字段为可选字段。要对结果进行筛选和排序，请执行以下操作：

  • 筛选结果：使用 filters 字段来筛选结果。有关更多信息，请参阅筛选结果。

  • 对结果进行排序：使用包含 SessionDataSortBy 或 UtteranceDataSortBy 对象的 sortBy 字段对结果进行排序。在字段 name 中指定要作为排序依据的值，并且在 order 字段中指定以 Ascending 还是 Descending 进行排序。

使用以下字段来处理响应的显示：

  • 在 maxResults 字段中指定一个介于 1 到 1,000 之间的数字，以限制单个响应中返回的结果数。

  • 如果结果数大于您在 maxResults 字段中指定的数字，则响应中包含 nextToken。再次发出请求，但使用 nextToken 字段中的值以便返回下一批结果。

在响应中，sessions 或 utterances 字段映射到 SessionSpecification 或 UtteranceSpecification 对象的列表。每个对象均包含单个会话或言语的元数据。

检索意图路径分析数据

使用 ListIntentPaths 操作检索关于客户在与机器人对话时所采用的意图顺序的指标。

对于这些操作，请填写以下必填字段：

  • 提供 startTime 和 endTime 以定义要检索结果的时间范围。

  • 提供 intentPath 以定义检索指标的意图顺序。路径中的意图用正斜杠隔开。例如，将 intentPath 字段填充为 /BookCar/BookHotel，以查看关于用户以该顺序调用 BookCar 和 BookHotel 意图的次数的详细信息。

使用可选的 filters 字段来筛选结果。有关更多详细信息，请参阅 筛选结果。

查看 Lex V2 对话中的言语统计数据

您可以使用言语统计数据来确定您的用户向机器人发送的言语。系统将统计 Amazon Lex V2 成功检测到的言语以及未成功检测到的言语。您可以使用此信息来优化机器人。

例如，如果您发现用户正在发送 Amazon Lex V2 遗漏的言语，则可以将该言语添加到意图中。系统将使用新的言语来更新此意图的 Draft 版本，以便您在将其部署到机器人之前对其进行测试。

当 Amazon Lex V2 将某个言语识别为试图调用为机器人配置的意图时，该言语即被检测到。当 Amazon Lex V2 未能识别某个言语而是调用 AMAZON.FallbackIntent 时，将错过该言语。

可以使用 ListUtteranceMetrics API 和 ListAggregatedUtterance API 来查看言语统计信息。

以下条件下，系统不会使用 ListUtteranceMetrics API 生成言语统计数据：

  • 当使用控制台创建机器人时，“儿童在线隐私保护法案”设置被设置为是，或者在使用 CreateBot 操作创建机器人时，childDirected 字段被设置为 true。

该 ListUtteranceMetrics API 还提供其他功能，包括：

  • 更多可用信息，例如检测到言语的被映射意图。

  • 更多筛选功能（包括频道和模式）。

  • 更长的保留日期范围（30 天）。

  • 即使您已选择退出数据存储，也可以使用该 API。控制台依赖于 ListUtteranceMetrics API 来实现对遗漏和检测到的言语的功能。

以下条件下，系统不会使用 ListAggregatedUtterance API 生成言语统计数据：

  • 当使用控制台创建机器人时，“儿童在线隐私保护法案”设置被设置为是，或者在使用 CreateBot 操作创建机器人时，childDirected 字段被设置为 true。

  • 您正在对一个或多个槽位使用槽位模糊处理。

  • 您已选择退出 Amazon Lex 改进计划。

该 ListAggregatedUtterance API 所提供的功能包括：

  • 可用的详细信息较少（不存在言语的被映射意图）。

  • 有限的筛选功能（不包括频道和模式）。

  • 较短的保留日期范围（15 天）。

您可以使用言语统计信息来查看是否检测到或遗漏了特定的话语，以及机器人交互中上次使用该言语的时间。

当用户与您的机器人交互时，Amazon Lex V2 会持续不断地存储言语。您可以使用控制台或 ListAggregatedUtterances 操作来查询统计数据。数据保留期为 15 天。如果用户选择退出数据存储，则不可用。您可以使用 DeleteUtterances 操作或选择退出数据存储来删除言语。如果您关闭 AWS 账户，则所有言语都将被删除。所存储的言语使用服务器管理的密钥进行加密。

如果使用 ListUtteranceMetrics 删除机器人版本，则该版本的言语统计数据最多可用 30 天，而如果使用 ListAggregatedUtterances 删除机器人版本，则该版本的言语统计数据最多可用 15 天。您无法在 Amazon Lex V2 控制台中查看已删除版本的统计数据。要查看已删除版本的统计数据，可以使用 ListAggregatedUtterances 和 ListUtteranceMetrics 操作。

对于 ListAggregatedUtterances 和 ListUtteranceMetrics API，按言语的文本对言语进行汇总。例如，客户发出“我想订购披萨”的话语的所有实例均会在回复中汇总到同一行中。当您使用 RecognizeUtterance 操作时，所使用的文本是输入转录。

要使用 ListAggregatedUtterances 和 ListUtteranceMetrics API，请将以下策略应用于角色。

JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "ListAggregatedUtterancesPolicy",
            "Effect": "Allow",
            "Action": "lex:ListAggregatedUtterances",
            "Resource": "*"
        }
    ]
}