MLX 环境配置与模型微调文档

暂无标签

一、环境准备

1. 安装 uv 包管理工具

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 配置环境变量

# 查看 uv 安装位置
ls -la ~/.local/bin/uv

# 添加 uv 到 PATH
export PATH="$HOME/.local/bin:$PATH"

# 永久配置（使用 zsh）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证安装
uv --version

3. 安装 mlx-tune

uv pip install mlx-tune

二、模型下载

1. 配置 HuggingFace 镜像（国内加速）

export HF_ENDPOINT=https://hf-mirror.com

2. 下载模型

hf download mlx-community/Qwen3.5-4B-MLX-4bit

3. 进入模型缓存目录

cd /Users/t-mac/.cache/huggingface/hub/models--mlx-community--Qwen3.5-4B-MLX-4bit/

三、Conda 环境管理

1. 查看已有环境

conda env list

2. 激活目标环境

# 注意：命令是 activate，不是 active
conda activate langchain-dev

四、模型微调

1. 运行训练脚本

# 添加执行权限
chmod +x ./train.sh

# 执行训练
./train.sh

2. 使用 MLX LoRA 进行微调

mlx_lm.lora --config config.yaml

五、模型融合（Fuse）

将 LoRA 适配器与基础模型融合，生成最终模型：

python -m mlx_lm fuse \
    --model /Users/t-mac/.cache/huggingface/hub/models--mlx-community--Qwen3.5-4B-MLX-4bit/snapshots/32f3e8ecf65426fc3306969496342d504bfa13f3 \
    --adapter-path adapters \
    --save-path dongdong_fused_final \
    --dequantize

参数说明：

参数说明
--model基础模型路径
--adapter-pathLoRA 微调后的适配器路径
--save-path融合后模型的保存路径
--dequantize反量化处理

六、常用命令速查

操作命令
激活 conda 环境conda activate <环境名>
退出 conda 环境conda deactivate
查看环境列表conda env list
设置 HF 镜像export HF_ENDPOINT=https://hf-mirror.com
下载模型hf download <模型名>

七、注意事项

  1. 命令区分：conda 激活命令是 activate，不是 active
  2. 路径适配：请根据实际模型快照路径替换命令中的路径
  3. Shell 配置：如果使用 bash，将 ~/.zshrc 替换为 ~/.bashrc
  4. 镜像加速：国内用户建议设置 HF_ENDPOINT 镜像加速下载

八、模型推理测试

1. 基础推理命令

使用融合后的模型进行文本生成：

mlx_lm generate \
    --model ./dongdong_fused_final \
    --prompt "你是谁？" \
    --max-tokens 100

2. 参数说明

参数说明示例
--model模型路径（融合后的模型目录）./dongdong_fused_final
--prompt输入提示词/问题"你是谁？"
--max-tokens最大生成 token 数量100

3. 更多推理参数示例

# 带温度参数的生成（控制随机性）
mlx_lm generate \
    --model ./dongdong_fused_final \
    --prompt "请介绍一下你自己" \
    --max-tokens 200 \
    --temp 0.7

# 带 top-p 采样的生成
mlx_lm generate \
    --model ./dongdong_fused_final \
    --prompt "用一句话介绍人工智能" \
    --max-tokens 150 \
    --temp 0.8 \
    --top-p 0.9

# 交互式对话模式
mlx_lm generate \
    --model ./dongdong_fused_final \
    --prompt "你好" \
    --max-tokens 500 \
    --interactive

4. 完整参数列表

参数类型默认值说明
--model必填-模型路径
--prompt可选None输入提示词
--max-tokens可选100最大生成 token 数
--temp可选0.8温度参数（越高越随机）
--top-p可选0.95nucleus 采样参数
--seed可选0随机种子
--interactive标志False启用交互模式

九、完整工作流程总结

# 1. 环境准备
export HF_ENDPOINT=https://hf-mirror.com
conda activate langchain-dev

# 2. 模型下载
hf download mlx-community/Qwen3.5-4B-MLX-4bit

# 3. 模型微调
mlx_lm.lora --config config.yaml

# 4. 模型融合
python -m mlx_lm fuse \
    --model /path/to/base/model \
    --adapter-path adapters \
    --save-path dongdong_fused_final \
    --dequantize

# 5. 模型推理测试
mlx_lm generate \
    --model ./dongdong_fused_final \
    --prompt "你是谁？" \
    --max-tokens 100

十、常见问题

Q1: 推理速度慢？

  • 确保使用 --dequantize 融合后的模型
  • 检查是否在 Apple Silicon (M系列芯片) 上运行

Q2: 生成结果不符合预期？

  • 调整 --temp 参数（降低可减少随机性）
  • 增加 --max-tokens 值
  • 优化 prompt 提示词

Q3: 内存不足？

  • 减小 --max-tokens 值
  • 使用更小的量化模型（如 4bit 版本）
标签：
暂无标签