양방향 API를 사용하여 출력 이벤트 처리
Amazon Nova Sonic 모델이 응답하면 구조화된 이벤트 시퀀스를 따릅니다. 이 흐름은 sessionId, promptName, completionId와 같은 고유 식별자를 포함하는 completionStart 이벤트로 시작합니다. 이러한 식별자는 응답 주기 전체에서 일관되며 모든 후속 응답 이벤트를 통합합니다.
각 응답 유형은 일관된 세 부분으로 된 패턴을 따릅니다. contentStart는 콘텐츠 유형 및 형식, 실제 콘텐츠 이벤트를 정의하고, contentEnd는 해당 세그먼트를 닫습니다. 응답에는 일반적으로 자동 음성 인식(ASR) 트랜스크립션(사용자가 말한 내용), 선택적 도구 사용(외부 정보가 필요한 경우), 텍스트 응답(모델이 말하려는 내용), 오디오 응답(음성 출력) 등 여러 콘텐츠 블록이 순차적으로 포함됩니다.
ASR 트랜스크립션이 먼저 표시되어 contentStart에 role: "USER" 및 "additionalModelFields":
"{\"generationStage\":\"FINAL\"}"을 사용하여 모델이 사용자 음성을 이해한 내용을 전달합니다. 모델에 외부 데이터가 필요한 경우 특정 도구 이름과 파라미터를 포함하는 도구 관련 이벤트를 전송합니다. 텍스트 응답은 role:
"ASSISTANT" 및 "additionalModelFields":
"{\"generationStage\":\"SPECULATIVE\"}"를 사용하여 계획된 음성의 미리 보기를 제공합니다. 그런 다음 오디오 응답은 스트림 전체에서 동일한 contentId를 공유하는 base64로 인코딩된 음성 청크를 전달합니다.
오디오 생성 중 Amazon Nova Sonic은 개입 기능을 통해 자연스러운 대화 흐름을 지원합니다. Amazon Nova Sonic이 말하는 동안 사용자가 Nova Sonic을 중단하면 Nova Sonic은 즉시 음성 생성을 중지하고 듣기 모드로 전환한 다음, 중단 발생을 알리는 콘텐츠 알림을 전송합니다. Nova Sonic은 실시간보다 빠르게 작동하기 때문에 일부 오디오는 이미 전송되었지만 아직 재생되지 않았을 수 있습니다. 중단 알림을 통해 클라이언트 애플리케이션은 오디오 대기열을 지우고 즉시 재생을 중지하여 응답성이 뛰어난 대화 경험을 제공할 수 있습니다.
오디오 생성이 완료되거나 개입을 통해 중단된 후 Amazon Nova Sonic은 실제로 말한 내용의 문장 수준 트랜스크립션이 포함된 추가 텍스트 응답을 제공합니다. 이 텍스트 응답에는 role:
"ASSISTANT" 및 "additionalModelFields":
"{\"generationStage\":\"FINAL\"}"이 있는 contentStart 이벤트가 포함됩니다.
응답 처리 과정에서 토큰 소비를 추적하기 위해 usageEvent 이벤트가 전송됩니다. 이러한 이벤트에는 입력 토큰과 출력 토큰(음성 및 텍스트 모두)에 대한 자세한 지표와 그 누적 합계가 포함되어 있습니다. 각 usageEvent는 대화 흐름의 다른 이벤트와 동일한 sessionId, promptName, completionId를 유지합니다. 세부 정보 섹션에서는 토큰 사용량의 증분 변경 사항(델타)과 총합을 모두 제공하여 대화 중 사용량을 정확하게 모니터링할 수 있습니다.
모델은 원래 식별자와 대화가 어떻게 끝났는지를 나타내는 stopReason이 포함된 completionEnd 이벤트를 전송합니다. 이 이벤트 계층 구조는 애플리케이션이 응답의 어느 부분이 함께 속하는지 추적하고 그에 따라 처리하여 여러 턴에 걸쳐 대화 컨텍스트를 유지할 수 있도록 합니다.
출력 이벤트 흐름은 응답 생성 단계로 들어가면서 시작됩니다. 자동 음성 인식으로 시작하여 사용할 도구를 선택하고, 음성을 트랜스크립션하고, 오디오를 생성하고, 트랜스크립션을 완료하고, 세션을 끝냅니다.
출력 이벤트 흐름
이 섹션에서는 출력 이벤트 흐름의 구조를 설명합니다.
-
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 } } -
CompleteStartEvent"event": { "completionStart": { "sessionId": "string", // unique identifier "promptName": "string", // same unique identifier from promptStart event "completionId": "string", // unique identifier } } -
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" } }
-
-
ToolUse-
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" } } } -
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" } } -
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" } }
-
-
AudioOutputContent-
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 } } } -
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 } } -
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" } }
-
-
CompletionEndEvent"event": { "completionEnd": { "sessionId": "string", // unique identifier "promptName": "string", // same unique identifier from promptStart event "completionId": "string", // unique identifier "stopReason": "END_TURN" } }
