mlx-fine-tuning

用途

MLX Fine-Tuning 是一个用于在 Apple Silicon（M1/M2/M3/M4）上使用 MLX 框架微调大语言模型的综合技能。其目标是利用 MLX 的统一内存架构与 Metal GPU 加速，在 Apple Silicon 上高效完成 LLM 微调，重点采用 LoRA（低秩适配）实现参数高效微调，无需昂贵的 GPU 硬件。

适用时机

在以下情况调用该技能：

在 Apple Silicon 上搭建 MLX 微调环境
将模型从 HuggingFace 转换为 MLX 格式
配置用于微调的 LoRA 适配器
针对特定数据集优化超参数
排查内存或性能问题
对微调后的模型进行基准测试
管理与导出适配器

平台要求

关键限制：MLX 仅能在原生运行 macOS 的 Apple Silicon（M1/M2/M3/M4）上工作。

架构必须为 arm64（可用 uname -m 验证）
无法在 Docker 或虚拟机中运行
需要 macOS 11.0 或更高版本

工作流程

1. 环境校验

首先使用提供的脚本校验环境：

python scripts/validate_environment.py

该脚本检查：Apple Silicon 架构、MLX 安装、Metal GPU 可用性、内存容量。

2. 模型准备

将 HuggingFace 模型转换为 MLX 格式，或使用预转换模型：

# 选项 A：使用 MLX Community 的预转换模型
--model mlx-community/Qwen2.5-3B-Instruct-4bit

# 选项 B：从 HuggingFace 转换
uv run mlx_lm.convert \
    --hf-path Qwen/Qwen2.5-3B-Instruct \
    --mlx-path models/Qwen2.5-3B-Instruct-mlx \
    --quantize  # 可选：用于 4-bit 量化

3. 数据准备

以 MLX 聊天格式（JSONL）准备训练数据：

{"messages": [
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "What is machine learning?"},
  {"role": "assistant", "content": "Machine learning is..."}
]}

将 train.jsonl 与 valid.jsonl 保存到数据目录中。

4. 超参数选择

加载 references/hyperparameter_guidelines.md 获取基于数据集规模的详细指导。

快速参考：

小数据集（<1k 样本）：学习率 2e-5，200-500 次迭代，4-8 层
中等数据集（1k-10k）：学习率 1e-5，500-1000 次迭代，8-16 层
大数据集（10k+）：学习率 5e-6，1000-2000 次迭代，16-32 层

5. 训练执行

使用 mlx_lm 运行微调：

uv run python -m mlx_lm lora \
    --model models/Qwen2.5-3B-Instruct-mlx \
    --train \
    --data ./data \
    --batch-size 1 \
    --iters 500 \
    --learning-rate 1e-5 \
    --num-layers 8 \
    --adapter-path adapters/my-lora \
    --save-every 100 \
    --grad-checkpoint  # 启用可提升内存效率

6. 内存优化

若遇到内存问题，加载 references/memory_optimization.md 获取技术：

梯度检查点（--grad-checkpoint）
减小批量大小
模型量化（4-bit）
减少层数

7. 评估与测试

测试微调后的模型：

# 交互式生成
uv run python -m mlx_lm lora \
    --model models/Qwen2.5-3B-Instruct-mlx \
    --adapter-path adapters/my-lora \
    --prompt "Your test prompt"

# 基准对比
uv run python scripts/hyperparameter_optimizer.py \
    --model models/Qwen2.5-3B-Instruct-mlx \
    --adapter adapters/my-lora \
    --test-samples 20

8. 适配器管理

导出并合并适配器：

# 导出为 safetensors 格式
uv run mlx_lm.fuse \
    --model models/base-model \
    --adapter-path adapters/my-lora \
    --save-path models/fused-model

# 转换回 HuggingFace 格式
uv run mlx_lm.convert \
    --mlx-path models/fused-model \
    --hf-path models/hf-export

故障排查

常见问题可加载 references/common_issues.md。快速解决方案：

内存错误：将批量大小减至 1，启用梯度检查点
训练缓慢：用 mx.default_device() 验证 Metal GPU 使用情况
训练不稳定：降低学习率，提高预热比例
格式错误：验证数据格式与 MLX 聊天结构匹配

高级技术

多阶段训练与学习率衰减

# 渐进式学习率调度
--lr-schedule "400:2e-5,400:1e-5,200:2e-6"

A/B 测试配置

使用 scripts/hyperparameter_optimizer.py 测试多种配置：

python scripts/hyperparameter_optimizer.py \
    --config-file configs/experiment.yaml \
    --parallel-runs 4

监控训练

跟踪关键指标：训练/验证损失曲线、内存使用（mx.metal.get_active_memory()）、Token 吞吐量、梯度范数。

最佳实践

从小规模开始：在完整训练前先用少量迭代测试
频繁检查点：使用 --save-every 避免丢失进度
监控内存：全程跟踪统一内存使用
经常验证：检查验证损失以尽早发现过拟合
对比性能：始终与基础模型进行基准对比
版本控制：为适配器目录使用描述性名称
记录实验：记录所有超参数与结果

资源参考

加载 references/hyperparameter_guidelines.md 获取详细参数选择
加载 references/memory_optimization.md 获取内存管理技术
加载 references/common_issues.md 获取故障排查指南
加载 references/mlx_api_reference.md 获取 MLX 特定函数

输出产物

训练产生：

adapters/*/adapters.safetensors - LoRA 权重
adapters/*/adapter_config.json - 配置
带损失曲线的训练日志
按指定间隔保存的检查点

与流水线集成

对于程序化训练，可与流水线系统集成：

from training.mlx import TrainConfig, TrainPipeline

config = TrainConfig(
    model="mlx-community/Qwen2.5-3B-Instruct-4bit",
    train_data="data/train.jsonl",
    iters=500,
    learning_rate=1e-5,
    num_layers=8,
    grad_checkpoint=True
)

pipeline = TrainPipeline(config)
result = pipeline.execute()