Qwen-Audio は、低遅延の音声会話を実現するエンドツーエンドのリアルタイム音声対話モデルです。音声アシスタント、AI カスタマーサービス、AI コンパニオンなどのユースケースで利用できます。
概要
Qwen-Audio は、ストリーミング入出力に対応した全二重接続を介して、リアルタイムの音声を音声とテキストに変換します。
このモデルは WebSocket に加えて、AOQ と WebRTC をサポートします。安定したレイテンシー、弱いネットワークでの対話性能、リアルタイム全二重通信のノイズ抑制とエコーキャンセルを重視するクライアント統合では、AOQ を優先的に検討してください。プロトコルの比較と選択は、API リファレンスをご覧ください。
- 3つの対話モード:音響 VAD (server_vad)、インテリジェントな意味的発話ターン検出 (smart_turn)、手動制御 (プッシュツートーク)
- smart_turn モードでは、モデルは音響知覚と意味理解を組み合わせて発話ターンの境界を判断するため、「えーと」や「うーん」などのフィラー音で会話が中断されることはありません。
- Function Calling のサポートにより、モデルは追加情報を得るためにいつ外部ツールを呼び出すかを判断できます。
- 会話コンテキスト管理:会話アイテムを作成、取得、削除して、過去のコンテキストを注入したり、無関係なアイテムを削除したりできます。
- 会話のコンテキストに基づいてトーン、ペース、感情を動的に調整する表現力豊かな音声出力
- システム音声とクローン音声のサポート:Voice Cloning を使用して、音声出力用のカスタム AI 音声を作成できます。
- smart_turn モードでの話者強調:ターゲットユーザーから事前に録音された音声を渡すことで、モデルが全二重会話中にその話者にロックオンし、他の声やバックグラウンドノイズを効果的にブロックします。
仕組み
Qwen-Audio は、イベント駆動型アーキテクチャによる全二重接続を使用します。持続的接続を介して、クライアントはマイクの音声を継続的にストリーミングし、サーバーはリアルタイムで音声とテキストの応答を返すことで、両者が同時にデータを交換します。全体のやり取りはイベント駆動型であり、クライアントが session.update や input_audio_buffer.append などのイベントを送信すると、サーバーは response.audio.delta や response.done などのイベントで応答します。ポーリングは不要です。
一般的な接続ライフサイクルは、WebSocket 接続を確立し、session.update を送信して会話パラメーターを設定し、音声をストリームして応答を受信し、最後に接続を閉じるという流れです。
音声フォーマット
方向 | フォーマット | 仕様 |
|---|---|---|
入力 (クライアントからサーバー) | PCM | 16 kHz サンプルレート、16 ビット深度、モノラル |
出力 (サーバーからクライアント) | PCM | 24 kHz サンプルレート、16 ビット深度、モノラル |
qwen-audio-3.1-realtime-plus を使用する場合、session.input_audio_transcription.language と session.output_audio.language で、入力音声のソース言語と出力音声のターゲット言語をそれぞれ指定できます。各パラメータに指定できる言語コードについては、クライアントイベントをご参照ください。このうち session.output_audio.language は音声合成(TTS)に作用し、可能な限りターゲット言語で音声を出力しますが、常に有効になるとは限らず、モデルが返すテキストの言語も変わりません。
コンテキスト容量
モデルは会話履歴を保持します。ターン数または累積音声時間が以下の制限を超えると、古い履歴は自動的に破棄されます。最大音声時間は、モデルのコンテキストが保持できる累積音声時間の上限です。
モデル | 最大音声ターン数 | 最大音声時間 |
|---|---|---|
qwen-audio-3.0-realtime-plus | 50 | 300 秒 |
qwen-audio-3.0-realtime-flash | 50 | 300 秒 |
前提条件
クイックスタート
以下の手順に従って、Qwen-Audio モデルとのリアルタイム音声会話を開始します。
- ネイティブ WebSocket
server_vad モードでネイティブ WebSocket 接続を使用したリアルタイムのマイク会話を示します。実行する前に、必須の依存関係をインストールしてください。realtime_quickstart.py として保存します:python realtime_quickstart.py を実行し、マイクに話しかけると、リアルタイムの会話を開始できます。サーバーは自動的に発話アクティビティを検出し、応答をトリガーします。完全な例次の例は、基本的な会話に音声割り込み処理とエコーキャンセレーションを追加したものです。2つのファイルを同じディレクトリに作成してください:B64PCMPlayer.py
B64PCMPlayer.py
realtime_demo.py
realtime_demo.py
websockets のバージョンが 11 未満の場合は、コード内で additional_headers を extra_headers に変更するか、pip install --upgrade websockets を実行してアップグレードします。python realtime_demo.py を実行し、マイクに話しかけると、リアルタイムの会話が始まります。システムが自動的に発話アクティビティを検出し、応答をトリガーします。セッション設定
対話モード
Qwen-Audio は、server_vad(音響 VAD が発話の開始と終了を自動検出)、smart_turn(音響情報と意味情報を組み合わせるインテリジェントなターン検出。smart_turn_v2 を推奨)、push-to-talk(クライアントによる手動制御)の 3 つの対話モードをサポートします。詳細とシーケンス図を含むイベントのやり取りの順序は、対話モードをご覧ください。
turn_detection は、最初の音声が送信される前 (IDLE 状態) にのみ設定できます。セッション中に対話モードを切り替えるには、接続を切断して再接続してください。session.update イベントで turn_detection フィールドを設定します:
- server_vad:
- smart_turn:
- プッシュツートーク:
manual_funchat.py
manual_funchat.py
システム指示
instructions パラメーターを使用して、モデルのロール、応答スタイル、および動作プリファレンスを定義します。このパラメーターを session.update で設定すると、会話全体に適用されます。
- 明確なロールアイデンティティ (例:「あなたはインテリジェントな音声アシスタントです」または「あなたは英会話の家庭教師です」) を定義し、任意で名前や性別などの詳細を含めます。
- 自然なトーンが内容の完全性を損なわないことを強調しつつ、会話のトーンや表現スタイルを指定します。詳細、数値、具体的な推奨事項は、リラックスした自然な方法で表現されるだけで、引き続き含める必要があります。
- 会話中のすべてのコンテキスト制約 (予算、好み、制限、以前の合意など) を考慮するようにモデルに指示します。複数の条件が適用される場合は、それぞれに対処し、重要な情報を省略しないようにします。
- 出力形式を制御します:ユーザーが特に要求しない限り、絵文字やその他の特殊文字、Markdown 形式を避けます。自然な TTS 再生を保証するために、プレーンテキストを出力します。
- 応答戦略を定義します:簡単な挨拶やカジュアルなやり取りは簡潔で自然に保ちます。推論、複数条件の問題、推奨リスト、または安全に関するアドバイスについては、完全性を優先します。重要な情報 (価格、場所、条件など) が完全に存在し、不要な前置き、繰り返し、またはフィラーがないことを確認します。
- フォローアップ戦略を設定します:「まずユーザーの現在の質問に答え、次に会話を進めるために最後に自然にフォローアップの質問をする」という原則に従います。一度に1つの質問のみを行い、連続して複数の質問をしたり、繰り返し確認したりしないでください。
instructions 構成です。この構成には、ロールの定義、会話スタイル、フォーマット制御、フォローアップ戦略が含まれています。そのまま直接使用するか、ニーズに合わせて調整してください:
命令の例を示します。ユースケースに合わせて選択するか、さらにカスタマイズしてください。
- デイジー (甘くてクールなコンパニオン):
- レン (クールで辛口):
- モーチェン (穏やかでカリスマ的):
- ハンニバル (エレガントで鋭敏):
- ヘイズ (東北の仲間):
音声設定
voice パラメーターを使用して、モデルの応答の TTS 音声を設定します。デフォルトは longanqian です。2 種類の音声がサポートされています。
システムボイス:音声名を直接指定します。使用可能な値: longanqian、longanlingxin、longanlingxi、longanxiaoxin、longanlufeng。
target_model を qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus、または qwen-audio-3.0-realtime-flash に設定し、返された voice_id を voice パラメーターに設定します。
出力モダリティ
モデルの出力タイプをコントロールするには、modalities パラメーターを使用します:
["audio", "text"](デフォルト):音声とテキストの両方を出力します。["text"]: 音声は出力せず、テキストのみを出力します。デバッグ、ロギング、またはテキスト応答のみが必要なシナリオに適しています。
response.create の response.modalities フィールドを使用して、単一の応答のモダリティ設定をオーバーライドします。
VAD 設定
server_vad モードでは、VAD の動作を調整するために、session.turn_detection オブジェクトで以下のパラメーターを設定します (これらのパラメーターは smart_turn モードでは効果がありません):
パラメーター | タイプ | 説明 |
|---|---|---|
| float | VAD の感度。値を低くすると VAD の感度が上がり、かすかな音 (バックグラウンドノイズを含む) も音声として検出しやすくなります。値を高くすると感度が下がり、検出にはより明瞭で大きな音声が必要になります。範囲:[-1.0, 1.0]。デフォルト:0.5。 |
| integer | 音声が終了してからモデルの応答をトリガーするまでの最小無音時間 (ミリ秒単位)。値を低くすると応答は速くなりますが、短い間での誤トリガーの原因になることがあります。範囲:[200, 6000]。デフォルト:800。会話での推奨範囲:400-800。 |
履歴ターン制御
max_history_turns パラメーターを使用して、推論中にモデルが参照する過去の QA ターン数を制御します。値を高くすると、モデルはより多くの会話履歴を確認してコンテキスト理解を向上させることができますが、トークン消費量と推論遅延が増加します。
max_history_turns の有効値: 1~50。デフォルト: 20。
チューニングのヒント:
- 短い会話 (簡単な Q&A など):遅延を減らすために低い値 (例:5-10) を設定します。
- 長い会話 (複数ターンのカスタマーサービスなど):モデルが完全なコンテキストを理解するのを助けるために高い値 (例:30-50) を設定します。
高度な機能
Function Calling
Qwen-Audio は Function Calling をサポートしており、モデルが会話のコンテキストに基づいていつ外部ツールを呼び出すかを決定できます。
1. ツールの登録
session.update を使用して tools を設定します:
response.function_call_arguments.done を受信した後、クライアントでツールを実行し、 conversation.item.create を介して結果を返送します:
response.create を送信します:
function_call アイテムを含めることができ、通常のメッセージと関数呼び出しの両方が含まれる場合があります。関数呼び出しの内容は、再生のために TTS に送信されません。realtime_demo.py をベースに、Function Calling サポートを統合します。実行する前に、B64PCMPlayer.py が同じディレクトリにあることを確認してください。
realtime_fc_demo.py
realtime_fc_demo.py
python realtime_fc_demo.py を実行し、マイクに向かって話しかけて、Function Calling を使用したリアルタイムの会話をお試しください。例えば、「杭州の天気は?」や「北京から上海までの列車のチケットはいくらですか?」などと質問すると、モデルが自動的に対応するツールを呼び出し、結果を返します。
会話コンテキスト管理
Qwen-Audio では、クライアントイベントを通じてコンテキスト内の会話アイテムを管理できます。これを使用して、過去のコンテキストを注入したり、テキスト情報を追加したり、無関係な会話アイテムを削除したりします。
-
会話アイテムの作成 (
conversation.item.create): コンテキストに会話アイテムを挿入します。以下の 3 つのitem.typeの値がサポートされています:message: 通常の会話メッセージです。role(system、user、またはassistant) とcontent配列を指定します。会話履歴やシステム命令を注入するために使用します。function_call: 関数呼び出しリクエストです。call_id、name、およびarguments(JSON 文字列) を指定します。通常はサーバーによって生成されますが、クライアントがこれを使用して過去の関数呼び出しレコードを挿入することもできます。function_call_output: ツールの実行結果です。call_idとoutput(JSON 文字列) を指定します。function_callを受信後、クライアントでツールを実行し、このタイプで結果を返します。
previous_item_idパラメーターは、どの既存の会話アイテムの後に新しいアイテムを挿入するかを指定します。これにより、会話履歴の任意の位置にコンテンツを挿入できます。省略された場合、新しいアイテムは末尾に追加されます。- 特定の位置にユーザーメッセージを挿入する:
- Function Calling の結果を返す:
conversation.item.create で指定された item.id がカンバセーション内にすでに存在する場合、エラーが返されます。- 会話アイテムの取得 (
conversation.item.retrieve): サーバーに保存されている会話アイテムを照会します。音声タイプのコンテンツの場合、生の音声データではなく、文字起こしテキストのみが返されます。
- 会話アイテムの削除 (
conversation.item.delete): 会話コンテキストから特定のアイテムを削除します。
環境音の文字起こし
smart_turn モードのみ。VAD が音声アクティビティを検出したものの、意味解析によってそれが有効なターンではない (ノイズや、「uh」や「hmm」などのフィラー音) と判断された場合、サーバーは会話のターンをトリガーしません。代わりに、ASR 結果を ambient_audio_transcription イベントとしてクライアントに送信します。このトランスクリプションは、会話のコンテキストには書き込まれません。
delta と completed のフェーズが含まれます。このイベントを使用すると、周囲の音声のモニタリングや会話シーンの認識を実装できます。
話者強調
smart_turn モードのみ。対象ユーザーの事前に録音された音声 URL を session.update で渡します。モデルが双方向の会話中にその話者にロックオンすることで、他の音声やバックグラウンドノイズは効果的に無視され、オープンな環境でもスムーズな双方向のやり取りが可能になります。
設定: 最初の session.update 内で、turn_detection.voiceprint_audio_urls に公開アクセス可能なボイスプリント音声 URL を渡します。
- 最大5つの URL。音声は 16 kHz PCM または WAV 形式である必要があります。
- このパラメーターは、最初の
session.updateでのみ有効になります。このフィールドは、後続の呼び出しでは無視されます。
voiceprint_audio_list.in_progress: 登録が開始されました。session.updatedの前に送信され、item_idを含みます。voiceprint_audio_list.completed: 登録が成功しました。item_idはin_progressのものと一致します。voiceprint_audio_list.failed: 登録は失敗し、エラーの理由を示すreasonフィールドが含まれます (例: 音声 URL にアクセスできない)。登録が失敗しても、進行中の会話はブロックされません。
本番運用
フォールトトレランスの設定
- クライアントの再接続: ネットワークジッターに対処するために自動再接続を実装します。
on_errorコールバックで再接続信号を設定し、再試行にはエクスポネンシャルバックオフ (例: 1 秒、2 秒、4 秒待機) を使用します。 - エラーの分類: クライアントエラー (
invalid_request_error) は会話を切断しません。ログに記録するか、パラメーターを調整する必要があります。サーバーエラー (server_error) は接続を終了し、再接続が必要になります。 - 割り込み処理:
server_vad/smart_turnモードでは、新しいユーザーの発話がモデルの進行中の応答を自動的に中断し、response.doneはstatus=cancelledを返します。音声の重複を避けるため、input_audio_buffer.speech_startedを受信したら、直ちにローカルの再生バッファーをクリアしてください。
接続ライフサイクル
典型的な WebSocket セッションは、以下のライフサイクルに従います:
- 接続: クライアントが WebSocket 接続を開始し、サーバーが
session.createdイベントを返します。 - 設定:クライアントは
session.updateを送信して、対話モード、音声、ツール、およびその他のパラメーターを設定します。オーディオを送信する前に、このステップを完了してください。 - インタラクト: クライアントはオーディオを継続的にストリーミングします (
input_audio_buffer.append)。サーバーは VAD 検出または手動トリガーに基づいて推論を実行し、音声とテキストをストリーミングで返します。 - 切断:クライアントが WebSocket 接続を閉じます。接続が長時間アイドル状態の場合、サーバーも切断することがあります。
遅延の最適化
- 音声チャンクサイズ:チャンクあたり約 100 ms の音声データ (16 kHz x 16 ビット x モノラル = 3,200 バイト/チャンク) を送信します。これにより、リアルタイム性能とネットワーク効率のバランスが取れます。
- ストリーミング再生:
response.audio.deltaが到着次第、オーディオの再生を開始します。完全な応答を再生するためにresponse.doneを待つ必要はありません。 - 中断時のバッファーのクリア:
input_audio_buffer.speech_startedを受信したときは、直ちにローカル再生バッファーをクリアして、古い音声が再生され続けるのを防ぎます。
サポートされるモデルとリージョン
- シンガポール
- 中国 (北京)
- qwen-audio-3.0-realtime-plus
- qwen-audio-3.0-realtime-flash
API リファレンス
AOQ のアクセスフローとサンプルは、AOQ アクセスをご覧ください。プロトコルの選択とリファレンスの入口は、API リファレンスをご覧ください。
- WebSocket API
- クライアントイベント
- サーバーイベント
- AOQ クライアント SDK
- WebRTC アクセス