Skip to main content

Qwen-Omni-Realtime Python SDK

このトピックでは、DashScope Python SDK を使用して Qwen-Omni-Realtime を呼び出すための主要なインターフェイスとリクエストパラメーターについて説明します。

接続と認証は、WebSocket アクセスをご覧ください。イベントフィールドと JSON の例は、クライアントイベントとサーバーイベントをご覧ください。

前提条件

SDK のバージョンは 1.23.9 以降である必要があります。開始する前に、「リアルタイムマルチモーダルインタラクションフロー」をご確認ください。

使用開始

GitHub にアクセスしてサンプルコードをダウンロードしてください。3 つの呼び出しメソッドのサンプルコードを提供しています:
  1. 音声会話の例: マイクからリアルタイムの音声入力をキャプチャし、音声アクティビティ検出 (VAD) モードを有効にし、音声による割り込みをサポートします。
    enable_turn_detection パラメーターを True に設定します。
    エコーによる音声割り込みのトリガーを防ぐため、音声再生にはヘッドフォンを使用してください。
  2. 音声とビデオの会話の例: マイクとカメラからリアルタイムの音声とビデオの入力をキャプチャし、VAD モードを有効にし、音声による割り込みをサポートします。
    enable_turn_detection パラメーターを True に設定します。
    エコーによる音声割り込みのトリガーを防ぐため、音声再生にはヘッドフォンを使用してください。
  3. ローカル呼び出し: ローカルの音声とイメージを入力として使用し、手動モードを有効にします。これにより、送信ペースを手動でコントロールできます。
    enable_turn_detection パラメーターを False に設定します。

リクエストパラメーター

OmniRealtimeConversation クラスのコンストラクターメソッド (init) を使用して、次のリクエストパラメーターを設定できます。

パラメーター

タイプ

説明

model

str

Qwen-Omni モデルの名前。詳細については、「モデルリスト」をご参照ください。

url

str

呼び出しアドレス:

  • シンガポールリージョン: wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime

  • 北京リージョン: wss://dashscope.aliyuncs.com/api-ws/v1/realtime

update_session インターフェイスを使用して、次のリクエストパラメーターを構成できます。
パラメータータイプ説明
output_modalitieslist[MultiModality]モデルの出力モダリティ。テキストのみを出力する場合は [MultiModality.TEXT] に、音声とテキストの両方を出力する場合は [MultiModality.TEXT, MultiModality.AUDIO] に設定します。
voicestrモデルによって生成される音声の声。サポートされている声のリストについては、「声のリスト」をご参照ください。デフォルトの声:
  • qwen3-omni-flash-realtime-2025-09-15: "Cherry"
input_audio_formatAudioFormatユーザーの入力音声のフォーマット。現在、PCM_16000HZ_MONO_16BIT のみサポートされています。
output_audio_formatAudioFormatモデルの出力音声のフォーマット。現在、PCM_24000HZ_MONO_16BIT のみサポートされています。
smooth_outputboolこのパラメーターは qwen3-omni-flash-realtime-2025-09-15 でのみサポートされています。
  • True: 会話的な応答を取得します。
  • False: よりフォーマルな書き言葉スタイルの応答を取得します。
    ただし、コンテンツが音読しにくい場合、品質が低下する可能性があります。
  • None: モデルが会話的またはフォーマルな応答スタイルを自動的に選択します。
instructionsstrモデルの目的またはロールを設定するシステムメッセージ。例: あなたは五つ星ホテルの AI エージェントです。客室タイプ、施設、価格、予約ポリシーに関する顧客の質問に答えてください。正確かつフレンドリに対応してください。常にプロフェッショナルで役立つ態度で応答してください。未確認の情報やホテルのサービス範囲外の情報は提供しないでください。
enable_input_audio_transcriptionbool入力音声の音声認識を有効にするかどうかを指定します。
input_audio_transcription_modelstr入力音声の文字起こしに使用する音声認識モデルは qwen3-asr-flash-realtime に固定されており、変更できません。
turn_detection_typestrサーバー側の VAD タイプ。これは「server_vad」に固定されています。
turn_detection_thresholdfloatVAD 検出のしきい値。騒がしい環境ではこの値を増やし、静かな環境では減らします。
  • 値が -1 に近いほど、ノイズが音声として検出されやすくなります。
  • 値が 1 に近いほど、ノイズが音声として検出されにくくなります。
デフォルト値: 0.2。有効な値: [-1.0, 1.0]。
turn_detection_silence_duration_msint発話の終了を示す無音の期間。この期間を超えると、モデルは応答をトリガーします。デフォルト値: 800。有効な値: [200, 6000]。

主要なインターフェイス

OmniRealtimeConversation クラス

from dashscope.audio.qwen_omni import OmniRealtimeConversation 文を使用して OmniRealtimeConversation クラスをインポートできます。
メソッドシグネチャサーバー応答イベント (コールバック経由で配信)説明
def connect(self,) -> None
session.created
セッションが作成されました
session.updated
セッション構成が更新されました
サーバーとの接続を作成します。
def update_session(self,
                       output_modalities: list[MultiModality],
                       voice: str,
                       input_audio_format: AudioFormat = AudioFormat.
                       PCM_16000HZ_MONO_16BIT,
                       output_audio_format: AudioFormat = AudioFormat.
                       PCM_24000HZ_MONO_16BIT,
                       enable_input_audio_transcription: bool = True,
                       input_audio_transcription_model: str = None,
                       enable_turn_detection: bool = True,
                       turn_detection_type: str = 'server_vad',
                       prefix_padding_ms: int = 300,
                       turn_detection_threshold: float = 0.2,
                       turn_detection_silence_duration_ms: int = 800,
                       turn_detection_param: dict = None,
                       smooth_output: bool = True
                       **kwargs) -> None
session.updated
セッション構成が更新されました
現在のセッションインタラクションのデフォルト構成を更新します。パラメーター構成については、「リクエストパラメーター」セクションをご参照ください。接続を確立すると、サーバーはセッションのデフォルトの入力および出力構成を迅速に返します。デフォルトのセッション構成を更新するには、接続を確立した直後にこのインターフェイスを呼び出します。サーバーが session.update イベントを受信した後、パラメーター検証を実行します。パラメーターが無効な場合はエラーが返されます。それ以外の場合、サーバー側のセッション構成が更新されます。
def append_audio(self, audio_b64: str) -> None
NoneBase64 エンコードされた音声データセグメントをクラウド入力音声バッファーに追加します。音声バッファーは、書き込み後にコミットできる一時的なストレージです。
  • 「turn_detection」が有効な場合、音声バッファーは音声検出に使用され、サーバーがコミットするタイミングを決定します。
  • 「turn_detection」が無効な場合、クライアントは各イベントに配置する音声の量を選択でき、最大 15 MiB までです。たとえば、クライアントからより小さなデータブロックをストリーミングすると、VAD の応答性が向上します。
def append_video(self, video_b64: str) -> None
NoneBase64 エンコードされたイメージデータをクラウドビデオバッファーに追加します。イメージデータは、ローカルイメージまたはビデオストリームからリアルタイムでキャプチャされたイメージです。イメージ入力には次の制限が適用されます:
  • イメージフォーマットは JPG または JPEG である必要があります。推奨されるイメージ解像度は 480p または 720p で、最大 1080p です。
  • 単一のイメージのサイズは 500 KB (Base64 エンコーディング前) を超えることはできません。
  • イメージデータは Base64 エンコードされている必要があります。
  • 1 イメージ/秒の周波数でサーバーにイメージを送信します。
def clear_appended_audio(self, ) -> None
input_audio_buffer.cleared
サーバーが受信した音声をクリアします
現在のクラウドバッファーから音声を削除します。
def commit(self, ) -> None
input_audio_buffer.committed
サーバーがコミットされた音声を受信しました
append を使用して以前にクラウドバッファーに追加された音声とビデオをコミットします。入力音声バッファーが空の場合、エラーが発生します。
  • 「turn_detection」が有効な場合、クライアントはこのイベントを送信する必要はありません。サーバーは自動的に音声バッファーをコミットします。
  • 「turn_detection」が無効な場合、クライアントはユーザーメッセージアイテムを作成するために音声バッファーをコミットする必要があります。
注意 :
  1. input_audio_transcription を使用してセッションに音声文字起こしが構成されている場合、システムは音声を文字起こしします。
  2. 入力音声バッファーをコミットしても、モデルからの応答は作成されません。
def create_response(self,
        instructions: str = None,
        output_modalities: list[MultiModality] = None) -> None
response.created
サーバーが応答の生成を開始します
response.output_item.added
応答に新しい出力コンテンツが利用可能です
conversation.item.created
会話アイテムが作成されました
response.content_part.added
アシスタントメッセージアイテムに新しい出力コンテンツが追加されました
response.audio_transcript.delta
インクリメンタルに生成された文字起こしテキスト
response.audio.delta
モデルからインクリメンタルに生成された音声
response.audio_transcript.done
テキストの文字起こしが完了しました
response.audio.done
音声生成が完了しました
response.content_part.done
アシスタントメッセージのテキストまたは音声コンテンツのストリーミングが完了しました
response.output_item.done
アシスタントメッセージの出力アイテム全体のストリーミングが完了しました
response.done
応答が完了しました
サーバーにモデルの応答を作成するよう命令します。セッションが「turn_detection」モードで構成されている場合、サーバーは自動的にモデルの応答を作成します。
def cancel_response(self, ) -> None
None進行中の応答をキャンセルします。キャンセルする応答がない場合、サーバーはエラーで応答します。
def close(self, ) -> None
Noneタスクを終了し、接続を閉じます。
def get_session_id(self) -> str
None現在のタスクの session_id を取得します。
def get_last_response_id(self) -> str
None最後の応答の response_id を取得します。
def get_last_first_text_delay(self)
None最後の応答の最初のパケットのテキスト待機時間を取得します。
def get_last_first_audio_delay(self)
None最後の応答の最初のパケットの音声待機時間を取得します。

OmniRealtimeCallback

サーバーはコールバックを使用して、応答イベントとデータをクライアントに返します。サーバーが返す情報やデータを処理するために、コールバックメソッドを実装する必要があります。 from dashscope.audio.qwen_omni import OmniRealtimeCallback 文を使用してインターフェイスをインポートします。
メソッドパラメーター戻り値説明
def on_open(self) -> None
NoneNoneこのメソッドは、サーバーとの接続が確立された直後に呼び出されます。
def on_event(self, message: str) -> None
message: サーバーの応答イベント。Noneインターフェイス呼び出しへの応答と、モデルによって生成されたテキストと音声が含まれます。詳細については、「サーバーイベント」をご参照ください。
def on_close(self, close_status_code, close_msg) -> None
close_status_code: WebSocket を閉じるための状態コード。close_msg: WebSocket のクローズメッセージ。Noneこのメソッドは、サービスが接続を閉じた後に呼び出されます。

よくある質問

Q: 入力音声とイメージはどのようにアライメントされますか？

Qwen-Omni-Realtime は、音声を入力のタイムラインとして使用します。イメージは、送信された時間に基づいて音声ストリームに挿入されます。音声タイムライン上の任意のポイントにイメージを挿入できます。 リアルタイムのインタラクションシナリオでは、いつでもビデオ入力を有効または無効にできます。

Q: イメージと音声を入力するための推奨周波数は何ですか？

リアルタイムのインタラクションシナリオでは、1 fps または 2 fps のフレームレートでイメージを、100 ms のパケットで音声を送信できます。

Q: turn_detection スイッチの 2 つのモードの違いは何ですか？

現在、turn_detection が有効な場合、server_vad モードのみがサポートされています:
  • 「turn_detection」が有効な場合:
    • 入力状態: クラウドベースの VAD は、入力音声に基づいて発話文の終わりを判断します。その後、自動的に Qwen-Omni モデルを呼び出して推論を行い、テキストと音声の応答を送信します。
    • 応答状態: この状態では、モデルの応答フェーズ中に音声とビデオの入力を中断することなく継続できます。応答が完了すると、状態は入力状態に戻り、音声入力を待ちます。
    • 割り込み: モデルの応答中にユーザーが話し始めると、割り込みがトリガーされます。サービスは現在の応答を直ちに停止し、入力状態に切り替わります。
  • 「turn_detection」が無効な場合:
    • 音声とビデオの入力ターンの終わりを自分で判断する必要があります。その後、commit と create_response を使用して Qwen-Omni モデルの推論を手動でトリガーし、応答を取得する必要があります。
    • モデルの応答状態中は、音声とビデオの入力を停止する必要があります。モデルが応答を終えた後にのみ、次のターンの入力を再開できます。
    • モデルの応答を中断するには、cancel_response インターフェイスを使用する必要があります。
「turn_detection」が有効な場合でも、commit と create_response を使用して応答をアクティブにトリガーし、cancel_response を使用してアクティブに中断できることに注意してください。

Q: なぜ input_audio_transcription に別のモデルを選択するのですか？

Qwen-Omni-Realtime はエンドツーエンドのマルチモーダルモデルです。そのテキスト出力は入力に対する応答であるため、入力音声の文字起こしを直接生成しません。文字起こしのためには、別の自動音声認識 (ASR) モデルを統合する必要があります。