本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 管理聊天歷史記錄
<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>

對話歷史記錄只能在系統/語音提示之後以及在音訊串流開始之前包含一次。整體聊天歷史記錄不能大於 40KB。下圖顯示聊天歷史記錄在事件生命週期期間傳入的時間：

![\[alt text not found\]](http://docs.aws.amazon.com/zh_tw/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 不能大於 1KB。若是如此，請在相同的內容區塊中分割成多個 textInputs。如果對話大於 40KB，請裁剪整體聊天歷史記錄。

  ```
  {
    "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>"
      }
    }
  }
  ```

對聊天歷史記錄中的每個訊息重複這三個事件，在 USER 和 ASSISTANT 角色之間交替。

**重要考量事項：**
+ 每個工作階段只能包含**一次**聊天歷史記錄
+ 聊天歷史記錄必須在**系統提示後**和**音訊串流開始之前**傳送
+ 在開始音訊串流之前，必須傳送所有歷史訊息
+ 每個訊息都必須指定 USER 或 ASSISTANT 角色
+ 使用來自 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"
    }
  }
}
```

 相同的三事件模式適用於 USER 和 ASSISTANT 角色。從`textOutput`事件擷取 `content` 欄位，從`contentStart`事件擷取 `role` 欄位，以建置您的聊天歷史記錄。

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

一律存放聊天歷史記錄以啟用：
+ 不同裝置的工作階段恢復
+ 對話記錄和稽核
+ 追蹤互動的內容保留

重要：儲存聊天歷史記錄時，請根據其 generationStage 使用文字輸出：
+ 推測 - 預覽 Nova 2 Sonic 計劃說的內容，在音訊合成開始之前產生
+ 最終 - 音訊回應中所說內容的實際句子層級轉錄

一律將最終文字輸出儲存到您的聊天歷史記錄，因為它代表對話的準確記錄。

FINAL 輸出範例 （將此儲存到聊天歷史記錄）：

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

SPECULATIVE 輸出範例 （選用預覽，不適用於歷史記錄）：

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