Paraformer リアルタイム音声認識 Python SDK のパラメーターおよびインターフェイスについて説明します。
このドキュメントは 中国 (北京) リージョンにのみ適用されます。モデルを使用するには、中国 (北京) リージョンの API キー を使用する必要があります。
Alibaba Cloud Model Studio は、中国 (北京) リージョン向けにワークスペース専用ドメインをリリースしました。この新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com への移行を推奨します。
{WorkspaceId} は、実際の ワークスペース ID に置き換えてください。既存のドメインは引き続き完全に機能します。
ユーザーガイド: モデルの概要および選定に関する推奨事項については、「リアルタイム音声認識 - Fun-ASR/Paraformer」をご参照ください。
前提条件
-
サービスを有効化し、API キーを取得 してください。セキュリティリスクを回避するため、コード内に API キーをハードコードせず、環境変数として API キーを構成 することを推奨します。
説明サードパーティ製アプリケーションやユーザーに一時的なアクセス権を付与する場合、または機密データへのアクセスや削除など高リスク操作を厳密に制御したい場合は、一時認証トークン の使用を推奨します。
長期的な API キーよりも、一時認証トークンは有効期間が短く(60 秒)、セキュリティが高いため、一時的な呼び出しシナリオに適しており、API キー漏洩のリスクを効果的に低減できます。
使用方法: コード内で、認証に使用していた API キーを取得した一時認証トークンに置き換えます。
-
最新の DashScope SDK をインストール してください。
モデル一覧
|
paraformer-realtime-v2 |
paraformer-realtime-8k-v2 |
|
|
シナリオ |
ライブ配信、会議などのシナリオ |
電話オペレーターやボイスメールなどの 8 kHz 音声認識 |
|
サンプルレート |
任意 |
8kHz |
|
言語 |
中国語(標準中国語および各種方言)、英語、日本語、韓国語、ドイツ語、フランス語、ロシア語 サポートされる中国語方言: 上海語、呉語、閩南語、東北弁、甘粛弁、貴州弁、河南弁、湖北弁、湖南弁、江西弁、寧夏弁、山西弁、陝西弁、山東弁、四川弁、天津弁、雲南弁、広東語 |
中国語 |
|
句読点予測 |
✅ デフォルトでサポートされています。追加の設定は不要です。 |
✅ デフォルトでサポートされています。追加の設定は不要です。 |
|
逆テキスト正規化(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 では、グローバルインタープリターロック(GIL) の影響により、一度に 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(Voice Activity Detection)セグメンテーションは遅延が少なく、インタラクティブなシナリオに適しています。
このパラメーターは、モデルが v2 以降の場合にのみ有効になります。 |
|
max_sentence_silence |
int |
800 |
いいえ |
VAD(Voice Activity Detection)セグメンテーションのサイレンス持続時間しきい値(ミリ秒単位)を設定します。 発話セグメント後のサイレンス持続時間がこのしきい値を超えると、システムは文が終了したと判断します。 パラメーターの範囲は 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)
双方向ストリーミング呼び出し 中、サーバーはコールバックを使用して重要なプロセス情報およびデータをクライアントに返します。返された情報およびデータを処理するために、コールバックメソッドを実装する必要があります。
|
メソッド |
パラメーター |
戻り値 |
説明 |
|
なし |
なし |
サーバーとの接続が確立された直後にこのメソッドが呼び出されます。 |
|
|
なし |
サービスが応答を送信する際にこのメソッドが呼び出されます。 |
|
なし |
なし |
すべての認識結果が返された後にこのメソッドが呼び出されます。 |
|
|
なし |
例外が発生した際にこのメソッドが呼び出されます。 |
|
なし |
なし |
サービスが接続を閉じた後にこのメソッドが呼び出されます。 |
応答結果
認識結果(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 |
句読点。 |
エラーコード
エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者コミュニティ に参加し、問題を報告するとともに調査のために Request 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 codec_name -b:a bitrate -ar sample_rate -ac 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.opus
Q: 各文の時間範囲を確認できますか?
はい。音声認識結果には各文の開始および終了タイムスタンプが含まれているため、各文の時間範囲を確認できます。
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.xxx -
-
paraformer-realtime-v2モデルを使用する場合、language_hintsで設定された言語が音声の実際の言語と一致しているかどうかを確認してください。例: 音声は実際には中国語ですが、
language_hintsがen(英語)に設定されている。 -
上記のすべてのチェックに合格すれば、特定の単語の認識精度を向上させるためにカスタムホットワードを使用できます。