このトピックでは、Qwen-Audio-ASR-Streaming リアルタイム音声認識用の Java SDK のパラメーターとインターフェイスについて説明します。
前提条件
クイックスタート
Recognition クラスは、同期呼び出しと双方向ストリーミング呼び出しの両方のインターフェイスを提供します。ニーズに合ったアプローチを選択してください:
- 同期呼び出し:ローカルファイルを認識し、完全な結果を一度に返します。録音済みの音声を処理するのに最適です。
- 双方向ストリーミング呼び出し:音声ストリームを直接認識し、リアルタイムで結果を返します。音声ストリームは、マイクなどの外部デバイスから取得することも、ローカルファイルから読み取ることもできます。即時のフィードバックが必要なシナリオに最適です。
- 同期呼び出し
- 双方向ストリーミング呼び出し:コールバックベース
- 双方向ストリーミング呼び出し:Flowable ベース
ローカルファイルを渡すことで、単一のリアルタイム音声認識タスクを送信し、認識結果を同期的に取得します。この呼び出しは、結果が返されるまでブロックされます。Recognition クラスをインスタンス化し、
call メソッドを呼び出してリクエストパラメーターと認識するファイルをバインドします。このメソッドは認識を実行し、最終結果を返します。高い同時実行性呼び出し
DashScope Java SDK は、OkHttp3 のコネクションプーリングを使用して、接続を繰り返し確立するオーバーヘッドを削減します。詳細については、「高同時実行時のベストプラクティス」をご参照ください。
リクエストパラメーター
RecognitionParam のチェーンメソッドを使用して、モデル、サンプルレート、音声フォーマット、その他のパラメーターを設定します。設定したパラメーターオブジェクトを Recognition クラスの call/streamCall メソッドに渡します。
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
model | String | はい | モデル名。 |
sampleRate | Integer | はい | サンプリングレート(Hz)。任意のサンプリングレートをサポートします。 |
format | String | はい | 音声フォーマット。有効値:
|
keep_dialect | boolean | いいえ | qwen-audio-3.1-asr-flash-streaming のみに適用します。false で、方言を標準中国語に変換します。true に設定すると、方言表現を保持します。 .parameter("keep_dialect", value) で設定します。 |
vad_model | String | いいえ | qwen-audio-3.1-asr-flash-streaming のみに適用します。near_meeting_16k(近距離)または far_field_meeting_16k(遠距離、デフォルト)を指定します。 .parameter("vad_model", value) で設定します。 |
vocabularyId | String | いいえ | プリコンパイルされたホットワードリストの ID。この ID は、ホットワードリスト作成 API を呼び出して事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。語彙が既知で比較的安定しており、同じ単語リストをリクエスト間で再利用する必要があるシナリオに適しています。使用方法の詳細については、「プリコンパイルされたホットワード」をご参照ください。 |
vocabulary | Map<String, Integer> | いいえ | 即時ホットワード。キーと値のペアとして渡されます。キーはホットワードのテキスト (string)、値はホットワードの重み (integer) です。事前にホットワードリストを作成する必要はありません。重みの範囲は [1, 5] または 50 に設定されます:[1, 5] の値は、値が大きくなるにつれてモデルがその単語を出力する可能性が高くなります。値 50 はスーパーホットワードを指定し、再現率を大幅に向上させますが、スーパーホットワードの数は 50 を超えることはできません。一時的な、セッションレベルのホットワード最適化に適しています。プリコンパイルされたホットワードと一緒に設定された場合、即時ホットワードのみが有効になります。使用方法の詳細については、「即時ホットワード」をご参照ください。vocabulary は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します: |
max_sentence_silence | Integer | いいえ | セグメンテーションのための VAD 無音しきい値 (ms)。音声セグメントの後の無音がこのしきい値を超えると、システムは文が終了したと判断します。デフォルト値:800。有効値:[200, 6000]。max_sentence_silence は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します: |
multi_threshold_mode_enabled | boolean | いいえ | マルチしきい値モードを有効にするかどうか。有効にすると、VAD セグメントが長くなりすぎるのを防ぎます。デフォルト値:false。multi_threshold_mode_enabled は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します: |
punctuation_prediction_enabled | boolean | いいえ | 認識結果に句読点を自動的に追加するかどうかを設定します:
punctuation_prediction_enabled は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します: |
heartbeat | boolean | いいえ | ハートビートパケットを有効にするかどうか。デフォルト値:false。
このフィールドを使用するには、SDK バージョンが 2.19.1 以降である必要があります。 heartbeat は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します: |
language_hints | String[] | いいえ | 認識する音声の言語。デフォルト値はありません。設定しない場合、モデルは自動的に言語を検出します。最大 4 つの値を設定できます。それ以上設定した場合は、最初の 4 つのみが有効です。
クリックしてサポートされている言語コードを表示
language_hints は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します: |
speech_noise_threshold | float | いいえ | 音声とノイズを区別するためのしきい値で、音声アクティビティ検出 (VAD) の感度を調整するために使用されます。有効値:[-1.0, 1.0]。値の説明:
speech_noise_threshold は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します: |
special_word_filter | String | いいえ | 音声認識中に処理する禁止用語を指定し、異なる禁止用語に対して異なる処理方法を設定することをサポートします。詳細については、「禁止用語フィルター」をご参照ください。special_word_filter は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します: |
input | Map<String, Object> | いいえ | 会話コンテキストを渡す入力オブジェクト。コンテキストは認識を助け、固有名詞の認識精度を向上させます。使用方法については、「クイックスタート」をご参照ください。Map には、List<Map<String, Object>> 型のメッセージ配列である context キーが含まれている必要があります。各メッセージには次のフィールドが含まれます:
このフィールドを使用するには、SDK バージョンが 2.22.23 以降である必要があります。 input は、RecognitionParam インスタンスの input メソッドを通じて設定します: |
apiKey | String | いいえ | ご利用の API キー。 |
主要なインターフェイス
Recognition クラス
import com.alibaba.dashscope.audio.asr.recognition.Recognition; で Recognition をインポートします。その主要なインターフェイスは次のとおりです:
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| なし | コールバックベースのストリーミングリアルタイム認識。このメソッドは現在のスレッドをブロックしません。 | |
| 認識結果。 | ローカルファイルの非ストリーミング認識。このメソッドは、音声ファイル全体が読み取られるまで現在のスレッドをブロックします。ファイルは読み取り可能でなければなりません。 | |
| Flowable<RecognitionResult> | Flowable ベースのストリーミングリアルタイム認識。 | |
| なし | 音声を送信します。プッシュされる各音声チャンクを適切なサイズに保ちます。推奨されるチャンクは、約 100 ms の音声を保持し、サイズは 1 KB から 16 KB です。認識結果は、コールバックインターフェイス (ResultCallback) の onEvent メソッドを通じて配信されます。 | |
| なし | なし | リアルタイム認識を停止します。このメソッドは、ResultCallback コールバックの onComplete または onError が呼び出されるまで現在のスレッドをブロックします。 | |
| code:WebSocket のクローズコード。reason:クローズの理由。これら 2 つのパラメーターの設定に関するガイダンスについては、「The WebSocket Protocol」をご参照ください。 | true | タスクが終了した後、例外が発生したかどうかに関わらず、常に WebSocket 接続を閉じて、接続リークを回避してください。接続を再利用して効率を向上させるには、「Paraformer リアルタイム音声認識の高い同時実行性のための最適化」をご参照ください。 | |
| なし | requestId | 現在のタスクの requestId を取得します。call または streamingCall で新しいタスクが開始された後に利用可能です。このメソッドは、SDK バージョン 2.18.0 以降でのみ利用可能です。 | |
| なし | 最初のパケットのレイテンシ。 | 最初のパケットのレイテンシ、つまり最初の音声パケットを送信してから最初の認識結果を受信するまでの遅延を取得します。タスク完了後に使用します。 このメソッドは、SDK バージョン 2.18.0 以降でのみ利用可能です。 | |
| なし | 最後のパケットのレイテンシ。 | 最後のパケットのレイテンシ、つまり stop コマンドを送信してから最終的な認識結果を受信するまでの時間を取得します。タスク完了後に使用します。このメソッドは、SDK バージョン 2.18.0 以降でのみ利用可能です。 |
コールバックインターフェイス (ResultCallback)
双方向ストリーミング呼び出し中、サーバーはコールバックを通じて主要なプロセス情報とデータをクライアントに返します。コールバックメソッドを実装して、サーバーから返された情報やデータを処理します。
抽象クラス ResultCallback を拡張してコールバックメソッドを実装します。このクラスを拡張する際、ジェネリック型を RecognitionResult に設定できます。RecognitionResult は、サーバーから返されたデータ構造をラップします。
Java は接続の再利用をサポートしているため、onClose や onOpen はありません。
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
result:リアルタイム認識結果 (RecognitionResult) | なし | サーバーが応答を送信したときに呼び出されます。 | |
| なし | なし | タスク完了後に呼び出されます。 | |
e:例外情報。 | なし | 例外が発生したときに呼び出されます。 |
応答
リアルタイム認識結果 (RecognitionResult)
RecognitionResult は、単一のリアルタイム認識の結果を表します。
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| なし | requestId | requestId を取得します。 | |
| なし | 完全な文が形成されたかどうか、つまり文の境界が検出されたかどうか。 | 与えられた文が終了したかどうかを判断します。 | |
| なし | 文情報 (Sentence) | タイムスタンプやテキストを含む文情報を取得します。 |
文情報 (Sentence)
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| なし | 文の開始時刻 (ms)。 | 文の開始時刻を返します。 | |
| なし | 文の終了時刻 (ms)。 | 文の終了時刻を返します。 | |
| なし | 認識されたテキスト。 | 認識されたテキストを返します。 | |
| なし | 単語レベルのタイムスタンプ情報 (Word) オブジェクトのリスト。 | 単語レベルのタイムスタンプ情報を返します。 |
単語レベルのタイムスタンプ情報 (Word)
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| なし | 単語の開始時刻 (ms)。 | 単語の開始時刻を返します。 | |
| なし | 単語の終了時刻 (ms)。 | 単語の終了時刻を返します。 | |
| なし | 単語。 | 認識された単語を返します。 | |
| なし | 句読点。 | 句読点を返します。 |
エラーコード
エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者コミュニティに参加して問題を報告し、詳細な調査のためにリクエスト ID を提供してください。
よくある質問
機能
Q:長時間の無音中にサーバーへの接続を維持するにはどうすればよいですか?
リクエストパラメーター heartbeat を true に設定し、サーバーに無音音声を送信し続けます。
無音音声とは、ファイルまたはデータストリームに音響信号が含まれていない音声です。Audacity や Adobe Audition などの音声編集ソフトウェア、または FFmpeg などのコマンドラインツールを使用して、いくつかの方法で無音音声を生成できます。
Q:音声をサポートされているフォーマットに変換するにはどうすればよいですか?
FFmpeg ツールを使用します。その他の使用方法については、FFmpeg の公式ウェブサイトをご参照ください。
Q:ローカルファイル (録音) を認識するにはどうすればよいですか?
ローカルファイルを認識するには 2 つの方法があります:
-
ローカルファイルパスを直接渡す:このアプローチは、認識が終了した後にのみ完全な認識結果を返すため、即時のフィードバックが必要なシナリオには適していません。
「同期呼び出し」を参照し、ファイルパスを Recognition クラスの
callメソッドに渡して録音を直接認識します。 -
ローカルファイルをバイナリストリームに変換して認識する:このアプローチは、ファイルを認識し、同時に結果をストリーミングするため、即時のフィードバックが必要なシナリオに適しています。
- 「双方向ストリーミング呼び出し:コールバックベース」を参照し、Recognition クラスの
sendAudioFrameメソッドを通じてバイナリストリームをサーバーに送信して認識します。 - 「双方向ストリーミング呼び出し:Flowable ベース」を参照し、Recognition クラスの
streamCallメソッドを通じてバイナリストリームをサーバーに送信して認識します。
- 「双方向ストリーミング呼び出し:コールバックベース」を参照し、Recognition クラスの
トラブルシューティング
Q:なぜ音声が認識されないのですか (認識結果がない)?
-
リクエストパラメーターの音声フォーマット (
format) とサンプルレート (sampleRate/sample_rate) が正しく、パラメーターの制約を満たしていることを確認してください。よくある間違いは次のとおりです:- 音声ファイルの拡張子は .wav ですが、実際には MP3 フォーマットであり、リクエストパラメーター
formatが mp3 に設定されている (不正なパラメーター設定)。 - 音声のサンプルレートは 3600 Hz ですが、リクエストパラメーター
sampleRate/sample_rateが 48000 に設定されている (不正なパラメーター設定)。
- 音声ファイルの拡張子は .wav ですが、実際には MP3 フォーマットであり、リクエストパラメーター
-
language_hintsで設定された言語が、音声の実際の言語と一致していることを確認してください。 たとえば、音声は実際には中国語ですが、language_hintsはen(英語) に設定されています。 - 上記のチェックで問題が見つからない場合は、カスタムホットワードを設定して特定の用語の認識を向上させてください。