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

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

當 Amazon Nova Sonic 模型回應時，它會遵循結構化事件序列。該流程從包含 `sessionId`、`promptName` 和 `completionId` 等唯一識別符的 `completionStart` 事件開始。這些識別符在整個回應週期中是一致的，並統一所有後續的回應事件。

## 概觀
<a name="sonic-output-overview"></a>

每個回應類型都遵循一致的三部分模式：`contentStart` 定義內容類型和格式，實際內容事件，`contentEnd` 關閉該區段。回應通常會依序包含多個內容區塊：自動語音辨識 (ASR) 轉錄 (使用者說的話)、選用的工具使用 (需要外部資訊時)、文字回應 (模型打算說的話) 和音訊回應 (口語輸出)。

## 回應內容類型
<a name="sonic-response-content-types"></a>

### ASR 轉錄
<a name="sonic-asr-transcription"></a>

ASR 轉錄會先出現，在 `contentStart` 中使用 `role: "USER"` 和 `"additionalModelFields": "{\"generationStage\":\"FINAL\"}"` 提供模型對使用者語音的理解。

### 工具使用
<a name="sonic-tool-use-response"></a>

當模型需要外部資料時，它會傳送具有特定工具名稱和參數的工具相關事件。

### 文字回應
<a name="sonic-text-response"></a>

文字回應透過 `role: "ASSISTANT"` 和 `"additionalModelFields": "{\"generationStage\":\"SPECULATIVE\"}"` 提供規劃語音的預覽。

### 音訊回應
<a name="sonic-audio-response"></a>

然後，音訊回應會傳送 base64 編碼的語音區塊，這些區塊在整個串流中共用相同的 `contentId`。

## 插斷支援
<a name="sonic-barge-in-support"></a>

在音訊產生期間，Amazon Nova Sonic 透過其插斷功能支援自然對話流程。當使用者在 Amazon Nova Sonic 說話時將其打斷，Nova Sonic 會立即停止產生語音、切換到聆聽模式，並傳送內容通知，指出已發生中斷。由於 Nova Sonic 的運作速度比即時快，因此有些音訊可能已交付但尚未播放。中斷通知可讓用戶端應用程式清除其音訊佇列並立即停止播放，從而建立回應式對話體驗。

## 最終轉錄
<a name="sonic-final-transcription"></a>

音訊產生完成 (或透過插斷將其中斷) 後，Amazon Nova Sonic 會提供額外的文字回應，其中包含實際說話內容的句子層級轉錄。此文字回應包含一個帶有 `role: "ASSISTANT"` 和 `"additionalModelFields": "{\"generationStage\":\"FINAL\"}"` 的 `contentStart` 事件。

## 用量追蹤
<a name="sonic-usage-tracking"></a>

在整個回應處理過程中，會傳送 `usageEvent` 事件來追蹤詞元消耗。這些事件包含關於輸入詞元和輸出詞元 (語音和文字) 及其累積總數的詳細指標。每個 `usageEvent` 都會維護與對話流程中其他事件相同的 `sessionId`、`promptName` 和 `completionId`。詳細資訊區段同時提供增量變更 (差異) 和累積的記號用量總計，以便精確監控對話期間的用量。

## 完成
<a name="sonic-completion"></a>

模型會傳送帶有原始識別符的 `completionEnd` 事件，並傳送 `stopReason` 指出對話結束的方式。此事件階層可確保您的應用程式可以追蹤回應的哪些部分屬於一起，並相應地處理它們，從而在多個回合中維持對話上下文。

輸出事件流程從進入回應產生階段開始。它從自動語音辨識開始，選取要使用的工具，轉錄語音，產生音訊，完成轉錄，以及完成工作階段。

![\[alt text not found\]](http://docs.aws.amazon.com/zh_tw/nova/latest/nova2-userguide/images/Output-Event -Flow_3.png)


## 輸出事件流程
<a name="sonic-output-event-flow"></a>

本節描述了輸出事件流程的結構。

### 1. UsageEvent
<a name="sonic-usage-event"></a>

```
"event": {
    "usageEvent": {
        "completionId": "string", // unique identifier for completion
        "details": {
            "delta": { // incremental changes since last event
                "input": {
                    "speechTokens": number, // input speech tokens
                    "textTokens": number // input text tokens
                },
                "output": {
                    "speechTokens": number, // speech tokens generated
                    "textTokens": number // text tokens generated
                }
            },
            "total": { // cumulative counts
                "input": {
                    "speechTokens": number, // total speech tokens processed
                    "textTokens": number // total text tokens processed
                },
                "output": {
                    "speechTokens": number, // total speech tokens generated
                    "textTokens": number // total text tokens generated
                }
            }
        },
        "promptName": "string", // same unique identifier from promptStart event
        "sessionId": "string", // unique identifier
        "totalInputTokens": number, // cumulative input tokens
        "totalOutputTokens": number, // cumulative output tokens
        "totalTokens": number // total tokens in the session
    }
}
```

### 2. CompleteStartEvent
<a name="sonic-completion-start-event"></a>

```
"event": {
    "completionStart": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
    }
}
```

### 3. TextOutputContent
<a name="sonic-text-output-content"></a>

#### ContentStart
<a name="sonic-text-output-content-start"></a>

```
"event": {
    "contentStart": {
        "additionalModelFields": "{\"generationStage\":\"FINAL\"}" | "{\"generationStage\":\"SPECULATIVE\"}",
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // unique identifier for the content block
        "type": "TEXT",
        "role": "USER" | "ASSISTANT",
        "textOutputConfiguration": {
            "mediaType": "text/plain"
        }
    }
}
```

#### TextOutput
<a name="sonic-text-output"></a>

```
"event": {
    "textOutput": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "content": "string" // User transcribe or Text Response
    }
}
```

#### ContentEnd
<a name="sonic-text-output-content-end"></a>

```
"event": {
    "contentEnd": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "stopReason": "PARTIAL_TURN" | "END_TURN" | "INTERRUPTED",
        "type": "TEXT"
    }
}
```

### 4. ToolUse
<a name="sonic-tool-use-output"></a>

#### ContentStart
<a name="sonic-tool-use-content-start"></a>

```
"event": {
    "contentStart": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // unique identifier for the content block
        "type": "TOOL",
        "role": "TOOL",
        "toolUseOutputConfiguration": {
            "mediaType": "application/json"
        }
    }
}
```

#### ToolUse
<a name="sonic-tool-use-event"></a>

```
"event": {
    "toolUse": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "content": "json",
        "toolName": "string",
        "toolUseId": "string"
    }
}
```

#### ContentEnd
<a name="sonic-tool-use-content-end"></a>

```
"event": {
    "contentEnd": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "stopReason": "TOOL_USE",
        "type": "TOOL"
    }
}
```

### 5. AudioOutputContent
<a name="sonic-audio-output-content"></a>

#### ContentStart
<a name="sonic-audio-output-content-start"></a>

```
"event": {
    "contentStart": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // unique identifier for the content block
        "type": "AUDIO",
        "role": "ASSISTANT",
        "audioOutputConfiguration": {
            "mediaType": "audio/lpcm",
            "sampleRateHertz": 8000 | 16000 | 24000,
            "sampleSizeBits": 16,
            "encoding": "base64",
            "channelCount": 1
        }
    }
}
```

#### AudioOutput
<a name="sonic-audio-output-event"></a>

```
"event": {
    "audioOutput": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "content": "base64EncodedAudioData", // Audio
    }
}
```

#### ContentEnd
<a name="sonic-audio-output-content-end"></a>

```
"event": {
    "contentEnd": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "stopReason": "PARTIAL_TURN" | "END_TURN",
        "type": "AUDIO"
    }
}
```

### 6. CompletionEndEvent
<a name="sonic-completion-end-event"></a>

```
"event": {
    "completionEnd": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "stopReason": "END_TURN" 
    }
}
```