Unsloth：2 倍速度微调大模型显存优化指南

unslothai/unsloth 是大模型生态中备受关注的开源项目，实时 Star 数约 78.6k。本文基于官方 README 完整翻译整理，从项目定位、核心特性、全部安装方式、命令行用法、环境变量开关到卸载方法进行全面说明，帮助开发者在本地快速跑起并训练大模型。

Unsloth 的定位是「第一个可以在桌面端运行并训练模型的应用」。它把原本需要云端 A100 集群才能完成的微调工作，压缩到消费级显卡甚至笔记本上即可完成：官方宣称训练速度提升 2 倍、显存占用降低 70%，且不损失精度。项目同时提供三种形态：面向普通用户的 Unsloth Desktop 桌面应用、面向工作流的 Unsloth Studio 网页 UI，以及面向工程师的 Unsloth Core 代码库。

从技术栈看，Unsloth 底层依赖 llama.cpp 完成模型加载与 GGUF 推理，上层与 Hugging Face 的 transformers、TRL 库深度兼容，微调后的模型可以无缝导出到 PyTorch、vLLM、llama.cpp 等生态。对国内开发者而言，它最大的价值在于：一张 24GB 显存的游戏卡就能完成 7B 级模型的全流程微调，并用免费的 Colab Notebook 跑通从数据集到导出的完整链路，不需要申请任何云额度。

适合人群包括三类：一是想在本地跑大模型做日常编程助手的个人开发者，用 Desktop 或 Studio 把 Qwen、DeepSeek 等模型接到 Claude Code、Codex 即可；二是有垂直领域微调需求的算法工程师，用 Core 版在脚本里跑 LoRA/GRPO/DPO；三是对数据隐私敏感的小企业，通过 Cloudflare 隧道把家里的工作站变成私有模型服务器。下面按安装方式、启动命令、环境变量与卸载方法逐一说明，所有命令与版本号均与官方 README 一致，端口、镜像名、环境变量名均照抄官方文档，不做任何臆造。

一、项目官方信息

需要注意的是，Unsloth 采用双重许可结构：核心 Python 包仍然是宽松的 Apache 2.0，允许商业集成；而 Studio 图形界面等可选组件采用 AGPL-3.0，衍生作品需开源。这种结构既支持生态持续商业化，又保持了核心库的开放。

二、官方图片

封面取 GitHub 仓库官方图，本文不重复贴图。项目视觉素材见 仓库 images 目录，包含黑白两版 Logo、训练速度对比图与「Made with Unsloth」贴纸——用 Unsloth 训练完模型后，作者鼓励在项目 README 里贴这枚贴纸作为致谢。

三、环境要求

Unsloth 桌面版支持 Windows、Linux、WSL 与 macOS，覆盖 多 GPU 组网、NVIDIA、AMD、Intel GPU、CPU 以及 Vulkan 后端。三种使用形态的要求如下：

• Unsloth Desktop（推荐）：原生桌面应用，Windows 提供 x64 与 ARM64 安装包，macOS 提供 dmg，Linux 提供 deb 与 AppImage；无需手动配置 Python 环境，下载安装即可用。
• Unsloth Studio（网页 UI）：通过一键脚本安装，Linux/macOS/WSL 用 curl 脚本，Windows 用 PowerShell 脚本；GPU 机器可选择额外安装 NVIDIA Container Toolkit 以获得容器内 GPU 访问能力。
• Unsloth Core（代码版）：要求 Python 3.13（官方示例使用 uv 创建 unsloth_env --python 3.13），Windows 上需先单独安装 torchao 再安装 unsloth，否则会静默回退到旧版本。

此外，模型权重默认缓存在 Hugging Face 目录：macOS/Linux/WSL 为 ~/.cache/huggingface/hub/，Windows 为 %USERPROFILE%\.cache\huggingface\hub\，按模型大小预留几十 GB 磁盘空间。内存方面，跑 7B 级模型建议 32GB 系统内存起步；跑 20B 级模型建议 64GB 以上；只做 GGUF 推理时对显存要求最低，4-bit 量化后 8GB 显存即可加载小模型。网络上需要能访问 Hugging Face Hub 或官方 CDN 以下载模型权重，国内用户可自行配置 HF 镜像端点。AMD 与 Intel GPU 请分别参考 AMD 指南 与 Intel 指南，Blackwell 与 DGX Spark 机型见 Blackwell 指南 与 DGX Spark 指南。

四、项目结构与版本要求

从仓库结构看，主仓库 unslothai/unsloth 包含：安装脚本 install.sh / install.ps1、Docker 目录（含 NVIDIA Toolkit 一键安装脚本）、Studio 前端源码、scripts/uninstall.sh 等卸载脚本，以及 images 视觉素材目录。Notebook 单独放在 unslothai/notebooks 仓库，音频引擎另有 unslothai/audio.cpp 预构建仓库。

版本要求方面，Unsloth Core 官方示例锁定 Python 3.13；Studio 与 Desktop 内置运行时无需关心 Python 版本；GGUF 模式可跳过 PyTorch 安装以节省磁盘；Windows 用户必须先装 torchao；AMD 与 Intel GPU 走独立指南。

五、完整部署步骤

1. 下载桌面应用（最快上手）

从 Unsloth 官网下载页 或 GitHub Releases 直接下载对应平台的安装包，双击安装即可：

2. 脚本一键安装 Studio

macOS、Linux、WSL 执行：

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

Windows（PowerShell）执行：

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

也可使用系统包管理器：macOS 上用 Homebrew：

brew install --cask unsloth

Windows 上用 winget：

winget install --id UnslothAI.Unsloth -e

3. Docker 部署

官方镜像 unsloth/unsloth 已发布在 Docker Hub，完整说明见 Docker 部署指南。Linux 与 macOS 首次使用需一次性配置 NVIDIA Container Toolkit：

curl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/docker/install_nvidia_toolkit.sh -o install_nvidia_toolkit.sh && sudo -E bash install_nvidia_toolkit.sh

随后启动容器（Linux / WSL）：

# 如需公开 Cloudflare HTTPS 链接：用 -e UNSLOTH_STUDIO_SECURE=1 替代 -p 8000:8000，
# 并用 -p 127.0.0.1:8888:8888 替代 -p 8888:8888
docker run -d --name unsloth --gpus all --ipc=host \
  -p 8000:8000 -p 8888:8888 \
  -v "$PWD":/workspace/host \
  -v unsloth-workspace:/workspace \
  -v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
  -v unsloth-studio:/opt/unsloth-studio \
  unsloth/unsloth && docker logs -f unsloth

这条命令做了几件事：把宿主机当前目录挂到容器内 /workspace/host 方便读写，把 Hugging Face 缓存挂进去避免重复下载模型，把 Studio 工作区与配置持久化到两个 volume，保证容器重启后数据集和设置不丢失。--gpus all 把宿主机全部 GPU 透传进容器，--ipc=host 是为了让多进程训练共享内存正常工作。只跑 notebook 可使用 unsloth/unsloth:core 轻量标签，全部标签见 Docker Hub；AMD 用户使用单独镜像 unsloth/unsloth-rocm。Windows 下的 Docker 安装细节与排错见官方 Unsloth Docker 指南。

4. 源码 / 开发版安装

开发版从 main 分支构建（即最新 nightly 源码），适合想尝鲜或二次开发的用户。macOS、Linux、WSL：

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

Windows PowerShell：

git clone https://github.com/unslothai/unsloth.git
cd unsloth
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
.\install.ps1 --local
unsloth studio -p 8888

后续更新只需进入目录执行 git pull，再重新跑一遍安装脚本即可。若想把安装目录隔离到本地，可设置 UNSLOTH_STUDIO_HOME 环境变量，例如 UNSLOTH_STUDIO_HOME="$PWD/.studio" ./install.sh --local。

5. Unsloth Core 代码版

不想用 GUI、只在 Python 脚本里微调模型的用户，安装代码版即可。Linux、WSL：

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv unsloth_env --python 3.13
source unsloth_env/bin/activate
uv pip install unsloth --torch-backend=auto

Windows：

winget install -e --id Python.Python.3.13
winget install --id=astral-sh.uv  -e
uv venv unsloth_env --python 3.13
.\unsloth_env\Scripts\activate
uv pip install torchao
uv pip install unsloth --torch-backend=auto

这里有一个 Windows 专属坑：必须先单独安装 torchao。因为 --torch-backend 只在 PyTorch 官方索引里查找 torchao，而该索引没有较新的 Windows 版本，一步到位安装会静默解析到旧版 Unsloth，功能缺失且难以排查。

六、使用方法

1. 启动 Studio

unsloth studio

安全部署（自动创建免费 Cloudflare 公网链接，手机也能访问）：

unsloth studio --secure

绑定指定网卡与端口：

unsloth studio -H 0.0.0.0 -p 8888

局域网访问可在网页端 设置 > API keys > LAN access 中开启，开启后同一 Wi-Fi 下的手机、平板都能直接访问本机模型，相当于把家里的电脑变成一台私人 ChatGPT 服务器。需要特别注意：服务端工具默认开启，对外暴露时这意味着任何人拿到链接都能让你的机器执行工具调用，因此务必保管好密码，或者在暴露时加 --disable-tools 关闭服务端工具。

2. 密码管理与无交互启动

对外暴露 Unsloth（--secure、--cloudflare 或非回环地址 -H）时，终端会提示一次新管理员密码；此时按 Ctrl+C 会中止启动，而不会暴露自动生成的密码。想在脚本里无人值守启动，用环境变量预设：

UNSLOTH_STUDIO_PASSWORD='your-strong-password' unsloth studio --secure

忘记密码时重置：

unsloth studio reset-password

3. 一键接入 Agent 工具

Unsloth Start 一条命令即可把本地模型接到 Claude Code、Codex 等编程 Agent，例如：

unsloth start claude --model unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL

各 Agent 对应命令如下：

4. 核心能力一览

• 运行与训练多类模型：支持 LLM、MLX、GGUF、扩散模型、决策模型、嵌入模型与音频模型，覆盖 Qwen3.8、GLM-5.3-Flash、Kimi K3、Qwen-Image-2.1、MiniMax-H3、DeepSeek-V4、Gemma 4 等主流开源模型。
• Agent 与工具调用：本地模型可配合 Claude Code、Codex 与 MCP，完整支持工具调用与代码执行，等于在本地复刻一套 Cursor 式工作流。
• 搜索与 RAG：内置私有无限制网页搜索、深度研究、自动压缩（滚动上下文窗口）与 RAG，长对话不会被上下文窗口截断。
• 图像视频：运行与训练 图像/视频扩散模型或多模态模型。
• 远程与局域网访问：通过 LAN 或 Cloudflare HTTPS 安全远程访问，把家里的工作站变成随处可访问的模型服务器。
• 兼容 API：对外提供 OpenAI 兼容 API，现有调用 OpenAI SDK 的代码只需改 base_url 即可切到本地模型；也可反向接入 ChatGPT/Codex 订阅与 云厂商连接。
• 微调加速：LLM、扩散、决策、TTS、嵌入模型训练速度提升 2 倍、显存降低 70%，官方数据称精度无损；支持 强化学习、LoRA、QLoRA、全量微调、预训练、RL、GRPO、DPO 与 FP8。
• 导出与部署：支持 GGUF、NVFP4、FP8 等格式 导出与部署，微调完可直接导出给 llama.cpp、vLLM 等推理框架。
• 数据集构建：通过 Data Recipes 从 PDF、CSV、DOCX 等文件直接构建训练数据集。

典型工作流是这样的：先用 Desktop 或 Studio 在图形界面里下载一个开源底座模型，通过 Data Recipes 把业务 PDF、CSV 或 DOCX 整理成数据集，选择 LoRA 或 QLoRA 方式微调（显存不足时自动降精度），训练完直接在同一个界面里对话测试，满意后导出 GGUF 或 OpenAI 兼容 API 部署。整个流程不离开本机，数据不出内网，这也是 Unsloth 主打「桌面端」的核心卖点——对隐私敏感的企业和个人开发者尤其友好。

5. 环境变量与高级安装开关

官方提供了一组安装期与运行期环境变量，方便自动化部署与企业定制：

• 跳过 PyTorch（仅 GGUF 模式）：安装时设置 UNSLOTH_NO_TORCH=1，只需要 GGUF 推理时可大幅节省安装体积。
• 跳过安装后自动启动提示：UNSLOTH_SKIP_AUTOSTART=1，适合 CI/CD 自动化安装。
• 隔离 uv 缓存：UNSLOTH_ISOLATE_UV_CACHE=1（本地运行对应 --isolated-uv-cache），把安装期包缓存放进 Studio 目录而不是复用全局 uv 缓存；首次下载较慢，但环境完全自包含。
• 重装不回滚旧环境：UNSLOTH_INSTALL_NO_ROLLBACK=1（对应 --no-rollback），默认重装会新旧环境并存直到新版验证通过，这个开关直接丢弃旧环境，磁盘只占一份，但失败无法回退。
• 固定 Python 版本：UNSLOTH_PYTHON=3.12。
• 自定义安装目录：UNSLOTH_STUDIO_HOME=/abs/path。
• 企业 npm 镜像：UNSLOTH_NPM_REGISTRY 指向内网 npm 代理，解决前端构建拉不到包的问题。
• 限制 CPU 线程池：在高核数主机上用 UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888 限制原生线程池大小，避免抢满整机 CPU。
• 强制推理后端：export UNSLOTH_LLAMA_CPP_BACKEND=vulkan（可选 cpu、cuda、rocm、auto），强制使用 Vulkan 或其他后端。
• audio.cpp 音频引擎：UNSLOTH_SKIP_AUDIO_CPP_INSTALL=1 可跳过安装；UNSLOTH_AUDIO_CPP_ACCELERATOR=cpu/cuda/vulkan/metal 指定加速后端；AUDIOCPP_SERVER_PATH=/path/to/audiocpp_server 使用自建的 audiocpp_server 二进制。

七、免费 Notebook 与 FAQ

官方提供大量 Colab 免费 Notebook，涵盖决策模型、视觉模型、GRPO 强化学习、嵌入模型、TTS 等场景，使用方法见 微调指南，添加数据集、点运行、部署模型即可走完全流程。全部模型目录见 Unsloth Model Catalog，全部 Notebook 见 Notebooks 汇总。

官方 Notebook 实测效果对照如下（性能与显存数据均来自 README）：

此外，Kaggle 版 Notebook、GRPO 推理强化学习、TTS 语音合成、嵌入微调与视觉多模态专题分别见官方文档的 Kaggle Notebooks、GRPO 专题、TTS 专题、嵌入微调 与 视觉多模态 章节。对新手来说，建议从 Unsloth Studio 官方 Colab 开始，它把模型下载、数据集上传、训练按钮、导出向导全做成了图形界面，最不容易踩坑。

常见问题解答：

• 如何卸载？ macOS/WSL/Linux 执行 curl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.sh | sh；Windows PowerShell 执行 irm https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.ps1 | iex。
• 如何删除旧模型文件？ 在模型搜索页点垃圾桶图标，或手动删除 Hugging Face 缓存目录（~/.cache/huggingface/hub/ 或 %USERPROFILE%\.cache\huggingface\hub\）下对应的模型文件夹。
• Windows 安装后 Unsloth 版本过旧、功能缺失？ 先单独执行 uv pip install torchao，再安装 unsloth，不要一步到位。
• 对外暴露后不放心安全？ 用 --disable-tools 关闭服务端工具，或只绑定回环地址 -H 127.0.0.1，配合 SSH 隧道访问。
• 训练完的模型怎么交付给业务？ 用导出功能转成 GGUF、NVFP4 或 FP8 格式，再交给 vLLM、llama.cpp 或自家推理服务，导出路径见 Studio 导出文档。
• 没有 NVIDIA 显卡能玩吗？ 可以。AMD 走 AMD 指南，Intel GPU 走 Intel 指南，CPU 与 Vulkan 后端也受支持，只是速度慢一些。
• 安装问题看哪里？ 完整文档见 unsloth.ai/docs，Core 版高级安装问题见 高级安装文档，社区问题可在 Discord 或 Reddit 提问。

八、跳转链接

本文所有命令与版本号均来自官方 README，转载或二次使用前建议先核对双重许可协议（核心 Apache 2.0、Studio UI 为 AGPL-3.0）。更多入口：

• 官方网站与下载：unsloth.ai/download
• 完整文档：unsloth.ai/docs
• GitHub 仓库：unslothai/unsloth
• GitHub Releases：下载页面
• Docker 镜像：unsloth/unsloth
• 博客：unsloth.ai/blog
• 致谢与依赖：llama.cpp、transformers、TRL、NeMo DataDesigner

引用方式：

@software{unsloth,
  author = {Daniel Han, Michael Han and Unsloth team},
  title = {Unsloth},
  url = {https://github.com/unslothai/unsloth},
  year = {2023}
}