本ガイドでは、Paraformer リアルタイム音声認識 Python ソフトウェア開発キット(SDK)のパラメーターおよびインターフェイスについて説明します。
本ドキュメントは、中国 (北京) リージョンのみに適用されます。モデルを利用するには、中国 (北京) リージョンから取得した API キー を使用する必要があります。
ユーザーガイド: モデルの概要および選択に関するガイダンスについては、「リアルタイム音声認識 — Fun-ASR/Gummy/Paraformer」をご参照ください。
前提条件
Model Studio を有効化し、API キーを作成済みである必要があります。コード漏洩によるセキュリティリスクを防止するため、API キーをコード内にハードコーディングしないでください。代わりに、環境変数としてエクスポートしてください。
説明第三者アプリケーションまたはユーザーへの一時的なアクセス許可、あるいは機密データへのアクセスや削除といった高リスク操作を厳密に制御する場合、一時認証トークン を使用してください。
一時認証トークンは、有効期限が 60 秒と短いため、永続的な API キーよりも安全性が高く、一時的な呼び出しシナリオに最適であり、悪用された API キーによるリスクを大幅に低減できます。
この方法を使用する場合は、コード内の API キーを一時認証トークンに置き換えてください。
DashScope SDK の最新版をインストールしてください。
モデル一覧
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 では、グローバル インタープリター ロック (GIL) により、一度に 1 つの スレッド のみが Python コードを実行できます。ただし、パフォーマンス重視のライブラリの中には、この制限を回避できるものもあります。マルチコアプロセッサをより効果的に活用するには、multiprocessing または concurrent.futures.ProcessPoolExecutor を使用します。高い同時実行性の条件下では、マルチスレッド処理 により SDK 呼び出しの遅延が大幅に増加する場合があることに注意してください。
リクエストパラメーター
リクエストパラメーターは、Recognition クラス のコンストラクター(__init__)で設定します。
パラメーター | 型 | デフォルト値 | 必須 | 説明 |
model | str | - | はい | リアルタイム音声認識に使用するモデルです。詳細については、「モデル一覧」をご参照ください。 |
sample_rate | int | - | はい | 音声のサンプルレート(Hz 単位)です。 このパラメーターはモデルによって異なります:
|
format | str | - | はい | 音声のフォーマットです。 対応音声フォーマット: 重要
|
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 | いいえ |
このパラメーターは、 |
punctuation_prediction_enabled | bool | True | いいえ | 認識結果に自動的に句読点を追加するかどうかを指定します:
このパラメーターは v2 以降のモデルにのみ適用されます。 |
heartbeat | bool | False | いいえ | サーバーとの持続的接続を維持するかどうかを指定します:
このパラメーターは v2 以降のモデルにのみ適用されます。 このパラメーターを使用するには、SDK のバージョンが 1.23.1 以降である必要があります。 |
inverse_text_normalization_enabled | bool | True | いいえ | 逆テキスト正規化(ITN)を有効にするかどうかを指定します。 有効にすると、中国語の数字がアラビア数字に変換されます。 このパラメーターは v2 以降のモデルにのみ適用されます。 |
callback | RecognitionCallback | - | いいえ | RecognitionCallback インターフェイス(ストリーミング結果の処理用)です。 |
主要インターフェイス
Recognition クラス
Recognition クラスは、from dashscope.audio.asr import * を使用してインポートします。
メンバーメソッド | メソッド署名 | 説明 |
call | | ローカルファイルからのノンストリーミング認識を実行します。このメソッドは、音声ファイル全体が読み込まれるまで現在のスレッドをブロックします。ファイルには読み取り権限が必要です。
|
start | | 音声認識を開始します。 このメソッドは、コールバックベースのリアルタイムストリーミング認識を実行します。現在のスレッドをブロックせず、 |
send_audio_frame | | 最適なパフォーマンスを得るには、各音声パケットの持続時間は約 100 ミリ秒、サイズは 1 KB ~ 16 KB であることを推奨します。 認識結果は、 |
stop | | 音声認識を停止します。このメソッドは、サーバーが受信したすべての音声を認識し、タスクが完了するまで現在のスレッドをブロックします。 |
get_last_request_id | |
|
get_first_package_delay | | 最初のパッケージ遅延(First Packet Delay)を取得します。これは、最初の音声パケットを送信してから最初の認識結果を受信するまでのレイテンシーです。タスク完了後にこのメソッドを呼び出してください。 |
get_last_package_delay | | 最後のパッケージ遅延(Last Packet Delay)は、 |
RecognitionCallback インターフェイス
双方向ストリーミング呼び出し 中、サーバーはコールバックを介して重要な処理情報およびデータをクライアントに返します。サーバーから返されるデータを処理するには、コールバックメソッドを実装する必要があります。
メソッド | パラメーター | 戻り値 | 説明 |
| なし | なし | サーバーとの接続が確立された直後に呼び出されます。 |
|
| なし | サーバーが認識結果を送信したときに呼び出されます。 |
| なし | なし | すべての認識結果が返された後に呼び出されます。 |
|
| なし | エラーが発生したときに呼び出されます。 |
| なし | なし | サーバーが接続を閉じた後に呼び出されます。 |
応答結果
認識結果(RecognitionResult)
RecognitionResult オブジェクトは、双方向ストリーミング呼び出し または ノンストリーミング呼び出し における単一のリアルタイム認識の結果を表します。
メソッド | メソッド署名 | 説明 |
get_sentence | | 現在の文のテキストおよびタイムスタンプ情報を返します。コールバックでは、このメソッドは単一の文に対して 詳細については、「Sentence」をご参照ください。 |
get_request_id | | リクエストの 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)
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 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 # 256k ビットレートで再エンコーディング
# 例: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(英語)に設定されています。