suzuna / state suzuna setup wizard

STATE_Suzuna_Setup_Wizard.md

概要

Suzunaの初回起動時に自動で Python 環境を構築するセットアップウィザード。
python-build-standalone でPython 3.10を同梱し、初回のみ依存関係をpip installで自動インストールする。
GPU（CUDA）の有無を自動検出して、PyTorchのインストール内容を切り替える。

方針

項目内容
Python同梱python-build-standalone (3.10.x, Windows x86_64)
同梱先src-tauri/resources/python/
venv作成先{app_data_dir}/Suzuna/venv/ （%APPDATA%\Suzuna\venv\）
GPU検出Rustから nvidia-smi を実行して有無を判定
pip install初回起動時にRustの Command でバックグラウンド実行
セットアップ完了フラグ{app_data_dir}/Suzuna/setup_done.json に記録
2回目以降フラグを見てスキップ、即起動

フロー

アプリ起動
  ↓
setup_done.json を確認
  ├── 存在する → 通常起動（Python serverをそのまま起動）
  └── 存在しない → セットアップウィザード画面へ
        ↓
        Step 1: nvidia-smi でGPU検出
          ├── GPU あり → CUDA用PyTorchをインストール
          └── GPU なし → CPU版PyTorchをインストール
        ↓
        Step 2: venv作成（同梱Pythonで）
        ↓
        Step 3: pip install（進捗をフロントに通知）
        ↓
        Step 4: setup_done.json を書き込み
        ↓
        通常起動

Rustの実装タスク（src-tauri/src/lib.rs）

追加するTauriコマンド

// GPU検出
#[tauri::command]
async fn detect_gpu() -> bool

// セットアップ済みか確認
#[tauri::command]
async fn is_setup_done(app: tauri::AppHandle) -> bool

// セットアップ実行（進捗をフロントにemit）
#[tauri::command]
async fn run_setup(app: tauri::AppHandle, window: tauri::Window)

detect_gpu の実装方針

async fn detect_gpu() -> bool {
    // nvidia-smiをwhereで探してから実行
    // 成功（exit code 0）ならtrue
    // 失敗 or 見つからないならfalse
    Command::new("nvidia-smi")
        .output()
        .map(|o| o.status.success())
        .unwrap_or(false)
}

run_setup の実装方針

進捗はTauriのeventでフロントに送る。

// emit するイベント
window.emit("setup_progress", SetupProgress {
    step: "venv",          // "venv" | "pip_torch" | "pip_rvc" | "pip_other" | "done" | "error"
    message: "仮想環境を作成中...",
    percent: 10,           // 0-100
}).unwrap();

ステップ別コマンド

Step 1: venv作成

{resources}/python/python.exe -m venv {app_data}/Suzuna/venv

Step 2: pip upgrade

{app_data}/Suzuna/venv/Scripts/pip.exe install --upgrade pip

Step 3a: PyTorch（GPU検出時）

{app_data}/Suzuna/venv/Scripts/pip.exe install
  torch==2.4.1 torchaudio==2.4.1
  --index-url https://download.pytorch.org/whl/cu118

Step 3b: PyTorch（CPU時）

{app_data}/Suzuna/venv/Scripts/pip.exe install
  torch==2.4.1 torchaudio==2.4.1

Step 4: FastAPI他

{app_data}/Suzuna/venv/Scripts/pip.exe install
  fastapi "uvicorn[standard]" pydantic httpx librosa soundfile scipy numpy av

Step 5: rvc-python

{app_data}/Suzuna/venv/Scripts/pip.exe install rvc-python

⚠ rvc-pythonはnumpy<=1.23.5をピン留めするため、必ずfastapi等の後にインストールする

Python server起動の変更点

既存の .venv 優先ロジックを以下の優先順位に変更：

1. {app_data}/Suzuna/venv/Scripts/python.exe  ← 新規追加（最優先）
2. {app_dir}/.venv/Scripts/python.exe         ← 既存（開発用フォールバック）
3. システムpython                              ← 最終フォールバック

フロントの実装タスク（React/TypeScript）

新規ファイル: src/pages/SetupPage.tsx

セットアップウィザード画面。App.tsxで is_setup_done をチェックして、未完了なら最初に表示する。

UI構成

┌─────────────────────────────────────┐
│  Suzuna セットアップ                 │
│                                     │
│  初回のみ、依存関係をインストール    │
│  します（3〜8分）                   │
│                                     │
│  [GPU検出中...]                     │
│  ✅ NVIDIA GPU を検出しました        │
│     → CUDA版PyTorchをインストール   │
│                                     │
│  ████████████░░░░░░  60%            │
│  rvc-python をインストール中...     │
│                                     │
│  ※ この画面は初回のみ表示されます  │
└─────────────────────────────────────┘

状態管理

type SetupStep =
  | "idle"
  | "detecting_gpu"
  | "venv"
  | "pip_torch"
  | "pip_rvc"
  | "pip_other"
  | "done"
  | "error";

interface SetupProgress {
  step: SetupStep;
  message: string;
  percent: number;
}

Tauriイベントのリッスン

import { listen } from "@tauri-apps/api/event";
import { invoke } from "@tauri-apps/api/core";

// セットアップ進捗を受け取る
const unlisten = await listen<SetupProgress>("setup_progress", (event) => {
  setProgress(event.payload);
});

// セットアップ開始
await invoke("run_setup");

App.tsx の変更点

// 起動時にセットアップ済みか確認
const [setupDone, setSetupDone] = useState<boolean | null>(null);

useEffect(() => {
  invoke<boolean>("is_setup_done").then(setSetupDone);
}, []);

if (setupDone === null) return <SplashScreen />;
if (!setupDone) return <SetupPage onComplete={() => setSetupDone(true)} />;
return <MainApp />;

同梱Python（python-build-standalone）の取得

ダウンロード先

https://github.com/indygreg/python-build-standalone/releases

使用するビルド

cpython-3.10.x+xxxxxxxx-x86_64-pc-windows-msvc-install_only.tar.gz

install_only ビルドを使う（最小構成）。

配置

src-tauri/resources/python/
├── python.exe
├── python310.dll
├── Lib/
└── ...（展開したファイルすべて）

tauri.conf.json への追記

"bundle": {
  "resources": {
    "resources/python/**/*": "python/"
  }
}

setup_done.json のフォーマット

{
  "version": "1.0.0",
  "gpu": true,
  "torch": "cu118",
  "installed_at": "2025-05-09T12:00:00Z"
}

バージョンが変わったら再セットアップを促す仕組みを将来的に追加できる。

エラーハンドリング方針

エラー対応
pip install失敗エラーメッセージ + ログ表示 + 「再試行」ボタン
ネットワーク未接続「インターネット接続を確認してください」
ディスク空き不足「空き容量が不足しています（5GB以上必要）」

エラー発生時は setup_done.json を書き込まないことで、次回起動時に再チャレンジできる。

実装の優先順位

  1. detect_gpu() コマンド追加（Rust）
  2. is_setup_done() コマンド追加（Rust）
  3. run_setup() コマンド追加（Rust） + progressイベントemit
  4. Python server起動ロジックをvenv優先に変更（Rust）
  5. SetupPage.tsx 作成（React）
  6. App.tsx にセットアップチェック追加（React）
  7. python-build-standaloneをresourcesに配置 + tauri.conf.json更新

注意事項

  • resources/python/ はgit管理外にする（.gitignoreに追加）
  • CIビルド時はpython-build-standaloneの取得をビルドスクリプトに組み込む
  • rvc-python はnumpy<=1.23.5をピン留めするため、インストール順は必ず最後
  • praat-parselmouth はGPLv3+のため依存しないよう注意（既存のREADMEにも記載あり）