このトピックでは、Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime リアルタイム音声認識モデル用の Python SDK のパラメータとインターフェイスについて説明します。
重要Alibaba Cloud Model Studio は、中国 (北京) およびシンガポールの各リージョン向けにワークスペース固有ドメインをリリースしました。これらの新しい専用ドメインにより、推論リクエストのパフォーマンスと安定性が向上します。以下の新しいドメインへの移行を推奨します:
- 中国 (北京):
dashscope.aliyuncs.comから{WorkspaceId}.cn-beijing.maas.aliyuncs.comへ - シンガポール:
dashscope-intl.aliyuncs.comから{WorkspaceId}.ap-southeast-1.maas.aliyuncs.comへ
{WorkspaceId} を実際の ワークスペース ID に置き換えてください。既存のドメインは引き続き問題なく利用できます。
ユーザーガイド:モデルの説明と選定ガイダンスについては、「音声テキスト変換」をご参照ください。
前提条件
サービスが有効化されており、「API キーの取得」が完了していること。コード漏洩によるセキュリティリスクを防ぐため、コードにハードコーディングするのではなく、「API キーを環境変数として設定」してください。
クイックスタート
Recognition クラスは、非ストリーミング呼び出しと双方向ストリーミング呼び出しの両方のインターフェイスを提供します。ニーズに合わせて呼び出し方法を選択してください:
- 非ストリーミング呼び出し:ローカルファイルを認識し、1 回のレスポンスで完全な結果を返します。録音済みの音声を処理する場合に適しています。
- 双方向ストリーミング呼び出し:音声ストリームを直接認識し、結果をリアルタイムで出力します。音声ストリームは、マイクなどの外部デバイスから取得することも、ローカルファイルから読み取ることもできます。即時のフィードバックが必要なシナリオに適しています。
非ストリーミング呼び出し
単一のリアルタイム音声認識タスクを送信し、ローカルファイルを渡すことで認識結果を同期的に取得します。
Recognition クラスをインスタンス化し、リクエストパラメーターをバインドし、call を呼び出して認識または翻訳を実行し、最終的な 認識結果 (RecognitionResult) を取得します。
完全な例の表示
from http import HTTPStatus
import dashscope
from dashscope.audio.asr import Recognition
import os
# API キーは、シンガポールリージョンと北京リージョンで異なります。 API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
# 以下はシンガポールリージョンの設定です。 呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。 設定はリージョンによって異なります。
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'
recognition = Recognition(model='qwen-audio-3.0-asr-flash-streaming',
format='wav',
sample_rate=16000,
callback=None)
result = recognition.call('{YOUR_AUDIO_FILE}')
if result.status_code == HTTPStatus.OK:
print('Recognition result:')
print(result.get_sentence())
else:
print('Error: ', result.message)
print(
'[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
.format(
recognition.get_last_request_id(),
recognition.get_first_package_delay(),
recognition.get_last_package_delay(),
))
双方向ストリーミング呼び出し
単一のリアルタイム音声認識タスクを送信し、コールバックインターフェイスを実装することで、リアルタイムの認識結果をストリーミングで取得します。
-
ストリーミング音声認識を開始します。
Recognition クラス をインスタンス化し、リクエストパラメーター とコールバックインターフェイス (RecognitionCallback) をバインドして、
startメソッドを呼び出し、ストリーミング音声認識を開始します。 -
音声をストリーミングします。
Recognition クラス の
send_audio_frameメソッドをループで呼び出し、バイナリ音声ストリームをセグメントに分けてサーバーに送信します。ストリームは、ローカルファイルまたはマイクなどのデバイスから読み取られます。音声の送信中に、サーバーは コールバックインターフェイス (RecognitionCallback) の
on_eventメソッドを通じて、認識結果をリアルタイムでクライアントに返します。フレームあたり約 100 ms の音声を送信し、各フレームを 1 KB から 16 KB の間に保ってください。
-
タスクを終了します。
Recognition クラス の
stopメソッドを呼び出して、音声認識を終了します。このメソッドは、 コールバックインターフェイス (RecognitionCallback) の
on_completeまたはon_errorコールバックがトリガーされるまで、現在のスレッドをブロックします。
完全な例の表示
import os
import signal # キーボードイベント処理用 (「Ctrl+C」を押して録音を終了)
import sys
import dashscope
import pyaudio
from dashscope.audio.asr import *
mic = None
stream = None
# 録音パラメーターの設定
sample_rate = 16000 # サンプリングレート (Hz)
channels = 1 # モノラルチャネル
dtype = 'int16' # データ型
format_pcm = 'pcm' # 音声データのフォーマット
block_size = 3200 # バッファあたりのフレーム数
# リアルタイム音声認識コールバック
class Callback(RecognitionCallback):
def on_open(self) -> None:
global mic
global stream
print('RecognitionCallback open.')
mic = pyaudio.PyAudio()
stream = mic.open(format=pyaudio.paInt16,
channels=1,
rate=16000,
input=True)
def on_close(self) -> None:
global mic
global stream
print('RecognitionCallback close.')
stream.stop_stream()
stream.close()
mic.terminate()
stream = None
mic = None
def on_complete(self) -> None:
print('RecognitionCallback completed.') # 認識完了
def on_error(self, message) -> None:
print('RecognitionCallback task_id: ', message.request_id)
print('RecognitionCallback error: ', message.message)
# 音声ストリームが実行中の場合は停止して閉じます
if 'stream' in globals() and stream.active:
stream.stop()
stream.close()
# プログラムを強制終了します
sys.exit(1)
def on_event(self, result: RecognitionResult) -> None:
sentence = result.get_sentence()
if 'text' in sentence:
print('RecognitionCallback text: ', sentence['text'])
if RecognitionResult.is_sentence_end(sentence):
print(
'RecognitionCallback sentence end, request_id:%s, usage:%s'
% (result.get_request_id(), result.get_usage(sentence)))
def signal_handler(sig, frame):
print('Ctrl+C pressed, stop recognition ...')
# 認識を停止
recognition.stop()
print('Recognition stopped.')
print(
'[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
.format(
recognition.get_last_request_id(),
recognition.get_first_package_delay(),
recognition.get_last_package_delay(),
))
# プログラムを強制終了します
sys.exit(0)
# メイン関数
if __name__ == '__main__':
# API キーは、シンガポールリージョンと北京リージョンで異なります。 API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
# 以下はシンガポールリージョンの設定です。 呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。 設定はリージョンによって異なります。
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'
# 認識コールバックを作成します
callback = Callback()
# 非同期モードで認識サービスを呼び出します。モデル、フォーマット、
# サンプリングレートなどの認識パラメーターをカスタマイズできます
recognition = Recognition(
model='qwen-audio-3.0-asr-flash-streaming',
format=format_pcm,
# 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr'。サポートされているフォーマットはドキュメントで確認できます
sample_rate=sample_rate,
# 8000、16000 をサポート
semantic_punctuation_enabled=False,
callback=callback)
# 認識を開始
recognition.start()
signal.signal(signal.SIGINT, signal_handler)
print("Press 'Ctrl+C' to stop recording and recognition...")
# 「Ctrl+C」が押された際の処理を設定します
while True:
if stream:
data = stream.read(3200, exception_on_overflow=False)
recognition.send_audio_frame(data)
else:
break
recognition.stop()
import os
import time
import dashscope
from dashscope.audio.asr import *
# API キーは、シンガポールリージョンと北京リージョンで異なります。 API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')
# 以下はシンガポールリージョンの設定です。 呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。 設定はリージョンによって異なります。
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'
from datetime import datetime
def get_timestamp():
now = datetime.now()
formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
return formatted_timestamp
class Callback(RecognitionCallback):
def on_complete(self) -> None:
print(get_timestamp() + ' Recognition completed') # 認識完了
def on_error(self, result: RecognitionResult) -> None:
print('Recognition task_id: ', result.request_id)
print('Recognition error: ', result.message)
exit(0)
def on_event(self, result: RecognitionResult) -> None:
sentence = result.get_sentence()
if 'text' in sentence:
print(get_timestamp() + ' RecognitionCallback text: ', sentence['text'])
if RecognitionResult.is_sentence_end(sentence):
print(get_timestamp() +
'RecognitionCallback sentence end, request_id:%s, usage:%s'
% (result.get_request_id(), result.get_usage(sentence)))
callback = Callback()
recognition = Recognition(model='qwen-audio-3.0-asr-flash-streaming',
format='wav',
sample_rate=16000,
callback=callback)
try:
audio_data: bytes = None
f = open("{YOUR_AUDIO_FILE}", 'rb')
if os.path.getsize("{YOUR_AUDIO_FILE}"):
# ファイルデータを一度にすべてバッファに読み込みます
file_buffer = f.read()
f.close()
print("Start Recognition")
recognition.start()
# バッファから一度に 3200 バイトを送信します
buffer_size = len(file_buffer)
offset = 0
chunk_size = 3200
while offset < buffer_size:
# 今回送信するデータチャンクのサイズを計算します
remaining_bytes = buffer_size - offset
current_chunk_size = min(chunk_size, remaining_bytes)
# バッファから現在のデータチャンクを抽出します
audio_data = file_buffer[offset:offset + current_chunk_size]
# 音声データフレームを送信します
recognition.send_audio_frame(audio_data)
# オフセットを更新します
offset += current_chunk_size
# リアルタイム伝送をシミュレートするために遅延を追加します
time.sleep(0.1)
recognition.stop()
else:
raise Exception(
'The supplied file was empty (zero bytes long)')
except Exception as e:
raise e
print(
'[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
.format(
recognition.get_last_request_id(),
recognition.get_first_package_delay(),
recognition.get_last_package_delay(),
))
リクエストパラメーター
リクエストパラメーターは、Recognition クラスのコンストラクター (init) で設定します。
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
model | str | はい | モデル名。 Qwen-Audio-3.0-ASR-Flash-Streaming および Fun-ASR-Realtime モデルシリーズがサポートされています。詳細については、「サポートされているモデルとリージョン」をご参照ください。 |
sample_rate | int | はい | サンプリングレート (Hz)。 有効な値: 8 kHz モデルは 8000 Hz のみをサポートします。その他のモデルは任意のサンプリングレートをサポートします。 |
format | str | はい | オーディオフォーマット。 有効な値:
重要opus/speex: Ogg カプセル化を使用する必要があります。 wav: PCM エンコーディングを使用する必要があります。 amr: AMR-NB タイプのみをサポートしています。 |
vocabulary_id | str | いいえ | 事前コンパイル済みのホットワードリストのID。 ホットワードリスト作成 API を呼び出して、この ID を事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。 語彙が既知で比較的安定しており、リクエスト間で同じ単語リストを再利用する必要があるシナリオに適しています。 使用法の詳細については、「事前コンパイル済みホットワード」をご参照ください。 |
vocabulary | dict | いいえ | インスタントホットワード。 キーと値のペアとして渡します。キーはホットワードのテキスト ( 一時的なセッションレベルのホットワードの最適化に適しています。 事前コンパイル済みのホットワードと一緒に設定した場合、インスタントホットワードのみが有効になります。使用法の詳細については、「インスタントホットワード」をご参照ください。 重要 例: |
semantic_punctuation_enabled | bool | いいえ | セマンティックセグメンテーションを有効にするかどうか。 デフォルト:False。
セマンティックセグメンテーションはより正確で、会議の文字起こしに適しています。音声アクティビティ検出 (VAD) セグメンテーションはレイテンシーが低く、対話型のシナリオに適しています。 |
max_sentence_silence | int | いいえ | セグメンテーションのための VAD の無音しきい値 (ミリ秒)。音声セグメントの後の無音時間がこのしきい値を超えると、システムは文が終了したと判断します。 デフォルト値: 1300。 有効な値: [200, 6000]。 |
multi_threshold_mode_enabled | bool | いいえ | 重要 マルチしきい値モードを有効にするかどうか。有効にすると、VAD セグメンテーションが長すぎるセグメントを生成するのを防ぎます。 デフォルト:False。 |
punctuation_prediction_enabled | bool | いいえ | 認識結果に句読点を自動的に追加するかどうか:
|
heartbeat | bool | いいえ | ハートビートパケットを有効にするかどうか。 デフォルト:False。
無音オーディオとは、オーディオファイルまたはデータストリーム内で音声信号を含まないコンテンツを指します。 Audacity や Adobe Audition のような音声編集ソフトウェアを使用したり、FFmpeg のようなコマンドラインツールを使用したりするなど、いくつかの方法で無音のオーディオを生成できます。 このフィールドには SDK バージョン 1.23.1 以降が必要です。 |
language_hints | list[str] | いいえ | 認識する音声の言語。デフォルト値はありません。設定しない場合、モデルは自動的に言語を検出します。 Qwen-Audio-3.0-ASR-Flash-Streaming モデルシリーズでは、最大 4 つの値を設定できます。4 つ以上設定した場合、最初の 4 つのみが有効になります。Fun-ASR-Realtime モデルシリーズでは、1 つの値しか設定できません。複数の値を設定した場合、最初の値のみが有効になります。 クリックしてサポートされている言語コードを表示
|
speech_noise_threshold | float | いいえ | 音声とノイズを区別するためのしきい値であり、VAD (音声アクティビティ検出) の感度調整に使用します。 有効な値: [-1.0, 1.0]。 値の説明:
これは高度な設定パラメーターです。調整すると認識結果に大きな影響を与える可能性があります。推奨事項:
|
special_word_filter | str | いいえ | 音声認識中に処理するセンシティブな単語を指定し、単語ごとに異なる処理方法を設定できます。詳細については、「センシティブな単語のフィルタリング」をご参照ください。 |
callback | RecognitionCallback | いいえ |
以下のパラメーターを、Recognition インスタンスの call または start メソッドにキーワード引数として渡します。
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
raw_input | dict | いいえ | 会話コンテキストを渡すために使用される入力オブジェクト。コンテキスト強化により、ドメイン固有の用語の認識精度が向上します。使用方法については、「クイックスタート」をご参照ください。 重要コンテキストパラメーターは、 dict には、値がメッセージのリスト (list[dict]) である
重要制限: 重要コンテキストを渡す際、 注記このフィールドには SDK バージョン 1.25.23 以降が必要です。
|
主要なインターフェイス
Recognition クラス
"from dashscope.audio.asr import *" を使用して Recognition をインポートします。
| メンバーメソッド | メソッドシグネチャ | 説明 |
|---|---|---|
call | | ローカルファイルに基づく非ストリーミング呼び出しです。このメソッドは、すべての音声が読み取られるまで現在のスレッドをブロックし、ファイルに対する読み取り権限も必要です。 認識結果は |
start | | 音声認識を開始します。 コールバックベースのストリーミングによるリアルタイム認識です。このメソッドは現在のスレッドをブロックしません。 |
send_audio_frame | | 音声を送信します。送信するオーディオフレームは大きすぎず小さすぎないようにしてください。目安はフレームあたり約 100 ms、サイズは 1 KB ~ 16 KB です。 認識結果は、 コールバックインターフェイス (RecognitionCallback) の on_event メソッドで取得します。 |
stop | | 音声認識を停止します。サーバーが受信済みのすべての音声の認識を完了するまで呼び出しをブロックし、その後タスクを終了します。 |
get_last_request_id | | リクエスト ID を取得します。コンストラクターの呼び出し (オブジェクトの作成) 後に利用できます。 |
get_first_package_delay | | 初回パケット遅延を取得します。これは、最初の音声パケットを送信してから最初の認識結果を受信するまでのレイテンシーです。タスク完了後に使用してください。 |
get_last_package_delay | | 最終パケット遅延を取得します。これは、 |
get_response | | 最後のメッセージを取得します。タスク失敗時のエラーを取得するために使用します。 |
コールバックインターフェイス (RecognitionCallback)
双方向ストリーミング 呼び出しでは、サーバーはコールバックを通じて、主要なプロセス情報とデータをクライアントに返します。コールバックメソッドを実装して、サーバーから返される情報とデータを処理してください。
例を表示
class Callback(RecognitionCallback):
def on_open(self) -> None:
print('Connection established')
def on_event(self, result: RecognitionResult) -> None:
# 認識結果を受信するロジックを実装します
pass
def on_complete(self) -> None:
print('Task completed')
def on_error(self, result: RecognitionResult) -> None:
print('An error occurred:', result)
def on_close(self) -> None:
print('Connection closed')
callback = Callback()
| メソッド | パラメーター | 戻り値 | 説明 |
|---|---|---|---|
| None | None | サーバーへの接続が確立された直後に呼び出されます。 |
|
| None | サーバーから応答があった場合に呼び出されます。 |
| None | None | すべての認識結果が返された後に呼び出されます。 |
|
| None | エラーが発生した場合に呼び出されます。 |
| None | None | サーバーが接続を閉じた後に呼び出されます。 |
応答
認識結果 (RecognitionResult)
RecognitionResult は、双方向ストリーミング呼び出しにおける 1 回のリアルタイム認識の結果、または非ストリーミング呼び出しの結果を表します。
| メンバーメソッド | メソッドシグネチャ | 説明 |
|---|---|---|
get_sentence | | 現在認識されている文と、そのタイムスタンプ情報を取得します。コールバックは 1 文ずつ返すため、このメソッドは Dict[str, Any] を返します。 詳細については、「文 (Sentence)」をご参照ください。 |
get_request_id | | リクエスト ID を取得します。 |
is_sentence_end | | 指定した文が終了しているかどうかを判断します。このメソッドは、 |
文情報 (Sentence)
Sentence クラスのメンバーは次のとおりです:
パラメーター | 型 | 説明 |
|---|---|---|
begin_time | int | 文の開始時刻 (ms) です。 |
end_time | int | 文の終了時刻 (ms) です。 |
text | str | 認識されたテキストです。 |
words | 単語レベルのタイムスタンプ情報です。 |
単語レベルのタイムスタンプ情報 (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 の公式サイトをご参照ください。
# 基本的な変換コマンド (汎用テンプレート)
# -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:ローカルファイル (録音) を認識するにはどうすればよいですか?
ローカルファイルを認識するには 2 つの方法があります:
-
ローカルファイルパスを直接渡す:この方法では、認識が完了した後にのみ完全な結果が返されるため、即時のフィードバックが必要なシナリオには適していません。
「非ストリーミング呼び出し」を参照し、Recognition クラス の
callメソッドにファイルパスを渡して録音を直接認識します。 -
ローカルファイルをバイナリストリームに変換して認識する:この方法では、結果をストリーミングしながらファイルを認識するため、即時のフィードバックが必要なシナリオに適しています。
「双方向ストリーミングコール」を参照し、Recognition クラスの
send_audio_frameメソッドを使用して、バイナリ ストリームをサーバーに送信して認識を行います。
トラブルシューティング
Q:音声が認識されない (認識結果がない) のはなぜですか?
-
リクエストパラメーターの音声フォーマット (
format) とサンプルレート (sampleRate/sample_rate) が正しいこと、およびパラメーターの制約を満たしていることを確認してください。 よくあるエラーとして、以下が挙げられます。- 音声ファイルの拡張子は .wav ですが、実際は MP3 形式であり、
formatリクエストパラメーターは mp3 に設定されています(パラメーター設定が正しくありません)。 - 音声サンプルレートは 3600 Hz ですが、
sampleRate/sample_rateリクエストパラメーターは 48000 に設定されています (不正なパラメーター設定)。
ffprobe ツールを使用して、オーディオのコンテナ、コーデック、サンプルレート、チャンネル数、その他の情報を取得します:
- 音声ファイルの拡張子は .wav ですが、実際は MP3 形式であり、
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
- 上記のいずれのチェックでも問題が解決しない場合は、カスタムホットワードを追加して特定の用語の認識を向上させてください。