本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 在 Lex V2 中使用对话日志记录对话
您可以启用*对话日志* 来存储自动程序的交互。您可以使用这些日志查看机器人的性能，并解决与对话相关的问题。您可以记录 [RecognizeText](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_RecognizeText.html) 操作的文本。您可以记录 [RecognizeUtterance](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_RecognizeUtterance.html) 操作的文本和音频。您可以启用对话日志，以查看用户与机器人所进行对话的详细信息。
例如，与您的自动程序开展的会话具有会话 ID。您可以使用此 ID 获取对话的记录，包括用户话语和相应的自动程序响应。您还可以获取元数据，例如话语的意图名称和槽位值。
**注意**
您不能将对话日志用于受儿童在线隐私保护法案（COPPA）约束的自动程序。
对话日志是为别名配置的。每个别名的文本日志和音频日志都可以有不同的设置。您可以为每个别名启用文本日志和/或音频日志。文本日志在 CloudWatch 日志中存储文本输入、音频输入脚本和相关元数据。音频日志将音频输入存储在 Amazon S3 中。您可以使用 AWS KMS 客户管理功能启用文本和音频日志的加密 CMKs。
要配置日志记录，请使用控制台或[CreateBotAlias](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_CreateBotAlias.html)或[UpdateBotAlias](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_UpdateBotAlias.html)操作。为别名启用对话日志后，对该别名使用[RecognizeText](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_RecognizeText.html)或[RecognizeUtterance](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_RecognizeUtterance.html)操作将文本或音频语句记录在已配置的 CloudWatch 日志日志组或 S3 存储桶中。
**Topics**
+ [用于对话日志的 IAM 策略](conversation-logs-policies.md)
+ [为 Lex V2 机器人配置对话日志](conversation-logs-configure.md)
+ [从 Lex V2 中查看亚马逊 CloudWatch 日志中的文本日志](conversation-logs-cw.md)
+ [访问 Amazon S3 中的音频日志](conversation-logs-s3.md)
+ [使用 CloudWatch 指标监控对话日志状态](conversation-logs-monitoring.md)
# 用于对话日志的 IAM 策略
根据您选择的日志类型，Amazon Lex V2 需要权限才能使用亚马逊 CloudWatch 日志和亚马逊简单存储服务 (S3) 存储桶来存储您的日志。您必须创建 AWS Identity and Access Management 角色和权限才能让 Amazon Lex V2 访问这些资源。
## 为对话日志创建 IAM 角色和策略
要启用对话日志，您必须授予 CloudWatch 日志和 Amazon S3 的写入权限。如果您为 S3 对象启用对象加密，则需要向用于加密对象的 AWS KMS 密钥授予访问权限。
您可以使用 IAM 控制台、IAM API 或 AWS Command Line Interface 来创建角色和策略。这些说明使用 AWS CLI 创建角色和策略。
**注意**
以下代码针对 Linux 和 macOS 编排了格式。对于 Windows，将 Linux 行继续符（\$1）替换为脱字号（^）。
**为对话日志创建 IAM 角色**
1. 在名为 **LexConversationLogsAssumeRolePolicyDocument.json** 的当前目录中创建一个文档，向其中添加以下代码并保存。此策略文档将 Amazon Lex V2 作为受信任实体添加到角色中。这允许 Amazon Lex V2 担任向为对话日志配置的资源传送日志的角色。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lexv2.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. 在 AWS CLI 中，运行以下命令为对话日志创建 IAM 角色。
```
aws iam create-role \
--role-name role-name \
--assume-role-policy-document file://LexConversationLogsAssumeRolePolicyDocument.json
```
接下来，创建策略并将其附加到该角色以允许 Amazon Lex V2 写入 CloudWatch 日志。
**创建用于将对话文本记录到 Log CloudWatch s 的 IAM 策略**
1. 在名为 **LexConversationLogsCloudWatchLogsPolicy.json** 的当前目录中创建一个文档，向其中添加 IAM 策略并保存。
1. 在 AWS CLI 中，创建向 CloudWatch 日志组授予写入权限的 IAM 策略。
```
aws iam create-policy \
--policy-name cloudwatch-policy-name \
--policy-document file://LexConversationLogsCloudWatchLogsPolicy.json
```
1. 将该策略附加到您为对话日志创建的 IAM 角色中。
```
aws iam attach-role-policy \
--policy-arn arn:aws:iam::account-id:policy/cloudwatch-policy-name \
--role-name role-name
```
如果要将音频日志记录到 S3 存储桶，请创建允许 Amazon Lex V2 写入存储桶的策略。
**要创建用于将音频日志记录到 S3 存储桶中的 IAM 策略，请执行以下操作：**
1. 在名为 **LexConversationLogsS3Policy.json** 的当前目录中创建一个文档，向其中添加以下策略并保存。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject"
],
"Resource": "arn:aws:s3:::bucket-name/*"
}
]
}
```
------
1. 在 AWS CLI 中，创建授予您的 S3 存储桶写入权限的 IAM 策略。
```
aws iam create-policy \
--policy-name s3-policy-name \
--policy-document file://LexConversationLogsS3Policy.json
```
1. 将该策略附加到您为对话日志创建的角色。
```
aws iam attach-role-policy \
--policy-arn arn:aws:iam::account-id:policy/s3-policy-name \
--role-name role-name
```
## 授予传递 IAM 角色的权限
当您使用控制台 AWS Command Line Interface、或 AWS 开发工具包指定用于对话日志的 IAM 角色时，指定对话日志 IAM 角色的用户必须有权将该角色传递给 Amazon Lex V2。要允许用户将角色传递给 Amazon Lex V2，您必须向该用户的 IAM 用户、角色或组授予 `PassRole` 权限。
以下策略定义要授予用户、角色或组的权限。您可以使用 `iam:AssociatedResourceArn` 和 `iam:PassedToService` 条件键来限制权限的范围。有关更多信息，请参阅 AWS Identity and [Access Management 用户指南中的授予用户向 AWS 服务传递角色的权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html)*以及 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-name",
"Condition": {
"StringEquals": {
"iam:PassedToService": "lexv2.amazonaws.com"
},
"StringLike": {
"iam:AssociatedResourceARN": "arn:aws:lex:region:123456789012:bot:bot-name:bot-alias"
}
}
}
]
}
```
------
# 为 Lex V2 机器人配置对话日志
您可以使用控制台或 `CreateBotAlias` 和 `UpdateBotAlias` 操作的 `conversationLogSettings` 字段来启用和禁用对话日志。您可以启用或禁用音频日志和/或文本日志。日志记录将在新自动程序会话上启动。对日志设置的更改不会体现在活动会话中。
要存储文本日志，请使用您的 AWS 账户中的 Amazon CloudWatch 日志组。您可以使用任何有效的日志组。日志组必须与 Amazon Lex V2 机器人位于同一区域中。有关创建 CloudWatch 日志组的更多信息，请参阅 *Amazon 日志用户指南中的使用日志组和 CloudWatch 日志*[流](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)。
要存储音频日志，请在您的 AWS 账户中使用一个 Amazon S3 存储桶。您可以使用任何有效的 S3 存储桶。该存储桶必须与 Amazon Lex V2 机器人位于同一区域。有关创建 S3 存储桶的更多信息，请参阅《Amazon Simple Storage Service 入门指南》中的[创建存储桶](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html)。
当您使用控制台管理对话日志时，控制台会更新您的服务角色，以便拥有访问日志组和 S3 存储桶的权限。
如果您不使用控制台，则必须为 IAM 角色提供策略，以便 Amazon Lex V2 拥有写入所配置的日志组或存储桶的权限。如果您使用创建服务相关角色 AWS Command Line Interface，则必须使用`custom-suffix`选项为该角色添加自定义后缀，如下例所示。有关更多信息，请参阅 [为对话日志创建 IAM 角色和策略](conversation-logs-policies.md#conversation-logs-role-and-policy)。
```
aws iam create-service-linked-role \
--aws-service-name lexv2.amazon.aws.com \
--custom-suffix suffix
```
您用于启用对话日志的 IAM 角色必须具有 `iam:PassRole` 权限。应将以下策略附加到角色：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/role"
}
]
}
```
------
## 启用对话日志
**使用控制台启用日志**
1. 打开 Amazon Lex V2 控制台 [https://console.aws.amazon.com/](https://console.aws.amazon.com/lexv2)lexv2。
1. 从列表中，选择一个机器人。
1. 在左侧菜单中选择**别名**。
1. 在别名列表中，选择要为其配置对话日志的别名。
1. 在**对话日志**部分，选择**管理对话日志**。
1. 对于文本日志，请选择**启用**，然后输入 Amazon Log CloudWatch s 日志组名称。
1. 对于音频日志，请选择**启用**，然后输入 S3 存储桶信息。
1. 可选。要加密音频日志，请选择用于加密的密 AWS KMS 钥。
1. 选择 **Save（保存）**以开始记录对话。如有必要，Amazon Lex V2 将更新您的服务角色，使其具有访问 CloudWatch 日志日志组和所选 S3 存储桶的权限。
## 在 Lex V2 中禁用对话日志
**使用控制台禁用日志**
1. 打开 Amazon Lex V2 控制台 [https://console.aws.amazon.com/](https://console.aws.amazon.com/lexv2)lexv2。
1. 从列表中，选择一个机器人。
1. 在左侧菜单中选择**别名**。
1. 在别名列表中，选择要为其配置对话日志的别名。
1. 在**对话日志**部分，选择**管理对话日志**。
1. 禁用文本日志记录、音频日志记录或这两者，以关闭日志记录。
1. 选择 **Save（保存）**以停止记录对话。
# 从 Lex V2 中查看亚马逊 CloudWatch 日志中的文本日志
Amazon Lex V2 将您的对话文本日志存储在亚马逊 CloudWatch 日志中。要查看日志，请使用 CloudWatch 日志控制台或 API。有关更多信息，请参阅 *Amazon Logs 用户指南中的[使用筛选模式搜索CloudWatch 日志数据](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SearchDataFilterPattern.html)和 CloudWatch 日志*[见解查询语法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)。
**要使用 Amazon Lex V2 控制台查看日志，请执行以下操作：**
1. 打开 Amazon Lex V2 控制台 [https://console.aws.amazon.com/](https://console.aws.amazon.com/lexv2)lexv2。
1. 从列表中，选择一个机器人。
1. 从左侧菜单中选择 “**分析**”，然后选择 “**CloudWatch 指标**”。
1. 在指标页面上查看您的机器人的**CloudWatch 指标**。
您也可以使用 CloudWatch 控制台或 API 来查看日志条目。要查找日志条目，请导航到为该别名配置的日志组。您可以在 Amazon Lex V2 控制台中或使用[DescribeBotAlias](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_DescribeBotAlias.html)操作来找到日志的日志流前缀。
用户言语的日志条目位于多个日志流中。对话中的一个话语在一个日志流中具有一个带指定前缀的条目。日志流中的条目包含以下信息：
message-version
消息架构版本。
自动程序
有关客户正在与之交互的机器人的详细信息。
消息
机器人发回给用户的响应。
utteranceContext
有关处理该言语的信息。
+ `runtimeHints`：用于转录和解释用户输入的运行时上下文。有关更多信息，请参阅 [在对话中使用运行时提示改善对槽位值的识别](using-hints.md)。
+ `slotElicitationStyle`：用于解释用户输入的槽位引发样式。有关更多信息，请参阅 [在对话期间使用拼写样式捕获槽位值](spelling-styles.md)。
sessionState
用户与机器人之间对话的当前状态。有关更多信息，请参阅 [了解 Amazon Lex V2 机器人对话](managing-conversations.md)。
interpretations
Amazon Lex V2 确定可以满足用户言语的意图列表。[使用置信度分数提高对话的准确性](confidence-scores.md)。
interpretationSource
表示插槽是由亚马逊 Lex V2 还是由 Amazon Bedrock 解析的。值：Lex \$1 Bedrock
sessionId
正在进行对话的用户会话的标识符。
inputTranscript
用户输入的转录。
+ 对于文本输入，表示用户键入的文本。对于 DTMF 输入，表示用户输入的密钥。
+ 对于语音输入，这是 Amazon Lex V2 将用户言语转换成的文本，以便调用意图或填补槽位。
rawInputTranscript
应用任何文本处理之前的用户输入原始转录。注意：文本处理仅适用于 en-US 和 en-GB 区域设置。
transcriptions
用户输入的潜在转录列表。有关更多信息，请参阅 [使用语音转录置信度分数来改善与 Lex V2 机器人的对话](using-transcript-confidence-scores.md)。
rawTranscription
使用语音转录置信度分数。有关更多信息，请参阅 [使用语音转录置信度分数来改善与 Lex V2 机器人的对话](using-transcript-confidence-scores.md)。
missedUtterance
指示 Amazon Lex V2 是否能够识别用户的言语。
requestId
Amazon Lex V2 为用户输入生成的请求 ID。
timestamp
用户输入的时间戳。
developerOverride
指示是否使用对话代码挂钩更新了对话流程。有关使用对话代码挂钩的更多信息，请参阅[将AWS Lambda功能集成到您的 Amazon Lex V2 机器人中](lambda.md)。
inputMode
指示输入的类型。可以是音频、DTMF 或文本。
requestAttributes
处理用户输入时使用的请求属性。
audioProperties
如果启用了音频对话日志，并且用户输入是音频格式，则包括音频输入的总时长、语音持续时间以及音频中的静默持续时间。它还包括一个指向音频文件的链接。
bargeIn
指示用户输入是否中断了之前的机器人响应。
responseReason
生成响应的原因。可以是以下值之一：
+ `UtteranceResponse`：对用户输入的响应
+ `StartTimeout`：当用户未提供输入时，服务器生成的响应
+ `StillWaitingResponse`：当用户请求机器人等待时，服务器生成的响应
+ `FulfillmentInitiated`：服务器生成的指示即将触发履行的响应
+ `FulfillmentStartedResponse`：服务器生成的指示履行已开始的响应
+ `FulfillmentUpdateResponse`：在履行过程中，服务器定期生成的响应
+ `FulfillmentCompletedResponse`：履行完成后，服务器生成的响应。
operationName
用于与机器人交互的 API。可以为以下值之一：`PutSession`、`RecognizeText`、`RecognizeUtterance` 或 `StartConversation`。
```
{
"message-version": "2.0",
"bot": {
"id": "string",
"name": "string",
"aliasId": "string",
"aliasName": "string",
"localeId": "string",
"version": "string"
},
"messages": [
{
"contentType": "PlainText | SSML | CustomPayload | ImageResponseCard",
"content": "string",
"imageResponseCard": {
"title": "string",
"subtitle": "string",
"imageUrl": "string",
"buttonsList": [
{
"text": "string",
"value": "string"
}
]
}
}
],
"utteranceContext": {
"activeRuntimeHints": {
"slotHints": {
"string": {
"string": {
"runtimeHintValues": [
{
"phrase": "string"
},
{
"phrase": "string"
}
]
}
}
}
},
"slotElicitationStyle": "string"
},
"sessionState": {
"dialogAction": {
"type": "Close | ConfirmIntent | Delegate | ElicitIntent | ElicitSlot",
"slotToElicit": "string"
},
"intent": {
"name": "string",
"slots": {
"string": {
"value": {
"interpretedValue": "string",
"originalValue": "string",
"resolvedValues": [ "string" ]
}
},
"string": {
"shape": "List",
"value": {
"originalValue": "string",
"interpretedValue": "string",
"resolvedValues": [ "string" ]
},
"values": [
{
"shape": "Scalar",
"value": {
"originalValue": "string",
"interpretedValue": "string",
"resolvedValues": [ "string" ]
}
},
{
"shape": "Scalar",
"value": {
"originalValue": "string",
"interpretedValue": "string",
"resolvedValues": [ "string" ]
}
}
]
}
},
"kendraResponse": {
// Only present when intent is KendraSearchIntent. For details, see
// https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html#API_Query_ResponseSyntax
},
"state": "InProgress | ReadyForFulfillment | Fulfilled | Failed",
"confirmationState": "Confirmed | Denied | None"
},
"originatingRequestId": "string",
"sessionAttributes": {
"string": "string"
},
"runtimeHints": {
"slotHints": {
"string": {
"string": {
"runtimeHintValues": [
{
"phrase": "string"
},
{
"phrase": "string"
}
]
}
}
}
}
},
"dialogEventLogs": [
{
// only for conditional
"conditionalEvaluationResult":[
// all the branches until true
{
"conditionalBranchName": "string",
"expressionString": "string",
"evaluatedExpression": "string",
"evaluationResult": "true | false"
}
],
"dialogCodeHookInvocationLabel": "string",
"response": "string",
"nextStep": {
"dialogAction": {
"type": "Close | ConfirmIntent | Delegate | ElicitIntent | ElicitSlot",
"slotToElicit": "string"
},
"intent": {
"name": "string",
"slots": {
}
}
}
]
"interpretations": [
{
"interpretationSource": "Bedrock | Lex",
"nluConfidence": "string",
"intent": {
"name": "string",
"slots": {
"string": {
"value": {
"originalValue": "string",
"interpretedValue": "string",
"resolvedValues": [ "string" ]
}
},
"string": {
"shape": "List",
"value": {
"interpretedValue": "string",
"originalValue": "string",
"resolvedValues": [ "string" ]
},
"values": [
{
"shape": "Scalar",
"value": {
"interpretedValue": "string",
"originalValue": "string",
"resolvedValues": [ "string" ]
}
},
{
"shape": "Scalar",
"value": {
"interpretedValue": "string",
"originalValue": "string",
"resolvedValues": [ "string" ]
}
}
]
}
},
"kendraResponse": {
// Only present when intent is KendraSearchIntent. For details, see
// https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html#API_Query_ResponseSyntax
},
"state": "InProgress | ReadyForFulfillment | Fulfilled | Failed",
"confirmationState": "Confirmed | Denied | None"
},
"sentimentResponse": {
"sentiment": "string",
"sentimentScore": {
"positive": "string",
"negative": "string",
"neutral": "string",
"mixed": "string"
}
}
}
],
"sessionId": "string",
"inputTranscript": "string",
"rawInputTranscript": "string",
"transcriptions": [
{
"transcription": "string",
"rawTranscription": "string",
"transcriptionConfidence": "number",
},
"resolvedContext": {
"intent": "string"
},
"resolvedSlots": {
"string": {
"name": "slotName",
"shape": "List",
"value": {
"originalValue": "string",
"resolvedValues": [
"string"
]
}
}
}
}
],
"missedUtterance": "bool",
"requestId": "string",
"timestamp": "string",
"developerOverride": "bool",
"inputMode": "DTMF | Speech | Text",
"requestAttributes": {
"string": "string"
},
"audioProperties": {
"contentType": "string",
"s3Path": "string",
"duration": {
"total": "integer",
"voice": "integer",
"silence": "integer"
}
},
"bargeIn": "string",
"responseReason": "string",
"operationName": "string"
}
```
日志条目的内容取决于事务的结果以及机器人和请求的配置。
+ 如果 `missedUtterance` 字段为 `true`，则 `intent`、`slots` 和 `slotToElicit` 字段不会显示在条目中。
+ 如果音频日志已禁用或者 `inputDialogMode` 字段为 `Text`，则不显示 `s3PathForAudio` 字段。
+ 仅当您为自动程序定义了响应卡时，才会显示 `responseCard` 字段。
+ 仅当您在请求中指定了请求属性时，才会显示 `requestAttributes` 映射。
+ 只有在 `AMAZON.KendraSearchIntent` 请求搜索 Amazon Kendra 索引时，`kendraResponse` 字段才会出现。
+ 当在机器人的 Lambda 函数中指定了替代意图时，`developerOverride` 字段的值为 True。
+ 仅当在请求中指定了会话属性时，才会显示 `sessionAttributes` 映射。
+ 仅当将自动程序配置为返回情绪值时，才会显示 `sentimentResponse` 映射。
**注意**
输入格式可以更改，但不必对 `messageVersion` 做出相应更改。您的代码不应在有新字段时引发错误。
# 访问 Amazon S3 中的音频日志
Amazon Lex V2 将对话的音频日志存储在 S3 存储桶中。
您也可以使用 Amazon S3 控制台或 API 来访问音频日志。您可以在 Amazon Lex V2 控制台或 `DescribeBotAlias` 操作响应的 `conversationLogSettings` 字段中查看音频文件的 S3 对象键前缀。
# 使用 CloudWatch 指标监控对话日志状态
使用 Amazon CloudWatch 监控您的对话日志的交付指标。您可以在指标上设置警报，以便在日志记录发生问题时获取通知。
Amazon Lex V2 在 `AWS/Lex` 命名空间中为对话日志提供了四个指标：
+ `ConversationLogsAudioDeliverySuccess`
+ `ConversationLogsAudioDeliveryFailure`
+ `ConversationLogsTextDeliverySuccess`
+ `ConversationLogsTextDeliveryFailure`
成功指标表明 Amazon Lex V2 已成功将音频或文本日志写入其目标。
失败指标表明 Amazon Lex V2 无法将音频或文本日志传输到指定目标。这通常是配置错误。当您的失败指标大于零时，请检查以下内容：
+ 确保 Amazon Lex V2 是 IAM 角色的可信实体。
+ 对于文本记录，请确保 CloudWatch 日志组存在。对于音频日志记录，请确保 S3 存储桶存在。
+ 确保 Amazon Lex V2 用于访问 CloudWatch 日志日志组或 S3 存储桶的 IAM 角色具有日志组或存储桶的写入权限。
+ 确保 S3 存储桶与 Amazon Lex V2 机器人位于相同的区域，并且属于您的账户。