Macでuvとvenvを使いQwen TTSの実行環境を構築する

macOS (Apple Silicon推奨) にて、高速なPythonパッケージマネージャーであるuvを使い、Qwenシリーズの音声モデル（TTS）の実行環境を構築する手順を解説します。

前提条件

macOS (Apple Silicon M1/M2/M3/M4 推奨)
Homebrew がインストールされていること

ステップ 1: uv のインストール

まだuvをインストールしていない場合は、以下のコマンドでインストールします。

# 公式のインストールスクリプト
curl -LsSf https://astral.sh/uv/install.sh | sh

インストール後、シェルを再起動するか source $HOME/.cargo/env を実行してパスを通してください。

ステップ 2: プロジェクトとvenvの作成

uvのプロジェクト機能 (uv init) を使うと、ディレクトリ作成と仮想環境（venv）の管理が非常に楽になります。

# 1. プロジェクトディレクトリの作成と移動
mkdir qwen-tts-project
cd qwen-tts-project

# 2. uvプロジェクトの初期化 (Python 3.11を推奨)
# ML系は3.10-3.11が最も安定しています
uv init --python 3.11

# 3. 仮想環境(.venv)の作成
uv venv

これでカレントディレクトリに.venvが作成され、プロジェクト設定用のpyproject.tomlが生成されます。

Qwen3-TTS 環境構築 (Web UI)

次に、PyPIパッケージとして公開されているqwen-ttsを利用して、Web UIデモを起動する手順です。

手順 1: システムライブラリのインストール

音声処理のため、ffmpegに加えてsoxもインストールします。

brew install ffmpeg sox

手順 2: uvプロジェクトの作成 (Python 3.12)

新しいプロジェクトディレクトリを作成し、Python 3.12で初期化します。

# プロジェクト用ディレクトリを作成して移動
mkdir qwen3-tts-local
cd qwen3-tts-local

# uvプロジェクトの初期化 (Python 3.12を指定)
uv init --python 3.12

# 仮想環境を作成
uv venv

手順 3: 依存パッケージのインストール

qwen-ttsパッケージとPyTorch関連をインストールします。

uv add torch torchvision torchaudio qwen-tts

手順 4: Web UIデモの起動

qwen-tts-demoコマンドを使ってWeb UIを起動します。MacでGPU (MPS) を利用するには--device mpsと、Flash Attentionを無効化する--no-flash-attnオプションが重要です。

uv run qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base \
    --ip 127.0.0.1 \
    --port 8000 \
    --device mps \
    --no-flash-attn

初回起動時: モデル（約4GB）が自動でダウンロードされます。
モデルの種類:
- Base (ボイスクローン向け): Qwen/Qwen3-TTS-12Hz-1.7B-Base
- 声質デザイン向け: Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign
- プリセット話者: Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice

手順 5: ブラウザでアクセス

ターミナルにRunning on local URL: http://127.0.0.1:8000と表示されたら、そのURLをブラウザで開きます。

モデルの保存場所について

Hugging Face経由でダウンロードされたモデルは、デフォルトでは以下のパスに保存されます。

/Users/あなたのユーザー名/.cache/huggingface/hub

Finderの「フォルダへ移動」（Cmd+Shift+G）で~/.cache/huggingface/hubと入力すると確認できます。

保存場所の変更

ストレージ容量を節約したい場合など、保存場所を変更するには環境変数HF_HOMEを指定します。

# 例: 外付けSSDに保存する場合
export HF_HOME="/Volumes/MyExternalSSD/AI_Models"

# 環境変数を指定して実行
uv run qwen-tts-demo ...

これで、指定したフォルダにモデルがダウンロード・参照されるようになります。

まとめ

uvを使うことで、Pythonのバージョン管理からパッケージインストールまでをスムーズに行い、Mac上でQwen TTSの環境をクリーンに構築できました。特に、Web UIデモはオプションを指定するだけで簡単に試せるので、ぜひ挑戦してみてください。

参考資料

note - Hugging Face Spacesで動作するQwen3-TTSを使ってみた（ボイスクローンもできる）