# 채팅 기록 관리
<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보다 클 수 없습니다. 다음 다이어그램에서는 이벤트 수명 주기 동안 채팅 기록이 전달되는 시점을 보여줍니다.

![](http://docs.aws.amazon.com/ko_kr/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" 
}
```