すべてのプロダクト
Search
ドキュメントセンター

Alibaba Cloud Model Studio:Qwen-Audio-ASR / Fun-ASR Python SDK

最終更新日:Nov 19, 2026

前提条件

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

クイックスタート

以下の呼び出し例を共用できます。表に従ってモデル ID を置き換えてください。

モデルサンプルのモデル ID
Qwen-Audio-ASR-Streamingqwen-audio-3.1-asr-flash-streaming
マイクのサンプルでは qwen-audio-3.0-asr-flash-streaming を使用します。
Qwen-Audio-ASR-Messageqwen-audio-3.1-asr-flash-message
サンプリングレートは 16000 Hz のみ対応しています。
Fun-ASR-Realtimefun-asr-realtime

コアリソース(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'),
    # 以下はシンガポール (ap-southeast-1) リージョンの設定です。呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# ローカル音声ファイルを認識します:recognize_file は音声を自動的にチャンク送信し、タスクを完遂まで駆動します
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='qwen-audio-3.1-asr-flash-streaming',
        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'])

双方向ストリーミング呼び出し

単一の音声リアルタイム認識タスクを送信し、イベントを反復処理することでリアルタイムの認識結果をストリーミングで取得します。

  1. ストリーミング音声認識を開始します。

    コアリソース(client.audio.asr)の recognize メソッドを呼び出して認識セッションを作成し、リクエストパラメーターをバインドし、with コンテキストに入る(start メソッドを自動的に呼び出して接続を確立しタスクを送信します)ことで、ストリーミング音声認識を開始します。

  2. 音声をストリーミングします。

    セッションの send_audio_frame メソッドをループで呼び出し、バイナリ音声ストリームをセグメントに分けてサーバーに送信します。ストリームは、ローカルファイルまたはマイクなどのデバイスから読み取られます。

    送信と受信は並行して実行する必要があります:受信スレッドがセッションの events() メソッドでサーバーイベントを反復処理し、認識結果がリアルタイムでクライアントに返されます。

    フレームあたり約 100 ms の音声を送信し、各フレームを 1 KB から 16 KB の間に保ってください。

  3. タスクを終了します。

    セッションの stop メソッドを呼び出して、音声認識を終了します。

    このメソッドはサーバーに入力が終了したことを通知するだけです。受信スレッドは task-finished イベントまで events() を消費し続け、最終的な認識結果と統計を取得する必要があります。WebSocket 層のエラーは DashScopeError 例外としてスローされるため、送信または受信の箇所で try/except により捕捉できます。

import os
import signal  # キーボードイベント処理用 (「Ctrl+C」を押して録音を終了)
import sys

import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor

mic = None
stream = None

# 録音パラメーターの設定
sample_rate = 16000  # サンプリングレート (Hz)
channels = 1  # モノラルチャネル
dtype = 'int16'  # データ型
format_pcm = 'pcm'  # 音声データのフォーマット
block_size = 3200  # バッファあたりのフレーム数

# リアルタイム音声認識イベントレシーバー
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'])
            if sentence.get('sentence_end'):
                print(
                    'Recognition sentence end, request_id:%s, usage:%s'
                    % (rec.request_id, rec.usage))

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.request_id,
            recognition.first_package_delay,
            recognition.last_package_delay,
        ))
    # プログラムを強制終了します
    sys.exit(0)

# メイン関数
if __name__ == '__main__':
    # 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'),
        # 以下はシンガポール (ap-southeast-1) リージョンの設定です。呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
        workspace="{WorkspaceId}",
        region="ap-southeast-1",
    )

    # 認識サービスを呼び出します。モデル、フォーマット、
    # サンプリングレートなどの認識パラメーターをカスタマイズできます
    with client.audio.asr.recognize(
            model='qwen-audio-3.0-asr-flash-streaming',
            format=format_pcm,
            # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr'。サポートされているフォーマットはドキュメントで確認できます
            sample_rate=sample_rate,
            # 8000、16000 をサポート
    ) as recognition:
        # マイクを開きます
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=16000,
                          input=True)
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, recognition)
            try:
                # 「Ctrl+C」が押されるまでマイクから音声を送信します
                while stream:
                    data = stream.read(3200, exception_on_overflow=False)
                    recognition.send_audio_frame(data)
                recognition.stop()
                receiver.result()
            finally:
                # close はレシーバーのブロックを解除するため、プールのコンテキスト内で実行する必要があります
                recognition.close()
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None
import os
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor

# 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'),
    # 以下はシンガポール (ap-southeast-1) リージョンの設定です。呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

from datetime import datetime

def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp

# リアルタイム音声認識イベントレシーバー
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(get_timestamp() + ' Recognition text: ', sentence['text'])
        if sentence.get('sentence_end'):
            print(get_timestamp() +
                  'Recognition sentence end, request_id:%s, usage:%s'
                  % (rec.request_id, rec.usage))

with client.audio.asr.recognize(
        model='qwen-audio-3.1-asr-flash-streaming',
        format='wav',
        sample_rate=16000,
) as recognition:
    with ThreadPoolExecutor(max_workers=1) as pool:
        receiver = pool.submit(receive_events, recognition)
        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")

                # バッファから一度に 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()
                receiver.result()
            else:
                raise Exception(
                    'The supplied file was empty (zero bytes long)')
        finally:
            # close はレシーバーのブロックを解除するため、プールのコンテキスト内で実行する必要があります
            recognition.close()

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.request_id,
        recognition.first_package_delay,
        recognition.last_package_delay,
    ))

リクエストパラメーター

Qwen-Audio-ASR-Streaming

共通リファレンス

最新のリファレンスは Qwen-Audio-ASR-Streaming Python SDK をご参照ください。

リクエストパラメーターはコアリソース(client.audio.asr)の recognize/recognize_file メソッドで設定します:model、format、sample_rate、vocabulary_id は具名パラメーターであり、その他のパラメーター(language_hints など)は parameters 辞書で渡します。

パラメータータイプ必須説明
modelstr

はい

モデル名。
sample_rateint

はい

サンプリングレート(Hz)。任意のサンプリングレートをサポートします。

formatstr

はい

オーディオフォーマット。

有効な値:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

重要opus/speex: Ogg カプセル化を使用する必要があります。

wav: PCM エンコーディングを使用する必要があります。

amr: AMR-NB タイプのみをサポートしています。

keep_dialectbool

いいえ

注記qwen-audio-3.1-asr-flash-streaming のみに適用します。

デフォルトは false で、方言を標準中国語に変換します。true に設定すると、方言表現を保持します。 同名のキーワード引数で指定します。

vad_modelstr

いいえ

注記qwen-audio-3.1-asr-flash-streaming のみに適用します。

VAD モデル。near_meeting_16k(近距離)または far_field_meeting_16k(遠距離、デフォルト)を指定します。 同名のキーワード引数で指定します。

vocabulary_idstr

いいえ

事前コンパイル済みのホットワードリストのID。

ホットワードリスト作成 API を呼び出して、この ID を事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。

語彙が既知で比較的安定しており、リクエスト間で同じ単語リストを再利用する必要があるシナリオに適しています。

使用法の詳細については、「事前コンパイル済みホットワード」をご参照ください。

vocabularydict

いいえ

インスタントホットワード。

キーと値のペアとして渡します。キーはホットワードのテキスト (文字列)、値はホットワードの重み (整数) です。事前にホットワードリストを作成する必要はありません。重みの範囲は [1, 5] または 50 に設定します。値が [1, 5] の範囲内である場合、値が大きくなるほどモデルがその単語を出力する可能性が高くなります。値が 50 の場合はスーパーホットワードを指定し、再現率が大幅に向上しますが、スーパーホットワードの数は 50 を超えることはできません。

一時的なセッションレベルのホットワードの最適化に適しています。

事前コンパイル済みのホットワードと一緒に設定した場合、インスタントホットワードのみが有効になります。使用法の詳細については、「インスタントホットワード」をご参照ください。

例:

import os
import dashscope

client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# インスタントホットワードは parameters で渡します
vocab = {"John Smith": 5, "Jane Doe": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)
max_sentence_silenceint

いいえ

セグメンテーションのための VAD の無音しきい値 (ミリ秒)。音声セグメントの後の無音時間がこのしきい値を超えると、システムは文が終了したと判断します。

デフォルト値: 800。

有効な値: [200, 6000]。

multi_threshold_mode_enabledbool

いいえ

マルチしきい値モードを有効にするかどうか。有効にすると、VAD セグメンテーションが長すぎるセグメントを生成するのを防ぎます。

デフォルト:False。

punctuation_prediction_enabledbool

いいえ

認識結果に句読点を自動的に追加するかどうか:

  • True (デフォルト):有効。この値は変更できません。
heartbeatbool

いいえ

ハートビートパケットを有効にするかどうか。

デフォルト:False。

  • True:無音音声が継続的に送信されている間、サーバーへの接続を維持します。
  • False (デフォルト):無音音声が継続的に送信されていても、接続は一定時間後にタイムアウトして切断されます。

無音オーディオとは、オーディオファイルまたはデータストリーム内で音声信号を含まないコンテンツを指します。 Audacity や Adobe Audition のような音声編集ソフトウェアを使用したり、FFmpeg のようなコマンドラインツールを使用したりするなど、いくつかの方法で無音のオーディオを生成できます。

このフィールドには SDK バージョン 2.0.1 以降が必要です。

language_hintslist[str]

いいえ

認識する音声の言語。デフォルト値はありません。設定しない場合、モデルは自動的に言語を検出します。

最大 4 つの値を設定できます。それ以上設定した場合は、最初の 4 つのみが有効です。

クリックしてサポートされている言語コードを表示

  • 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: スロバキア語
speech_noise_thresholdfloat

いいえ

音声とノイズを区別するためのしきい値であり、VAD (音声アクティビティ検出) の感度調整に使用します。

有効な値: [-1.0, 1.0]。

値の説明:

  • 値が -1 に近いほど: ノイズしきい値が低下するため、ノイズが音声として認識されやすくなり、より多くのノイズが文字起こしされる可能性があります。
  • 値が +1 に近いほど: ノイズしきい値が上昇するため、音声がノイズとして誤って判断されやすくなり、一部の音声がフィルタリングされる可能性があります。

これは高度な設定パラメーターです。調整すると認識結果に大きな影響を与える可能性があります。推奨事項:

  • 調整する前に、結果を十分にテストおよび検証してください。
  • 実際の音声環境に基づいて、少しずつ調整してください (0.1 のステップを推奨します)。
special_word_filterstr

いいえ

音声認識中に処理するセンシティブな単語を指定し、単語ごとに異なる処理方法を設定できます。詳細については、「センシティブな単語のフィルタリング」をご参照ください。

以下のパラメーターを、Recognition インスタンスの call または start メソッドにキーワード引数として渡します。

パラメータータイプ必須説明
raw_inputdict

いいえ

会話コンテキストを渡すために使用される入力オブジェクト。コンテキスト強化により、ドメイン固有の用語の認識精度が向上します。使用方法については、「クイックスタート」をご参照ください。

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='qwen-audio-3.1-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

Qwen-Audio-ASR-Message

共通リファレンス

最新のリファレンスは Qwen-Audio-ASR-Message Python SDK をご参照ください。

リクエストパラメーターは、コアリソース(client.audio.asr)の recognize/recognize_file メソッドで設定します:model、format、sample_rate、vocabulary_id は具名パラメーター、その他のパラメーター(language_hints など)は parameters 辞書で渡します。

パラメータータイプ必須説明
modelstr

はい

モデル名。
sample_rateint

はい

サンプリングレート(Hz)。16000 のみをサポートします。

formatstr

はい

オーディオフォーマット。

有効な値:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

重要opus/speex: Ogg カプセル化を使用する必要があります。

wav: PCM エンコーディングを使用する必要があります。

amr: AMR-NB タイプのみをサポートしています。

keep_dialectbool

いいえ

デフォルトは false で、方言を標準中国語に変換します。true に設定すると、方言表現を保持します。 同名のキーワード引数で指定します。

最終結果(sentence_end=true)にのみ適用され、中間結果(sentence_end=false)ではサポートされません。

vad_modelstr

いいえ

VAD モデル。near_meeting_16k(近距離)または far_field_meeting_16k(遠距離、デフォルト)を指定します。 同名のキーワード引数で指定します。

disfluency_removal_enabledbool

いいえ

つなぎ言葉を除去し、出力を整えるかどうか。デフォルトは false。有効にするには true に設定します。 同名のキーワード引数で指定します。

intermediate_result_enabledbool

いいえ

ストリーミング中間結果を返すかどうか。デフォルトは false。中間結果を返すには true に設定します。 同名のキーワード引数で指定します。

vocabulary_idstr

いいえ

事前コンパイル済みのホットワードリストのID。

ホットワードリスト作成 API を呼び出して、この ID を事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。

語彙が既知で比較的安定しており、リクエスト間で同じ単語リストを再利用する必要があるシナリオに適しています。

使用法の詳細については、「事前コンパイル済みホットワード」をご参照ください。

vocabularydict

いいえ

インスタントホットワード。

キーと値のペアとして渡します。キーはホットワードのテキスト (文字列)、値はホットワードの重み (整数) です。事前にホットワードリストを作成する必要はありません。重みの範囲は [1, 5] または 50 に設定します。値が [1, 5] の範囲内である場合、値が大きくなるほどモデルがその単語を出力する可能性が高くなります。値が 50 の場合はスーパーホットワードを指定し、再現率が大幅に向上しますが、スーパーホットワードの数は 50 を超えることはできません。

一時的なセッションレベルのホットワードの最適化に適しています。

事前コンパイル済みのホットワードと一緒に設定した場合、インスタントホットワードのみが有効になります。使用法の詳細については、「インスタントホットワード」をご参照ください。

重要qwen-audio-3.1-asr-flash-message のみがインスタントホットワードをサポートします。

例:

import os
import dashscope

client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# インスタント語彙は parameters を通じて渡します
vocab = {"John Smith": 5, "Jane Doe": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)
language_hintslist[str]

いいえ

認識する音声の言語。デフォルト値はありません。設定しない場合、モデルは自動的に言語を検出します。

最大 4 つの値を設定できます。それ以上設定した場合は、最初の 4 つのみが有効です。

クリックしてサポートされている言語コードを表示

  • 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: スロバキア語

同名のキーワード引数として渡します。

最終結果(sentence_end=true)にのみ適用され、中間結果(sentence_end=false)ではサポートされません。

max_sentence_silenceint

いいえ

VAD の文分割の無音しきい値(ミリ秒)。発話後の無音時間がこの値を超えると、文の終了と判断します。デフォルト:800。有効範囲:[200, 6000]。

heartbeatbool

いいえ

ハートビートパケットを有効にするかどうか。

デフォルト:False。

  • True:無音音声が継続的に送信されている間、サーバーへの接続を維持します。
  • False (デフォルト):無音音声が継続的に送信されていても、接続は一定時間後にタイムアウトして切断されます。

無音オーディオとは、オーディオファイルまたはデータストリーム内で音声信号を含まないコンテンツを指します。 Audacity や Adobe Audition のような音声編集ソフトウェアを使用したり、FFmpeg のようなコマンドラインツールを使用したりするなど、いくつかの方法で無音のオーディオを生成できます。

このフィールドには SDK バージョン 1.23.1 以降が必要です。

speech_noise_thresholdfloat

いいえ

音声とノイズを区別するためのしきい値であり、VAD (音声アクティビティ検出) の感度調整に使用します。

有効な値: [-1.0, 1.0]。

値の説明:

  • 値が -1 に近いほど: ノイズしきい値が低下するため、ノイズが音声として認識されやすくなり、より多くのノイズが文字起こしされる可能性があります。
  • 値が +1 に近いほど: ノイズしきい値が上昇するため、音声がノイズとして誤って判断されやすくなり、一部の音声がフィルタリングされる可能性があります。

これは高度な設定パラメーターです。調整すると認識結果に大きな影響を与える可能性があります。推奨事項:

  • 調整する前に、結果を十分にテストおよび検証してください。
  • 実際の音声環境に基づいて、少しずつ調整してください (0.1 のステップを推奨します)。

以下のパラメーターは、recognize/recognize_file メソッドの input キーワード引数で渡します。

パラメータータイプ必須説明
inputdict

いいえ

会話コンテキストを渡すために使用される入力オブジェクト。コンテキスト強化により、ドメイン固有の用語の認識精度が向上します。使用方法については、「クイックスタート」をご参照ください。

重要コンテキストパラメーターは、qwen-audio-3.1-asr-flash-message モデルでのみサポートされています。

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 1.25.23 で導入されたもので、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='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

Fun-ASR-Realtime

共通リファレンス

最新のリファレンスは Fun-ASR-Realtime Python SDK をご参照ください。

リクエストパラメーターは、コアリソース(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,
)

API リファレンス

共通インターフェイス

文情報 (Sentence)

Sentence クラスのメンバーは次のとおりです:

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

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

Word クラスのメンバーは次のとおりです:

パラメーター型説明
begin_timeint単語の開始時刻 (ms) です。
end_timeint単語の終了時刻 (ms) です。
textstr単語です。
punctuationstr句読点です。

Qwen-Audio-ASR-Streaming

主要なインターフェイス

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

リアルタイム音声認識能力は client.audio.asr リソースにマウントされています:recognize は双方向ストリーミング認識セッション(Recognition)を作成し、recognize_file はローカルファイルを 1 回の呼び出しで認識します。

メンバーメソッドメソッドシグネチャ説明

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]
ローカルファイルに基づく非ストリーミング呼び出しです:音声を自動的にチャンク送信し、タスクを完遂まで駆動して、サーバーイベントを 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)

音声認識を停止します:サーバーに入力が終了したことを通知するだけです。受信スレッドは task-finished イベントまで events() を消費し続ける必要があります。

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 は最後に正常に読み取られたメッセージであり、失敗したタスクのエラーを取得するために使用できます。セッションを閉じた後も引き続き読み取り可能です。
イベント反復(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('Recognized text:', sentence['text'])


# または認識結果フレームのみを反復処理します(RecognitionResult を返し、ハートビートフレームはフィルターされます)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Recognized text:', sentence['text'])
メソッド/イベント反復出力戻り値説明
event["header"]["event"] == "task-started"

task-started イベント

Nonestart() が内部で読み取り、戻り時に last_response に保存されます。events() はこれを再び返しません。
def events(self) -> Iterator[Dict]
event:サーバーの dict イベント反復子サーバーに応答があるたびにイベントを返します。認識結果は payload.output.sentence にあり、ハートビートや空のテキストのイベントが含まれる場合があるため、アプリケーションで必要に応じて無視できます。単一の受信スレッドで消費を維持し、複数の並行リーダーを作成しないでください。
def results(self) -> Iterator[RecognitionResult]
result:認識結果(RecognitionResult)反復子認識結果フレームのみを返します(ハートビートフレームはフィルターされます)。すべての認識結果が返された後に反復が終了します。
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
DashScopeError 例外Noneエラー発生時に送信/受信スレッドでスローされます。try/except で捕捉してください。
event["header"]["event"] == "task-finished"

task-finished イベント

Noneサーバーがすべての認識を完了した後に events() から返され、その時点で反復が終了します。stop() 呼び出し後もこのイベントを読み取り続ける必要があります。

応答

認識結果 (RecognitionResult)

RecognitionResult は、双方向ストリーミング呼び出しにおける 1 回のリアルタイム認識の結果、または非ストリーミング呼び出しの結果を表します。

メンバーメソッドメソッドシグネチャ説明
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
@staticmethod
def is_sentence_end(sentence: Dict[str, Any]) -> bool

指定した文が終了しているかどうかを判断します。このメソッドは、sentence 内の end_time フィールドが None かどうかを確認します。end_time が None でない場合は、文が終了したことを示します。RecognitionResult.is_sentence_end(sentence) として呼び出してください。ここでの sentence は、get_sentence() が返す 1 文の dict であり、Sentence インスタンスのブール値フィールドではありません。

Qwen-Audio-ASR-Message

主要なインターフェイス

コアリソース(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]

ローカルファイルに基づく非ストリーミング呼び出しです:音声を自動的にブロック単位で送信し、タスクを完了まで駆動して、サービス側イベントを 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)

音声認識を停止します:サーバーに入力が完了したことを通知するだけです。受信スレッドは task-finished イベントまで events() を消費し続ける必要があります。

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 は、最後に正常に読み取られた生のメッセージであり、失敗したタスクのエラーを復元するために使用できます。これらはセッションを閉じた後も読み取り可能です。

会話コンテキストの更新

認識タスクの実行中に update_context を呼び出して会話コンテキストを更新します。コンテキストは、後続の音声の認識を支援するために使用されます。このメソッドには DashScope Python SDK 2.0.1 以降が必要です。

def update_context(self, context: dict)
  • 呼び出しタイミング:with コンテキストに入って(start が自動的に呼び出されます)ストリーミング認識を開始した後、stop を呼び出す前。
  • パラメーター:context は辞書で、continue-task イベントの payload.input オブジェクトを渡します(context フィールドを含む)。payload や input の階層を追加でラップしないでください。
  • サポート範囲とパラメーターの制約:continue-task をご参照ください。

以下の例は、起動済みの recognition インスタンスを再利用します。

payload_input = {
    "context": [
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "Hello"}]
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "Hello, I am Qwen. How can I help you?"}]
        }
    ]
}
recognition.update_context(context=payload_input)
イベント反復(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('Recognized text: ', sentence['text'])


# または認識結果フレームのみを反復処理します(RecognitionResult を返し、ハートビートフレームはフィルター済み)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Recognized text: ', sentence['text'])
イベント/反復メソッド産出内容戻り値説明
event["header"]["event"] == "task-started"

task-started イベント

なし

start() 内部で読み取られ、起動の戻り時に last_response に保存されます。events() からは再度産出されません。

def events(self) -> Iterator[Dict]

event:サービス側イベントの dict

反復子

サーバーから応答があった場合にイベントを産出します。認識結果は payload.output.sentence にあり、ハートビートや空テキストのイベントである可能性があるため、アプリケーションで必要に応じて無視できます。単一の受信スレッドで継続的に消費し、並行して複数のリーダーを作成しないでください。

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 でない場合は、文が終了したことを示します。

Fun-ASR-Realtime

主要なインターフェイス

コアリソース(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 でない場合は、文が終了したことを示します。

エラーコード

エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。

問題が解決しない場合は、開発者コミュニティ に参加し、問題を報告して Request ID を提供してください。