Unsloth 详细部署教程

Unsloth 是一个强大的本地桌面应用，让你可以在自己的电脑上运行和训练 LLM、扩散模型等 AI 模型，支持 GGUF、MLX 等多种格式，并兼容 NVIDIA、AMD、Intel 等各类 GPU 甚至 CPU。

本教程将指导你完成 Unsloth 的安装、配置和基本使用。

一、系统要求

Unsloth 支持 Windows、Linux、macOS 以及 WSL，硬件兼容性广泛：

  • GPU：支持 NVIDIA (CUDA)、AMD (ROCm)、Intel 显卡，以及 Vulkan 后端
  • CPU：纯 CPU 模式亦可运行，但速度较慢
  • 内存：至少 8GB，推荐 16GB 以上
  • 磁盘：至少 20GB 可用空间（用于存放模型文件）

二、安装方式

Unsloth 提供三种使用方式，你可以根据需求选择。

2.1 方式一：Unsloth Desktop（桌面应用，最推荐）

这是最便捷的方式，提供完整的图形界面，适合所有用户。

下载对应操作系统的安装包：

平台 下载链接
Windows 下载 .exe 安装包
macOS 下载 .dmg 安装包
Linux (Ubuntu/Debian) 下载 .deb 安装包
Linux (通用 AppImage) 下载 .AppImage 文件

下载后，双击运行即可完成安装。这是开始使用 Unsloth 最简单的方法。

2.2 方式二：Unsloth Studio（Web UI）

如果你更喜欢在浏览器中使用，或需要进行远程部署，可以选择安装 Unsloth Studio。

macOS / Linux / WSL 用户：

1
curl -fsSL https://unsloth.ai/install.sh | sh

Windows 用户（在 PowerShell 中）：

1
irm https://unsloth.ai/install.ps1 | iex

启动 Studio：
安装完成后，在终端中运行以下命令启动 Web 界面：

1
unsloth studio

浏览器会自动打开 http://localhost:8888（默认端口）。

启用远程 HTTPS 访问（通过 Cloudflare 隧道）：

1
unsloth studio --secure

执行后，你会获得一个公网可访问的 Cloudflare 链接，可以在任何设备（包括手机）上访问。

启用局域网访问：

1
unsloth studio -H 0.0.0.0 -p 8888

然后在 Studio 的 Settings > API keys > LAN access 中开启相关设置。

设置访问密码（用于安全暴露）：

1
2
3
4
5
# 通过环境变量设置密码
UNSLOTH_STUDIO_PASSWORD='你的强密码' unsloth studio --secure

# 或事后重置密码
unsloth studio reset-password

2.3 方式三：Unsloth Core（Python 库，适合开发者）

如果你需要在 Python 脚本或项目中使用 Unsloth 的训练和推理能力，可以安装核心库。

macOS / Linux / WSL：

1
2
3
4
5
6
7
# 安装 uv 包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境并安装 Unsloth
uv venv unsloth_env --python 3.13
source unsloth_env/bin/activate
uv pip install unsloth --torch-backend=auto

Windows (PowerShell)：

1
2
3
4
5
6
7
8
# 安装 Python 3.13 和 uv
winget install -e --id Python.Python.3.13
winget install --id=astral-sh.uv -e

# 创建虚拟环境并安装 Unsloth
uv venv unsloth_env --python 3.13
.\unsloth_env\Scripts\activate
uv pip install unsloth --torch-backend=auto

安装特定后端：
如果你使用 AMD 或 Intel GPU，请参考官方 AMD 指南 和 Intel 指南。

三、Docker 部署（适合服务器）

对于服务器环境，Unsloth 提供了官方 Docker 镜像，支持 GPU 加速。

1
2
3
4
5
6
docker run -d \
  -e JUPYTER_PASSWORD="设置你的密码" \
  -p 8888:8888 -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth

启动后，通过 http://localhost:8888 访问 Jupyter 环境，即可开始使用 Unsloth。

四、高级安装与配置

4.1 开发者/夜间版（从源码安装）

如果你想体验最新功能或进行开发，可以从 GitHub 克隆源码安装。

macOS / Linux / WSL：

1
2
3
4
git clone https://github.com/unslothai/unsloth
cd unsloth
./install.sh --local
unsloth studio -p 8888

Windows PowerShell：

1
2
3
4
5
git clone https://github.com/unslothai/unsloth.git
cd unsloth
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1 --local
unsloth studio -p 8888

4.2 自定义安装选项

安装时，你可以通过环境变量控制安装行为：

  • 跳过 PyTorch（仅 GGUF 模式）：

    1
    curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_NO_TORCH=1 sh

  • 指定 Python 版本：

    1
    curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_PYTHON=3.12 sh

  • 安装到自定义目录：

    1
    curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_STUDIO_HOME=/自定义/路径 sh

  • 强制指定 llama.cpp 后端（用于特定硬件）：

    1
    2
    export UNSLOTH_LLAMA_CPP_BACKEND=vulkan   # 可选: cpu, cuda, rocm, auto
    curl -fsSL https://unsloth.ai/install.sh | sh

4.3 卸载 Unsloth

如果需要完全卸载，可以运行以下命令：

macOS / Linux / WSL：

1
curl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.sh | sh

Windows (PowerShell)：

1
irm https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.ps1 | iex

五、快速使用指南

5.1 运行模型

  1. 打开 Unsloth Desktop 或 Studio。
  2. 在模型库中搜索并下载你需要的模型（如 Qwen3.8、Gemma 4 等）。
  3. 点击“运行”，即可开始对话。

5.2 连接 AI 代理

Unsloth 支持通过一条命令将本地模型连接到 Claude Code、Codex 等代理：

1
2
3
4
5
6
7
8
# 连接 Claude Code
unsloth start claude --model unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL

# 连接 OpenAI Codex
unsloth start codex

# 连接 Hermes Agent
unsloth start hermes

5.3 微调模型

Unsloth 支持 2 倍速、70% 更少显存占用的高效微调（LoRA、QLoRA 等）：

  1. 在 Studio 中进入“训练”选项卡。
  2. 选择基础模型和数据集。
  3. 配置训练参数（如学习率、轮数）。
  4. 点击“开始训练”。

5.4 导出与部署

训练完成后，你可以将模型导出为 GGUF、FP8 等格式，以便在其他平台部署。

六、常见问题排查

问题 可能原因与解决方案
安装脚本执行失败 检查网络连接，确保能访问 unsloth.ai。Windows 用户请以管理员身份运行 PowerShell。
GPU 不可用 1. 确认已安装最新的显卡驱动。 2. 对于 NVIDIA 卡，安装 CUDA Toolkit。 3. 在启动命令前设置 UNSLOTH_LLAMA_CPP_BACKEND=cuda。
启动 Studio 后无法访问 检查防火墙是否放行端口（默认 8888）。如果使用 --secure，检查 Cloudflare 隧道是否成功创建。
模型下载失败 检查磁盘空间是否充足。默认下载目录在 ~/.cache/huggingface/hub/，可检查该目录权限。
训练时显存不足 (OOM) 1. 尝试使用更小的模型或更低的量化级别。 2. 减小批次大小 (batch_size)。 3. 启用梯度检查点 (gradient_checkpointing)。

七、获取帮助与社区

至此，你已经完成了 Unsloth 的部署，并可以开始在本地运行和训练各种先进的 AI 模型了。