# 双方向 API を使用した入力イベントの処理
双方向 Stream API は、構造化された入出力イベントを持つイベント駆動型アーキテクチャを使用します。会話型アプリケーションを正常に実装し、インタラクション全体を通して適切な会話状態を維持するには、正しいイベントの順序を理解することが不可欠です。
## 概要
Nova Sonic の会話は、構造化されたイベントシーケンスに従います。まず、温度やトークンの制限などの推論設定パラメータを含む `sessionStart` イベントを送信します。次に、`promptStart` を送信してオーディオ出力形式とツール設定を定義し、後続のすべてのイベントに含める必要がある一意の `promptName` 識別子を割り当てます。
インタラクションタイプ (システムプロンプト、オーディオなど) ごとに、3 つの部分からなるパターンに従います。`contentStart` を使用してコンテンツタイプとコンテンツのロール (`SYSTEM`、`USER`、`ASSISTANT`、`TOOL`、`SYSTEM_SPEECH`) を定義し、実際のコンテンツイベントを指定し、`contentEnd` で終了してそのセグメントを閉じます。`contentStart` イベントは、ツールの結果を送信するか、オーディオをストリーミングするか、システムプロンプトを送信するかを指定します。`contentStart` イベントに固有の `contentName` 識別子。
## 会話履歴
会話履歴は、システムプロンプトの後、音声ストリーミングが開始される前に 1 回のみ含めることができます。同じ `contentStart`/`textInput`/`contentEnd` のパターンに従います。`USER` および `ASSISTANT` ロールは、履歴メッセージごとに `contentStart` イベントで定義する必要があります。これにより、現在の会話に不可欠なコンテキストが提供されますが、新しいユーザー入力が開始される前に完了する必要があります。
## オーディオストリーミング
オーディオストリーミングは、継続的なマイクサンプリングで動作します。最初の `contentStart` を送信した後、オーディオフレーム (それぞれ約 32 ミリ秒) はマイクから直接キャプチャされ、同じ `contentName` を使用してすぐに `audioInput` イベントとして送信されます。これらのオーディオサンプルは、キャプチャ時にリアルタイムでストリーミングし、会話全体で自然なマイクサンプリング頻度を維持する必要があります。すべてのオーディオフレームは、会話が終了して明示的に閉じられるまで、単一のコンテンツコンテナを共有します。
## セッションを終了する
会話が終了した後、または終了する必要がある場合は、開いているすべてのストリームを適切に閉じ、セッションを正しい順序で終了することが重要です。セッションを適切に終了し、リソースリークを回避するには、特定の終了シーケンスに従う必要があります。
+ `contentEnd` イベントで開いているオーディオストリームをすべて閉じます。
+ 元の `promptName` を参照する `promptEnd` イベントを送信します。
+ `sessionEnd` イベントを送信します。
これらの終了イベントのいずれかをスキップすると、不完全な会話や孤立したリソースが発生する可能性があります。
これらの識別子は階層構造を作成します。`promptName` はすべての会話イベントを結び付け、それぞれの `contentName` は特定のコンテンツブロックの境界を示します。この階層により、モデルはインタラクション全体で適切なコンテキストを維持できます。
## 入力イベントフロー
入力イベントフローの構造は、このセクションで説明します。
### 1. RequestStartEvent (セッション開始)
セッション開始イベントは、推論設定とターン検出設定を使用して会話を初期化します。
**推論の設定:**
+ `maxTokens`: レスポンスで生成するトークンの最大数
+ `topP`: ランダム性を制御するための Nucleus サンプリングパラメータ (0.0～1.0)
+ `temperature`: 生成時のランダム性を制御します (0.0 to 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
プロンプト開始イベントは、出力形式、音声選択、使用可能なツールなどの会話設定を定義します。
使用可能な音声 ID については、「[言語サポートと多言語機能](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`: ヒンディー語コードスイッチングの文字起こしフォーマットを制御します (ラテン/デーヴァナーガリー/混合スクリプト)
```
{
"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": {}
}
}
```