Paraformer リアルタイム音声認識 Python SDK のパラメーターとインターフェース。
前提条件
モデル一覧
| paraformer-realtime-v2 | paraformer-realtime-8k-v2 | |
|---|---|---|
| シナリオ | ライブ配信、会議などのシナリオ | 電話オペレーターやボイスメールなどの 8 kHz 音声の認識 |
| サンプリングレート | 任意 | 8kHz |
| 言語 | 中国語(標準中国語および各種方言)、英語、日本語、韓国語、ドイツ語、フランス語、ロシア語サポートされる中国語方言: 上海語、呉語、閩南語、東北弁、甘粛弁、貴州弁、河南弁、湖北弁、湖南弁、江西弁、寧夏弁、山西弁、陝西弁、山東弁、四川弁、天津弁、雲南弁、広東語 | 中国語 |
| 句読点予測 | デフォルトでサポートされています。設定は不要です。 | デフォルトでサポートされています。設定は不要です。 |
| 逆テキスト正規化 (ITN) | デフォルトでサポートされています。設定は不要です。 | デフォルトでサポートされています。設定は不要です。 |
| カスタム語彙 | 詳細については、「ホットワードをカスタマイズする」をご参照ください。 | 「ホットワードのカスタマイズ」をご参照ください。 |
| 認識言語の指定 | language_hints パラメーターを使用して言語を指定します。 | 非対応 |
| 感情認識 | 非対応 |
使用方法を表示するにはクリック 感情認識には以下の制約があります:
emo_tag フィールドと emo_confidence フィールドからそれぞれ取得します。 |
開始方法
コアリソース(client.audio.asr)は、非ストリーミングコールと双方向ストリーミングコールのインターフェイスを提供します。実際の要件に応じて、適切な呼び出し方法を選択してください:
- 非ストリーミングコール(
recognize_file):ローカルファイルを認識します。SDK が自動的に音声を分割送信し、タスクの終了までドライブします。事前に録音された音声の処理に適しています。 - 双方向ストリーミングコール:音声ストリームを認識し、結果をリアルタイムで出力します。音声ストリームは、マイクなどの外部デバイスから取得することも、ローカルファイルから読み取ることもできます。即時のフィードバックを必要とするシナリオに適しています。
非ストリーミングコール
1 つのリアルタイム音声テキスト変換タスクを送信し、ローカルファイルを渡す方式で同期的にブロックして文字起こし結果を取得します。
client.audio.asr)の recognize_file メソッドを呼び出してリクエストパラメーターをバインドし、ローカルファイルのパスを渡します。サーバーイベントを反復処理して認識結果(RecognitionResult)を取得します。
クリックして完全な例を表示
クリックして完全な例を表示
recognize_file はサーバーイベント(Dict[str, Any])を 1 つずつ産出します:イベントタイプは event['header']['event']、認識テキストは event['payload']['output']['sentence'] にあります(sentence_end が true の場合はその文が終了したことを示します。begin_time / end_time はタイムスタンプ、words は単語ごとのタイムスタンプであり、その他のフィールドについては単文情報(Sentence)をご参照ください)。ハートビートおよび空テキストのイベントも産出されるため、必要に応じて無視できます。双方向ストリーミングセッションでは、events() のほかに、results() で認識結果フレームのみを反復処理することもできます(型付きの認識結果(RecognitionResult)を返し、ハートビートフレームはフィルタリング済み)。詳細は get_sentence メソッドの説明をご参照ください。双方向ストリーミングコール
1 つのリアルタイム音声テキスト変換タスクを送信し、イベントを反復処理する方式でリアルタイム認識結果をストリーミング出力します。
-
ストリーミング音声認識の開始
コアリソース(
client.audio.asr)のrecognizeメソッドを呼び出して認識セッションを作成しリクエストパラメーターをバインドします。withコンテキストに入ると(startメソッドが自動的に呼び出され、接続の確立とタスクの送信が行われます)、ストリーミング音声認識が開始されます。 -
ストリーミング
セッションの
send_audio_frameメソッドを繰り返し呼び出して、ローカルファイルまたはデバイス (マイクなど) から読み取ったバイナリ音声ストリームをセグメント単位でサーバーに送信します。送信と受信は並行して行う必要があります:受信スレッドはイベント反復(events()/results())でサーバーイベントを反復処理し、認識結果をリアルタイムでクライアントに返します。 送信する各音声セグメントの長さは約 100 ミリ秒、データサイズは 1 KB から 16 KB の範囲にすることを推奨します。 -
処理の終了
セッションの
stopメソッドを呼び出して音声認識を終了します。 このメソッドはサーバーに入力の終了のみを通知します。受信スレッドはevents()をtask-finishedイベントまで消費し続け、最後の認識結果と統計情報を取得する必要があります。ws 層のエラーはDashScopeError例外としてスローされるため、送信/受信処理で try/except で捕捉できます。
クリックして完全な例を表示
クリックして完全な例を表示
同時コール
Python では、グローバルインタプリタロック (GIL) のため、一度に 1 つのスレッドしか Python コードを実行できません (ただし、一部のパフォーマンス指向のライブラリではこの制限が解除される場合があります)。マルチコアコンピューターのコンピューティングリソースをより有効に活用したい場合は、マルチプロセッシングまたは concurrent.futures.ProcessPoolExecutor を使用することを推奨します。マルチスレッドは、高い同時実行性の場合、SDK のコールレイテンシーを大幅に増加させる可能性があります。
リクエストパラメーター
リクエストパラメーターは、コアリソース(client.audio.asr)の recognize/recognize_file メソッドで設定します:model、format、sample_rate、vocabulary_id、disfluency_removal_enabled は具名パラメーターで、その他のパラメーター(language_hints、semantic_punctuation_enabled など)は parameters ディクショナリで渡します。
パラメーター | タイプ | デフォルト | 必須 | 説明 |
|---|---|---|---|---|
model | str | - | はい | リアルタイム音声認識に使用するモデルです。 詳細については、「モデル一覧」をご参照ください。 |
sample_rate | int | - | はい | 認識対象の音声のサンプルレート(Hz 単位)を設定します。 モデルによって異なります:
|
format | str | - | はい | 認識対象の音声フォーマットを設定します。 サポートされる音声フォーマット: pcm、wav、mp3、opus、speex、aac、amr。 opus/speex: Ogg カプセル化を使用する必要があります。 wav: PCM エンコーディングである必要があります。 amr: AMR-NB タイプのみをサポートします。 |
vocabulary_id | str | - | いいえ | ホットワード ID を設定します。設定しない場合、ホットワードは有効になりません。v2 以降のモデルでは、このフィールドを使用してホットワード ID を設定します。 現在の音声認識セッションでは、このホットワード ID に対応するホットワード情報が適用されます。詳細な使用方法については、「カスタムホットワード」をご参照ください。 |
disfluency_removal_enabled | bool | False | いいえ | フィラー語のフィルターを設定します:
|
language_hints | list[str] | ["zh", "en"] | いいえ | 認識対象の言語コードを設定します。事前に言語を特定できない場合は、未設定のままにしておくと、モデルが自動的に言語を検出します。 現在サポートされている言語コード:
このパラメーターは多言語モデルにのみ適用されます。 詳細については、「モデル一覧」をご参照ください。 |
semantic_punctuation_enabled | bool | False | いいえ | セマンティックセグメンテーションを有効にするかどうかを設定します。デフォルトでは無効です。
セマンティックセグメンテーションは精度が高く、会議の文字起こしなどのシナリオに適しています。VAD(Voice Activity Detection)セグメンテーションは遅延が低く、インタラクティブなシナリオに適しています。
このパラメーターは、モデルが v2 以降の場合にのみ有効になります。 |
max_sentence_silence | int | 800 | いいえ | VAD(Voice Activity Detection)セグメンテーションのサイレンス持続時間しきい値(ms 単位)を設定します。 発話セグメント後のサイレンス持続時間がこのしきい値を超えると、システムは文が終了したと判断します。 パラメーター範囲は 200 ms ~ 6000 ms で、デフォルト値は 800 ms です。 このパラメーターは、 |
multi_threshold_mode_enabled | bool | False | いいえ | このスイッチを有効にすると(true)、VAD セグメンテーションによる長すぎる文の切断を防止します。デフォルトでは無効です。 このパラメーターは、 |
punctuation_prediction_enabled | bool | True | いいえ | 認識結果に自動的に句読点を追加するかどうかを設定します:
このパラメーターは、モデルが v2 以降の場合にのみ有効になります。 |
heartbeat | bool | False | いいえ | サーバーとの長時間接続を維持する必要がある場合、このスイッチで動作を制御します:
このパラメーターは、モデルが v2 以降の場合にのみ有効になります。 このフィールドは SDK 1.23.1 で導入され、2.0.1 以降のバージョンに含まれています。 |
inverse_text_normalization_enabled | bool | True | いいえ | ITN(逆テキスト正規化)を有効にするかどうかを設定します。 デフォルトでは有効(true)です。有効にすると、漢数字がアラビア数字に変換されます。 このパラメーターは、モデルが v2 以降の場合にのみ有効になります。 |
主要なインターフェイス
コアリソース(client.audio.asr)
リアルタイム音声認識能力は client.audio.asr リソースにマウントされています:recognize は双方向ストリーミング認識セッション(Recognition)を作成し、recognize_file はローカルファイルを一度に認識します。
| メンバーメソッド | メソッドシグネチャ | 説明 |
|---|---|---|
| recognize | 双方向ストリーミング認識セッションを作成します。with コンテキストに入ると start が自動的に呼び出され、接続の確立とタスクの送信が行われます。音声の送信とイベントの消費は並行して行う必要があります(send_audio_frame、events()/results()、stop と組み合わせて使用します)。 | |
| recognize_file | ローカルファイルをベースとした非ストリーミング呼び出しです:SDK が自動的に音声を分割送信し、タスクの終了までドライブして、サーバーイベントを 1 つずつ産出します。このメソッドは、認識対象のファイルに読み取り権限があることを要求します。 | |
| start | 音声認識を開始します:接続を確立し、タスクを送信して task-started を待機します。with コンテキストに入ると自動的に呼び出され、起動に成功した後に音声を送信できます。 | |
| send_audio_frame | 音声をプッシュします。毎回プッシュされる音声ストリームは、大きすぎたり小さすぎたりしないようにしてください。各音声パケットの長さは約 100 ms、サイズは 1 KB~16 KB の間にすることを推奨します。認識結果はイベント反復(events()/results())で取得します。 | |
| stop | 音声認識を停止します:サーバーに入力の終了のみを通知します。受信スレッドは events() を task-finished イベントまで消費し続ける必要があります。 | |
| events / results | サーバーイベントを反復処理します:events() は原始イベント dict を産出します(認識テキストは payload.output.sentence にあります)。results() は認識結果フレームのみを産出し、認識結果(RecognitionResult)の型付きオブジェクトを返します(ハートビートフレームはフィルタリング済み)。 | |
| close | 認識セッションを閉じます。with コンテキストから抜けるときに自動的に呼び出されます。 | |
| request_id / first_package_delay / last_package_delay | request_id、最初のパケットのレイテンシー(最初の音声パケットの送信から最初の認識結果パケットの受信までのレイテンシー)、最後のパケットのレイテンシー(stop 指令の送信から最後の認識結果パケットの受信までの所要時間)を取得します。タスク完了後に使用します。セッションを閉じた後も読み取り可能です。 |
イベント反復(events()/results())
双方向ストリーミング呼び出しでは、サーバーはイベントの方式で主要なプロセス情報とデータをクライアントに返します。受信スレッドでセッションの events()(原始イベント dict)または results()(型付き認識結果フレーム)を反復処理し、サーバーから返された情報やデータを処理する必要があります。
クリックして例を表示
クリックして例を表示
| イベント/反復メソッド | 産出内容 | 戻り値 | 説明 |
|---|---|---|---|
task-started イベント | なし | start() 内部で読み取られ、起動の戻り時に last_response に保存されます。events() から再度産出されることはありません。 | |
event: サーバーイベント dict | イテレーター | サーバーからの返信があるときにイベントを産出します。認識結果は payload.output.sentence にあり、ハートビートや空テキストのイベントである場合があります。アプリケーションは必要に応じて無視できます。1 つの受信スレッドで消費し続けてください。複数の読み取り者を並行して作成しないでください。 | |
result: 認識結果(RecognitionResult) | イテレーター | 認識結果フレームのみを産出します(ハートビートフレームはフィルタリング済み)。すべての認識結果が返された後に反復処理が終了します。 | |
DashScopeError 例外 | なし | 異常発生時に送信/受信スレッドでスローされます。try/except で捕捉できます。 | |
task-finished イベント | なし | サーバーがすべての認識を完了した後に events() から産出され、その後反復処理が終了します。stop() を送信した後もこのイベントを読み取る必要があります。 |
応答結果
認識結果(RecognitionResult)
RecognitionResult は、セッションの results() の反復処理で産出される 1 回の認識結果フレームを表します(双方向ストリーミング呼び出しと非ストリーミング呼び出しのどちらでも使用できます。events() が産出するのは原始イベント dict であるため、この型付きビューが必要な場合は results() を使用してください)。
| メンバーメソッド | メソッドシグネチャ | 説明 |
|---|---|---|
| get_sentence | 現在認識されている文とタイムスタンプ情報を取得します。このメソッドは、Dict[str, Any] 型(単文情報)を返します。詳細については、「単文情報 (Sentence)」をご参照ください。 | |
| request_id | 現在のイベントに対応するリクエストの request_id。 | |
| is_sentence_end | 現在の文が終了したかどうかを判定します(文に end_time がある場合に True)。 |
文 (Sentence)
Sentence クラスのメンバーは以下のとおりです。
パラメーター | 型 | 説明 |
|---|---|---|
begin_time | int | 文の開始時刻 (ミリ秒単位)。 |
end_time | int | 文の終了時刻 (ミリ秒単位)。 |
text | str | 認識されたテキスト。 |
words | 単語のタイムスタンプ情報 (Word) のリスト | 単語のタイムスタンプ情報。 |
emo_tag | str | 現在の文の感情:
感情認識には以下の制約があります:
|
emo_confidence | 浮動小数点数 | 現在の文で認識された感情の信頼度。値の範囲は 0.0 から 1.0 です。値が大きいほど、信頼度が高いことを示します。 感情認識には以下の制約があります:
|
単語のタイムスタンプ情報(Word)
Word クラスのメンバーは次のとおりです。
パラメーター | 型 | 説明 |
|---|---|---|
begin_time | int | 単語の開始時刻 (ミリ秒単位)。 |
end_time | int | 単語の終了時刻 (ミリ秒単位)。 |
text | str | 単語。 |
punctuation | str | 句読点。 |
エラーコード
エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者コミュニティ に参加し、問題を報告して Request ID を提供してください。
その他の例
その他の例については、GitHub をご参照ください。
よくある質問
機能
Q: 長時間のサイレンス中にサーバーとの長時間接続を維持するにはどうすればよいですか?
リクエストパラメーター heartbeat を true に設定し、サーバーに継続的にサイレント音声を送信します。
サイレント音声とは、音声信号を含まない音声ファイルまたはデータストリームを指します。サイレント音声は、Audacity や Adobe Audition などの音声編集ソフトウェアや、FFmpeg などのコマンドラインツールを使用して生成できます。
Q: 音声をサポートされているフォーマットに変換するにはどうすればよいですか?
FFmpeg ツール を使用できます。詳細な使用方法については、FFmpeg 公式サイトをご参照ください。
Q: 各文の時間範囲を確認できますか?
はい。音声認識結果には各文の開始時刻および終了時刻のタイムスタンプが含まれており、これを使用して各文の時間範囲を確認できます。Q:ローカルファイル (録音済みの音声ファイル) を認識するにはどうすればよいですか?
ローカルファイルを認識する方法は 2 つあります:
-
ローカルファイルパスを直接渡す:この方法では、ファイルの処理が完了した後に、完全な認識結果を返します。即時のフィードバックが必要なシナリオには適していません。
Recognition クラスの
callメソッドにファイルパスを渡して、音声ファイルを直接認識します。詳細については、「非ストリーミング呼び出し」をご参照ください。 -
ローカルファイルをバイナリ ストリームに変換して認識する:この方法では、ファイルの処理中に認識結果をストリームとして返します。即時のフィードバックが必要なシナリオに適しています。
Recognition クラスの
send_audio_frameメソッドを使用して、バイナリ ストリームをサーバーに送信し、認識できます。詳細については、「双方向ストリーミング呼び出し」をご参照ください。
トラブルシューティング
Q: 音声が認識されない(認識結果がない)原因は何ですか?
-
リクエストパラメーター内の音声フォーマット(
format)およびサンプルレート(sampleRate/sample_rate)が正しく設定され、パラメーター制約に準拠しているか確認してください。以下は一般的なエラー例です:- 音声ファイルの拡張子が .wav ですが、実際のフォーマットは MP3 であり、リクエストパラメーター
formatがwavに設定されている(不正確なパラメーター設定)。 - 音声のサンプルレートが 3600 Hz ですが、リクエストパラメーター
sampleRate/sample_rateが 48000 に設定されている(不正確なパラメーター設定)。
- 音声ファイルの拡張子が .wav ですが、実際のフォーマットは MP3 であり、リクエストパラメーター
-
paraformer-realtime-v2モデルを使用する場合、language_hintsで設定された言語が音声の実際の言語と一致しているか確認してください。 例: 音声は実際に中国語ですが、language_hintsがen(英語)に設定されている。 - 上記のすべてのチェックに合格すれば、特定の単語に対する認識精度を向上させるためにカスタムホットワードを使用できます。
Q: 音声フォーマットパラメーターの設定が誤っているために認識結果が得られない場合、どうすればよいですか?
format は必須パラメーターで、音声の実際のフォーマットに合わせて設定する必要があります。たとえば、実際のフォーマットが MP3 で、拡張子が .wav の音声ファイルには、format='mp3' を設定します。
-
音声の実際のフォーマットを確認する:
ffprobeを使用して、音声のコンテナ、コーデック、サンプルレート、チャンネル情報を確認します。 -
リクエストパラメーターを設定する:
formatを音声の実際のフォーマットに設定します。sample_rateを実際のサンプルレートに設定し、使用するモデルの要件を満たしていることを確認します。 -
必要に応じて音声フォーマットを変換する: WAV 音声が必要な場合は、次のコマンドを使用して、PCM エンコード、16 kHz、モノラルの WAV ファイルを生成します。
変換後は、
format='wav'とsample_rate=16000を設定します。