Skip to main content

Qwen-Omni-Realtime Java SDK

この Topic では、 Qwen-Omni リアルタイムモデル で DashScope Java SDK を使用するための主要なインターフェイスとリクエストパラメーターについて説明します。

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

前提条件

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

使用開始

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

リクエストパラメーター

次のリクエストパラメーターを OmniRealtimeParam オブジェクトのチェーンメソッドまたはセッターを使用して設定します。次に、このオブジェクトをパラメーターとして OmniRealtimeConversation コンストラクターに渡します。

パラメーター

タイプ

説明

model

String

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

url

String

エンドポイント URL:

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

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

次のリクエストパラメーターを OmniRealtimeConfig オブジェクトのチェーンメソッドまたはセッターを使用して設定します。次に、このオブジェクトをパラメーターとして updateSession インターフェイスに渡します。
パラメータータイプ説明
modalitiesList<OmniRealtimeModality>モデルの出力モダリティ。テキスト出力のみの場合は [OmniRealtimeModality.TEXT] に、音声とテキストの両方を出力する場合は [OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO] に設定します。
voiceStringモデルによって生成される音声の声。サポートされている声のリストについては、「声のリスト」をご参照ください。デフォルトの声:
  • qwen3-omni-flash-realtime-2025-09-15: "Cherry"
inputAudioFormatOmniRealtimeAudioFormatユーザーの入力音声のフォーマット。現在、PCM_16000HZ_MONO_16BIT のみがサポートされています。
outputAudioFormatOmniRealtimeAudioFormatモデルの出力音声のフォーマット。現在、PCM_24000HZ_MONO_16BIT のみがサポートされています。
smooth_outputBooleanこのパラメーターは qwen3-omni-flash-realtime-2025-09-15 でのみサポートされています。
  • true: 会話的な応答。
  • false: フォーマルな応答。
    ただし、読み上げが難しいコンテンツの場合、パフォーマンスが最適でない可能性があります。
  • null: デフォルト値。モデルは会話的応答スタイルとフォーマルな応答スタイルを自動的に選択します。
smooth_output を OmniRealtimeConfig インスタンスの parameters メソッドを使用して設定します。
OmniRealtimeConfig config = OmniRealtimeConfig.builder()
        .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
        .voice("Tina")
        .enableInputAudioTranscription(true)
        .parameters(new HashMap<String, Object>() {{
            put("smooth_output", true);
        }})
        .build();
instructionsStringモデルの目標やロールを設定するシステムメッセージ。例: 「あなたは 5 つ星ホテルの AI カスタマーサービスエージェントです。客室タイプ、施設、価格、予約ポリシーに関する顧客の質問に、正確かつフレンドリな態度で答えてください。常にプロフェッショナルで役立つ対応を心がけてください。未確認の情報やホテルのサービスの範囲外の情報は提供しないでください。」
instructions を OmniRealtimeConfig インスタンスの parameters メソッドを使用して設定します。
OmniRealtimeConfig config = OmniRealtimeConfig.builder()
        .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
        .voice("Tina")
        .enableTurnDetection(true)
        .enableInputAudioTranscription(true)
        .parameters(new HashMap<String, Object>() {{
            put("instructions","あなたは 5 つ星ホテルの AI カスタマーサービスエージェントです。客室タイプ、施設、価格、予約ポリシーに関する顧客の質問に、正確かつフレンドリな態度で答えてください。常にプロフェッショナルで役立つ対応を心がけてください。未確認の情報やホテルのサービスの範囲外の情報は提供しないでください。");
        }})
        .build();
enableInputAudioTranscriptionBoolean入力音声の音声認識を有効にするかどうかを指定します。
InputAudioTranscriptionString入力音声の文字起こしに使用する音声認識モデルは qwen3-asr-flash-realtime に固定されており、変更できません。
enableTurnDetectionBoolean音声区間検出 (VAD) を有効にするかどうかを指定します。無効にした場合、ユーザーは手動で音声を送信して omni 応答を作成する必要があります。
turnDetectionTypeStringサーバー側の VAD タイプ。これは「server_vad」に固定されています。
turnDetectionThresholdFloatVAD 検出のしきい値。騒がしい環境ではこの値を大きくし、静かな環境では小さくします。
  • 値が -1 に近いほど、ノイズが音声として検出されやすくなります。
  • 値が 1 に近いほど、ノイズが音声として検出されにくくなります。
デフォルト値: 0.2。有効値: [-1.0, 1.0]。
turnDetectionSilenceDurationMsInteger発話の終了を示す無音の期間。この期間を超えると、モデルは応答をトリガーします。デフォルト値: 800。有効値: [200, 6000]。

主要なインターフェイス

OmniRealtimeConversation クラス

import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation; を使用して OmniRealtimeConversation クラスをインポートします。
メソッドシグネチャサーバー応答イベント (コールバック経由で送信)説明
public void connect() throws NoApiKeyException, InterruptedException
session.created
セッションが作成されました
session.updated
セッション構成が更新されました
サーバーとの接続を作成します。
public void updateSession(OmniRealtimeConfig config)
session.updated
セッション構成が更新されました
現在のセッションのデフォルト構成を更新します。パラメーター構成については、「リクエストパラメーター」セクションをご参照ください。接続を確立すると、サーバーはセッションのデフォルトの入力および出力構成を即座に返します。デフォルトのセッション構成を更新するには、接続を確立した直後にこのインターフェイスを呼び出すことをお勧めします。session.update イベントを受信した後、サーバーはパラメーター検証を実行します。パラメーターが無効な場合、エラーが返されます。それ以外の場合、サーバー側のセッション構成が更新されます。
public void appendAudio(String audioBase64)
なしBase64 でエンコードされた音声データセグメントをクラウドの入力音声バッファーに追加します。音声バッファーは、データを書き込んで後で送信できる一時的なストレージです。
  • 「turn_detection」が有効な場合、音声バッファーは音声の検出に使用され、サーバーがいつ送信するかを決定します。
  • 「turn_detection」が無効な場合、クライアントは各イベントに配置する音声の量を選択できます (最大 15 MiB)。たとえば、クライアントからより小さなデータブロックをストリーミングすると、VAD の応答性が向上します。
public void appendVideo(String videoBase64)
なしBase64 でエンコードされたイメージデータをクラウドのビデオバッファーに追加します。イメージデータは、ローカルイメージまたはビデオストリームからリアルタイムでキャプチャされたイメージです。イメージ入力には次の制限が適用されます。
  • イメージフォーマットは JPG または JPEG である必要があります。推奨されるイメージ解像度は 480p または 720p で、最大 1080p です。
  • 単一のイメージのサイズは 500 KB (Base64 エンコーディング前) を超えることはできません。
  • イメージデータは Base64 でエンコードされている必要があります。
  • 1 秒あたり 1 イメージの頻度でサーバーにイメージを送信します。
public void clearAppendedAudio()
input_audio_buffer.cleared
サーバーが受信した音声がクリアされました
現在のクラウドバッファー内の音声を削除します。
public void commit()
input_audio_buffer.committed
サーバーが送信された音声を受信しました
append を使用して以前にクラウドバッファーに追加された音声とビデオを送信します。入力音声バッファーが空の場合、エラーが発生します。
  • 「turn_detection」が有効な場合、クライアントはこのイベントを送信する必要はありません。サーバーは自動的に音声バッファーを送信します。
  • 「turn_detection」が無効な場合、クライアントは音声バッファーを送信してユーザーメッセージアイテムを作成する必要があります。
注 :
  1. input_audio_transcription を使用してセッションに音声文字起こしが構成されている場合、システムは音声を文字起こしします。
  2. 入力音声バッファーを送信しても、モデルからの応答は作成されません。
public void createResponse(String instructions, List<OmniRealtimeModality> modalities)
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」モードを有効にして構成されている場合、サーバーは自動的にモデルの応答を作成します。
public void cancelResponse()
なし進行中の応答をキャンセルします。キャンセルする応答がない場合、サーバーはエラーを返します。
public void close()
なしタスクを停止し、接続を閉じます。
public String getSessionId()
なし現在のタスクの session_id を取得します。
public String getResponseId()
なし最新の応答の response_id を取得します。
public long getFirstTextDelay()
なし最新の応答の最初のパケットのテキスト待機時間を取得します。
public long getFirstAudioDelay()
なし最新の応答の最初のパケットの音声待機時間を取得します。

コールバックインターフェイス (OmniRealtimeCallback)

サーバーはコールバックを使用して、イベントとデータをクライアントに返します。サーバーから返されたイベントとデータを処理するために、コールバックメソッドを実装します。 import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback; を使用してインターフェイスをインポートします。
メソッドパラメーター戻り値説明
public void onOpen()
なしなしこのメソッドは、サーバーとの接続が確立された直後に呼び出されます。
public abstract void onEvent(JsonObject message)
message: サーバー応答イベント。なしインターフェイス呼び出しへの応答と、モデルによって生成されたテキストおよび音声が含まれます。詳細については、「サーバーイベント」をご参照ください。
public abstract void onClose(int code, String reason)
code: WebSocket を閉じるための状態コード。reason: WebSocket を閉じる理由。なしこのメソッドは、サービスへの接続が閉じた後に呼び出されます。

よくある質問

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

A: omni-realtime モデルは、音声ストリームをタイムラインとして使用します。イメージは、送信された時間に基づいて音声ストリームに関連付けられます。音声タイムライン上の任意の時点でイメージを追加できます。 リアルタイムのインタラクションシナリオでは、いつでもビデオ入力を有効または無効にできます。

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

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

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

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

Q: input_audio_transcription に別のモデルを選択する必要があるのはなぜですか？

A: omni モデルは、エンドツーエンドのマルチモーダル大規模モデルです。そのテキスト出力は入力に対する応答であり、入力音声の直接的な文字起こしではありません。したがって、文字起こしには別の自動音声認識 (ASR) モデルを使用する必要があります。