在 Apple Silicon Mac 上微调 Gemma…

适用场景：需要在 macOS Apple Silicon 上用 PyTorch/MPS 对 Gemma 3n/4 做文本、图像或音频 LoRA 微调，且希望无需 NVIDIA GPU、可流式读取云端大数据。

适用场景

解决思路

1. 确认环境：macOS 12.3+、Apple Silicon (arm64)、Python 3.10+ 原生 arm64（非 Rosetta），并准备有 Gemma 访问权限的 Hugging Face 账号。
2. 安装 Python 3.12：`brew install python@3.12`。
3. 创建并激活虚拟环境：`python3.12 -m venv .venv`，`source .venv/bin/activate`。
4. 验证 Python 为原生 arm64：`python -c 'import platform; print(platform.machine())'`，输出必须是 `arm64`，不能是 `x86_64`。
5. 安装 PyTorch 与音频支持：`pip install torch torchaudio`。
6. 克隆并安装微调器：`git clone https://github.com/mattmireles/gemma-tuner-multimodal`，`cd gemma-tuner-multimodal`，`pip install -e .`。
7. 若要支持 Gemma 4，安装专用依赖：`pip install -r requirements/requirements-gemma4.txt`；建议为 Gemma 4 单独建 venv，以免与 Gemma 3n 依赖冲突。
8. 配置 Hugging Face 认证：运行 `huggingface-cli login`，或设置 `export HF_TOKEN=your_token_here`，并确保已接受 Gemma 模型许可。
9. 运行系统检查：`gemma-macos-tuner system-check`。
10. 首次使用运行向导：`gemma-macos-tuner wizard`。
11. 准备数据集：`gemma-macos-tuner prepare <dataset-profile>`。
12. 启动微调：`gemma-macos-tuner finetune <profile> --json-logging`。
13. 评估训练：`gemma-macos-tuner evaluate <profile-or-run>`。
14. 导出合并权重：`gemma-macos-tuner export <run-dir-or-profile>`；当存在 `adapter_config.json` 时会合并 LoRA。
15. 从错误中拉黑坏样本：`gemma-macos-tuner blacklist <profile>`。
16. 查看训练运行列表：`gemma-macos-tuner runs list`。
17. 配置 `config/config.ini`，使用层级 INI：defaults → groups → models → datasets → profiles。
18. 若配置不在仓库根目录，设置 `export GEMMA_TUNER_CONFIG=/path/to/my/config.ini`。
19. 在 `[defaults]` 设置训练默认项：`output_dir`、`batch_size`、`gradient_accumulation_steps`、`learning_rate`、`num_train_epochs`。
20. 在 `[model:...]` 定义模型，例如 `group = gemma`、`base_model = google/gemma-3n-E2B-it` 或 `base_model = google/gemma-4-E2B-it`。
21. 在 `[dataset:...]` 定义数据集，例如 `data_dir`、`audio_column`、`text_column`。
22. 在 `[profile:...]` 定义训练配置，指定 `model`、`dataset`、`modality`、`lora_r`、`lora_alpha`、`lora_dropout`、`max_seq_length`。
23. 文本指令微调：profile 设置 `modality = text`、`text_sub_mode = instruction`、`prompt_column`、`text_column`、`max_seq_length`、LoRA 参数；CSV 列使用 `prompt,response`。
24. 文本 completion 微调：profile 设置 `modality = text`、`text_sub_mode = completion`、`text_column`、`max_seq_length`。
25. 图像微调：profile 设置 `modality = image`、`image_sub_mode = captioning`、`image_token_budget = 256`、`prompt_column`、`text_column`、`max_seq_length`；CSV 列使用 `image_path,prompt,caption`。
26. 音频微调：profile 设置 `modality = audio`、`audio_column = audio_path`、`text_column = transcript`、`max_seq_length`、`lora_r`、`lora_alpha`、`lora_dropout`；CSV 列使用 `audio_path,transcript`。
27. 使用内置模型 key 之一：`gemma-3n-e2b-it`、`gemma-3n-e4b-it`、`gemma-4-e2b-it`、`gemma-4-e4b-it`、`gemma-4-e2b`、`gemma-4-e4b`；Gemma 4 需要 `requirements-gemma4.txt`。
28. 添加自定义 Gemma 模型：新增 `[model:your-name]`，设置 `group = gemma` 和 `base_model`。
29. 按目录布局放数据：`data/datasets/<dataset-name>/train.csv` 必需，`validation.csv`、`test.csv` 可选。
30. 训练输出在 `output/{run-id}-{profile}/`，包含 `metadata.json`、`metrics.json`、`checkpoint-*/`、`adapter_model/`。
31. 用 Python API 运行微调：`from gemma_tuner.core.config import load_config`，`from gemma_tuner.core.ops import run_finetune`，调用 `run_finetune(profile='my-audio-profile', config=config, json_logging=True)`。
32. 用设备工具选择设备与查看内存提示：`from gemma_tuner.utils.device import get_device, memory_hint`，`get_device()` 返回 `mps`/`cuda`/`cpu`，`memory_hint(model_key='gemma-3n-e2b-it')`。
33. 用数据集工具加载 CSV：`from gemma_tuner.utils.dataset_utils import load_csv_dataset`，传入 `data_dir`、`text_column`、`prompt_column`，得到 `train_df, val_df`。
34. 自定义 LoRA 配置：从预训练模型加载时设置 `device_map='mps'`；使用 `LoraConfig(r=16, lora_alpha=32, lora_dropout=0.05, target_modules=['q_proj', 'v_proj', 'k_proj', 'o_proj'], task_type='CAUSAL_LM')`，再 `get_peft_model(model, lora_config)` 并 `model.print_trainable_parameters()`。
35. 完整文本指令微调工作流：创建 `data/datasets/my-dataset` 并复制 `train.csv`/`validation.csv`；向 `config/config.ini` 追加 `[dataset:my-dataset]` 和 `[profile:my-text-run]`；依次运行 `gemma-macos-tuner prepare my-dataset`、`gemma-macos-tuner finetune my-text-run --json-logging`、`gemma-macos-tuner export my-text-run`。
36. GCS 流式大数据：dataset 设置 `source = gcs`、`gcs_bucket`、`gcs_prefix`、`audio_column`、`text_column`；profile 使用该 dataset；设置 `export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json` 后运行 `gemma-macos-tuner finetune large-audio-run`。
37. 添加自定义 Gemma checkpoint：新增 `[model:my-custom-gemma]`，设置 `group = gemma`、`base_model = my-org/my-gemma-checkpoint`，再在 profile 中引用。
38. 架构错误修复：若 `platform.machine()` 输出 `x86_64`，用 `brew install python@3.12` 重装原生 Python，再 `python3.12 -m venv .venv && source .venv/bin/activate`。
39. MPS 显存不足时：把 `batch_size` 降到 1；提高 `gradient_accumulation_steps` 补偿；改用更小模型如 `e2b`；降低 `max_seq_length`。
40. Gemma 4 加载失败时：安装 `pip install -r requirements/requirements-gemma4.txt`；若同时需要 Gemma 3n，使用单独 venv。
41. 配置找不到时：`export GEMMA_TUNER_CONFIG=/absolute/path/to/config/config.ini`，再运行 `gemma-macos-tuner finetune my-profile`。
42. Hugging Face 认证错误时：运行 `huggingface-cli login` 或设置 `export HF_TOKEN=your_hf_token`，并到模型页接受 Gemma 许可。
43. 调试前先运行 `gemma-macos-tuner system-check`。
44. 已知音频塔问题：即使 `modality = text`，v1 仍可能把 USM audio tower 权重留在内存；参考 `README/KNOWN_ISSUES.md`，临时用更小模型控制 RAM。
45. 代码结构参考：`gemma_tuner/cli_typer.py` 是 CLI 入口；`gemma_tuner/core/ops.py` 分发 prepare/finetune/evaluate/export；`gemma_tuner/scripts/finetune.py` 路由模型；`gemma_tuner/models/gemma/finetune.py` 是 LoRA 训练循环；`gemma_tuner/scripts/export.py` 合并 LoRA；`gemma_tuner/utils/device.py` 选择设备；`gemma_tuner/utils/dataset_utils.py` 加载 CSV 与黑名单；`gemma_tuner/wizard/` 是向导；`config/config.ini` 是配置。

适用边界 · 注意事项

• 不适用于没有 Apple Silicon Mac、macOS 12.3+ 或原生 arm64 Python 的环境。
• 不适用于没有 Hugging Face 账号、未接受 Gemma 许可，或不愿使用 `gemma-tuner-multimodal` 工具链的场景。
• 不适用于需要多卡 NVIDIA GPU 大规模训练，或目标模型/序列长度超出 MPS 内存预算的场景。