本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用雙向 API 處理輸入事件
雙向串流 API 使用具有結構化輸入和輸出事件的事件驅動型架構。了解正確的事件排序對於實作成功的對話式應用程式，以及在互動期間全程維持適當的對話狀態至關重要。
## 概觀
Nova Sonic 對話遵循結構化事件序列。首先傳送包含推論組態參數的 `sessionStart` 事件，例如溫度和詞元限制。接著傳送 `promptStart` 來定義音訊輸出格式和工具組態，指派唯一 `promptName` 識別符，該識別符必須包含在所有後續事件中。
對於每個互動類型 （系統提示、音訊等），您遵循三個部分模式：使用 `contentStart` 定義內容類型和內容的角色 (`SYSTEM`、、`USER``ASSISTANT``TOOL`、、`SYSTEM_SPEECH`)，然後提供實際的內容事件，並以 `contentEnd` 結束該區段。`contentStart` 事件指定您要傳送工具結果、串流音訊還是系統提示詞。`contentStart` 事件包含唯一 `contentName` 識別符。
## 對話歷史記錄
對話歷史記錄只能在系統提示詞之後以及音訊串流開始之前包含一次。它遵循相同的 `contentStart`/`textInput`/`contentEnd` 模式。必須在 `contentStart` 事件中為每個歷史訊息定義 `USER` 和 `ASSISTANT` 角色。這為目前的對話提供了基本上下文，但必須在任何新的使用者輸入開始之前完成。
## 音訊串流
音訊串流透過連續麥克風取樣來運作。傳送初始 `contentStart` 直接從麥克風擷取音訊影格 (每個影格約 32 毫秒)，並立即使用相同的 `contentName` 將其做為 `audioInput` 事件傳送。這些音訊範例應在擷取時即時串流，從而在對話期間全程保持自然麥克風取樣節奏。所有音訊幀都會共用單一內容容器，直至對話結束且內容容器被明確關閉為止。
## 關閉工作階段
在對話結束或需要終止之後，請務必正確關閉所有開啟的串流，並以正確的順序結束工作階段。若要正確結束工作階段並避免資源洩漏，必須遵循特定的關閉順序：
+ 使用 `contentEnd` 事件關閉任何開啟的音訊串流。
+ 傳送參考原始 `promptName` 的 `promptEnd` 事件。
+ 傳送 `sessionEnd` 事件。
略過任何這些關閉事件都可能導致未完成的對話或孤立的資源。
這些識別符會建立階層結構：`promptName` 將所有對話事件繫結在一起，而每個 `contentName` 則會標記特定內容區塊的邊界。此階層可確保模型在整個互動期間維持適當的上下文。
## 輸入事件流程
本節提供了輸入事件流程的結構。
### 1. RequestStartEvent （工作階段開始）
工作階段開始事件會使用推論組態初始化對話，並開啟偵測設定。
**推論組態：**
+ `maxTokens`：回應中要產生的字符數量上限
+ `topP`：Nucleus 取樣參數 (0.0 到 1.0) 用於控制隨機性
+ `temperature`：控制產生時的隨機性 (0.0 到 1.0)
**轉動偵測組態：** `endpointingSensitivity` 參數控制 Nova Sonic 偵測使用者何時完成說話的速度：
+ `HIGH`：快速偵測暫停，啟用更快的回應，但可能會中斷較慢的發言者
+ `MEDIUM`：大多數對話案例的平衡敏感度 （建議預設值）
+ `LOW`：在偵測語音結束之前等待更長的時間，適合深思熟慮或遲疑的發言者
```
{
"event": {
"sessionStart": {
"inferenceConfiguration": {
"maxTokens": "int",
"topP": "float",
"temperature": "float"
},
"turnDetectionConfiguration": {
"endpointingSensitivity": "HIGH" | "MEDIUM" | "LOW"
}
}
}
}
```
**範例**：
```
{
"event": {
"sessionStart": {
"inferenceConfiguration": {
"maxTokens": 2048,
"topP": 0.9,
"temperature": 0.7
},
"turnDetectionConfiguration": {
"endpointingSensitivity": "MEDIUM"
}
}
}
}
```
### 2. PromptStartEvent
提示啟動事件會定義對話組態，包括輸出格式、語音選擇和可用的工具。
如需可用語音 IDs的清單，請參閱[語言支援和多語言功能](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-language-support.html)
```
{
"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" | "olivia" | "lupe" | "carlos" | "ambre" | "florian" | "lennart" | "beatrice" | "lorenzo" |
"tina" | "carolina" | "leo" | "kiara" | "arjun",
"encoding": "base64",
"audioType": "SPEECH"
},
"toolUseOutputConfiguration": {
"mediaType": "application/json"
},
"toolConfiguration": {
"tools": [
{
"toolSpec": {
"name": "string",
"description": "string",
"inputSchema": {
"json": "{}"
}
}
}
]
}
}
}
}
```
### 3. InputContentStartEvent
#### 文字
文字內容開始事件用於系統提示、對話歷史記錄和跨模式文字輸入。
**互動式參數：**
+ `true`：啟用跨模式輸入，允許在作用中語音工作階段期間傳送文字訊息
+ `false`：系統提示和對話歷史記錄的標準文字輸入
**角色類型：**
+ `SYSTEM`：系統指示和提示
+ `USER`：對話歷史記錄或跨模式輸入中的使用者訊息
+ `ASSISTANT`：對話歷史記錄中的助理回應
+ `SYSTEM_SPEECH`：控制印地文程式碼切換的轉錄格式 (Latin/Devanagari/mixed 指令碼）
```
{
"event": {
"contentStart": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // unique identifier for the content block
"type": "TEXT",
"interactive": "boolean", // true for cross-modal input
"role": "SYSTEM" | "USER" | "ASSISTANT" | "TOOL" | "SYSTEM_SPEECH",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
**範例 - 系統提示：**
```
{
"event": {
"contentStart": {
"promptName": "conv-12345",
"contentName": "system-prompt-1",
"type": "TEXT",
"interactive": false,
"role": "SYSTEM",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
**範例 - 跨模式輸入：**
```
{
"event": {
"contentStart": {
"promptName": "conv-12345",
"contentName": "user-text-1",
"type": "TEXT",
"interactive": true,
"role": "USER",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
#### 音訊
```
{
"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"
}
}
}
}
```
#### 工具
```
{
"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"
}
}
}
}
}
```
### 4. TextInputContent
```
{
"event": {
"textInput": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // unique identifier for the content block
"content": "string"
}
}
}
```
### 5. AudioInputContent
```
{
"event": {
"audioInput": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // same unique identifier from its contentStart
"content": "base64EncodedAudioData"
}
}
}
```
### 6. 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
}
}
```
### 7. InputContentEndEvent
```
{
"event": {
"contentEnd": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string" // same unique identifier from its contentStart
}
}
}
```
### 8. PromptEndEvent
```
{
"event": {
"promptEnd": {
"promptName": "string" // same unique identifier from promptStart event
}
}
}
```
### 9. RequestEndEvent
```
{
"event": {
"sessionEnd": {}
}
}
```