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）

是什麼 – 一個 Python 套件，可在搭載 Apple Silicon（MPS）的 Mac 上，使用 LoRA 適配器 對 Google 的 Gemma 語言模型（包含 3n 與 4 系列）在 文字、影像與音訊 資料上進行微調，無需 NVIDIA GPU。該工具包含一個小型 CLI 向導、即時 Web 可視化介面，並支援從 Google Cloud Storage 或 BigQuery 流式載入大型資料集。

核心功能（如 README 所述）

功能	詳細
模態支援	• 僅文字（指令或補全）
• 影像 + 文字（圖像描述或 VQA）
• 音訊 + 文字（ASR 類型）
硬體	原生運行於 Apple Silicon（PyTorch MPS）；若擁有 NVIDIA GPU，可選 CUDA 支援。
資料攝入	僅需 CSV 檔案（訓練/驗證）作為格式。CSV 行可引用本機檔案、HTTP URL、GCS 路徑或 BigQuery 表；`prepare` 命令可流式載入資料，無需將 TB 級資料複製到本機。
訓練 UI	當設定檔中 `visualize = true` 時，會自動啟動基於瀏覽器的可視化工具（損失曲線、注意力熱力圖、梯度訊號、記憶體使用、token 預測）。
模型目標	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 摘要）

建立原生 arm64 Python 3.10+ 虛擬環境（Homebrew python@3.12 可用）。
安裝 PyTorch（pip install torch torchaudio）。
安裝該套件（pip install -e .）。
登入 Hugging Face 並接受 Gemma 模型授權。
（可選）安裝 Gemma‑4 擴充（pip install -r requirements/requirements-gemma4.txt）。
執行向導 – gemma-macos-tuner wizard。將產生 config/config.ini，並引導完成模型、資料集和超參數選擇。
訓練 – 透過向導或直接執行：gemma-macos-tuner finetune <profile>。使用 --json-logging 可取得機器可讀日誌。
匯出 – 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。