tkasr_qwen_api.py Documentation

ライブラリの機能や目的

tkasr_qwen_api.py は、Qwen3-ASRモデルを対象としたOpenAI互換の音声認識(ASR)APIバックエンドを提供するPythonライブラリです。このライブラリの主な目的は、tkasrプロジェクト内でQwen3-ASRのAPIを利用して音声ファイルをテキストに変換する機能を提供することです。

主な機能は以下の通りです。

  • Qwen3-ASR APIエンドポイントへのHTTP POSTリクエストを構築し、音声ファイルをアップロードします。

  • 指定された言語やプロンプト(指示テキスト)をAPIリクエストに含めることができます。

  • APIからの応答を処理し、認識されたテキストと関連するメタデータを返します。

  • ネットワークエラーやAPI応答形式の不正に対する堅牢なエラーハンドリングを提供します。

このライブラリは、外部のHTTPリクエストライブラリ(例: requests)に依存せず、Pythonの標準ライブラリ(urllib.requestなど)のみを使用してAPIとの通信を行います。

importする方法

このライブラリは、tkasrプロジェクトのバックエンドとして設計されており、Backendクラスをインポートして使用します。

from tkasr_qwen_api import Backend
# Backend クラスのインスタンスを作成し、音声認識処理を実行
# my_backend = Backend(args)

必要な非標準ライブラリとインストール方法

このライブラリは、内部でPythonの標準ライブラリのみを使用してHTTP通信を行いますが、tkasr_commonという非標準ライブラリ(モジュール)に依存しています。

  • tkasr_common: ASRResult データ構造を定義しています。これはおそらくtkasrプロジェクトの一部であり、このライブラリが動作するためには、tkasr_commonモジュールがPythonの検索パスに存在している必要があります。

一般的なpipコマンドでのインストール方法は想定されていませんが、もし利用可能な場合は以下のようになります。

pip install tkasr_common # (もしPyPIなどで公開されている場合)

通常は、tkasrプロジェクト全体をクローンまたはインストールする際に、この依存関係も満たされることを想定しています。

importできる変数と関数

変数

  • BACKEND_NAME: このバックエンドの名前を定義する文字列定数です。 値: "qwen-api"

    print(BACKEND_NAME) # 出力: qwen-api
    

クラス

Backend クラス

Qwen3-ASR APIとのインタラクションを管理するクラスです。

コンストラクタ: __init__(self, args)

  • 説明: Backend クラスの新しいインスタンスを初期化します。

  • 引数:

    • self: インスタンス自身。

    • args: API接続設定を含むオブジェクト。通常、以下の属性を持つことが期待されます。

      • api_base: Qwen3-ASR APIのエンドポイントURL (例: http://localhost:8000).

      • model: 使用するASRモデル名 (例: "qwen-turbo").

      • timeout: APIリクエストのタイムアウト時間(秒)。

メソッド:

  • load(self)

    • 説明: バックエンドのロード処理を実行します。現在の実装では何もしません。将来的な拡張のためのプレースホルダーです。

    • 引数: self (インスタンス自身)。

    • 戻り値: なし。

  • describe(self)

    • 説明: このバックエンドに関する情報を辞書形式で返します。

    • 引数: self (インスタンス自身)。

    • 戻り値: dict

      • backend: バックエンドの名前 (BACKEND_NAME)。

      • api_base: __init__で設定されたAPIベースURL。

      • model: __init__で設定されたモデル名。

    # 例:
    # my_backend = Backend(args_object)
    # info = my_backend.describe()
    # print(info) # 例: {'backend': 'qwen-api', 'api_base': 'http://localhost:8000', 'model': 'qwen-turbo'}
    
  • transcribe(self, audio: Path, language: Optional[str], prompt: str) -> ASRResult

    • 説明: 指定された音声ファイルをQwen3-ASR APIに送信し、テキストに書き起こします。

    • 引数:

      • self: インスタンス自身。

      • audio: 転写する音声ファイルへの pathlib.Path オブジェクト。

      • language: 音声の言語コード(例: "ja"、"en")。None の場合、API側で自動検出されます。

      • prompt: ASRモデルに与える初期プロンプト(指示テキスト)。これにより、特定の語彙やスタイルでの認識精度を高めることができます。空文字列または空白のみの場合、無視されます。

    • 戻り値: ASRResult

      • text: 認識されたテキスト。

      • language: (オプション) APIによって検出または指定された言語。

      • metadata: API応答全体を含む追加情報。キー api_response に生のAPIペイロードが含まれます。

    • 例外:

      • RuntimeError: APIへの接続エラー、HTTPエラー、またはAPIからの応答形式が不正な場合に発生します。

    from pathlib import Path
    # args_object は api_base, model, timeout を持つオブジェクトを想定
    # from types import SimpleNamespace
    # args_object = SimpleNamespace(api_base="http://localhost:8000", model="qwen-turbo", timeout=60)
    
    # backend = Backend(args_object)
    # audio_file = Path("path/to/your/audio.wav")
    # try:
    #     result = backend.transcribe(audio_file, language="ja", prompt="これは音声認識のテストです。")
    #     print(f"認識結果: {result.text}")
    #     print(f"検出言語: {result.language}")
    # except RuntimeError as e:
    #     print(f"エラー: {e}")
    

main scriptとして実行したときの動作

tkasr_qwen_api.py には if __name__ == "__main__": ブロックが実装されていないため、このファイルを直接Pythonスクリプトとして実行しても、特定の動作は何も行われません。このファイルは、他のPythonプログラムからモジュールとしてインポートされ、その中の Backend クラスが利用されることを前提として設計されています。