用 MLX 在 Mac Studio 上做 LoRA 微调：
从环境到合并的入门流程

准备环境

mlx-lm 只能在 Apple 芯片的 Mac 上运行。建议为它建一个独立的 Python 虚拟环境：

python3 -m venv ~/mlx-env
source ~/mlx-env/bin/activate
pip install -U mlx-lm

# 先确认能正常推理
mlx_lm.generate --model mlx-community/<模型名> --prompt "你好"

基础模型可以直接使用 Hugging Face 上 mlx-community 组织转换好的 MLX 格式模型，也可以用 mlx_lm.convert 自己转换。选择已经量化为 4-bit 的模型作为基础时，训练就是 QLoRA，内存占用小很多。

数据格式

准备一个数据目录，里面放 train.jsonl 和 valid.jsonl，需要评估测试集时再加 test.jsonl。每行一个 JSON 对象，常用三种格式（同一个文件内保持一种）：

# 对话格式（会套用模型自带的对话模板）
{"messages": [{"role": "user", "content": "问题"}, {"role": "assistant", "content": "回答"}]}

# 补全格式
{"prompt": "输入", "completion": "期望输出"}

# 纯文本格式
{"text": "一段完整的训练文本"}

对指令类任务，对话格式最省事，因为模板和推理时一致。数据质量比数量更重要：先用几百条干净、风格一致的样本跑通流程，再逐步扩充。

训练与评估

# 训练，适配器默认保存到 ./adapters
mlx_lm.lora \
  --model mlx-community/<模型名> \
  --train \
  --data ./data \
  --iters 600 \
  --batch-size 4

# 在 test.jsonl 上评估
mlx_lm.lora \
  --model mlx-community/<模型名> \
  --adapter-path ./adapters \
  --data ./data \
  --test

训练过程中会定期输出训练损失和验证损失。验证损失不再下降甚至上升时，往往说明开始过拟合，可以减少迭代次数或增加数据。

常用的调节项还有应用 LoRA 的层数（--num-layers）、学习率、是否开启梯度检查点（--grad-checkpoint），也可以把所有参数写进 YAML 配置文件用 -c 传入。参数名称在不同版本之间有过调整，以 mlx_lm.lora --help 的输出和官方文档为准。

资料来源：ml-explore/mlx-lm · mlx-lm LoRA 文档

使用与合并适配器

# 不合并，直接加载适配器推理
mlx_lm.generate \
  --model mlx-community/<模型名> \
  --adapter-path ./adapters \
  --prompt "测试问题"

# 合并成一个独立的模型目录
mlx_lm.fuse \
  --model mlx-community/<模型名> \
  --adapter-path ./adapters \
  --save-path ./fused-model

mlx_lm.generate --model ./fused-model --prompt "测试问题"

合并后的目录可以像普通 MLX 模型一样加载，也可以上传到 Hugging Face。如果要转换成其他工具使用的格式（如 GGUF），各模型架构的支持情况不同，请参考官方仓库的说明。

内存估算思路

LoRA 微调的内存大致由四部分组成：

• 基础模型权重：参数量 × 每参数字节数。4-bit 量化约为 16-bit 的四分之一出头。这是最大的一块，且训练时被冻结。
• LoRA 参数及其优化器状态：只占基础模型的很小一部分，通常可以忽略。
• 激活值：随批大小、序列长度和应用 LoRA 的层数增长，是训练时比推理多出来的主要部分。
• 系统与其他程序：macOS 默认只允许 GPU 使用一部分统一内存，要留出余量。

实际做法是：先按权重大小选一档内存明显有富余的机器，用较小的批大小试跑几十步，用「活动监视器」或 memory_pressure 观察峰值，再逐步调大。权重估算方法可参考 Mac Studio 本地大模型内存估算 和 内存计算工具。三万主机的 Mac Studio 交付管理员账户，可以按需调整 GPU 可用内存上限。

常见问题