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。