用途
gemma-tuner-multimodal 用于在 Apple Silicon 设备上微调 Gemma 4 和 Gemma 3n 模型，支持文本、图像和音频三种模态。它基于 PyTorch 和 Metal Performance Shaders（MPS），无需 NVIDIA GPU，可在 MacBook Pro、MacBook Air 或 Mac Studio 上运行。
主要能力
- 文本 LoRA：支持指令微调（instruction tuning）和补全微调（completion fine-tuning），数据来自本地 CSV。
- 图像 + 文本 LoRA：支持图像描述（captioning）和视觉问答（VQA），数据来自本地 CSV。
- 音频 + 文本 LoRA：提供 Apple Silicon 原生路径。
- 云流式处理：可从 GCS/BigQuery 流式读取数 TB 数据，无需本地复制。
- MPS 原生：无需 NVIDIA GPU，在 Mac 上直接运行。
安装前提
- macOS 12.3+，Apple Silicon（arm64）
- Python 3.10+（原生 arm64，非 Rosetta）
- 拥有 Gemma 访问权限的 Hugging Face 账户
安装步骤：
# 安装 Python 3.12（如需）
brew install python@3.12
# 创建虚拟环境
python3.12 -m venv .venv
source .venv/bin/activate
# 验证 arm64（必须显示 arm64，而非 x86_64）
python -c "import platform; print(platform.machine())"
# 安装 PyTorch
pip install torch torchaudio
# 克隆并安装
git clone https://github.com/mattmireles/gemma-tuner-multimodal
cd gemma-tuner-multimodal
pip install -e .
# 支持 Gemma 4（建议单独虚拟环境）
pip install -r requirements/requirements-gemma4.txt
Hugging Face 认证：
huggingface-cli login
# 或设置环境变量：
export HF_TOKEN=your_token_here
使用方式
命令行命令
# 检查系统就绪
gemma-macos-tuner system-check
# 引导式设置向导（推荐首次运行）
gemma-macos-tuner wizard
# 准备数据集
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
配置
配置文件为层级 INI 格式：defaults → groups → models → datasets → profiles。可通过 GEMMA_TUNER_CONFIG 环境变量指定仓库根目录之外的配置。
适用场景
- 需要在 Mac 上微调 Gemma 多模态模型的研究者或开发者。
- 处理音频、图像、文本混合数据的小规模到大规模微调任务。
- 希望利用 GCS/BigQuery 流式处理避免本地存储压力的场景。
限制
- 仅支持 Apple Silicon（arm64），不支持 x86_64。
- 需要 Hugging Face 账户及 Gemma 访问权限。
- MPS 内存受限时需降低 batch_size、增大梯度累积、使用更小模型或减小 max_seq_length。
- Gemma 4 需要单独的 requirements-gemma4.txt，建议使用独立虚拟环境。
- 已知 v1 问题：即使仅文本模态，USM 音频塔权重仍会驻留内存，解决方法为使用更小模型变体。
- 其他未在资料中说明的限制暂未提供。