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-asrtorch(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プログラムからライブラリとしてインポートして利用することを前提として設計されています。