概要

qwen_asr_flask.py は、Flaskフレームワークを用いたOpenAI API互換の音声認識（ASR）サーバープログラムです。 Qwen3-ASRモデルを使用し、受信した音声ファイルの文字起こしを行います。 推論処理はリクエストごとに別プロセスとして実行されます。また、GPUリソースの競合を防ぐため、スレッドロックを用いて同時に実行される推論プロセスを1つに制限する設計となっています。

動作環境

  • Python 3.x

  • Flask実行環境

  • 推論用の別プロセスとして、設定されたパス（デフォルトでは同一ディレクトリの qwen_asr_once.py）にランナースクリプトが存在すること

依存ライブラリ

標準ライブラリ:

  • json

  • os

  • subprocess

  • sys

  • tempfile

  • threading

  • pathlib

非標準ライブラリ:

  • flask (Flask, jsonify, request)

処理概要・アルゴリズム

本プログラムは、主に以下の動作を行います。

  1. 環境変数の読み込み 起動時に以下の環境変数を読み込みます。設定されていない場合はデフォルト値が使用されます。

    • QWEN_ASR_MODEL: 使用するモデル名（デフォルト: Qwen/Qwen3-ASR-1.7B）

    • QWEN_ASR_RUNNER: 推論を実行するスクリプトのパス（デフォルト: 同一ディレクトリの qwen_asr_once.py）

    • QWEN_ASR_UPLOAD_DIR: 一時ファイルの保存ディレクトリ（デフォルト: /var/tmp/qwen-asr-upload）

    • QWEN_ASR_TIMEOUT_SECONDS: 推論処理のタイムアウト時間（デフォルト: 3600 秒）

  2. Webサーバーの構築 Flaskを用いてWebサーバーを構築し、以下のエンドポイントを提供します。最大アップロードサイズ制限は1GiBに設定されています。

    • GET /health: サーバーの生存確認用エンドポイントです。

    • GET /v1/models: 利用可能なモデルの情報をOpenAI API互換のJSON形式で返却します。

    • POST /v1/audio/transcriptions: 音声認識を実行するエンドポイントです。

  3. 音声認識リクエストの処理

    • 送信された音声ファイルを QWEN_ASR_UPLOAD_DIR に一時ファイルとして保存します。

    • GPUなどのリソース制約を考慮し、threading.Lock を用いて推論処理が同時に複数実行されないように排他制御を行います。他のリクエストはHTTP通信のまま待機状態になります。

    • subprocess.run を用いて別プロセスでランナースクリプトを起動します。この際、引数として --audio に一時ファイルのパス、 --model にモデル名を渡します。

    • サブプロセスの標準出力の最終行をJSONとしてパースし、認識結果のテキストと検出言語を取得します。

    • 処理完了後、またはタイムアウトなどのエラー発生後、一時ファイルを安全に削除します。

入出力仕様

入力

APIエンドポイント POST /v1/audio/transcriptions に対する multipart/form-data 形式のHTTPリクエストを受け付けます。

  • file: 音声ファイル本体（必須）

  • model: 使用するモデル名（任意。ただし指定する場合は環境変数 QWEN_ASR_MODEL の値と完全に一致している必要があります）

出力

推論が成功した場合は、以下のキーを持つJSONを返却します（HTTPステータスコード200）。

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

  • language: 検出された言語（ランナースクリプトから提供された場合）

エラー発生時は、以下のJSONを該当するHTTPステータスコード（400、500、504など）とともに返却します。

  • error: エラー内容を含むオブジェクト

    • message: エラーの詳細メッセージ（引数不足、モデル名不一致、サブプロセス実行エラー、タイムアウトなど）

実行例

サーバーを起動するコマンドの例です。デフォルトではすべてのインターフェースの 8001 ポートでリッスンします。

python3 qwen_asr_flask.py

環境変数を指定して起動する例です。

export QWEN_ASR_MODEL="Qwen/Qwen3-ASR-1.7B"
export QWEN_ASR_UPLOAD_DIR="/tmp/qwen_uploads"
python3 qwen_asr_flask.py

起動したサーバーに対して音声認識リクエストを送信する例です。

curl -X POST http://localhost:8001/v1/audio/transcriptions \
  -F "file=@sample_audio.wav" \
  -F "model=Qwen/Qwen3-ASR-1.7B"

モデル一覧を取得するリクエストの例です。

curl http://localhost:8001/v1/models