ターンのライフサイクル
ユーザーターンの合間、セッションはアイドル状態です。ユーザーが話し始めるとturn.start が発火し、トランスクリプトが構築されるに従って turn.update イベントが続きます。
例: 1 ターン
ユーザーが「Hi I need to cancel my subscription please.」と発話します。turn.eager_end は「cancel」のあとで早めに発火しますが、ユーザーが話し続けるため turn.resume が続きます。2 回目の turn.eager_end はユーザーが本当に話し終えたときに届き、turn.end がそれを確定します。
イベント
API は会話の状態を表すために以下のイベントを発行します。words と languages を返すのは ink-preview のみです。ink-2 のイベントには transcript のみが含まれます。単語タイムスタンプと言語を参照してください。
ライフサイクルにはいくつかの保証があります:
- すべてのターンの最初のイベントは
turn.startです。 turn.eager_endの後には必ずturn.endまたはturn.resumeが続きます。turn.resumeは直前のturn.eager_endのあとにのみ発火します。turn.endは常にターンを閉じ、次のターンは新しいturn.startで始まります。
トランスクリプトの動作
transcript プロパティはターン内で累積的です。デルタではなく、このユーザーターンでこれまでに文字起こしされた完全なテキストが含まれます。イベント間で部分結果を連結する必要はありません。
発行されるすべてのテキストは確定 (final) です。モデルは既に送信したテキストを修正しません。turn.update の部分トランスクリプトは、変更を心配することなく到着した瞬間に利用できます。
ink-preview では、words も同じように動作しますが、1 つ違いがあります。単語は、モデルがその単語全体を聞き終えた時点で初めて追加されます。そのため、ターンの途中では words が transcript よりわずかに遅れることがあります。単語タイムスタンプを参照してください。
ターン検出の設定
ターン検出は単一のシグナルによって駆動されます。各時点で、モデルはユーザーがアクティブなターンにある尤度を0 から 1 の値として推定します。この値に対する 3 つのしきい値によって、turn.start、turn.eager_end、turn.end を発火するタイミングが決まります。
ターン検出には、ほとんどのボイスエージェントで十分に機能するデフォルト値が用意されています。ink-2 と ink-preview はこれらのデフォルトを共有します。レイテンシーと、各ターンの開始と終了をモデルがどれだけ正確に検出するかのバランスを取りながら、ユースケースに合わせてエージェントの会話フローを最適化するよう調整してください。
各パラメーターはレイテンシーと精度のトレードオフです。以下の表は、どちらの方向に動かすと何が起こるかを示しています。
3 つのしきい値は次の順序を保つ必要があります:
start_threshold > eager_end_threshold > end_threshold。上記の範囲に加えて、各値はこの順序を保つために隣接する値によって制約されます。そのため、eager end のしきい値を start のしきい値より高く設定したり、end のしきい値を eager end のしきい値より高く設定したりすることはできません。
これらは接続時にクエリパラメーター(turn_start_threshold、turn_eager_end_threshold、turn_end_threshold、turn_end_timeout_ms)で設定するか、ストリームの途中で config メッセージを使って変更できます。
一般的な構成
以下は、有用な出発点となる構成の例です。ユースケースに最も近いものを選び、そこから個々のしきい値を調整してください。- バランス型はデフォルトであり、多くのボイスエージェントの会話で出発点として適しています。
- 応答重視型は低レイテンシーを優先し、速いテンポの会話のやり取りに適しています。
- 待機重視型は精度を優先し、考えたり情報を調べたりするためにポーズする発信者や、ターンの途中で遮ることが大きな損失になる場合に適しています。
サンプルコード
turn.start と turn.end を処理すれば、動作するエージェントが得られます。ユーザーが話し始めたらエージェントの発話に割り込み、話し終えたら応答を生成します。レイテンシーを削減するには、turn.eager_end も処理します。発火した瞬間に応答生成を開始し、turn.resume が到着したらキャンセルし、turn.end がユーザーの完了を確定した瞬間に再生します。
エッジケース
音声なし vs 無音
API は連続した音声ストリームを想定しているため、音声入力をミュートしている間は無音(すべてゼロ)を送信してください。 音声の送信を停止すると、サーバーはユーザーが無音であると見なすのではなく、追加の音声チャンクが到着するのを待ちます。ネットワークの遅延に対応できるため、これは通常望ましい挙動です。イベントのドレイン
セッションの音声を送信し終えたら、{"type": "close"} を送信します。モデルはバッファリングされている音声をフラッシュし、残りのイベントを送信します。モデルが完了すると、サーバーがソケットをクローズします。
サーバーは文字起こしの精度を高めるために音声を一定量バッファします。close コマンドを送信しなかったり、メッセージの読み取りを早期に停止したりすると、バッファされた音声は処理されません。最後の 1 秒の音声を気にしないのであれば、これは問題ありません。
トランスクリプトの結合
最終トランスクリプトには、完了したターンごとに 1 つずつ、各turn.end イベントから transcript フィールドを取得してください。全文を組み立てるときは、ターン間にスペースを追加してください。 ターンのトランスクリプトには区切りのスペースが含まれないため、そのまま結合すると単語がつながってしまいます。
transcript は 累積的 です。各 turn.update、turn.eager_end、turn.end イベントには、その時点までのターンの全文がすでに含まれています。そのため、turn.update や turn.eager_end イベントのトランスクリプトを結合すると、トランスクリプトの一部が繰り返されます。これはテキストの重複のよくある原因です。これらのイベントは、トランスクリプトのチャンクではなく、ターン状態の更新として扱ってください。
最終トランスクリプトは turn.end のみから読み取ってください。
次に進む
オンラインで試す
サインアップやコード不要でターン検出を動作確認
API を使う
Realtime STT API で構築を開始
SDK を使う
実際のコードを見てみる