在Mac上微调你的第一个大模型:mlx-tune SFT监督微调20行代码实战
在Mac上微调你的第一个大模型:mlx-tune SFT监督微调20行代码实战
Mac 也能本地微调大模型了!mlx-tune 是一个基于 Apple MLX 框架的 Mac 大模型微调工具,专为 M 系列芯片(M1~M5)设计,支持 SFT 监督微调、DPO、GRPO、视觉、语音等 16+ 种训练方式,并且提供与 Unsloth 完全兼容的 API。本文带你在自己的 MacBook 上,用 20 行 Python 代码跑通完整的 SFT 微调流程——从安装到模型导出,全程不花一分钱云 GPU 费用。
什么是 mlx-tune?Mac 本地微调大模型新选择
简单来说,mlx-tune 解决的是这样一个痛点:
- 🍎 过去:想在 Mac 上做微调?Unsloth 依赖 CUDA,用不了;只能租云 GPU
- ✨ 现在:mlx-tune 把 Apple 原生的 MLX 框架封装成 Unsloth 风格的 API,你的 Mac 统一内存(最高 512GB)就是"显存"
它的核心能力一览:
| 训练方式 | 对应 Trainer | 典型用途 |
|---|---|---|
| SFT 监督微调 | SFTTrainer |
指令微调、对话对齐 |
| DPO / ORPO / KTO / SimPO | 偏好训练器 | 让模型回答更符合偏好 |
| GRPO | GRPOTrainer |
推理能力强化(DeepSeek R1 风格) |
| 视觉模型微调 | VLMSFTTrainer |
Gemma 4、Qwen3.5 等多模态微调 |
| TTS / STT 语音微调 | TTSSFTTrainer 等 |
语音合成、语音识别 |
| Embedding / OCR | 专用训练器 | 语义检索、文档识别 |
对于新手,SFT 监督微调(Supervised Fine-Tuning) 是最标准的入门姿势:给模型一批"问题 → 标准答案",让它学会按你的风格回答。下面我们就从它开始。
环境要求与一键安装步骤
开始前的硬件要求非常友好:
| 项目 | 最低要求 | 推荐配置 |
|---|---|---|
| 芯片 | Apple Silicon(M1/M2/M3/M4/M5) | M3 及以上 |
| 内存 | 8GB 统一内存 | 16GB+(可微调 3B~7B 模型) |
| 系统 | macOS 13.0+ | 最新 macOS |
| Python | 3.9+ | 3.11+ |
最快安装方式,终端执行一条命令即可:
pip install mlx-tune
如果后续想做语音模型微调,可以加装音频依赖:
uv pip install 'mlx-tune[audio]'
也可以从源码安装(方便参与开发):
git clone https://gitcode.com/gh_mirrors/un/mlx-tune
cd mlx-tune
uv pip install -e .
💡 选模型小技巧:16GB 内存建议选 1B~3B 的 4-bit 量化模型;32GB 可以上 7B;48GB+ 可尝试 13B。模型名带
-4bit后缀的量化版本最省内存,这也是 QLoRA 微调的标准做法。
准备微调数据:3分钟搞定训练集
mlx-tune 的训练数据采用对话(messages)格式,每条数据就是一个 JSON:用户提问 + 助手回答。仓库里自带了一份可以直接使用的示例数据 train_data.jsonl:
{"messages": [{"role": "user", "content": "What is Python?"}, {"role": "assistant", "content": "Python is a high-level programming language known for its simplicity."}]}
你有两种数据来源:
- 现成数据集:直接用 HuggingFace 数据集,比如经典的
yahma/alpaca-cleaned(约 5 万条指令数据),一行代码加载; - 自己的数据:按上面的 messages 格式整理成 JSONL 文件即可,几百条就能开始实验。
数据质量比数量更重要——新手阶段用 100~500 条高质量问答就足够验证整个流程了。
20行代码完成SFT监督微调完整流程
下面是核心实战部分。完整脚本约 20 行,分四步走:加载模型 → 挂 LoRA → 配置训练 → 保存结果。
from mlx_tune import FastLanguageModel, SFTTrainer, SFTConfig
from datasets import load_dataset
# 1️⃣ 加载基座模型(4-bit 量化,16GB 内存友好)
model, tokenizer = FastLanguageModel.from_pretrained(
"mlx-community/Llama-3.2-1B-Instruct-4bit",
max_seq_length=2048,
load_in_4bit=True,
)
# 2️⃣ 添加 LoRA 适配器(只训练极少参数,快速又省内存)
model = FastLanguageModel.get_peft_model(
model,
r=16,
lora_alpha=16,
target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
)
# 3️⃣ 加载训练数据(这里取经典指令集前100条)
dataset = load_dataset("yahma/alpaca-cleaned", split="train[:100]")
# 4️⃣ 配置 SFT 训练器并开跑
trainer = SFTTrainer(
model=model,
train_dataset=dataset,
tokenizer=tokenizer,
args=SFTConfig(
output_dir="outputs",
per_device_train_batch_size=2,
learning_rate=2e-4,
max_steps=50,
),
)
trainer.train()
# 5️⃣ 保存成果
model.save_pretrained("lora_model") # 只存 LoRA 适配器(很小)
model.save_pretrained_merged("merged", tokenizer) # 合并成完整模型
就这么简单,trainer.train() 之后你的 Mac 就开始本地训练了。几个关键参数说明:
| 参数 | 示例值 | 怎么调 |
|---|---|---|
r(LoRA 秩) |
16 | 实验阶段用 8,追求质量用 16~32 |
target_modules |
4 个投影层 | 微调 MoE 模型时可加上 gate_proj, up_proj, down_proj |
learning_rate |
2e-4 | LoRA 常用范围 1e-4 ~ 5e-4 |
max_steps |
50 | 新手先跑 50~100 步验证流程,正式训练 500+ |
per_device_train_batch_size |
2 | 内存吃紧就降到 1 |
📦 更完整的参数说明见 SFTConfig 文档;仓库还提供了与 Unsloth 教程逐行对应的示例 examples/08_exact_unsloth_pipeline.py,以及更轻量的入门示例 examples/04_simple_finetuning.py。
为什么是 LoRA? 全参微调需要更新模型的全部数十亿参数,而 LoRA 只训练极少量"适配器"参数(通常不到 1%),在 Mac 的统一内存上几分钟就能跑完一轮,效果却足以满足原型验证需求。
微调完成后:保存与部署模型
训练结束后,mlx-tune 提供三种保存方式,同样兼容 Unsloth 的 API:
model.save_pretrained("lora_model") # ① 只存适配器,体积小
model.save_pretrained_merged("merged", tokenizer) # ② 合并基座,直接推理
model.save_pretrained_gguf("model", tokenizer) # ③ 导出 GGUF,供 Ollama/llama.cpp 使用
- 只存适配器:最省空间,加载基座模型后调用
model.load_adapter(...)即可复用; - 合并模型:
save_method默认merged_16bit,会先反量化基座再融合,完整保留微调效果,推荐新手使用; - GGUF 导出:适合部署到 Ollama。注意 4-bit 量化基座直接导出 GGUF 是 mlx-lm 的已知限制,建议改用非量化基座训练,或加
dequantize=True导出。
微调后的模型还能通过 model.push_to_hub(...) 一键上传分享。
新手常见问题速查(Troubleshooting)
遇到报错别慌,以下是三个最高频的问题:
❓ 内存不足(OOM / 系统卡顿)
按顺序尝试:换更小的模型(1B)、保持 4-bit 量化、把 max_seq_length 降到 1024、关闭其他占内存的应用。上下文 ≥4096 或内存紧张时,可在 get_peft_model 中加 use_gradient_checkpointing="unsloth",以约 2 倍时间换一半激活内存。
❓ 提示 "Model not found"
请改用 MLX 社区的模型名,例如 mlx-community/Llama-3.2-1B-Instruct-4bit,不要使用 CUDA 专属的 unsloth/... 模型路径。
❓ 想要更快迭代?
- 减少
max_steps,先看 loss 是否下降; - 使用
train_on_responses_only(...)只训练回答部分,忽略提示词部分,更高效; - 用
get_chat_template(tokenizer, chat_template="auto")自动套用 Llama / Qwen / Gemma 等 16 种对话模板。
更多排查方法可参考 docs/quick_start.md 的 Troubleshooting 章节。
进阶路线:从SFT到更多训练方式
跑通 SFT 之后,mlx-tune 的进阶玩法已经为你备好了,examples 目录包含 56 个开箱即用的示例脚本:
- 偏好对齐:DPO 偏好微调、GRPO 推理训练、ORPO / KTO / SimPO;
- 多模态:Gemma 4 视觉微调、Qwen 视觉 OCR;
- 语音:Whisper STT 微调、Orpheus TTS 微调;
- Embedding:语义检索微调;
- 持续预训练(CPT):领域知识注入。
mlx-tune 的设计目标不是替代 Unsloth,而是打通"Mac 本地原型 → 云端 GPU 全量训练"的工作流:在 Mac 上用 mlx_tune 验证思路,生产环境切回 unsloth,训练脚本几乎零改动。
🚀 现在,打开你的 Mac 终端,pip install mlx-tune,20 行代码之后,你就拥有了第一个亲手微调的大模型。

