Skip to main content

Fun-ASR-Realtime Python SDK

このトピックでは、Fun-ASR-Realtime リアルタイム音声認識モデル用の Python SDK のパラメータとインターフェイスについて説明します。

前提条件

サービスが有効化されており、「API キーの取得」が完了していること。コード漏洩によるセキュリティリスクを防ぐため、コードにハードコーディングするのではなく、「API キーを環境変数として設定」してください。

クイックスタート

コアリソース(client.audio.asr)は、非ストリーミング呼び出しと双方向ストリーミング呼び出しなどのインターフェイスを提供します。実際の要件に応じて、適切な呼び出し方法を選択してください:
  • 非ストリーミング呼び出し(recognize_file):ローカルファイルを認識します。SDK が自動的に音声を分割送信し、タスクの終了までドライブします。事前に録音された音声の処理に適しています。
  • 双方向ストリーミング呼び出し(recognize セッション):音声ストリームを直接認識し、結果をリアルタイムで出力します。音声ストリームは、マイクなどの外部デバイスから取得することも、ローカルファイルから読み取ることもできます。即時のフィードバックを必要とするシナリオに適しています。
  • 非ストリーミング呼び出し
  • 双方向ストリーミング呼び出し
単一のリアルタイム音声認識タスクを送信し、ローカルファイルを渡す方式で同期的にブロックして認識結果を取得します。コアリソース(client.audio.asr)の recognize_file メソッドを呼び出してリクエストパラメーターをバインドし、ローカルファイルのパスを渡します。サーバーイベントを反復処理して認識結果を取得します。
import os
import dashscope

# API キーは、シンガポールリージョンと北京リージョンで異なります。 API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください:api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # 以下はシンガポールリージョンの設定です。 呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。 設定はリージョンによって異なります。
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# ローカル音声ファイルを認識します:recognize_file が自動的に音声を分割送信し、タスクの終了までドライブします
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='fun-asr-realtime',
        format='wav',
        sample_rate=16000):
    payload = event.get('payload') or {}
    sentence = (payload.get('output') or {}).get('sentence') or {}
    if sentence.get('text') and not sentence.get('heartbeat'):
        print('Recognition result: ', sentence['text'])

リクエストパラメーター

リクエストパラメーターは、コアリソース(client.audio.asr)の recognize/recognize_file メソッドで設定します:model、format、sample_rate、vocabulary_id は具名パラメーターで、その他のパラメーター(max_sentence_silence、language_hints など)は parameters ディクショナリで渡します。
パラメータータイプ必須説明
modelstrはいモデル名。
sample_rateintはいサンプリングレート (Hz)。有効な値: 8 kHz モデルは 8000 Hz のみをサポートします。その他のモデルは任意のサンプリングレートをサポートします。
formatstrはいオーディオフォーマット。有効な値:
  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr
opus/speex: Ogg カプセル化を使用する必要があります。wav: PCM エンコーディングを使用する必要があります。amr: AMR-NB タイプのみをサポートしています。
vocabulary_idstrいいえ事前コンパイル済みのホットワードリストのID。ホットワードリスト作成 API を呼び出して、この ID を事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。語彙が既知で比較的安定しており、リクエスト間で同じ単語リストを再利用する必要があるシナリオに適しています。使用法の詳細については、「事前コンパイル済みホットワード」をご参照ください。
max_sentence_silenceintいいえセグメンテーションのための VAD の無音しきい値 (ミリ秒)。音声セグメントの後の無音時間がこのしきい値を超えると、システムは文が終了したと判断します。デフォルト値: 1300。有効な値: [200, 6000]。
multi_threshold_mode_enabledboolいいえマルチしきい値モードを有効にするかどうか。有効にすると、VAD セグメンテーションが長すぎるセグメントを生成するのを防ぎます。デフォルト:False。
punctuation_prediction_enabledboolいいえ認識結果に句読点を自動的に追加するかどうか:
  • True (デフォルト):有効。この値は変更できません。
heartbeatboolいいえハートビートパケットを有効にするかどうか。デフォルト:False。
  • True:無音音声が継続的に送信されている間、サーバーへの接続を維持します。
  • False (デフォルト):無音音声が継続的に送信されていても、接続は一定時間後にタイムアウトして切断されます。
無音オーディオとは、オーディオファイルまたはデータストリーム内で音声信号を含まないコンテンツを指します。 Audacity や Adobe Audition のような音声編集ソフトウェアを使用したり、FFmpeg のようなコマンドラインツールを使用したりするなど、いくつかの方法で無音のオーディオを生成できます。このフィールドには SDK バージョン 1.23.1 以降が必要です。
language_hintslist[str]いいえ認識する音声の言語。デフォルト値はありません。設定しない場合、モデルは自動的に言語を検出します。1 つの値を設定できます。複数設定した場合は、最初の値のみが有効です。
  • fun-asr-realtime:
    • zh: 中国語
    • en: 英語
    • ja: 日本語
    • ko: 韓国語
    • vi: ベトナム語
    • th: タイ語
    • id: インドネシア語
    • ms: マレー語
    • tl: フィリピノ語
    • hi: ヒンディー語
    • ar: アラビア語
    • fr: フランス語
    • de: ドイツ語
    • es: スペイン語
    • pt: ポルトガル語
    • ru: ロシア語
    • it: イタリア語
    • nl: オランダ語
    • sv: スウェーデン語
    • da: デンマーク語
    • fi: フィンランド語
    • no: ノルウェー語
    • el: ギリシャ語
    • pl: ポーランド語
    • cs: チェコ語
    • hu: ハンガリー語
    • ro: ルーマニア語
    • bg: ブルガリア語
    • hr: クロアチア語
    • sk: スロバキア語
  • fun-asr-realtime-2026-02-28:
    • zh: 中国語
    • en: 英語
    • ja: 日本語
  • fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28:
    • zh: 中国語
speech_noise_thresholdfloatいいえ音声とノイズを区別するためのしきい値であり、VAD (音声アクティビティ検出) の感度調整に使用します。有効な値: [-1.0, 1.0]。値の説明:
  • 値が -1 に近いほど: ノイズしきい値が低下するため、ノイズが音声として認識されやすくなり、より多くのノイズが文字起こしされる可能性があります。
  • 値が +1 に近いほど: ノイズしきい値が上昇するため、音声がノイズとして誤って判断されやすくなり、一部の音声がフィルタリングされる可能性があります。
これは高度な設定パラメーターです。調整すると認識結果に大きな影響を与える可能性があります。推奨事項:
  • 調整する前に、結果を十分にテストおよび検証してください。
  • 実際の音声環境に基づいて、少しずつ調整してください (0.1 のステップを推奨します)。
special_word_filterstrいいえ音声認識中に処理するセンシティブな単語を指定し、単語ごとに異なる処理方法を設定できます。詳細については、「センシティブな単語のフィルタリング」をご参照ください。
callbackRecognitionCallbackいいえコールバックインターフェイス (RecognitionCallback)。
以下のパラメーターを、Recognition インスタンスの call または start メソッドにキーワード引数として渡します。
パラメータータイプ必須説明
raw_inputdictいいえ会話コンテキストを渡すために使用される入力オブジェクト。コンテキスト強化により、ドメイン固有の用語の認識精度が向上します。使用方法については、「クイックスタート」をご参照ください。
コンテキストパラメーターは、fun-asr-realtime モデルでのみサポートされています。
dict には、値がメッセージのリスト (list[dict]) である context キーを含める必要があります。各メッセージには、次のフィールドが含まれます:
  • role (str, 必須):メッセージのロール。user は、以前のユーザーの会話ターンからの認識結果またはドメイン固有の単語リストを表します。assistant は、以前のターンからの大規模言語モデルのレスポンスを表します。
  • content (list[dict], 必須):メッセージコンテンツのリスト。各要素には type (str; ロールが user の場合は input_text、ロールが assistant の場合は text に設定) と text (str, テキストコンテンツ) が含まれます。
制限:input_text および text タイプのコンテキストメッセージは、それぞれ 5 メッセージに制限されます。制限を超えた場合、最新の 5 メッセージのみが保持されます。コンテキストターンあたりの合計テキスト長は 400 文字を超えることはできず、超過分は末尾から切り捨てられます。
コンテキストを渡す際、context 内のメッセージは特定の順序に従う必要があります。コンテキストメッセージは会話ターンごとに配置する必要があり、各ターン内で user メッセージ (input_text タイプ) は、対応する assistant メッセージ (text タイプ) の前に置く必要があります。
このフィールドには SDK バージョン 2.0.1 以降が必要です。
# 渡すための入力を構築します
input_context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Hello there"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, I am Qwen. How can I help you?"
                }
            ]
        }
    ]
}

# 認識セッション作成時に input パラメーターで渡します
recognition = client.audio.asr.recognize(
    model='fun-asr-realtime',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

主要なインターフェイス

コアリソース(client.audio.asr)

リアルタイム音声認識能力は client.audio.asr リソースにマウントされています:recognize は双方向ストリーミング認識セッション(Recognition)を作成し、recognize_file はローカルファイルを一度に認識します。
メンバーメソッドメソッドシグネチャ説明
recognize
def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition
双方向ストリーミング認識セッションを作成します。with コンテキストに入ると start が自動的に呼び出され、接続の確立とタスクの送信が行われます。音声の送信とイベントの消費は並行して行う必要があります(send_audio_frame、events()/results()、stop と組み合わせて使用します)。
recognize_file
def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]
ローカルファイルをベースとした非ストリーミング呼び出しです:SDK が自動的に音声を分割送信し、タスクの終了までドライブして、サーバーイベントを 1 つずつ産出します。このメソッドは、認識対象のファイルに読み取り権限があることを要求します。
start
def start(self)
音声認識を開始します:接続を確立し、タスクを送信して task-started を待機します。with コンテキストに入ると自動的に呼び出され、起動に成功した後に音声を送信できます。
send_audio_frame
def send_audio_frame(self, buffer: bytes)
音声をプッシュします。毎回プッシュされる音声ストリームは、大きすぎたり小さすぎたりしないようにしてください。各音声パケットの長さは約 100 ms、サイズは 1 KB~16 KB の間にすることを推奨します。認識結果は events()/results() の反復処理で取得します。
stop
def stop(self)
音声認識を停止します:サーバーに入力の終了のみを通知します。受信スレッドは events() を task-finished イベントまで消費し続ける必要があります。
events / results
def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]
サーバーイベントを反復処理します:events() は原始イベント dict を産出します(認識テキストは payload.output.sentence にあります)。results() は認識結果フレームのみを産出し、認識結果(RecognitionResult)の型付きオブジェクトを返します(ハートビートフレームはフィルタリング済み)。
close
def close(self)
認識セッションを閉じます。with コンテキストから抜けるときに自動的に呼び出されます。
request_id / first_package_delay / last_package_delay / last_response
rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.last_response
request_id、初回パケット遅延(最初の音声パケットの送信から最初の認識結果パケットの受信までのレイテンシー)、最終パケット遅延(stop 指令の送信から最後の認識結果パケットの受信までの所要時間)を取得します。タスク完了後に使用します。last_response は最後に正常に読み取った原始メッセージであり、task-failed のエラー取得に使用できます。セッションを閉じた後も読み取り可能です。

イベント反復(events()/results())

双方向ストリーミング呼び出しでは、サーバーはイベントの方式で主要なプロセス情報とデータをクライアントに返します。受信スレッドでセッションの events()(原始イベント dict)または results()(型付き認識結果フレーム)を反復処理し、サーバーから返された情報やデータを処理する必要があります。
# 原始イベントを反復処理します:認識テキストは payload.output.sentence にあります
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('Recognition text: ', sentence['text'])


# または認識結果フレームのみを反復処理します(RecognitionResult を返し、ハートビートフレームはフィルタリング済み)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Recognition text: ', sentence['text'])
イベント/反復メソッド産出内容戻り値説明
event["header"]["event"] == "task-started"
task-started イベントなしstart() 内部で読み取られ、起動の戻り時に last_response に保存されます。events() から再度産出されることはありません。
def events(self) -> Iterator[Dict]
event:サーバーイベント dictイテレーターサーバーからの返信があるときにイベントを産出します。認識結果は payload.output.sentence にあり、ハートビートや空テキストのイベントである場合があります。アプリケーションは必要に応じて無視できます。1 つの受信スレッドで消費し続けてください。複数の読み取り者を並行して作成しないでください。
def results(self) -> Iterator[RecognitionResult]
result:認識結果(RecognitionResult)イテレーター認識結果フレームのみを産出します(ハートビートフレームはフィルタリング済み)。すべての認識結果が返された後に反復処理が終了します。
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
DashScopeError 例外なし異常発生時に送信/受信スレッドでスローされます。try/except で捕捉できます。
event["header"]["event"] == "task-finished"
task-finished イベントなしサーバーがすべての認識を完了した後に events() から産出され、その後反復処理が終了します。stop() を送信した後もこのイベントを読み取る必要があります。

応答

認識結果 (RecognitionResult)

RecognitionResult は、セッションの results() の反復処理で産出される 1 回の認識結果フレームを表します(双方向ストリーミング呼び出しと非ストリーミング呼び出しのどちらでも使用できます。events() が産出するのは原始イベント dict であるため、この型付きビューが必要な場合は results() を使用してください)。
メンバーメソッドメソッドシグネチャ説明
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]
現在認識されている文と、そのタイムスタンプ情報を取得します。このメソッドは、Dict[str, Any](単文情報)を返します。詳細については、「単文情報 (Sentence)」をご参照ください。
request_id
result.request_id
現在のイベントに対応するリクエストの request_id。
is_sentence_end
def is_sentence_end(self) -> bool
現在の文が終了したかどうかを判定します。このメソッドは、get_sentence() が返す単文情報の end_time フィールドが None かどうかを確認します。end_time が None でない場合は、文が終了したことを示します。

文情報 (Sentence)

Sentence クラスのメンバーは次のとおりです:
パラメーター型説明
begin_timeint文の開始時刻 (ms) です。
end_timeint文の終了時刻 (ms) です。
textstr認識されたテキストです。
words単語レベルのタイムスタンプ情報 (Word) のリスト単語レベルのタイムスタンプ情報です。

単語レベルのタイムスタンプ情報 (Word)

Word クラスのメンバーは次のとおりです:
パラメーター型説明
begin_timeint単語の開始時刻 (ms) です。
end_timeint単語の終了時刻 (ms) です。
textstr単語です。
punctuationstr句読点です。

エラーコード

エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。 問題が解決しない場合は、開発者コミュニティ に参加し、問題を報告して 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:音声が認識されない (認識結果がない) のはなぜですか?

  1. リクエストパラメーターの音声フォーマット (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
  1. 上記のいずれのチェックでも問題が解決しない場合は、カスタムホットワードを追加して特定の用語の認識を向上させてください。