このトピックでは、Paraformer リアルタイム音声認識 Python SDK のパラメーターとインターフェイスについて説明します。
このドキュメントは、中国 (北京) リージョンにのみ適用されます。モデルを使用するには、中国 (北京) リージョンの API キー を使用する必要があります。
ユーザーガイド:モデルの説明と選択ガイダンスについては、「リアルタイム音声認識 - Fun-ASR/Paraformer」をご参照ください。
前提条件
Model Studio を有効化し、API キーを作成済みであること。セキュリティリスクを防ぐため、API キーをコードにハードコーディングするのではなく、環境変数としてエクスポートしてください。
説明サードパーティのアプリケーションやユーザーに一時的なアクセス権限を付与する場合、または機密データへのアクセスや削除などのリスクの高い操作を厳密に制御したい場合は、一時的な認証トークンの使用を推奨します。
長期的な API キーと比較して、一時的な認証トークンは有効期間が短い (60 秒) ため、より安全です。一時的な呼び出しシナリオに適しており、API キー漏洩のリスクを効果的に低減できます。
一時的なトークンを使用するには、コード内の認証に使用する API キーを一時的な認証トークンに置き換えます。
モデルリスト
paraformer-realtime-v2 | paraformer-realtime-8k-v2 | |
シナリオ | ライブストリーミングや会議などのシナリオ | 電話カスタマーサービスやボイスメールなど、8 kHz オーディオの認識シナリオ |
サンプルレート | 任意 | 8 kHz |
言語 | 中国語 (標準語および各種方言)、英語、日本語、韓国語、ドイツ語、フランス語、ロシア語 サポートされている中国語の方言:上海語、呉語、閩南語、東北方言、甘粛方言、貴州方言、河南方言、湖北方言、湖南方言、江西語、寧夏方言、山西語、陝西語、山東方言、四川方言、天津方言、雲南語、広東語 | 中国語 |
句読点予測 | ✅ デフォルトでサポート済み。設定は不要です。 | ✅ デフォルトでサポート済み。設定は不要です。 |
逆テキスト正規化 (ITN) | ✅ デフォルトでサポート済み。設定は不要です。 | ✅ デフォルトでサポート済み。設定は不要です。 |
カスタム語彙 | ✅ 「カスタムホットワード」をご参照ください | ✅ 「カスタムホットワード」をご参照ください |
認識言語の指定 | ✅ | ❌ |
感情認識 | ❌ |
はじめに
Recognition クラスは、非ストリーミングおよび双方向ストリーミング呼び出しのメソッドを提供します。要件に応じて適切なメソッドを選択できます:
非ストリーミング呼び出し:ローカルファイルを認識し、完全な結果を一度に返します。これは、事前に録音されたオーディオの処理に適しています。
双方向ストリーミング呼び出し:オーディオストリームを認識し、結果をリアルタイムで出力します。オーディオストリームは、マイクなどの外部デバイスから取得することも、ローカルファイルから読み取ることもできます。これは、即時のフィードバックが必要なシナリオに適しています。
非ストリーミング呼び出し
このメソッドは、ローカルファイルのリアルタイム音声テキスト変換タスクを送信します。プロセスは、完全な文字起こし結果が返されるまでブロックされます。
Recognition クラスをインスタンス化し、リクエストパラメーターを設定し、call メソッドを呼び出して認識を実行し、RecognitionResult を取得します。
双方向ストリーミング呼び出し
このメソッドは、リアルタイム音声テキスト変換タスクを送信し、コールバックインターフェイスを介してリアルタイムの認識結果を返します。
ストリーミング音声認識の開始
Recognition クラスをインスタンス化し、リクエストパラメーターとコールバックインターフェイス (RecognitionCallback) を設定してから、
startメソッドを呼び出します。オーディオのストリーミング
`Recognition` クラスの
send_audio_frameメソッドを繰り返し呼び出して、ローカルファイルまたはデバイス (マイクなど) からのバイナリオーディオストリームをセグメントに分けてサーバーに送信します。オーディオデータが送信されると、サーバーは RecognitionCallback コールバックインターフェイスの
on_eventメソッドを使用して、認識結果をリアルタイムでクライアントに返します。送信する各オーディオセグメントの長さは約 100 ミリ秒、データサイズは 1 KB から 16 KB の間にすることを推奨します。
処理の終了
Recognition クラスの
stopメソッドを呼び出して、音声認識を停止します。このメソッドは、コールバックインターフェイス (RecognitionCallback) の
on_completeまたはon_errorコールバックがトリガーされるまで、現在のスレッドをブロックします。
同時呼び出し
Python では、グローバルインタプリタロックのため、一度に 1 つのスレッドしか Python コードを実行できませんが、一部のパフォーマンス指向のライブラリではこの制限が解除される場合があります。マルチコアコンピュータの計算リソースをより有効に活用するためには、multiprocessing または concurrent.futures.ProcessPoolExecutor の使用を推奨します。マルチスレッドは、高い同時実行性下で SDK の呼び出しレイテンシーを大幅に増加させる可能性があります。
リクエストパラメーター
リクエストパラメーターは、Recognition クラスのコンストラクター (__init__) で設定します。
パラメーター | 型 | デフォルト | 必須 | 説明 |
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 による文分割はレイテンシーが低く、対話型シナリオに適しています。
このパラメーターは、v2 以降のモデルでのみ有効です。 |
max_sentence_silence | int | 800 | いいえ | VAD による文分割の無音期間のしきい値 (ミリ秒)。 音声セグメントの後の無音期間がこのしきい値を超えると、システムは文が終了したと判断します。 パラメーターの範囲は 200 ミリ秒から 6000 ミリ秒です。デフォルト値は 800 ミリ秒です。 このパラメーターは、 |
multi_threshold_mode_enabled | bool | False | いいえ | このパラメーターを `true` に設定すると、VAD が長すぎる文を分割するのを防ぎます。この機能はデフォルトで無効になっています。 このパラメーターは、 |
punctuation_prediction_enabled | bool | True | いいえ | 認識結果に句読点を自動的に追加するかどうかを指定します:
このパラメーターは、v2 以降のモデルでのみ有効です。 |
heartbeat | bool | False | いいえ | サーバーとの持続的接続を維持するかどうかを制御します:
このパラメーターは、v2 以降のモデルでのみ有効です。 このフィールドを使用する場合、SDK のバージョンは 1.23.1 以降である必要があります。 |
inverse_text_normalization_enabled | bool | True | いいえ | テキスト正規化 (ITN) を有効にするかどうかを指定します。 この機能はデフォルトで有効 (`true`) です。有効にすると、漢数字がアラビア数字に変換されます。 このパラメーターは、v2 以降のモデルでのみ有効です。 |
callback | RecognitionCallback | - | いいえ |
主要なインターフェイス
Recognition クラス
Recognition クラスは `from dashscope.audio.asr import *` を使用してインポートされます。
メンバーメソッド | メソッドシグネチャ | 説明 |
call | | ローカルファイルを使用する非ストリーミング呼び出し。このメソッドは、オーディオファイル全体が読み取られるまで現在のスレッドをブロックします。ファイルには読み取り権限が必要です。 認識結果は |
start | | 音声認識を開始します。 これはコールバックベースのストリーミングリアルタイム認識メソッドで、現在のスレッドをブロックしません。 |
send_audio_frame | | オーディオストリームをプッシュします。毎回プッシュするオーディオストリームは、大きすぎたり小さすぎたりしないようにしてください。各オーディオパケットの長さは約 100 ミリ秒、サイズは 1 KB から 16 KB の間にすることを推奨します。 認識結果は、コールバックインターフェイス (RecognitionCallback) の on_event メソッドを介して取得できます。 |
stop | | 音声認識を停止します。このメソッドは、サービスが受信したすべてのオーディオを認識し、タスクが完了するまでブロックします。 |
get_last_request_id | | request_id を取得します。これは、コンストラクターが呼び出された後 (オブジェクトが作成された後) に使用できます。 |
get_first_package_delay | | 最初のパケットの遅延を取得します。これは、最初のオーディオパケットを送信してから最初の認識結果パケットを受信するまでのレイテンシーです。タスク完了後に使用します。 |
get_last_package_delay | | 最後のパケットの遅延を取得します。これは、 |
コールバックインターフェイス (RecognitionCallback)
双方向ストリーミング呼び出し中、サーバーはコールバックを使用して主要なプロセス情報とデータをクライアントに返します。返された情報とデータを処理するために、コールバックメソッドを実装する必要があります。
メソッド | パラメーター | 戻り値 | 説明 |
| None | None | このメソッドは、サーバーとの接続が確立された直後に呼び出されます。 |
|
| None | このメソッドは、サービスが応答を送信したときに呼び出されます。 |
| None | None | このメソッドは、すべての認識結果が返された後に呼び出されます。 |
|
| None | このメソッドは、例外が発生したときに呼び出されます。 |
| None | None | このメソッドは、サービスが接続を閉じた後に呼び出されます。 |
応答結果
認識結果 (RecognitionResult)
RecognitionResult は、双方向ストリーミング呼び出しにおける単一のリアルタイム認識、または非ストリーミング呼び出しの認識結果を表します。
メンバーメソッド | メソッドシグネチャ | 説明 |
get_sentence | | 現在認識されている文とタイムスタンプ情報を取得します。コールバックでは単一の文が返されるため、このメソッドは Dict[str, Any] 型を返します。 詳細については、「Sentence」をご参照ください。 |
get_request_id | | リクエストの request_id を取得します。 |
is_sentence_end | | 指定された文が終了したかどうかを判断します。 |
Sentence (Sentence)
Sentence クラスのメンバーは次のとおりです:
パラメーター | 型 | 説明 |
begin_time | int | 文の開始時刻 (ミリ秒)。 |
end_time | int | 文の終了時刻 (ミリ秒)。 |
text | str | 認識されたテキスト。 |
words | 単語のタイムスタンプ情報 (Word) のリスト | 単語のタイムスタンプ情報。 |
emo_tag | str | 現在の文の感情:
感情認識には以下の制約があります:
|
emo_confidence | float | 現在の文で認識された感情の信頼度。値の範囲は 0.0 から 1.0 です。値が大きいほど信頼度が高くなります。 感情認識には以下の制約があります:
|
単語のタイムスタンプ情報 (Word)
Word クラスのメンバーは次のとおりです:
パラメーター | 型 | 説明 |
begin_time | int | 単語の開始時刻 (ミリ秒)。 |
end_time | int | 単語の終了時刻 (ミリ秒)。 |
text | str | 単語。 |
punctuation | str | 句読点。 |
エラーコード
エラーが発生した場合は、「エラーメッセージ」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者グループに参加して問題を報告してください。問題を調査するために、リクエスト ID をご提供ください。
その他の例
その他の例については、GitHub をご参照ください。
よくある質問
機能
Q:長時間の無音状態でもサーバーとの持続的接続を維持するにはどうすればよいですか?
heartbeat リクエストパラメーターを true に設定し、無音オーディオを継続的にサーバーに送信することで維持できます。
無音オーディオとは、オーディオファイルまたはデータストリーム内で音信号がないコンテンツを指します。Audacity や Adobe Audition などのオーディオ編集ソフトウェア、または FFmpeg などのコマンドラインツールを使用して、さまざまな方法で無音オーディオを生成できます。
Q:オーディオフォーマットを必要なフォーマットに変換するにはどうすればよいですか?
FFmpeg ツールを使用できます。詳細については、FFmpeg の公式ウェブサイトをご参照ください。
# 基本的な変換コマンド (汎用テンプレート)
# -i: 入力ファイルパスを指定します。例:audio.wav
# -c:a: オーディオエンコーダーを指定します。例:aac, libmp3lame, pcm_s16le
# -b:a: ビットレートを指定します (オーディオ品質を制御)。例:192k, 320k
# -ar: サンプルレートを指定します。例:44100 (CD), 48000, 16000
# -ac: サウンドチャンネル数を指定します。例:1 (モノラル), 2 (ステレオ)
# -y: 既存のファイルを上書きします (値は不要)。
ffmpeg -i input_audio.ext -c:a encoder_name -b:a bit_rate -ar sample_rate -ac num_channels output.ext
# 例:WAV から MP3 へ (元の品質を維持)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# 例:MP3 から WAV へ (16 ビット PCM 標準フォーマット)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# 例:M4A から AAC へ (Apple オーディオの抽出/変換)
ffmpeg -i input.m4a -c:a copy output.aac # 再エンコードせずに直接抽出
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac # 品質を向上させるために再エンコード
# 例:FLAC ロスレスから Opus へ (高圧縮)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opusQ:各文の時間範囲を表示できますか?
はい、できます。音声認識結果には、各文の開始と終了のタイムスタンプが含まれています。これらのタイムスタンプを使用して、各文の時間範囲を特定できます。
Q:ローカルファイル (録音済みオーディオファイル) を認識するにはどうすればよいですか?
ローカルファイルを認識するには、2 つの方法があります:
ローカルファイルのパスを直接渡す:この方法では、ファイルが完全に処理された後に完全な認識結果が返されます。即時のフィードバックが必要なシナリオには適していません。
Recognition クラスの
callメソッドにファイルパスを渡して、オーディオファイルを直接認識します。詳細については、「非ストリーミング呼び出し」をご参照ください。ローカルファイルをバイナリストリームに変換して認識する:この方法では、ファイルの処理中に認識結果がストリームで返されます。即時のフィードバックが必要なシナリオに適しています。
Recognition クラスの
send_audio_frameメソッドを使用して、バイナリストリームをサーバーに送信して認識します。詳細については、「双方向ストリーミング呼び出し」をご参照ください。
トラブルシューティング
Q:認識結果が表示されないのはなぜですか?
リクエストパラメーターのオーディオの
formatとsampleRate/sample_rateが正しく設定され、パラメーターの制約を満たしているか確認してください。以下は一般的なエラー例です:オーディオファイルの拡張子は .wav ですが、MP3 フォーマットであり、
formatパラメーターが誤って `mp3` に設定されている。オーディオのサンプルレートは 3600 Hz ですが、
sampleRate/sample_rateパラメーターが誤って 48000 に設定されている。
ffprobe ツールを使用して、コンテナー、エンコーディング、サンプルレート、サウンドチャンネルなどのオーディオ情報を取得できます:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxxparaformer-realtime-v2モデルを使用する場合、language_hintsで設定された言語がオーディオの実際の言語と一致しているか確認してください。例えば、オーディオは中国語ですが、
language_hintsがen(英語) に設定されている場合などです。上記のすべてのチェックをパスした場合、カスタムホットワードを使用して特定の単語の認識を向上させることができます。