gemma-tuner-multimodal

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

开源 🏷️完全免费 🔧 仅开源项目，无在线服务，需自行部署模型训练 🍴 复刻 105 🐛 待处理 4 👀 关注 9

GitHub ↗

GitHub 星标 ★ 1516

维护状态活跃

是否开源开源

定价模式 🏷️完全免费开源免费，需自行部署

项目预览

gemma-tuner-multimodal 项目界面预览图 — 图片来源：GitHub 官方仓库名片

项目数据

分类模型训练

开发团队mattmireles

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

定价模式🏷️完全免费

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

访问状态🔧 仅开源项目，无在线服务，需自行部署

是否开源是

开源协议MIT

主要语言Python

GitHub 星标★ 1516

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

代码更新2026-10-30

仓库体积3.0 MB

本站数据更新2026-11-04

维护状态活跃

收录时间2026-09-16

浏览次数1

项目介绍

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

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-09-16 · 当前星标 ★ 1516

使用教程

ℹ 本教程由 AI 依据该项目 README 整理，个别步骤可能需要按你的环境微调。

难度：进阶约 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。