このトピックでは、Qwen-Audio-ASR-Message リアルタイム音声認識モデル用の Python SDK のパラメータとインターフェイスについて説明します。
前提条件
クイックスタート
コアリソース(client.audio.asr)は、非ストリーミング呼び出しと双方向ストリーミング呼び出しの両方のインターフェイスを提供します。ニーズに合わせて呼び出し方法を選択してください:
- 非ストリーミング呼び出し(
recognize_file):ローカルファイルを認識します。SDK が自動的に音声をブロック単位で送信し、タスクを完了まで駆動します。録音済みの音声を処理する場合に適しています。 - 双方向ストリーミング呼び出し(
recognizeセッション):音声ストリームを直接認識し、結果をリアルタイムで出力します。音声ストリームは、マイクなどの外部デバイスから取得することも、ローカルファイルから読み取ることもできます。即時のフィードバックが必要なシナリオに適しています。
- 非ストリーミング呼び出し
- 双方向ストリーミング呼び出し
単一のリアルタイム音声認識タスクを送信し、ローカルファイルを渡すことで認識結果を同期的に取得します。コアリソース(
client.audio.asr)の recognize_file メソッドを呼び出してリクエストパラメーターをバインドし、ローカルファイルのパスを渡し、サービス側のイベントを反復処理して認識結果を取得します。リクエストパラメーター
リクエストパラメーターは、コアリソース(client.audio.asr)の recognize/recognize_file メソッドで設定します:model、format、sample_rate、vocabulary_id は具名パラメーター、その他のパラメーター(language_hints など)は parameters 辞書で渡します。
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
model | str | はい | モデル名。 |
sample_rate | int | はい | サンプリングレート(Hz)。16000 のみをサポートします。 |
format | str | はい | オーディオフォーマット。有効な値:
|
keep_dialect | bool | いいえ | デフォルトは false で、方言を標準中国語に変換します。true に設定すると、方言表現を保持します。 同名のキーワード引数で指定します。最終結果(sentence_end=true)にのみ適用され、中間結果(sentence_end=false)ではサポートされません。 |
vad_model | str | いいえ | VAD モデル。near_meeting_16k(近距離)または far_field_meeting_16k(遠距離、デフォルト)を指定します。 同名のキーワード引数で指定します。 |
disfluency_removal_enabled | bool | いいえ | つなぎ言葉を除去し、出力を整えるかどうか。デフォルトは false。有効にするには true に設定します。 同名のキーワード引数で指定します。 |
intermediate_result_enabled | bool | いいえ | ストリーミング中間結果を返すかどうか。デフォルトは false。中間結果を返すには true に設定します。 同名のキーワード引数で指定します。 |
vocabulary_id | str | いいえ | 事前コンパイル済みのホットワードリストのID。ホットワードリスト作成 API を呼び出して、この ID を事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。語彙が既知で比較的安定しており、リクエスト間で同じ単語リストを再利用する必要があるシナリオに適しています。使用法の詳細については、「事前コンパイル済みホットワード」をご参照ください。 |
vocabulary | dict | いいえ | インスタントホットワード。キーと値のペアとして渡します。キーはホットワードのテキスト (文字列)、値はホットワードの重み (整数) です。事前にホットワードリストを作成する必要はありません。重みの範囲は [1, 5] または 50 に設定します。値が [1, 5] の範囲内である場合、値が大きくなるほどモデルがその単語を出力する可能性が高くなります。値が 50 の場合はスーパーホットワードを指定し、再現率が大幅に向上しますが、スーパーホットワードの数は 50 を超えることはできません。一時的なセッションレベルのホットワードの最適化に適しています。事前コンパイル済みのホットワードと一緒に設定した場合、インスタントホットワードのみが有効になります。使用法の詳細については、「インスタントホットワード」をご参照ください。例: |
language_hints | list[str] | いいえ | 認識する音声の言語。デフォルト値はありません。設定しない場合、モデルは自動的に言語を検出します。最大 4 つの値を設定できます。それ以上設定した場合は、最初の 4 つのみが有効です。
クリックしてサポートされている言語コードを表示
sentence_end=true)にのみ適用され、中間結果(sentence_end=false)ではサポートされません。 |
max_sentence_silence | int | いいえ | VAD の文分割の無音しきい値(ミリ秒)。発話後の無音時間がこの値を超えると、文の終了と判断します。デフォルト:800。有効範囲:[200, 6000]。 |
heartbeat | bool | いいえ | ハートビートパケットを有効にするかどうか。デフォルト:False。
|
speech_noise_threshold | float | いいえ | 音声とノイズを区別するためのしきい値であり、VAD (音声アクティビティ検出) の感度調整に使用します。有効な値: [-1.0, 1.0]。値の説明:
|
recognize/recognize_file メソッドの input キーワード引数で渡します。
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
input | dict | いいえ | 会話コンテキストを渡すために使用される入力オブジェクト。コンテキスト強化により、ドメイン固有の用語の認識精度が向上します。使用方法については、「クイックスタート」をご参照ください。dict には、値がメッセージのリスト (list[dict]) である context キーを含める必要があります。各メッセージには、次のフィールドが含まれます:
このフィールドは SDK 1.25.23 で導入されたもので、2.0.1 以降のバージョンには含まれています。 |
主要なインターフェイス
コアリソース(client.audio.asr)
リアルタイム音声認識能力は client.audio.asr リソースにマウントされています:recognize は双方向ストリーミング認識セッション(Recognition)を作成し、recognize_file はローカルファイルに対して一回の認識を行います。
| メンバーメソッド | メソッドシグネチャ | 説明 |
|---|---|---|
| recognize | 双方向ストリーミング認識セッションを作成します。with コンテキストに入ると start が自動的に呼び出され、接続を確立してタスクを送信します。音声の送信とイベントの消費は並行して実行する必要があります(send_audio_frame、events()/results()、stop と併用してください)。 | |
| recognize_file | ローカルファイルに基づく非ストリーミング呼び出しです:音声を自動的にブロック単位で送信し、タスクを完了まで駆動して、サービス側イベントを 1 つずつ返します。このメソッドにはファイルに対する読み取り権限が必要です。 | |
start | 音声認識を開始します:接続を確立し、タスクを送信して、task-started イベントを待機します。with コンテキストに入ると自動的に呼び出され、成功した後にのみ音声を送信できます。 | |
send_audio_frame | 音声を送信します。送信するオーディオフレームは大きすぎず小さすぎないようにしてください。目安はフレームあたり約 100 ms、サイズは 1 KB ~ 16 KB です。認識結果は、イベント反復(events()/results())で取得します。 | |
stop | 音声認識を停止します:サーバーに入力が完了したことを通知するだけです。受信スレッドは task-finished イベントまで events() を消費し続ける必要があります。 | |
| events / results | サービス側のイベントを反復処理します:events() は生の dict イベントを返し(認識テキストは payload.output.sentence にあります)、results() は認識結果フレームのみを返し、型付きの認識結果 (RecognitionResult) オブジェクトを返します(ハートビートフレームはフィルターされます)。 | |
| close | 認識セッションを閉じます。with コンテキストの退出時に自動的に呼び出されます。 | |
| request_id / first_package_delay / last_package_delay / last_response | request_id、初回パケット遅延(最初の音声パケットを送信してから最初の認識結果を受信するまでのレイテンシー)、最終パケット遅延(stop コマンドを送信してから最後の認識結果が到着するまでの時間)を取得します。タスク完了後に使用してください。last_response は、最後に正常に読み取られた生のメッセージであり、失敗したタスクのエラーを復元するために使用できます。これらはセッションを閉じた後も読み取り可能です。 |
会話コンテキストの更新
認識タスクの実行中に update_context を呼び出して会話コンテキストを更新します。コンテキストは、後続の音声の認識を支援するために使用されます。このメソッドには DashScope Python SDK 2.0.1 以降が必要です。
- 呼び出しタイミング:
withコンテキストに入って(startが自動的に呼び出されます)ストリーミング認識を開始した後、stopを呼び出す前。 - パラメーター:
contextは辞書で、continue-taskイベントのpayload.inputオブジェクトを渡します(contextフィールドを含む)。payloadやinputの階層を追加でラップしないでください。 - サポート範囲とパラメーターの制約:continue-task をご参照ください。
recognition インスタンスを再利用します。
イベント反復(events()/results())
双方向ストリーミング呼び出しでは、サーバーはイベントを通じて、主要なプロセス情報とデータをクライアントに返します。受信スレッドでセッションの events()(生のイベント dict)または results()(型付き認識結果フレーム)を反復処理して、サーバーから返される情報とデータを処理してください。
| イベント/反復メソッド | 産出内容 | 戻り値 | 説明 |
|---|---|---|---|
task-started イベント | なし | start() 内部で読み取られ、起動の戻り時に last_response に保存されます。events() からは再度産出されません。 | |
event:サービス側イベントの dict | 反復子 | サーバーから応答があった場合にイベントを産出します。認識結果は payload.output.sentence にあり、ハートビートや空テキストのイベントである可能性があるため、アプリケーションで必要に応じて無視できます。単一の受信スレッドで継続的に消費し、並行して複数のリーダーを作成しないでください。 | |
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 | 現在の文が終了したかどうかを判断します。このメソッドは、get_sentence() が返す単文情報内の end_time フィールドが None かどうかを確認して判定します。end_time が None でない場合は、文が終了したことを示します。 |
文情報 (Sentence)
Sentence クラスのメンバーは次のとおりです:
| パラメーター | 型 | 説明 |
|---|---|---|
begin_time | int | 文の開始時刻 (ms) です。 |
end_time | int | 文の終了時刻 (ms) です。 |
text | str | 認識されたテキストです。 |
words | 単語レベルのタイムスタンプ情報 (Word) のリスト | 単語レベルのタイムスタンプ情報です。 |
単語レベルのタイムスタンプ情報 (Word)
Word クラスのメンバーは次のとおりです:
| パラメーター | 型 | 説明 |
|---|---|---|
begin_time | int | 単語の開始時刻 (ms) です。 |
end_time | int | 単語の終了時刻 (ms) です。 |
text | str | 単語です。 |
punctuation | str | 句読点です。 |
エラーコード
エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。
問題が解決しない場合は、開発者コミュニティ に参加し、問題を報告して Request ID を提供してください。
よくある質問
機能
Q:長時間の無音状態でも接続を維持するにはどうすればよいですか?
heartbeat リクエストパラメーターを true に設定し、サーバーに無音オーディオを送信し続けます。
無音オーディオは、オーディオファイルまたはストリームに含まれる音響信号のないコンテンツです。無音オーディオは、Audacity や Adobe Audition などのオーディオ編集ソフトウェア、または FFmpeg などのコマンドラインツールを使用して、いくつかの方法で生成できます。
Q:オーディオをサポートされているフォーマットに変換するにはどうすればよいですか?
FFmpeg を使用します。詳しい使い方については、FFmpeg の公式サイトをご参照ください。
Q:ローカルファイル (録音) を認識するにはどうすればよいですか?
ローカルファイルを認識するには 2 つの方法があります:
-
ローカルファイルパスを直接渡す:この方法では、認識が完了した後にのみ完全な結果が返されるため、即時のフィードバックが必要なシナリオには適していません。
非ストリーミング呼び出しを参照し、コアリソース(
client.audio.asr)のrecognize_fileメソッドにファイルパスを渡して録音を直接認識します。 -
ローカルファイルをバイナリストリームに変換して認識する:この方法では、結果をストリーミングしながらファイルを認識するため、即時のフィードバックが必要なシナリオに適しています。
双方向ストリーミング呼び出しを参照し、認識セッションの
send_audio_frameメソッドを使用して、バイナリ ストリームをサーバーに送信して認識を行います。
トラブルシューティング
Q:音声が認識されない (認識結果がない) のはなぜですか?
-
リクエストパラメーターの音声フォーマット (
format) とサンプルレート (sampleRate/sample_rate) が正しいこと、およびパラメーターの制約を満たしていることを確認してください。 よくあるエラーとして、以下が挙げられます。- 音声ファイルの拡張子は .wav ですが、実際は MP3 形式であり、
formatリクエストパラメーターは mp3 に設定されています(パラメーター設定が正しくありません)。 - 音声サンプルレートは 3600 Hz ですが、
sampleRate/sample_rateリクエストパラメーターは 48000 に設定されています (不正なパラメーター設定)。
- 音声ファイルの拡張子は .wav ですが、実際は MP3 形式であり、
- 上記のいずれのチェックでも問題が解決しない場合は、カスタムホットワードを追加して特定の用語の認識を向上させてください。