使用雙向 API 處理輸出事件 - Amazon Nova
輸出事件流程

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

使用雙向 API 處理輸出事件

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

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

ASR 轉錄會先出現，透過 role: "USER"和 "additionalModelFields": "{\"generationStage\":\"FINAL\"}"提供模型對使用者語音的了解contentStart。當模型需要外部資料時，它會傳送具有特定工具名稱和參數的工具相關事件。文字回應提供使用 role: "ASSISTANT"和 的規劃語音預覽"additionalModelFields": "{\"generationStage\":\"SPECULATIVE\"}"。然後，音訊回應會在整個串流contentId中交付共用相同的 base64 編碼語音區塊。

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

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

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

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

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

說明 Amazon Nova Sonic 輸出事件流程的圖表。

輸出事件流程

本節說明輸出事件流程的結構。

  1. UsageEvent

    "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

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

  3. TextOutputContent

    • ContentStart

      "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

      "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

      "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

    1. ContentStart

      "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"
      }
    }
  }

    2. ToolUse

      "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"
    }
  }

    3. ContentEnd

      "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

    1. ContentStart

      "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
            }
      }
  }

    2. AudioOutput

      "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
        }
    }

    3. ContentEnd

      "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

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