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

# 使用雙向 API 處理輸入事件
<a name="input-events"></a>

**注意**  
本文件適用於 Amazon Nova 第 1 版。如需 Amazon Nova 2 Sonic 指南，請造訪[使用雙向 API 處理輸入事件](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-input-events.html)。

雙向串流 API 使用具有結構化輸入和輸出事件的事件驅動型架構。了解正確的事件排序對於實作成功的對話式應用程式，以及在互動期間全程維持適當的對話狀態至關重要。

Nova Sonic 對話遵循結構化事件序列。首先傳送包含推論組態參數的 `sessionStart` 事件，例如溫度和詞元限制。接著傳送 `promptStart` 來定義音訊輸出格式和工具組態，指派唯一 `promptName` 識別符，該識別符必須包含在所有後續事件中。

對於每個互動類型 (系統提示詞、音訊等)，遵循三部分模式：使用 `contentStart` 定義內容類型和內容的角色 (`SYSTEM`、`USER`、`ASSISTANT`、`TOOL`)，然後提供實際內容事件，最後以 `contentEnd` 結束該區段。`contentStart` 事件指定您要傳送工具結果、串流音訊還是系統提示詞。`contentStart` 事件包含唯一 `contentName` 識別符。

對話歷史記錄只能在系統提示詞之後以及音訊串流開始之前包含一次。它遵循相同的 `contentStart`/`textInput`/`contentEnd` 模式。必須在 `contentStart` 事件中為每個歷史訊息定義 `USER` 和 `ASSISTANT` 角色。這為目前的對話提供了基本上下文，但必須在任何新的使用者輸入開始之前完成。

音訊串流透過連續麥克風取樣來運作。傳送初始 `contentStart` 直接從麥克風擷取音訊影格 (每個影格約 32 毫秒)，並立即使用相同的 `contentName` 將其做為 `audioInput` 事件傳送。這些音訊範例應在擷取時即時串流，從而在對話期間全程保持自然麥克風取樣節奏。所有音訊幀都會共用單一內容容器，直至對話結束且內容容器被明確關閉為止。

在對話結束或需要終止之後，請務必正確關閉所有開啟的串流，並以正確的順序結束工作階段。若要正確結束工作階段並避免資源洩漏，必須遵循特定的關閉順序：

1. 使用 `contentEnd` 事件關閉任何開啟的音訊串流。

1. 傳送參考原始 `promptName` 的 `promptEnd` 事件。

1. 傳送 `sessionEnd` 事件。

略過任何這些關閉事件都可能導致未完成的對話或孤立的資源。

這些識別符會建立階層結構：`promptName` 將所有對話事件繫結在一起，而每個 `contentName` 則會標記特定內容區塊的邊界。此階層可確保模型在整個互動期間維持適當的上下文。

![\[說明 Amazon Nova Sonic 輸入事件流程的圖表。\]](http://docs.aws.amazon.com/zh_tw/nova/latest/userguide/images/input-events.png)


## 輸入事件流程
<a name="input-event-flow"></a>

本節提供了輸入事件流程的結構。

1. `RequestStartEvent`

   ```
   {
       "event": {
           "sessionStart": {
               "inferenceConfiguration": {
                   "maxTokens": "int",
                   "topP": "float",
                   "temperature": "float"
               }
           }
       }
   }
   ```

1. `PromptStartEvent`

   ```
   {
       "event": {
           "promptStart": {
               "promptName": "string", // unique identifier same across all events i.e. UUID
               "textOutputConfiguration": {
                   "mediaType": "text/plain"
               },
               "audioOutputConfiguration": {
                   "mediaType": "audio/lpcm",
                   "sampleRateHertz": 8000 | 16000 | 24000,
                   "sampleSizeBits": 16,
                   "channelCount": 1,
                   "voiceId": "matthew" | "tiffany" | "amy" |
                           "lupe" | "carlos" | "ambre" | "florian" |
                           "greta" | "lennart" | "beatrice" | "lorenzo",
                   "encoding": "base64",
                   "audioType": "SPEECH",
               },
               "toolUseOutputConfiguration": {
                   "mediaType": "application/json"
               },
               "toolConfiguration": {
                   "tools": [{
                       "toolSpec": {
                           "name": "string",
                           "description": "string",
                           "inputSchema": {
                               "json": "{}"
                           }
                       }
                   }]
               }
           }
       }
   }
   ```

1. `InputContentStartEvent`
   + `Text`

     ```
     {
         "event": {
             "contentStart": {
                 "promptName": "string", // same unique identifier from promptStart event
                 "contentName": "string", // unique identifier for the content block
                 "type": "TEXT",
                 "interactive": false,
                 "role": "SYSTEM" | "USER" | "ASSISTANT",
                 "textInputConfiguration": {
                     "mediaType": "text/plain"
                 }
             }
         }
     }
     ```
   + `Audio`

     ```
     {
         "event": {
             "contentStart": {
                 "promptName": "string", // same unique identifier from promptStart event
                 "contentName": "string", // unique identifier for the content block
                 "type": "AUDIO",
                 "interactive": true,
                 "role": "USER",
                 "audioInputConfiguration": {
                     "mediaType": "audio/lpcm",
                     "sampleRateHertz": 8000 | 16000 | 24000,
                     "sampleSizeBits": 16,
                     "channelCount": 1,
                     "audioType": "SPEECH",
                     "encoding": "base64"
                 }
             }
         }
     }
     ```
   + `Tool`

     ```
     {
         "event": {
             "contentStart": {
                 "promptName": "string", // same unique identifier from promptStart event
                 "contentName": "string", // unique identifier for the content block
                 "interactive": false,
                 "type": "TOOL",
                 "role": "TOOL",
                 "toolResultInputConfiguration": {
                     "toolUseId": "string", // existing tool use id
                     "type": "TEXT",
                     "textInputConfiguration": {
                         "mediaType": "text/plain"
                     }
                 }
             }
         }
     }
     ```

1. `TextInputContent`

   ```
   {
       "event": {
           "textInput": {
               "promptName": "string", // same unique identifier from promptStart event
               "contentName": "string", // unique identifier for the content block
               "content": "string"
           }
       }
   }
   ```

1. `AudioInputContent`

   ```
   {
       "event": {
           "audioInput": {
               "promptName": "string", // same unique identifier from promptStart event
               "contentName": "string", // same unique identifier from its contentStart
               "content": "base64EncodedAudioData"
           }
       }
   }
   ```

1. `ToolResultContentEvent`

   ```
   "event": {
       "toolResult": {
           "promptName": "string", // same unique identifier from promptStart event
           "contentName": "string", // same unique identifier from its contentStart
           "content": "{\"key\": \"value\"}" // stringified JSON object as a tool result 
       }
   }
   ```

1. `InputContentEndEvent`

   ```
   {
       "event": {
           "contentEnd": {
               "promptName": "string", // same unique identifier from promptStart event
               "contentName": "string" // same unique identifier from its contentStart
           }
       }
   }
   ```

1. `PromptEndEvent`

   ```
   {
       "event": {
           "promptEnd": {
               "promptName": "string" // same unique identifier from promptStart event
           }
       }
   }
   ```

1. `RequestEndEvent`

   ```
   {
       "event": {
           "sessionEnd": {}
       }
   }
   ```