View a markdown version of this page

管理聊天记录 - Amazon Nova
发送聊天记录接收 ASR 转录文本最佳实践

管理聊天记录

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

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

  1. 聊天记录日志

  2. 对话恢复

发送聊天记录

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

每条历史消息都需要三个事件：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 转录文本

在对话期间，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 字段，用于构建聊天记录。

最佳实践

务必存储聊天记录以实现：

  • 跨设备恢复会话

  • 对话日志与审计

  • 为后续交互保留上下文

重要提示：保存聊天记录时，请根据 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" 
}