在Mac上微调你的第一个大模型:mlx-tune SFT监督微调20行代码实战

原创2026-10-11 15:20:351,361 阅读

在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大模型微调工具功能概览:SFT、DPO、GRPO、VLM 微调支持

简单来说,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 .

mlx-tune SFT微调官方文档页面预览:pip install 一键安装

💡 选模型小技巧: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."}]}

你有两种数据来源:

  1. 现成数据集:直接用 HuggingFace 数据集,比如经典的 yahma/alpaca-cleaned(约 5 万条指令数据),一行代码加载;
  2. 自己的数据:按上面的 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 个开箱即用的示例脚本:

mlx-tune 的设计目标不是替代 Unsloth,而是打通"Mac 本地原型 → 云端 GPU 全量训练"的工作流:在 Mac 上用 mlx_tune 验证思路,生产环境切回 unsloth,训练脚本几乎零改动。

🚀 现在,打开你的 Mac 终端,pip install mlx-tune,20 行代码之后,你就拥有了第一个亲手微调的大模型。

登录后查看全文
mlx-tune