mattmireles/gemma-tuner-multimodal

Fine-tune Gemma 4 and 3n with audio, images and text on Apple Silicon, using PyTorch and Metal Performance Shaders.

Gemma マルチモーダル微調整ツール（macOS専用）

何ができるか – Apple Silicon（MPS）でネイティブに動作する Python パッケージで、Google の Gemma 言語モデル（3n および 4 シリーズ）を LoRA アダプター で テキスト、画像、音声データ に対して微調整可能。NVIDIA GPU は不要。CLI ウィザード、リアルタイム Web ビジュアライザー、Google Cloud Storage や BigQuery からの大規模データストリーミングを内蔵。Core ML または GGUF 推論用にマージされたチェックポイントをエクスポート可能。

コア機能（README に記載）

機能 詳細
モダリティ対応 • テキストのみ（インストラクションまたは完了）
• 画像＋テキスト（キャプション生成または VQA）
• 音声＋テキスト（ASR 形式）
ハードウェア PyTorch MPS で Apple Silicon でネイティブ実行。NVIDIA GPU がある場合は CUDA サポートもオプション。
データインジェスト 学習／検証用 CSV ファイルが唯一の必須形式。CSV 行はローカルファイル、HTTP URL、GCS パス、BigQuery テーブルを参照可能。prepare コマンドはデータをストリーミングするため、テラバイト単位のデータをローカルにコピーする必要なし。
トレーニング UI profile で visualize = true を設定すると、ブラウザベースのビジュアライザー（損失曲線、アテンションヒートマップ、勾配信号、メモリ使用量、トークン予測）が自動起動。
モデル対象 Hugging Face から入手可能な Gemma‑3n（2B および 4B）および Gemma‑4（2B および 4B）のチェックポイント。LoRA アダプターは SafeTensors/HF ツリーにマージされてエクスポート可能。
エクスポート gemma-macos-tuner export で Core ML 変換または GGUF 推論用に準備されたマージ済みモデルが生成。
CLI ウィザード gemma-macos-tuner wizard で設定をガイド付きで作成。設定ファイルの生成、モデル選択、データセットプロファイルの選定、ワンクリックでトレーニングの開始。
ストリーミングと大規模データ prepare は GCS/BigQuery からの音声シャーディングをストリーミング可能。同じパイプラインは画像／音声モダリティにも適用され、SSD を満たさずに TB 級のコーパスでトレーニング可能。
パッケージ構造 • gemma_tuner/cli_typer.py – エントリーポイント CLI（gemma-macos-tuner）。
• gemma_tuner/scripts/finetune.py – Gemma 固有のトレーナーにディスパッチ。
• gemma_tuner/models/gemma/finetune.py – PEFT LoRA 微調整ロジック。
• gemma_tuner/wizard/ – Rich/Questionary UI を使用したウィザード。

一般的な利用例（README から）

  • ドメイン特化音声認識 – Gemma＋音声 LoRA を医療記録、法廷記録、コールセンター録音などに適応。
  • 特殊な視覚タスク – 請求書、チャート、製造欠陥、医療画像などに対してキャプション生成や VQA 用に微調整。
  • ドキュメントおよび UI 理解 – スクリーンショット → 構造化出力ペアで、オンデバイスアシスタント用にトレーニング。
  • リソースが少ない言語やアクセントの適応 – 代表されていない方言の音声認識や翻訳を改善。
  • プライベートオンデバイスパイプライン – すべてのトレーニングと推論は Mac 上で完結。データは機械外に流出しない。

セットアップ手順（README から要約）

  1. arm64 ネイティブ Python 3.10+ venv を作成（Homebrew の python@3.12 が利用可能）。
  2. PyTorch をインストール（pip install torch torchaudio）。
  3. パッケージをインストール（pip install -e .）。
  4. Hugging Face にログイン し、Gemma モデルのライセンスに同意。
  5. （オプション）Gemma‑4 用追加パッケージをインストール（pip install -r requirements/requirements-gemma4.txt）。
  6. ウィザードを実行 – gemma-macos-tuner wizard。config/config.ini を生成し、モデル、データセット、ハイパーパラメータの選択をガイド。
  7. トレーニング – ウィザード経由または直接実行：gemma-macos-tuner finetune <profile>。--json-logging を使用すると機械可読ログが取得可能。
  8. エクスポート – gemma-macos-tuner export <run‑dir-or‑profile> で Core ML または GGUF 用に準備されたマージ済みチェックポイントが生成。

制限事項と既知の問題（ドキュメント参照）

  • 画像・音声ストリーミング – 現在は音声パイプラインのみ GCS/BigQuery ストリーミングをサポート。画像微調整はまだローカル CSV ファイルが必要。
  • Gemma 4 大規模チェックポイント（26B/31B）は、トレーナーの AutoModelForCausalLM 音声パスが異なるアーキテクチャを期待しているため非対応。
  • 音声のみ LoRA は Apple Silicon で動作可能。CUDA 専用パスは「⚠️」マーク付きで、NVIDIA GPU が必要。
  • メモリ – 最低 16GB RAM。4B モデルには 32GB+ を推奨。OOM はバッチサイズの縮小または勾配チェックポイントで緩和可能。
  • MPS の安定性 – トレーナーは eager attention を強制し、bf16 を優先。デバッグ用に CPU フォールバック（PYTORCH_ENABLE_MPS_FALLBACK=1）は可能だが、トレーニングを大幅に遅くする。
  • Gemma 4 用エクスポート – 一部の推論ユーティリティは、コードパスのアップグレードまで Gemma 4 ID を拒否し続ける。

クイックリファレンスチートシート（README から）

# データ準備（CSV → オプションのストリーミング）
 gemma-macos-tuner prepare <dataset‑profile>

# トレーニング
 gemma-macos-tuner finetune <profile> --json-logging

# 評価
 gemma-macos-tuner evaluate <profile-or‑run>

# マージ済みチェックポイントのエクスポート
 gemma-macos-tuner export <run‑dir-or‑profile>

# ウィザード UI の起動
 gemma-macos-tuner wizard

結論 – Gemma‑tuner‑multimodal は Apple Silicon を最優先に設計された目的特化トレーナーで、Gemma ファミリーに LoRA を用いたマルチモーダル微調整（テキスト、画像、音声）を追加。親しみやすい CLI ウィザードとリアルタイムビジュアライザーを備えつつ、クラウドに保管された大規模データセットを Mac に直接ストリーミング可能。

関連

  • Dispatch
    Gemma 4 リリース：オンデバイス対応のオープンソース・マルチモーダルモデル

    Google DeepMind による新しいオープンソース・マルチモーダル・ファミリーである Gemma 4 が、画像、音声、ビデオのサポート、最大 256K のコンテキスト、および transformers、llama.cpp、MLX、Rust、WebGPU との Day-0 互換性を備えて Hugging Face でリリースされました。

  • Dispatch
    Hugging FaceでのGemmaモデルのファインチューニング

    Hugging Face は、パラメータ効率的ファインチューニング（PEFT）と低ランク適応（LoRA）を使用して、Google の Gemma モデルを GPU および Cloud TPU 上でカスタマイズするためのガイドを提供しています。

  • Dispatch
    Google Gemma オープン LLM リリース

    GoogleはGemmaをリリースしました。Geminiに基づくオープンアクセスの大規模言語モデルファミリーで、2Bと7Bのパラメータサイズがあり、ベースと指示チューニングされたバリアントが提供されます。

  • プロジェクト
    avifenesh/memra

    memra は、RTX PRO 6000 および RTX 5090 GPU にチューニングされた Rust + CUDA 推論エンジンです。Hugging Face safetensors または GGUF チェックポイントをロードし、OpenAI 互換の HTTP API を介して提供します。prefix‑cache 再利用、MTP speculative decoding、および image/video 入力などの機能を提供します。pre‑built binaries を提供し、クイックスタート・スクリプトを提供し、測定されたパフォーマンス (例: PRO 6000 で 140 tok/s decode, 0.156 s TTFT) を報告しています。厳選選定されたモデル (Qwen, Gemma‑4, Ornith, etc.) をサポートし、非常に大きなモデルをモデルを 2 枚の GPU に分割 (PP‑2) 2 枚の GPU に分割 (PP‑2) を可能です。単一 GPU または 2 枚の GPU ワークステーション用として設計されており、マルチノード・テンソル・パラレルを実現することは目指していません。

  • Dispatch
    macOS で Gemma 4 と llama.cpp を使用してローカルコーディングエージェントをセットアップする

    llama.cpp、Gemma 4 26B、および Pi エージェント・ハルネスを使用して、macOS 上でローカルコーディングエージェントをデプロイする方法を学びます。Multi-Token Prediction (MTP) により、最大 72.2 tokens per second の速度を実現します。