**Show HN：** Apple Silicon向けGemma 4マルチモーダルファインチューナー

Gemmaをテキスト・画像・音声でファインチューニング – Mac上でローカルに収まりきらないデータも扱える

• 🖼️ 画像＋テキスト LoRA – ローカルCSVからキャプション生成＆VQA
• 🎙️ 音声＋テキスト LoRA – Apple Silicon にネイティブ対応した唯一のパス
• 📝 テキストのみ LoRA – CSV で指示／完了タスクを学習
• ☁️ GCS / BigQuery からストリーム – SSD を埋めることなく数 TB のデータでトレーニング
• 🍎 Apple Silicon 上で動作 – MPS 本格サポート、NVIDIA GPU 不要

ソース: https://github.com/mattmireles/gemma-tuner-multimodal（公開）

他ツールキットとの比較

Gemma をテキスト・画像・音声のいずれも Apple Silicon 上でファインチューニングしたい場合、これが唯一のツールキットです。

何を作れるか

• ドメイン固有 ASR – 医療筆記、法廷証言、コールセンター録音など
• ドメイン固有ビジョン – レシート・チャート・スクリーンショット・製造欠陥・医用画像のキャプション／VQA
• 文書＆画面理解 – UI エージェント、OCR 近接パイプライン、チャート QA 用にスクリーンショット → 構造化出力ペアを学習
• アクセント・方言・低リソース言語適応 – 自身のラベル付き音声でベース Gemma を未代表の声・言語へ適応
• マルチモーダルアシスタント – 画像や音声を基盤にしてテキスト推論を拡張（文字起こし、キャプション生成、Q&A パイプライン）
• 完全ローカル・オンデバイスパイプライン – Mac 上でトレーニング＆実行。データは機械外へ出ません

GCS や BigQuery にデータがある場合でも、ローカルに数 TB をコピーせずにラップトップだけで済ませられます。データローダーは必要に応じてシャードをストリームします。

対応モデル

config/config.ini

base_model

requirements/requirements-gemma4.txt

pip install -e .

独自チェックポイントを追加したい場合は

[model:your-name]

group = gemma

base_model

アーキテクチャ概要

gemma_tuner/cli_typer.py          # 標準 CLI
gemma_tuner/core/ops.py           # prepare → scripts.prepare_data, finetune → scripts.finetune などをディスパッチ
gemma_tuner/scripts/finetune.py   # Gemma モデル用ルーター
gemma_tuner/utils/device.py       # MPS → CUDA → CPU 選択
gemma_tuner/utils/dataset_utils.py  # CSV 読み込み、パッチ適用、ブラックリスト意味論
gemma_tuner/wizard/               # Questionary + Rich UI；python -m gemma_tuner.main finetune … を起動

典型的な実行フォルダ構成：

output/
├── {id}-{profile}/
│   ├── metadata.json
│   ├── metrics.json
│   ├── checkpoint-*/
│   └── adapter_model/          # LoRA アーティファクト（該当時）

設定は階層型 INI で、デフォルト → グループ → モデル → データセット → プロファイルと順に読み込まれます。

gemma_tuner/core/config.py

GEMMA_TUNER_CONFIG

要件

• Python 3.10+（macOS 内蔵 Python は 3.9 → 古い）
• macOS 12.3+（MPS 用）; ARM64 ネイティブ Python を使用（Rosetta では不可）
• RAM 小規模 Gemma 実行なら 16 GB 程度で十分。多めに取ると安定します
• CUDA 必須なし；必要なら PyTorch の CUDA ビルドをインストール

インストール手順

1. 仮想環境作成（最初に実行）

   python3.12 -m venv .venv
   source .venv/bin/activate
   

2. ARM64 Python を確認

   python -c "import platform; print(platform.machine())"
   # arm64 が出力されるはず
   

3. PyTorch インストール

   pip install torch torchaudio
   

4. パッケージインストール

   pip install .
   

5. Gemma 4（オプション）

   pip install -r requirements/requirements-gemma4.txt
   

6. ウィザード実行

   ウィザードはモデル選択、データセット設定、トレーニングを対話形式で案内し、

   config/config.ini

   を自動生成します。

   事前に Hugging Face のライセンス同意と認証が必要です：

   huggingface-cli login
   

CLI チートシート

# データセット準備（プロファイル名は config.ini に記載）
gemma-macos-tuner prepare <dataset-profile>

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

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

# HF/SafeTensors ツリーをエクスポート（adapter_config.json があれば LoRA をマージ）
gemma-macos-tuner export <run-dir-or-profile>

# エラーからブラックリスト生成
gemma-macos-tuner blacklist <profile>

# 走行一覧表示
gemma-macos-tuner runs list

# ガイド付きセットアップ
gemma-macos-tuner wizard

テキストのみファインチューニング

ローカルに

data/datasets/<name>/

modality = text
text_sub_mode = instruction  # または completion
prompt_column = prompt        # 指示モードの場合
text_column = response       # 完成モードの場合は `text`
max_seq_length = 2048

チェックポイントはマルチモーダル Gemma の AutoModelForCausalLM を保持し、音声トワーの重みは v1 でメモリに残ります。

画像ファインチューニング

ローカル CSV (

train.csv

validation.csv

image_sub_mode = caption

image_sub_mode = vqa

例（キャプション）：

modality = image
image_sub_mode = caption
text_column = caption
image_path_column = image_path
image_token_budget = 280   # (70, 140, 280, 560, 1120 のいずれか)

例（VQA）：

modality = image
image_sub_mode = vqa
prompt_column = question
text_column = answer
image_path_column = image_path
image_token_budget = 560

トークン予算を増やすと詳細度は上がりますが、MPS 上でメモリ消費・ステップ時間も増加します。

Apple Silicon での実行

• エンドツーエンドノートは

  README/specifications/Gemma3n.md

  に記載
• マルチモーダル Gemma 4 + MPS ガイド:

  README/guides/apple-silicon/gemma4-guide.md

典型的なワークフロー：

python -m gemma_tuner.scripts.gemma_preflight
python -m gemma_tuner.scripts.gemma_profiler --model google/gemma-3n-E2B-it
gemma-macos-tuner wizard

bf16

PYTORCH_ENABLE_MPS_FALLBACK=1

データ：CSV、GCS、BigQuery

ローカルに GCS 音声をコピーせずに済ませたいときは：

gemma-macos-tuner prepare <profile> --no-download

BigQuery からのインポートには

pip install .[gcp]

gcloud auth application-default login

GOOGLE_APPLICATION_CREDENTIALS

_prepared.csv

config/config.ini

パッチディレクトリ構造：

data_patches/{source}/
├── override_text_perfect/
├── do_not_blacklist/
└── delete/

オプションのトレーニングビジュアライザー

visualize=true

トラブルシューティング

gemma

PYTORCH_MPS_HIGH_WATERMARK_RATIO

PYTORCH_ENABLE_MPS_FALLBACK

GEMMA_TUNER_CONFIG

config/config.ini

huggingface-cli login

HF_TOKEN

コントリビューション

詳細は

docs/CONTRIBUTING.md

cli_typer.py

gemma_tuner/core/

謝辞

Google の Gemma チーム、Hugging Face Transformers & PEFT、PyTorch MPS メンテナ、および Activity Monitor が赤くなるまで問題報告してくださったすべての方へ感謝します。

ライセンス

MIT ライセンスで公開。