# 管理聊天记录
<a name="sonic-chat-history"></a>

Amazon Nova 2 Sonic 的响应包括用户和助手语音的 ASR（自动语音识别）转录。存储聊天记录是一种最佳实践，不仅可用于日志记录，还可在连接意外关闭时恢复会话。这使得客户端能够将上下文回传到 Nova Sonic，实现对话无缝接续。

有关管理聊天记录的更多信息，请参阅以下资源：

1. [聊天记录日志](https://github.com/aws-samples/amazon-nova-samples/tree/main/speech-to-speech/amazon-nova-2-sonic/repeatable-patterns/chat-history-logger)

1. [对话恢复](https://github.com/aws-samples/amazon-nova-samples/tree/main/speech-to-speech/repeatable-patterns/resume-conversation)

## 发送聊天记录
<a name="sonic-chat-history-sending"></a>

对话历史仅可添加一次，且需在系统/语音提示之后、音频流开始之前传入。整体聊天记录不能超过 40 KB。下图展示了在事件生命周期中何时传入聊天记录：

![从客户端发送到 Bedrock 的聊天历史记录，位于系统提示和音频流式传输之间。](http://docs.aws.amazon.com/zh_cn/nova/latest/nova2-userguide/images/Sending-Chat-History_4.png)


每条历史消息都需要三个事件：`contentStart`、`textInput` 和 `contentEnd`。

**每条消息的事件架构：**
+ `contentStart`：定义消息角色和配置

  ```
  {
    "event": {
      "contentStart": {
        "promptName": "<prompt-id>",
        "contentName": "<content-id>",
        "type": "TEXT",
        "interactive": true,
        "role": "ASSISTANT",
        "textInputConfiguration": {
          "mediaType": "text/plain"
        }
      }
    }
  }
  ```
+ `textInput`：包含实际的消息内容。一个 textInput 不能大于 1 KB。如果大小超过限制，请在同一个内容块中拆分成多个 textInput。如果对话大于 40 KB，请修剪整个聊天记录。

  ```
  {
    "event": {
      "textInput": {
        "promptName": "<prompt-id>",
        "contentName": "<content-id>",
        "content": "Take your time, Don. I'll be here when you're ready."
      }
    }
  }
  ```
+ `contentEnd`：标记消息的结束

  ```
  {
    "event": {
      "contentEnd": {
        "promptName": "<prompt-id>",
        "contentName": "<content-id>"
      }
    }
  }
  ```

对聊天记录中的每条消息重复这三个事件，交替使用用户和助手角色。

**重要注意事项：**
+ 每次会话只能包含**一次**聊天记录
+ 聊天记录必须在**系统提示之后**和**音频流式传输开始之前**发送
+ 必须先发送所有历史消息，然后才能开始音频流式传输
+ 每条消息都必须指定用户或助手角色
+ 将 textOutput 事件中存储的转录内容用作 textInput 中的内容值

## 接收 ASR 转录文本
<a name="sonic-chat-history-receiving"></a>

在对话期间，Amazon Nova 2 Sonic 通过输出事件发送 ASR 转录文本。每份转录文本都以三个事件的序列形式交付：contentStart、textOutput 和 contentEnd。

**示例：用户演讲转录文本：**

1. contentStart – 表示转录文本开始：

```
{
  "event": {
    "contentStart": {
      "additionalModelFields": "{\"generationStage\":\"FINAL\"}",
      "completionId": "<completion-id>",
      "contentId": "<content-id>",
      "promptName": "<prompt-id>",
      "role": "USER",
      "sessionId": "<session-id>",
      "textOutputConfiguration": {
        "mediaType": "text/plain"
      },
      "type": "TEXT"
    }
  }
}
```

2. textOutput – 包含实际转录文本内容：

```
{
  "event": {
    "textOutput": {
      "completionId": "<completion-id>",
      "content": "hello how are you",
      "contentId": "<content-id>",
      "promptName": "<prompt-id>",
      "role": "USER",
      "sessionId": "<session-id>"
    }
  }
}
```

3. contentEnd – 标记转录文本结束：

```
{
  "event": {
    "contentEnd": {
      "completionId": "<completion-id>",
      "contentId": "<content-id>",
      "promptName": "<prompt-id>",
      "sessionId": "<session-id>",
      "stopReason": "PARTIAL_TURN",
      "type": "TEXT"
    }
  }
}
```

 相同的三事件模式适用于用户角色和助手角色。从 `textOutput` 事件中提取 `content` 字段，从 `contentStart` 事件中提取 `role` 字段，用于构建聊天记录。

## 最佳实践
<a name="sonic-chat-history-best-practices"></a>

务必存储聊天记录以实现：
+ 跨设备恢复会话
+ 对话日志与审计
+ 为后续交互保留上下文

重要提示：保存聊天记录时，请根据 generationStage 使用文本输出：
+ 预测文本 – 音频合成开始前生成的 Nova 2 Sonic 拟播报内容预览
+ 最终文本 – 对音频回复中实际播报内容的句子级转录结果

务必将最终文本输出存入聊天记录，因其为对话的准确记录。

最终输出示例（请将此内容保存到聊天记录）：

```
ContentStart event: { 
  "additionalModelFields": "{\"generationStage\":\"FINAL\"}", 
  "completionId": "<completion-id>", 
  "contentId": "<content-id>", 
  "role": "ASSISTANT", 
  "sessionId": "<session-id>", 
  "type": "TEXT" 
}
```

预测输出示例（仅作可选预览，不记入历史）：

```
ContentStart event: { 
  "additionalModelFields": "{\"generationStage\":\"SPECULATIVE\"}", 
  "completionId": "<completion-id>", 
  "contentId": "<content-id>", 
  "role": "ASSISTANT", 
  "sessionId": "<session-id>", 
  "type": "TEXT" 
}
```