このトピックでは、Paraformer リアルタイム音声認識 Java SDK のパラメーターおよびインターフェイスの詳細について説明します。
ユーザーガイド: モデルの概要および選択に関する推奨事項については、「リアルタイム音声認識 - Fun-ASR/Paraformer」をご参照ください。
Recognition クラス は、非ストリーミングおよび双方向ストリーミングの呼び出しインターフェイスを提供します。ニーズに応じて適切な呼び出し方法を選択してください:
ローカルファイルを渡して、単一のリアルタイム音声テキスト変換タスクを送信し、転写結果を同期的に取得します。
Recognition クラス のインスタンスを作成し、リクエストパラメーター および認識対象のファイルを指定して
単一のリアルタイム音声テキスト変換タスクを送信し、コールバックインターフェイスを通じてリアルタイム認識結果をストリーミングします。
単一のリアルタイム音声テキスト変換タスクを送信し、Flowable ワークフローを通じてリアルタイム認識結果をストリーミングします。
Flowable は Apache 2.0 ライセンスの下でリリースされた、ワークフローおよびビジネスプロセス管理のためのオープンソースフレームワークです。Flowable の詳細については、「Flowable API ドキュメント」をご参照ください。
DashScope Java SDK は、OkHttp3 のコネクションプーリングを使用して、接続を繰り返し確立するオーバーヘッドを削減します。詳細については、「Paraformer リアルタイム音声認識の高い同時実行性の最適化」をご参照ください。
双方向ストリーミング呼び出し 中、サーバーはコールバックを通じてクライアントに重要なプロセス情報およびデータを返します。サーバーから返された情報またはデータを処理するために、コールバックメソッドを実装する必要があります。
コールバックメソッドは、抽象クラス
エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者コミュニティ に参加し、問題を報告して Request ID を提供してください。
その他の例については、「GitHub」をご参照ください。
リクエストパラメーター
FFmpeg ツール を使用できます。詳細な使用方法については、FFmpeg 公式サイトをご参照ください。
はい。音声認識結果には各文の開始時刻および終了時刻のタイムスタンプが含まれており、これを使用して各文の時間範囲を確認できます。
ローカルファイルを認識するには、以下の 2 つの方法があります:
前提条件
サードパーティのアプリケーションやユーザーに一時的なアクセス権を付与する必要がある場合や、機密データへのアクセスや削除など高リスク操作を厳密に制御したい場合は、一時認証トークン の使用を推奨します。長期的な API キーと比較して、一時認証トークンは有効期間が短く(60 秒)、セキュリティが高く、一時的な呼び出しシナリオに適しており、API キーの漏洩リスクを効果的に低減できます。使用方法: コード内で、認証に使用していた API キーを取得した一時認証トークンに置き換えます。
モデル一覧
| paraformer-realtime-v2 | paraformer-realtime-8k-v2 | |
|---|---|---|
| 利用シーン | ライブ配信、会議などのシナリオ | 電話オペレーターやボイスメールなどの 8 kHz 音声の認識 |
| サンプルレート | 任意 | 8kHz |
| 言語 | 中国語(標準中国語および各種方言)、英語、日本語、韓国語、ドイツ語、フランス語、ロシア語サポートされる中国語方言: 上海語、呉語、閩南語、東北弁、甘粛弁、貴州弁、河南弁、湖北弁、湖南弁、江西弁、寧夏弁、山西弁、陝西弁、山東弁、四川弁、天津弁、雲南弁、広東語 | 中国語 |
| 句読点予測 | デフォルトでサポートされており、追加の設定は不要です | デフォルトでサポートされており、追加の設定は不要です |
| 逆テキスト正規化 (ITN) | デフォルトでサポートされており、追加の設定は不要です | デフォルトでサポートされており、追加の設定は不要です |
| カスタムホットワード | 「カスタムホットワード」をご参照ください | 「カスタムホットワード」をご参照ください |
| 認識言語の指定 | language_hints パラメーターで指定 | |
| 感情認識 |
(クリックして使用方法を表示) 感情認識には以下の制約があります:
getEmoTag メソッドおよび getEmoConfidence メソッドを呼び出して、それぞれ現在の文の感情および感情の信頼度を取得します。 |
クイックスタート
Recognition クラス は、非ストリーミングおよび双方向ストリーミングの呼び出しインターフェイスを提供します。ニーズに応じて適切な呼び出し方法を選択してください:
- 非ストリーミング呼び出し: ローカルファイルを認識し、一度に完全な結果を返します。事前に録音された音声の処理に適しています。
- 双方向ストリーミング呼び出し: 音声ストリームを直接認識し、結果をリアルタイムで出力します。音声ストリームは外部デバイス(マイクなど)から取得することも、ローカルファイルから読み取ることもできます。即時のフィードバックが必要なシナリオに適しています。
非ストリーミング呼び出し
ローカルファイルを渡して、単一のリアルタイム音声テキスト変換タスクを送信し、転写結果を同期的に取得します。
Recognition クラス のインスタンスを作成し、リクエストパラメーター および認識対象のファイルを指定して call メソッドを呼び出し、認識を実行して認識結果を取得します。
完全な例を表示
完全な例を表示
双方向ストリーミング: コールバックベース
単一のリアルタイム音声テキスト変換タスクを送信し、コールバックインターフェイスを通じてリアルタイム認識結果をストリーミングします。
-
ストリーミング音声認識を開始
Recognition クラス のインスタンスを作成し、リクエストパラメーター および コールバックインターフェイス (ResultCallback) を指定して
callメソッドを呼び出し、ストリーミング音声認識を開始します。 -
音声データをストリーミング
Recognition クラス の
sendAudioFrameメソッドをループで呼び出し、ローカルファイルまたはデバイス(マイクなど)から読み取ったバイナリ音声ストリームのセグメントをサーバーに送信します。 音声データ送信中に、サーバーは コールバックインターフェイス (ResultCallback) のonEventメソッドを通じて認識結果をリアルタイムでクライアントに返します。 各音声セグメントは約 100 ミリ秒の長さ、データサイズは 1 KB ~ 16 KB 程度にすることを推奨します。 -
処理を終了
Recognition クラス の
stopメソッドを呼び出して、音声認識を終了します。 このメソッドは、コールバックインターフェイス (ResultCallback) のonCompleteまたはonErrorコールバックがトリガーされるまで、現在のスレッドをブロックします。
完全な例を表示
完全な例を表示
双方向ストリーミング: Flowable ベース
単一のリアルタイム音声テキスト変換タスクを送信し、Flowable ワークフローを通じてリアルタイム認識結果をストリーミングします。
Flowable は Apache 2.0 ライセンスの下でリリースされた、ワークフローおよびビジネスプロセス管理のためのオープンソースフレームワークです。Flowable の詳細については、「Flowable API ドキュメント」をご参照ください。
完全な例を表示
完全な例を表示
Recognition クラス の
streamCall メソッドを直接呼び出して認識を開始します。streamCall メソッドは Flowable<RecognitionResult> インスタンスを返します。Flowable インスタンスの blockingForEach メソッドや subscribe メソッドを呼び出して認識結果を処理できます。認識結果は RecognitionResult にカプセル化されています。streamCall メソッドには以下の 2 つのパラメーターが必要です:RecognitionParamインスタンス (リクエストパラメーター): 音声認識のモデル、サンプルレート、音声フォーマットなどのパラメーターを設定するために使用します。Flowable<ByteBuffer>インスタンス:Flowable<ByteBuffer>型のインスタンスを作成し、その内部で音声ストリームの解析メソッドを実装する必要があります。
高同時実行呼び出し
DashScope Java SDK は、OkHttp3 のコネクションプーリングを使用して、接続を繰り返し確立するオーバーヘッドを削減します。詳細については、「Paraformer リアルタイム音声認識の高い同時実行性の最適化」をご参照ください。
リクエストパラメーター
RecognitionParam のチェーンメソッドを通じて、モデル、サンプルレート、音声フォーマットなどのパラメーターを構成します。構成済みのパラメーターオブジェクトを Recognition クラス の call/streamCall メソッドに渡します。
例を表示
例を表示
| パラメーター | 型 | デフォルト | 必須 | 説明 |
|---|---|---|---|---|
| model | String | はい | リアルタイム音声認識のモデル。詳細については、「モデル一覧」をご参照ください。 | |
| sampleRate | Integer | はい | 認識対象の音声のサンプルレート(Hz 単位)を設定します。モデルによって異なります:
| |
| format | String | はい | 認識対象の音声フォーマットを設定します。サポートされる音声フォーマット: pcm、wav、mp3、opus、speex、aac、amr。 | |
| vocabularyId | String | いいえ | ホットワード ID を設定します。設定しない場合、ホットワードは有効になりません。v2 以降のモデルでは、このフィールドを使用してホットワード ID を設定します。現在の音声認識セッションでは、このホットワード ID に対応するホットワード情報が適用されます。詳細な使用方法については、「カスタムホットワード」をご参照ください。 | |
| disfluencyRemovalEnabled | boolean | false | いいえ | フィラー語のフィルターを設定します:
|
| language_hints | String[] | ["zh", "en"] | いいえ | 認識対象の言語コードを設定します。事前に言語を特定できない場合は、未設定のままにしておくと、モデルが自動的に言語を検出します。現在サポートされている言語コード:
language_hints は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定する必要があります: |
| semantic_punctuation_enabled | boolean | false | いいえ | セマンティックセグメンテーションを有効にするかどうかを設定します。デフォルトでは無効です。
semantic_punctuation_enabled パラメーターを調整することで、異なるシナリオに合わせて音声認識のセグメンテーション方法を柔軟に切り替えることができます。このパラメーターは、モデルが v2 以降の場合にのみ有効になります。semantic_punctuation_enabled は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定する必要があります: |
| max_sentence_silence | Integer | 800 | いいえ | VAD(Voice Activity Detection)セグメンテーションのサイレンス持続時間しきい値(ms 単位)を設定します。発話セグメント後のサイレンス持続時間がこのしきい値を超えると、システムは文が終了したと判断します。パラメーター範囲は 200 ms ~ 6000 ms で、デフォルト値は 800 ms です。このパラメーターは、semantic_punctuation_enabled パラメーターが false(VAD セグメンテーション)で、かつモデルが v2 以降の場合にのみ有効になります。max_sentence_silence は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定する必要があります: |
| multi_threshold_mode_enabled | boolean | false | いいえ | このスイッチを有効にすると(true)、VAD セグメンテーションによる長すぎる文の切断を防止します。デフォルトでは無効です。このパラメーターは、semantic_punctuation_enabled パラメーターが false(VAD セグメンテーション)で、かつモデルが v2 以降の場合にのみ有効になります。multi_threshold_mode_enabled は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定する必要があります: |
| punctuation_prediction_enabled | boolean | true | いいえ | 認識結果に自動的に句読点を追加するかどうかを設定します:
punctuation_prediction_enabled は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定する必要があります: |
| heartbeat | boolean | false | いいえ | サーバーとの長時間接続を維持する必要がある場合、このスイッチで動作を制御します:
このフィールドを使用するには、SDK バージョンが 2.19.1 以降である必要があります。 heartbeat は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定する必要があります: |
| inverse_text_normalization_enabled | boolean | true | いいえ | ITN(逆テキスト正規化)を有効にするかどうかを設定します。デフォルトでは有効(true)です。有効にすると、漢数字がアラビア数字に変換されます。このパラメーターは、モデルが v2 以降の場合にのみ有効になります。inverse_text_normalization_enabled は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定する必要があります: |
| apiKey | String | いいえ | ユーザーの API キー。 |
主要インターフェイス
Recognition クラス
Recognition は "import com.alibaba.dashscope.audio.asr.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) のリスト | 単語レベルのタイムスタンプ情報を返します。 | |
| なし | 現在の文の感情 | 現在の文の感情を返します:
| |
| なし | 現在の文の感情信頼度 | 現在の文の感情信頼度を返します。値の範囲: [0.0, 1.0]。値が高いほど信頼度が高いことを示します。感情認識には以下の制約があります:
|
単語タイムスタンプ情報 (Word)
| インターフェイス/メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| なし | 単語の開始時刻(ms 単位) | 単語の開始時刻を返します。 | |
| なし | 単語の終了時刻(ms 単位) | 単語の終了時刻を返します。 | |
| なし | 単語 | 認識された単語を返します。 | |
| なし | 句読点 | 句読点を返します。 |
エラーコード
エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者コミュニティ に参加し、問題を報告して Request ID を提供してください。
その他の例
その他の例については、「GitHub」をご参照ください。
よくある質問
機能に関する質問
Q: 長時間のサイレンス中にサーバーとの長時間接続を維持するにはどうすればよいですか?
リクエストパラメーター heartbeat を true に設定し、サーバーに継続的にサイレント音声を送信します。
サイレント音声とは、音声信号を含まない音声ファイルまたはデータストリームを指します。サイレント音声は、Audacity や Adobe Audition などの音声編集ソフトウェアや、FFmpeg などのコマンドラインツールを使用して生成できます。
Q: 音声をサポートされているフォーマットに変換するにはどうすればよいですか?
FFmpeg ツール を使用できます。詳細な使用方法については、FFmpeg 公式サイトをご参照ください。
Q: 各文の時間範囲を確認できますか?
はい。音声認識結果には各文の開始時刻および終了時刻のタイムスタンプが含まれており、これを使用して各文の時間範囲を確認できます。
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 であり、リクエストパラメーター
-
paraformer-realtime-v2モデルを使用する場合、language_hintsで設定された言語が音声の実際の言語と一致しているか確認してください。 例: 音声は実際に中国語ですが、language_hintsがen(英語)に設定されている。 - 上記のすべてのチェックに合格すれば、特定の単語に対する認識精度を向上させるためにカスタムホットワードを使用できます。