Java SDK で Qwen-ASR-Realtime を統合 - Model Studio - Alibaba Cloud - Alibaba Cloud Model Studio

DashScope Java SDK を使用して Qwen-ASR-Realtime を呼び出します。

ユーザーガイド： モデルの概要、機能、および完全なサンプルコードについては、「リアルタイム音声認識 - Qwen」をご参照ください。

前提条件

DashScope SDK 2.22.5 以降 (SDK のインストール)
API キーの取得
クライアントとサーバー間のインタラクションフローを理解していること

重要

Alibaba Cloud Model Studio は、中国 (北京) リージョンおよびシンガポールリージョン向けにワークスペース専用ドメインをリリースしました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。新しいドメインへの移行を推奨します。

中国 (北京)： dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com へ
シンガポール： dashscope-intl.aliyuncs.com から {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com へ

{WorkspaceId} は、実際のワークスペース ID に置き換えてください。既存のドメインは引き続き完全に機能します。

インタラクションモード

Qwen-ASR-Realtime は、音声処理のタイミングを決定するための 2 つのモードをサポートしています。

モード	`enableTurnDetection`	動作方法
VAD モード (デフォルト)	`true`	サーバー側で音声区間検出 (VAD) を使用して発話区間を検出し、音声バッファーを認識処理にコミットするタイミングを決定します。
マニュアルモード	`false`	クライアントが `commit()` を呼び出すことで音声のコミットタイミングを制御します。これにより、セグメンテーションを完全制御できます。

各モードの詳細については、「VAD モード」および「マニュアルモード」をご参照ください。

リクエストパラメーター

接続パラメーター (OmniRealtimeParam)

これらのパラメーターは、OmniRealtimeParam クラスのチェーンメソッドを使用して設定します。

サンプルコードを表示するにはクリックしてください

OmniRealtimeParam param = OmniRealtimeParam.builder()
        .model("qwen3-asr-flash-realtime")
        // シンガポールリージョン用のエンドポイント。
        // 以下の構成はシンガポールリージョン用です。{WorkspaceId} を実際のワークスペース ID に置き換えてください。構成はリージョンによって異なります。
        .url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime")
        // シンガポールおよび北京リージョンの API キーは異なります。
        // API キーを取得するには、https://www.alibabacloud.com/help/ja/model-studio/get-api-key をご覧ください。
        // 環境変数を設定していない場合は、次の行を .apikey("sk-xxx") に置き換えてください。
        .apikey(System.getenv("DASHSCOPE_API_KEY"))
        .build();

パラメーター	型	必須	説明
`model`	`String`	はい	使用するモデル。例：`qwen3-asr-flash-realtime`。
`url`	`String`	はい	サービスエンドポイント。中国 (北京)：`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime`。シンガポール：`wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime`。`{WorkspaceId}` は、実際のワークスペース ID に置き換えてください。`{WorkspaceId}` は、実際のワークスペース ID に置き換えてください。
`apikey`	`String`	いいえ	API キー。

セッション構成 (OmniRealtimeConfig)

これらのパラメーターは、OmniRealtimeConfig クラスのチェーンメソッドを使用して設定します。

サンプルコードを表示するにはクリックしてください

OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
transcriptionParam.setLanguage("zh");
transcriptionParam.setInputSampleRate(16000);
transcriptionParam.setInputAudioFormat("pcm");

OmniRealtimeConfig config = OmniRealtimeConfig.builder()
        .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
        .enableTurnDetection(true)
        .turnDetectionType("server_vad")
        .turnDetectionThreshold(0.0f)
        .turnDetectionSilenceDurationMs(400)
        .transcriptionConfig(transcriptionParam)
        .build();

パラメーター	型	必須	説明
`modalities`	`List<OmniRealtimeModality>`	はい	出力モダリティ。固定値：`[OmniRealtimeModality.TEXT]`。
`enableTurnDetection`	`boolean`	いいえ	サーバー側 VAD を有効にします。無効にした場合、認識処理を手動でトリガーするために `commit()` を呼び出します。デフォルト：`true`。
`turnDetectionType`	`String`	いいえ	VAD タイプ。固定値：`server_vad`。
`turnDetectionThreshold`	`float`	いいえ	VAD 感度しきい値。推奨値：`0.0`。デフォルト：`0.2`。有効範囲：`[-1, 1]`。値を下げると感度が高まりますが（バックグラウンドノイズでトリガーされる可能性あり）、値を上げると感度が低下し、ノイズ環境での誤トリガーを回避しやすくなります。
`turnDetectionSilenceDurationMs`	`int`	いいえ	発話終了を示す無音持続時間（ミリ秒単位）。推奨値：`400`。デフォルト：`800`。有効範囲：`[200, 6000]`。短い持続時間（例：300 ms）は応答を高速化しますが、自然なポーズを分割する可能性があります。長い持続時間（例：1200 ms）はポーズをより適切に処理できますが、レイテンシーが増加します。
`transcriptionConfig`	`OmniRealtimeTranscriptionParam`	いいえ	音声認識設定。詳細については、「文字起こしパラメーター」をご参照ください。

文字起こしパラメーター (OmniRealtimeTranscriptionParam)

これらのパラメーターは、OmniRealtimeTranscriptionParam クラスのセッターメソッドを使用して設定します。

サンプルコードを表示するにはクリックしてください

OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
transcriptionParam.setLanguage("zh");
transcriptionParam.setInputSampleRate(16000);
transcriptionParam.setInputAudioFormat("pcm");

パラメーター	型	必須	説明
`language`	`String`	いいえ	音声ソースの言語。サポートされている言語については、「サポートされている言語」をご参照ください。
`inputSampleRate`	`int`	いいえ	音声サンプリングレート（Hz 単位）。有効値：`16000`、`8000`。デフォルト：`16000`。 `8000` を設定すると、サーバー側で 16,000 Hz にアップサンプリングされ、わずかなレイテンシーが発生する可能性があります。ネイティブで 8,000 Hz の音声（例：テレフォニー）にのみ使用してください。
`inputAudioFormat`	`String`	いいえ	音声エンコード形式。有効値：`pcm`、`opus`。デフォルト：`pcm`。
`corpusText`	`String`	いいえ	コンテキストバイアシング用のコンテキストテキスト。認識精度を向上させるために、背景テキスト、エンティティ語彙、または参照資料を提供します。最大：10,000 トークン。

主要インターフェイス

OmniRealtimeConversation

インポート：com.alibaba.dashscope.audio.omni.OmniRealtimeConversation

このクラスは WebSocket のライフサイクル（サーバーへの接続、音声送信、セッション終了）を管理します。

会話の作成

OmniRealtimeConversation conversation =
        new OmniRealtimeConversation(param, callback);

指定された接続パラメーターおよびコールバックハンドラーを使用して、新しい会話インスタンスを作成します。

サーバーへの接続

conversation.connect();

WebSocket 接続を開きます。サーバーは session.created イベントおよび session.updated イベントで応答します。

スロー：NoApiKeyException、InterruptedException。

セッションの構成

conversation.updateSession(config);

接続確立後にセッション構成を更新します。サーバーは session.updated イベントで応答します。呼び出されない場合、サーバーはデフォルト設定を使用します。

音声データの送信

conversation.appendAudio(audioBase64);

Base64 エンコードされた音声セグメントをサーバー側の音声バッファーに追加します。

VAD モード (enableTurnDetection=true)：サーバーが発話区間を検出し、バッファーを処理するタイミングを決定します。
マニュアルモード (enableTurnDetection=false)：音声はバッファーに蓄積され、認識処理をトリガーするために commit() を呼び出すまで待機します。各イベントには最大 15 MiB の音声データを含めることができます。

音声バッファーのコミット

conversation.commit();

バッファー内の音声を認識処理に送信します。サーバーは input_audio_buffer.committed イベントで応答します。

このメソッドはマニュアルモード (enableTurnDetection=false) のみで使用可能です。音声バッファーが空の場合、エラーが発生します。

セッションの終了

conversation.endSession();  // 同期
// または
conversation.endSessionAsync();  // 非同期

サーバーに残りの音声の処理を完了させ、セッションを終了するよう通知します。サーバーは session.finished イベントで応答します。

呼び出しタイミング：

VAD モード：音声の送信を完了した後。
マニュアルモード：commit() を呼び出した後。

接続のクローズ

conversation.close();

タスクを停止し、WebSocket 接続を即座に閉じます。

セッション ID および応答 ID の取得

String sessionId = conversation.getSessionId();
String responseId = conversation.getResponseId();

getSessionId() は、現在のタスクのセッション ID を返します。
getResponseId() は、最新のサーバー応答の応答 ID を返します。

OmniRealtimeCallback

インポート：com.alibaba.dashscope.audio.omni.OmniRealtimeCallback

このクラスを継承し、コールバックメソッドを実装することで、サーバーイベントを処理します。

メソッド	パラメーター	トリガー条件
`onOpen()`	なし	WebSocket 接続が確立されました。
`onEvent(JsonObject message)`	`message`：サーバーイベント（JSON 形式）。一般的なイベントタイプ：`session.created`、`session.updated`、`input_audio_buffer.committed`、`conversation.item.input_audio_transcription.completed`、`session.finished`。	サーバーイベントを受信したとき。`type` フィールドを解析してイベントタイプを判別します。
`onClose(int code, String reason)`	`code`：ステータスコード。`reason`：クローズ理由。	WebSocket 接続が閉じられました。