このトピックでは、Paraformer リアルタイム音声認識 Python SDK のパラメーターとインターフェイスについて説明します。
このドキュメントは、中国 (北京) リージョンにのみ適用されます。モデルを使用するには、中国 (北京) リージョンの API キーを使用する必要があります。
ユーザーガイド: モデルの説明とモデル選択のガイダンスについては、「リアルタイム音声認識」をご参照ください。
前提条件
サービスを有効化し、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 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 以降である必要があります。 |
inverse_text_normalization_enabled | bool | True | いいえ | テキスト逆正規化 (ITN) を有効にするかどうかを指定します。 この機能はデフォルトで有効 (`true`) です。有効にすると、漢数字がアラビア数字に変換されます。 このパラメーターは、v2 以降のモデルでのみ有効です。 |
callback | RecognitionCallback | - | いいえ |
主要なインターフェイス
Recognition クラス
Recognition クラスは `from dashscope.audio.asr import *` を使用してインポートされます。
メンバーメソッド | メソッドシグネチャ | 説明 |
call | | ローカルファイルを使用する同期呼び出し。このメソッドは、音声ファイル全体が読み取られるまで現在のスレッドをブロックします。ファイルには読み取り権限が必要です。 認識結果は |
start | | 音声認識を開始します。 これはコールバックベースのストリーミングリアルタイム認識メソッドで、現在のスレッドをブロックしません。 |
send_audio_frame | | オーディオストリームをプッシュします。毎回プッシュされるオーディオストリームは、大きすぎたり小さすぎたりしないようにしてください。各音声パケットの持続時間は約 100 ms で、サイズは 1 KB から 16 KB の間にすることをお勧めします。 認識結果は、コールバックインターフェイス (RecognitionCallback) の on_event メソッドを介して取得できます。 |
stop | | 音声認識を停止します。このメソッドは、サービスが受信したすべての音声を認識し、タスクが完了するまでブロックします。 |
get_last_request_id | | request_id を取得します。これは、コンストラクターが呼び出された後 (オブジェクトが作成された後) に使用できます。 |
get_first_package_delay | | 最初のパケットの遅延を取得します。これは、最初の音声パケットを送信してから最初の認識結果パケットを受信するまでの待機時間です。タスク完了後に使用します。 |
get_last_package_delay | | 最後のパケットの遅延を取得します。これは、 |
get_response | | 最後のメッセージを取得します。これは、タスク失敗のエラーを取得するために使用できます。 |
コールバックインターフェイス (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: 長い無音期間中にサーバーとの持続的接続を維持するにはどうすればよいですか?
A: heartbeat リクエストパラメーターを `true` に設定し、無音音声を継続的にサーバーに送信します。
無音音声とは、音声ファイルまたはデータストリーム内の音信号がないコンテンツを指します。Audacity や Adobe Audition などの音声編集ソフトウェア、または FFmpeg などのコマンドラインツールを使用して、さまざまな方法で無音音声を生成できます。
Q: 音声フォーマットを必要なフォーマットに変換するにはどうすればよいですか?
A: 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: ローカルファイル (録音済み音声ファイル) を認識するにはどうすればよいですか?
A: ローカルファイルを認識するには、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(英語) に設定されています。上記のすべてのチェックが通った場合は、カスタムホットワードを使用して特定の単語の認識を向上させることができます。