5分钟搞定Unsloth安装！Mac苹果芯片适配版本保姆级教程

1. 为什么Mac用户需要特别关注Unsloth的安装方式？

你是不是也遇到过这种情况：在自己的M1/M2/M3芯片Mac上，兴致勃勃地想用Unsloth微调一个LLM模型，结果刚执行pip install unsloth就报错？别急，不是你的环境有问题，而是官方主分支目前并不原生支持macOS系统。

Unsloth是一个非常强大的开源框架，主打“2倍训练速度 + 70%显存占用降低”，支持Llama、Qwen、Gemma等主流大模型的高效微调和强化学习。但它的GitHub主页明确写着只支持Windows和Linux——这意味着我们Mac用户必须另辟蹊径。

好消息是：社区已经出手了！

一位名叫 shashikanth-a 的开发者提交了一个PR（#1289），实现了对Apple Silicon（即M系列芯片）的完整支持，并发布在他自己的fork分支上。这个非官方但功能完整的版本，正是我们现在能在Mac上顺利运行Unsloth的关键。

本文将带你一步步完成从零到成功部署的全过程，确保你在5分钟内就能跑通第一个训练示例。

---

2. 安装前必读：关键注意事项

在开始之前，请务必了解以下几点，避免踩坑：

2.1 Python版本限制

Unsloth目前仅支持 Python 3.9 至 3.12，不兼容最新的Python 3.13。如果你系统默认安装的是3.13，一定要降级或创建指定版本的虚拟环境。

2.2 推荐使用Conda管理环境

虽然可以用venv，但我们强烈建议使用conda来创建独立环境。这样可以更好地隔离依赖，防止与其他项目冲突。

2.3 使用正确的分支

请记住：

• ❌ 不要克隆官方主仓库的main分支
• ✅ 必须使用 shashikanth-a/unsloth 的 apple_silicon_support 分支

否则你将无法在Mac上成功安装。

---

3. 手把手安装步骤（适用于M1/M2/M3芯片Mac）

3.1 创建独立的Conda环境

打开终端，输入以下命令创建一个新的Conda环境，并指定Python版本为3.12：

conda create -n unsloth_env python=3.12 -y

激活该环境：

conda activate unsloth_env

你可以通过以下命令确认当前Python版本是否正确：

python --version

输出应为 Python 3.12.x。

3.2 克隆支持Apple Silicon的Unsloth分支

接下来，我们需要从社区维护的分支下载代码。执行以下命令：

git clone https://github.com/shashikanth-a/unsloth.git -b apple_silicon_support

进入项目目录：

cd unsloth

确保当前目录下存在 pyproject.toml 文件，这是后续安装的关键配置文件。

⚠️ 提示：如果git clone失败，可以直接访问 https://github.com/shashikanth-a/unsloth/tree/apple_silicon_support 页面，点击“Code” → “Download ZIP”手动下载并解压。

3.3 安装Unsloth及其依赖

在项目根目录下执行安装命令：

pip install -e ".[huggingface]"

这里的 -e 表示“可编辑模式”，意味着你可以随时修改源码而无需重新安装；[huggingface] 是额外依赖组，包含了Hugging Face生态所需的组件。

安装过程会自动拉取大量依赖包，包括：

• transformers
• accelerate
• bitsandbytes
• peft
• mlx（Apple专属深度学习框架）
• 以及其他底层优化库

整个过程可能需要几分钟，请耐心等待。

3.4 验证安装是否成功

安装完成后，运行以下命令检查Unsloth是否正常加载：

python -m unsloth

如果看到类似如下输出（显示帮助信息或版本号），说明安装成功：

🦥 Unsloth: Will patch your computer to enable 2x faster free finetuning.
usage: unsloth-cli.py [-h] [--model_name MODEL_NAME] ...

恭喜！你现在已经在Mac上成功部署了Unsloth。

---

4. 快速上手：运行一个简单的LoRA微调示例

为了验证Unsloth能否真正工作，我们来运行一个轻量级的LoRA微调测试。

4.1 准备测试脚本

新建一个Python文件，例如 test_unsloth.py，粘贴以下代码：

from unsloth.mlx import mlx_utils
from unsloth.mlx import lora as mlx_lora
from unsloth import is_bfloat16_supported
from transformers.utils import strtobool
from datasets import Dataset
import logging
import os
import argparse

# 模拟命令行参数
args = argparse.Namespace(
    model_name="unsloth/Llama-3.2-3B-Instruct",
    max_seq_length=2048,
    dtype="bfloat16" if is_bfloat16_supported() else "float16",
    load_in_4bit=True,
    r=16,
    lora_alpha=16,
    lora_dropout=0.1,
    bias="none",
    use_gradient_checkpointing="unsloth",
    random_state=3407,
    use_rslora=False,
    loftq_config=None,
    per_device_train_batch_size=2,
    gradient_accumulation_steps=4,
    warmup_steps=5,
    max_steps=10,  # 小步数用于快速测试
    learning_rate=2e-4,
    optim="adamw_8bit",
    weight_decay=0.01,
    lr_scheduler_type="linear",
    seed=3407,
    output_dir="outputs",
    report_to="tensorboard",
    logging_steps=1,
    adapter_file="adapters.safetensors",
    save_model=False,  # 测试阶段不保存
    save_method="merged_16bit",
    save_gguf=False,
    save_path="model",
    quantization="q8_0"
)

logging.getLogger('hf-to-gguf').setLevel(logging.WARNING)

print("Loading pretrained model. This may take a while...")
model, tokenizer, config = mlx_utils.load_pretrained(
    args.model_name,
    dtype=args.dtype,
    load_in_4bit=args.load_in_4bit
)

print("Model loaded")

# 构建提示模板
alpaca_prompt = """Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.

### Instruction:
{}

### Input:
{}

### Response:
{}"""

EOS_TOKEN = tokenizer.eos_token

def formatting_prompts_func(examples):
    instructions = examples["instruction"]
    inputs       = examples["input"]
    outputs      = examples["output"]
    texts = []
    for instruction, input, output in zip(instructions, inputs, outputs):
        text = alpaca_prompt.format(instruction, input, output) + EOS_TOKEN
        texts.append(text)
    return {"text": texts}

# 创建小型测试数据集
basic_data = {
    "instruction": ["Summarize", "Translate", "Explain"],
    "input": ["The fox jumps over the dog.", "Hello world", "AI is evolving fast"],
    "output": [
        "A quick summary.",
        "Bonjour le monde",
        "Artificial intelligence is advancing rapidly."
    ]
}

dataset = Dataset.from_dict(basic_data)
print("Dataset initialized")

dataset = dataset.map(formatting_prompts_func, batched=True)
print("Data is formatted and ready!")

datasets = dataset.train_test_split(test_size=0.33)
print(f"Training examples: {len(datasets['train'])}, Test examples: {len(datasets['test'])}")

print("Starting training")
mlx_lora.train_model(args, model, tokenizer, datasets["train"], datasets["test"])

4.2 运行测试脚本

在终端中执行：

python test_unsloth.py

你会看到类似如下的输出：

Loading pretrained model. This may take a while...
Model loaded
Dataset initialized
Data is formatted and ready!
Training examples: 2, Test examples: 1
Starting training
Iter 1: Val loss 2.323, Val took 1.660s
Iter 1: Train loss 2.401, Learning Rate 0.000e+00, It/sec 0.580, Tokens/sec 117.208
...

只要没有报错，并且能看到训练迭代日志，就说明一切正常！

---

5. 常见问题与解决方案

5.1 ImportError: No module named 'unsloth.mlx'

这通常是因为你没有正确进入unsloth项目目录，或者未以可编辑模式安装。

✅ 解决方法：

• 确保你在unsloth根目录下运行脚本
• 检查是否执行了 pip install -e ".[huggingface]"

5.2 mx.metal.get_peak_memory is deprecated

这是MLX框架的警告信息，不影响运行。

✅ 解决方法： 忽略即可，或升级MLX至最新版（如有更新）。

5.3 pip安装时报错“Could not find a version that satisfies the requirement”

可能是网络问题导致依赖解析失败。

✅ 解决方法： 尝试更换国内镜像源：

pip install -e ".[huggingface]" -i https://pypi.tuna.tsinghua.edu.cn/simple

5.4 如何查看已安装的Unsloth环境？

运行以下命令查看所有Conda环境：

conda env list

你应该能看到 unsloth_env 出现在列表中。

激活它：

conda activate unsloth_env

---

6. 总结：Mac用户也能轻松玩转Unsloth

通过本文的详细指导，你现在应该已经成功在自己的Mac设备上安装并运行了Unsloth框架。尽管官方尚未正式支持macOS，但得益于开源社区的力量，我们已经有了稳定可用的替代方案。

回顾一下关键点：

1. 必须使用 shashikanth-a/unsloth 的 apple_silicon_support 分支
2. Python版本限定为 3.9–3.12，推荐使用 conda 管理环境
3. 安装时使用 pip install -e ".[huggingface]" 命令
4. 可通过简单LoRA示例验证安装效果

未来一旦Unsloth官方合并该PR并发布正式Mac支持版本，我们将第一时间更新教程。在此之前，这个非官方分支是你在苹果芯片上进行高效LLM微调的最佳选择。

现在，你已经具备了动手实践的能力。不妨尝试用自己的数据集训练一个专属模型吧！

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。