概要
Voxtral Mini 4B Realtime は、Rust製の ストリーミング音声認識モデル であり、 ネイティブ実行とブラウザ実行 の両方に対応。 Burn MLフレームワーク を利用し、 MistralのVoxtral Mini 4B Realtime を完全Rustで実装。 Q4 GGUF量子化モデル（2.5GB） は、 WASM+WebGPU 経由でブラウザタブ内で全てクライアントサイド実行可能。 CLIやブラウザデモ で簡単に試用可能。 モデルの構造や制約、ビルド方法、テスト方法 も詳細に説明。
Voxtral Mini 4B Realtime 概要
- Rust製ストリーミング音声認識モデル、MistralのVoxtral Mini 4B Realtime実装
- Burn MLフレームワーク による構築
- Q4 GGUF量子化モデル（2.5GB） がWASM+WebGPUでブラウザ実行対応
- ネイティブ（f32）とQ4 GGUF の2つの推論パス
- f32（約9GB）はSafeTensors形式、Q4 GGUFは2.5GB
- CLI・ブラウザデモ、HuggingFace Spacesでのホストデモ提供
クイックスタート（CLI）
- モデル重み（約9GB） のダウンロード
uv run --with huggingface_hub \ hf download mistralai/Voxtral-Mini-4B-Realtime-2602 --local-dir models/voxtral
- 音声ファイルの書き起こし（f32 SafeTensors）
cargo run --release --features "wgpu,cli,hub" --bin voxtral-transcribe -- \ --audio audio.wav --model models/voxtral
- Q4量子化パス（2.5GB） の利用
cargo run --release --features "wgpu,cli,hub" --bin voxtral-transcribe -- \ --audio audio.wav --gguf models/voxtral-q4.gguf --tokenizer models/voxtral/tekken.json
ブラウザデモ
- WASMパッケージのビルド
wasm-pack build --target web --no-default-features --features wasm
- 自己署名証明書の生成（WebGPUはセキュアコンテキスト必須）
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -keyout /tmp/voxtral-key.pem -out /tmp/voxtral-cert.pem -days 7 -nodes -subj "/CN=localhost"
- 開発サーバー起動
bun serve.mjs
- https://localhost:8443 を開き、証明書を承認し、「Load from Server」でモデルシャードをダウンロード
- マイク録音またはWAVファイルアップロード による書き起こし
- HuggingFace Spaces でのホストデモも選択可能
アーキテクチャ
- 入力 ：16kHz モノラル音声
- 前処理 ：Melスペクトログラム [B,128,T]
- エンコーダ ：32層、1280次元、スライディングウィンドウ750
- 畳み込み4倍ダウンサンプル
- リシェイプ ：[B, T/16, 5120]
- アダプタ ：[B, T/16, 3072]
- デコーダ ：自己回帰型、26層、3072次元、GQA 32Q/8KV
- 出力 ：トークンID → テキスト
推論パス
- F32（ネイティブ）
- SafeTensors（約9GB）
- Q4 GGUF（ネイティブ＋ブラウザ）
- GGUF Q4_0（約2.5GB）
線形演算・埋め込み
- 線形演算 ：Burnテンソルmatmul、カスタムWGSLシェーダ（融合dequant+matmul）
- 埋め込み ：f32テンソル（1.5GiB）、Q4はGPU上216MB＋CPU側ルックアップ
ブラウザ対応
- F32 ：非対応
- Q4 GGUF ：WASM+WebGPUで対応
Q4パディング問題とワークアラウンド
- mistral-common は音声先頭に32トークン分の無音パディング（12.5Hz）を付与
- mel/conv/reshape後、38デコーダープリフィックス中16のみが無音、残り22は実音声
- Q4_0量子化モデル はプリフィックスに音声があると全パッドトークン出力の不具合
- パディングを76トークンに増加 し、38トークン全て無音でカバー
- 詳細 はsrc/audio/pad.rs参照
WASM制約と解決策
- 2GBアロケーション制限 ：ShardedCursorで複数Vec<u8>バッファを跨いで読み込み
- 4GBアドレス空間制限 ：2段階ロード（重みパース→リーダ破棄→最終化）
- 1.5GiB埋め込みテーブル ：Q4埋め込みはGPU＋CPU側ルックアップ
- 同期GPUリードバック不可 ：全テンソル読み出しはinto_data_async().await利用
- 256ワークグループ制限 ：cubecl-wgpuをパッチ適用しカーネルワークグループ数を上限設定
ビルド方法
- ネイティブ（wgpu＋native-tokenizerがデフォルト）
cargo build --release
- 全機能有効
cargo build --release --features "wgpu,cli,hub"
- WASM
wasm-pack build --target web --no-default-features --features wasm
フィーチャーフラグ一覧
- wgpu ：Burn/CubeCL経由のGPUバックエンド（WebGPU, Vulkan, Metal）
- native-tokenizer ：Tekkenトークナイザ（C依存、WASM非対応）
- wasm ：ブラウザ用（wasm-bindgen、WebGPUデバイス初期化、JSバインディング）
- cli ：clap＋indicatifによるCLIバイナリ
- hub ：HuggingFace Hubからのモデルダウンロード
テスト・Lint
- ユニット＋統合テスト（GPU必須）
cargo test --features "wgpu,cli,hub"
- Lint
cargo clippy --features "wgpu,cli,hub" -- -D warningscargo clippy --no-default-features --features wasm --target wasm32-unknown-unknown -- -D warnings
- E2Eブラウザテスト（Playwright＋モデルシャード必須）
bunx playwright test tests/e2e_browser.spec.ts
- GPU依存テスト はCIではスキップ、ローカルGPU環境で実行
モデル準備（Q4 GGUFシャーディング）
- GGUFファイルを512MB以下に分割 （ブラウザのArrayBuffer制限回避）
split -b 512m models/voxtral-q4.gguf models/voxtral-q4-shards/shard-
- 開発サーバーとE2Eテスト は自動でシャードを検出
ベンチマーク
- 精度（WER）・推論速度ベンチマーク は近日公開予定
プロジェクト構成
- src/audio/ ：Melスペクトログラム、チャンク化、リサンプリング、パディング
- src/models/ ：f32モデル（エンコーダ、デコーダ、アダプタ、アテンション、RoPE、KVキャッシュ）
- src/gguf/ ：Q4 GGUF（リーダ、ローダ、モデル、テンソル、WGSLシェーダ、テスト）
- src/web/ ：WASMバインディング（VoxtralQ4、initWgpuDevice、非同期デコードループ）
- src/tokenizer/ ：Tekkenトークナイザラッパー（ネイティブのみ）
- bin/transcribe ：CLIバイナリ
- web/ ：ブラウザデモ（index.html、worker.js、voxtral-client.js）
- tests/ ：統合テスト＋Playwright E2Eスペック
- scripts/ ：開発用スクリプト（リファレンス実装、重み検証、E2Eヘルパー）
- patches/ ：WebGPU用cubecl-wgpuワークグループサイズ修正パッチ
ライセンス
- Apache-2.0