gemma-tuner-multimodal

Mac 上直接微调 Gemma 多模态模型，图文音一起训

gemma-tuner-multimodal 是一个面向 Apple Silicon 芯片的多模态微调工具，基于 PyTorch 和 Metal Performance Shaders（MPS）后端，让开发者能在 Mac 本地对 Gemma 系列模型进行音频、图像和文本三种模态的微调。它解决的核心问题是：以往多模态微调依赖 NVIDIA GPU 和 CUDA 环境，Mac 用户要么租云卡、要么放弃本地训练；该项目把训练流程适配到 MPS，使 M 系列芯片的 Mac 也能跑起多模态 LoRA/全参微调。核心能力包括：加载 Gemma 多模态权重、处理图文音混合数据集、支持 LoRA 等参数高效微调、利用统一内存减少显存搬运开销，并提供训练脚本与配置示例。适合个人开发者、研究者做小规模实验、领域适配和原型验证，无需额外硬件投入，在本地即可完成从数据准备到模型微调的闭环。

开源 free 模型训练

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1502

维护状态较活跃

是否开源是

定价模式 free

项目数据

分类模型训练

开发团队mattmireles

所属国家

官网地址

GitHubhttps://github.com/mattmireles/gemma-tuner-multimodal

定价模式free

价格说明开源免费，需自行部署

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型

GitHub 星标★ 1502

30天Star增速

HF 下载量

上线时间2026-04-07 00:00:00

最近更新2026-09-13 00:00:00

维护状态较活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-09-16

浏览次数0

使用教程

难度：进阶约 15 分钟部署方式：命令行工具 6 步

环境要求

Apple Silicon（M 系列）Mac，使用 MPS 后端，无需 NVIDIA GPU/CUDA
原生 arm64 Python（README 推荐 brew install python@3.12）
可用的 pip 环境与网络（需下载 torch、torchaudio）
Mac 本地磁盘空间（也可从 GCS/BigQuery 流式读取数据）

安装与启动步骤

1安装 arm64 Python

确认 Python 不是跑在 Rosetta（x86_64）下的版本，否则需安装原生 arm64 Python；README 推荐用 Homebrew 装 3.12。
```
brew install python@3.12
```
2创建虚拟环境

在项目目录下用原生 arm64 解释器建 venv 并激活；README 提到需重建 venv，但未给出具体命令，此处为常规做法。
```
python3.12 -m venv .venv
source .venv/bin/activate
```
3安装 PyTorch

安装 PyTorch 与 torchaudio，作为 MPS 后端训练依赖。
```
pip install torch torchaudio
```
4安装本项目

在项目根目录以可编辑模式安装本包，安装后获得 gemma-macos-tuner 命令。
```
pip install -e .
```
5运行配置向导

向导是主要交互界面：选择模型、数据集与超参数并启动训练，首次运行会生成 config/config.ini。
```
gemma-macos-tuner wizard
```
6查看运行记录

列出已完成的训练 run；README 说明 runs 管理已并入 runs 子命令，而非单独的 manage.py。
```
gemma-macos-tuner runs list
```

关键配置

配置项	必填	说明	示例
`config/config.ini`	是	向导自动生成的主配置，写入本地路径与 GCP 项目 ID，被 gitignore。	`config/config.ini`
`config/config.ini.example`	否	仓库中提交的配置模板，向导首次运行时据此生成 config.ini。	`config/config.ini.example`

如何确认成功

向导正常启动并生成 config/config.ini，终端给出可视化 URL；再执行 gemma-macos-tuner runs list 能列出运行索引即表示安装可用。

常见问题

Q：提示 Python 是 x86_64 / 在 Rosetta 下运行怎么办？

A：说明当前不是原生 arm64 Python。请按 README 安装原生 arm64 Python（如 brew install python@3.12），并用它重建虚拟环境后重新安装依赖。

Q：某条命令执行失败如何排查？

A：README 建议先运行 gemma-macos-tuner system-check，它会暴露环境层面的问题，再回到对应步骤修复。

Q：没有 NVIDIA 显卡能训练吗？

A：可以。项目基于 PyTorch + MPS，专为 Apple Silicon 设计，README 明确标注无需 NVIDIA 机器、无需 CUDA。

Q：为什么找不到 config/config.ini？

A：该文件被 gitignore，由向导首次运行时从 config/config.ini.example 生成，直接跑一次 wizard 即可得到。

Q：训练数据太大放不下怎么办？

A：README 支持从 GCS / BigQuery 流式读取训练数据，可在不占满本地 SSD 的情况下训练大数据集。

注意事项

README 安装章节只公开了第 3、4、7 步及后续命令，第 1、2、5、6 步内容缺失，本教程未补造任何未知命令。
浏览器实时可视化（Loss 曲线、注意力热图、显存压力等）无需 TensorBoard，需在配置中开启一个开关，终端会打印访问 URL，README 未给出该配置项的具体键名。
导出的模型与完成的 run 会包含 .integrity.json 清单文件，可用于校验完整性。
从旧版 main.py 工作流迁移请参考仓库内的 docs/MIGRATION.md。

核心亮点

专为 Apple Silicon 的 MPS 后端优化，Mac 用户无需 NVIDIA 显卡即可本地微调多模态模型
同时支持音频、图像、文本三种模态输入，覆盖 Gemma 3n/4 的多模态能力
基于 PyTorch 生态，训练脚本和配置直观，便于二次开发和接入自有数据集

不足之处

仅适配 Apple Silicon 与 MPS，Windows/Linux 及 CUDA 用户无法直接使用
多模态微调对统一内存占用较高，低配 Mac 可能受限于内存容量和训练速度

适用场景

个人开发者在 MacBook 上用自己的图文数据微调 Gemma，做垂直领域问答助手
研究者快速验证多模态微调想法，无需租用云 GPU 即可跑通实验
团队在本地做音频+文本的小规模领域适配，保护数据不出内网

替代项目

LLaMA-Factory、unsloth

项目介绍

gemma-tuner-multimodal 是一个模型训练领域的开源项目，官方简介：Fine-tune Gemma 4 and 3n with audio, images and text on Apple Silicon, using PyTorch and Metal Performance Shaders.。项目使用 Python 开发，在 GitHub 上获得 1502 星标。

上一篇：mttl

下一篇：burn-onnx