Alibaba Cloud Model Studio:Qwen-ASR-Realtime Java SDK - API リファレンス

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

前提条件

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

インタラクションモード

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

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

完全な例

ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm

import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.sound.sampled.LineUnavailableException;
import java.io.File;
import java.io.FileInputStream;
import java.util.Base64;
import java.util.Collections;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.atomic.AtomicReference;

public class Qwen3AsrRealtimeUsage {
    private static final Logger log = LoggerFactory.getLogger(Qwen3AsrRealtimeUsage.class);
    private static final int AUDIO_CHUNK_SIZE = 1024; // 音声チャンクサイズ (バイト単位)
    private static final int SLEEP_INTERVAL_MS = 30;  // スリープ間隔 (ミリ秒単位)

    public static void main(String[] args) throws InterruptedException, LineUnavailableException {
        CountDownLatch finishLatch = new CountDownLatch(1);

        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/zh/model-studio/get-api-key
                // 環境変数を設定していない場合は、次の行を Alibaba Cloud Model Studio API キーに置き換えてください: .apikey("sk-xxx")
                .apikey(System.getenv("DASHSCOPE_API_KEY"))
                .build();

        OmniRealtimeConversation conversation = null;
        final AtomicReference<OmniRealtimeConversation> conversationRef = new AtomicReference<>(null);
        conversation = new OmniRealtimeConversation(param, new OmniRealtimeCallback() {
            @Override
            public void onOpen() {
                System.out.println("接続が開かれました");
            }
            @Override
            public void onEvent(JsonObject message) {
                String type = message.get("type").getAsString();
                switch(type) {
                    case "session.created":
                        System.out.println("セッション開始: " + message.get("session").getAsJsonObject().get("id").getAsString());
                        break;
                    case "conversation.item.input_audio_transcription.completed":
                        System.out.println("文字起こし: " + message.get("transcript").getAsString());
                        finishLatch.countDown();
                        break;
                    case "input_audio_buffer.speech_started":
                        System.out.println("======VAD 音声開始======");
                        break;
                    case "input_audio_buffer.speech_stopped":
                        System.out.println("======VAD 音声停止======");
                        break;
                    case "conversation.item.input_audio_transcription.text":
                        System.out.println("文字起こし: " + message.get("text").getAsString() + message.get("stash").getAsString());
                        break;
                    default:
                        break;
                }
            }
            @Override
            public void onClose(int code, String reason) {
                System.out.println("接続が閉じられました コード: " + code + ", 理由: " + reason);
            }
        });
        conversationRef.set(conversation);
        try {
            conversation.connect();
        } catch (NoApiKeyException e) {
            throw new RuntimeException(e);
        }

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

        OmniRealtimeConfig config = OmniRealtimeConfig.builder()
                .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
                .transcriptionConfig(transcriptionParam)
                .build();
        conversation.updateSession(config);

        String filePath = "your_audio_file.pcm";
        File audioFile = new File(filePath);
        if (!audioFile.exists()) {
            log.error("音声ファイルが見つかりません: {}", filePath);
            return;
        }

        try (FileInputStream audioInputStream = new FileInputStream(audioFile)) {
            byte[] audioBuffer = new byte[AUDIO_CHUNK_SIZE];
            int bytesRead;
            int totalBytesRead = 0;

            log.info("音声データの送信を開始: {}", filePath);

            // チャンク単位で音声データを読み込んで送信
            while ((bytesRead = audioInputStream.read(audioBuffer)) != -1) {
                totalBytesRead += bytesRead;
                String audioB64 = Base64.getEncoder().encodeToString(audioBuffer);
                // 音声チャンクを会話に送信
                conversation.appendAudio(audioB64);

                // リアルタイム音声ストリーミングをシミュレートするために小さな遅延を追加
                Thread.sleep(SLEEP_INTERVAL_MS);
            }

            log.info("音声データの送信が完了しました。送信された総バイト数: {}", totalBytesRead);

        } catch (Exception e) {
            log.error("ファイルからの音声送信エラー: {}", filePath, e);
        }

        // session.finish を送信して終了を待ち、閉じる
        conversation.endSession();
        log.info("タスク完了");

        System.exit(0);
    }
}
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

リクエストパラメーター

接続パラメーター (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();

セッション構成 (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();

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

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

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

主要インターフェイス

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

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