tkasr_qwen_local.py Documentation

ライブラリの機能や目的

tkasr_qwen_local.py は、Qwen3-ASR モデルをローカル環境で利用するためのバックエンドライブラリです。このライブラリは、オーディオファイルからの自動音声認識(ASR)機能を提供し、特にQwen3-ASRのローカルデプロイメントを容易にします。主な目的は、外部APIに依存せず、ユーザー自身のハードウェア上で高度なASR処理を実行できるようにすることです。

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

  • Qwen3-ASRモデルのロード: 指定されたモデル(0.6B、1.7Bなど)をローカル環境にロードします。

  • デバイスとデータタイプの自動検出/設定: GPU (CUDA) または CPU を自動的に判別し、bfloat16, float16, float32 などのデータタイプを最適に選択または設定します。

  • 音声ファイルのテキスト変換: 与えられたオーディオファイルからテキストを生成します。

  • タイムスタンプ付きセグメンテーション: 音声認識結果に加えて、各単語やフレーズの開始・終了時刻情報(タイムスタンプ)を含むセグメントを提供できます。

  • エラーハンドリング: 必要な依存関係(qwen-asr, PyTorch)が不足している場合や、デバイス設定が不正な場合に適切なエラーを報告します。

このライブラリは、TkASR共通インターフェースの一部として機能し、ユーザーが複数のASRバックエンドをシームレスに切り替えることを可能にするエコシステムの中で、Qwen3-ASRのローカル実行オプションを提供することで、オフライン処理やプライバシーが重要なアプリケーションにおける課題を解決します。

importする方法

このライブラリから機能を利用するには、通常、以下のように Backend クラスをインポートします。

from tkasr_qwen_local import Backend

また、定義されている変数もインポートできます。

from tkasr_qwen_local import BACKEND_NAME, MODELS

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

tkasr_qwen_local.py を利用するには、以下の非標準ライブラリが必要です。

  • qwen-asr

  • torch (PyTorch)

これらのライブラリは pip コマンドを使用してインストールできます。

pip install qwen-asr torch

GPUサポートが必要な場合は、PyTorchの公式ドキュメントを参照し、お使いのCUDAバージョンに合わせたインストールコマンドを実行してください(例:pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118)。

importできる変数と関数

変数

  • BACKEND_NAME:

    • 説明: このバックエンドの名前を示す文字列です。

    • 値: "qwen-local"

  • MODELS:

    • 説明: Qwen3-ASRモデルの短縮名と、それに対応するHugging FaceモデルリポジトリIDをマッピングする辞書です。

    • 値:

      {"0.6B": "Qwen/Qwen3-ASR-0.6B", "1.7B": "Qwen/Qwen3-ASR-1.7B"}
      

クラス

  • class Backend:

    • 説明: Qwen3-ASRモデルのローカルバックエンドを管理するためのクラスです。モデルのロード、設定、および音声認識処理を行います。

Backend クラスのメソッド

  • __init__(self, args)

    • 動作: Backend ククラスの新しいインスタンスを初期化します。モデルはここではロードされず、load() メソッドが呼び出されたときにロードされます。

    • 引数:

      • args: モデルのロードと推論に関する設定を含むオブジェクト(通常は argparse.Namespace のようなもの)。

        • 主なプロパティ: device, dtype, model, max_inference_batch_size, max_new_tokens, timestamps, aligner, attention など。

    • 戻り値: なし

  • load(self)

    • 動作: Qwen3-ASRモデルとその必要な依存関係(torch および qwen_asr)をロードします。設定されたデバイス(GPUまたはCPU)とデータタイプ(bfloat16, float16, float32)に基づいてモデルを準備します。CUDAが指定されたが利用できない場合や、未対応のデータタイプが指定された場合にエラーを発生させます。

    • 引数: なし

    • 戻り値: なし

    • 例外:

      • OptionalDependencyError: qwen-asr または PyTorch がインストールされていない場合。

      • RuntimeError: CUDAが指定されたが利用できない場合、または未対応の --dtype が指定された場合。

  • describe(self)

    • 動作: 現在ロードされているバックエンドの設定に関する詳細な情報を辞書形式で返します。

    • 引数: なし

    • 戻り値:

      • dict: 以下のキーを持つ辞書。

        • "backend" (str): バックエンドの名前(例: "qwen-local")。

        • "model" (str): ロードされたモデルのHugging FaceリポジトリID。

        • "device" (str): モデルがロードされているデバイス(例: "cuda:0", "cpu")。

        • "dtype" (str): モデルが使用しているデータタイプ(例: "bfloat16", "float32")。

        • "timestamps" (bool): タイムスタンプの生成が有効かどうか。

  • transcribe(self, audio: Path, language: Optional[str], prompt: str) -> ASRResult

    • 動作: 指定されたオーディオファイルをQwen3-ASRモデルを使用してテキストに変換(転写)します。ASRResult オブジェクトとして、完全なテキスト、セグメント化されたテキストとタイムスタンプ(有効な場合)、および検出された言語を返します。

    • 引数:

      • audio: Path オブジェクト。転写するオーディオファイルへのパス。

      • language: Optional[str]。オーディオの言語を示す文字列(例: "ja", "en")。指定しない場合はモデルが自動検出を試みます。

      • prompt: str。音声認識のガイダンスとしてモデルに提供される初期プロンプト。

    • 戻り値:

      • ASRResult: 転写結果を含むオブジェクト。

        • ASRResult.text: 全体の転写テキスト。

        • ASRResult.segments: Segment オブジェクトのリスト。各 Segment は start (開始時刻), end (終了時刻), text (セグメントのテキスト) を持ちます。

        • ASRResult.language: 検出された(または指定された)言語。

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

tkasr_qwen_local.py は、if __name__ == "__main__": ブロックを含んでいません。そのため、このスクリプトは単独で実行されることを意図しておらず、直接実行しても特別な動作はしません。他のPythonプログラムからライブラリとしてインポートして利用することを前提として設計されています。