ITADN
unslothai/unsloth
代码 动态 Issues2340 合并请求817 版本24
unslothai/unsloth · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

Unsloth 徽标

Unsloth Studio 允许你在本地运行和训练模型。

功能 • 新闻 • 快速入门 • 笔记本 • 文档


unsloth studio ui 主页

⚡ 开始使用

macOS、Linux、WSL：

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

Windows：

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

社区：

⭐ 功能

Unsloth Studio（测试版）允许你在 Windows、Linux 和 macOS 上运行和训练文本、音频、嵌入、视觉模型。

推理

  • 搜索、下载并运行模型，包括 GGUF、LoRA 适配器以及 safetensors 格式的模型。

  • 模型导出：将模型保存或导出为 GGUF、16 位 safetensors 以及其他格式。]

  • 工具调用：支持自愈式工具调用功能以及网页搜索]。

  • 代码执行：允许大型语言模型在 Claude 的专用环境及沙箱环境中测试代码。

  • API 推理端点：借助 Unsloth 在 Claude Code、Codex 等工具中部署并运行本地大型语言模型。

  • 可自动设置推理参数，并自定义聊天模板。]

  • 我们直接与 gpt-oss、Qwen3、Llama 4、Mistral、Gemma 1-3以及Phi-4背后的开发团队合作，修复了诸多问题，从而提升了模型精度。]

  • 支持使用图片、音频、PDF、代码、DOCX 等格式进行聊天。可连接 API 提供商（如 OpenAI、Anthropic）或服务器（如 vLLM、Ollama）。]

  • 可使用相同提示词并排对比任意两个模型。]

  • 兼容 OpenAI/Anthropic 的 API：可通过 /v1/chat/completions、/v1/responses和/v1/messages来运行本地模型。

  • 将本地模型连接到智能体：可在 Claude Code、Codex、Hermes 等工具中使用 unsloth start功能。

  • 网页/PDF 搜索功能可读取 PDF 格式的论文、手册及其他相关内容。

  • GGUF 硬件控制：可选择 GPU/层配置，卸载 MoE 专家模块，同时支持多 GPU 运行或张量并行处理。

  • 可选功能的MCP 控制端点允许 AI 客户端管理模型、训练过程、配置方案以及模型导出操作。### 训练

  • 能够以快 2 倍的速度训练500 多种模型，同时仅占用少 70%的 VRAM 内存；对于 MoE 模型，训练速度更是可提升至快 12 倍。

  • 在 Windows、WSL 和 Linux 环境下的 AMD GPU 上训练并运行强化学习模型。

  • 数据处理功能：可从 PDF、CSV、DOCX 等格式**自动创建数据集**，并通过可视化节点工作流编辑数据。

  • 强化学习 技术在处理 GRPO、FP8 以及视觉强化学习任务时，能减少 80% 的显存占用，同时支持长达 7 倍的上下文长度。

  • 长上下文训练：训练速度提升 3 倍，显存占用减少 30%，且上下文长度可达 50 万以上。

  • 支持 LoRA/QLoRA、完整微调、强化学习、预训练，以及 4 位、16 位和 FP8 格式。

  • 可使用 PyTorch 和 Hugging Face 构建自定义的 Triton 以及数学内核。

  • 可观测性功能：可实时监控训练过程，追踪损失值与 GPU 使用情况，并自定义图表。

  • 支持 多 GPU训练**，相关功能即将迎来重大改进。

🚀 Unsloth 启动

Unsloth Start 可以通过一条命令，将 Claude Code、Codex 以及其他智能体连接到本地模型上。

启动 Unsloth，加载模型，打开你的项目文件夹，然后运行：

unsloth start claude

将 claude 替换为任何受支持的智能体：

智能体命令
Claude Codeunsloth start claude
OpenAI Codexunsloth start codex
Hermes Agentunsloth start hermes
OpenClawunsloth start openclaw
OpenCodeunsloth start opencode

Claude Code、Codex 与 OpenCode 可以保留其当前的模型，并将 Unsloth 作为本地子智能体使用：

unsloth start claude --as-subagent --model unsloth/model-GGUF:quant

📥 安装

Unsloth 有两种使用方式：通过基于网页的用户界面 Unsloth Studio，或通过基于代码的版本 Unsloth Core。两者的系统要求各不相同。

Unsloth Studio（网页界面）

Unsloth Studio（测试版）可在 Windows、Linux、WSL 以及 macOS 上运行。

  • CPU： 目前仅支持聊天功能及数据处理任务。
  • NVIDIA： RTX 30/40/50、Blackwell、DGX Spark、Station 等型号均支持训练功能。
  • macOS： 支持训练、MLX 模型格式推理以及 GGUF 模型格式推理。
  • AMD： 在 Windows、WSL 以及 Linux 系统上支持训练、强化学习、聊天功能以及模型部署。请阅读 AMD 相关指南。]
  • Vulkan： 包括 Intel GPU 在内的兼容 GPU 支持 GGUF 模型的推理功能。Vulkan 仅能加速 GGUF 推理过程；训练功能仍需依赖受支持的 PyTorch 或 MLX 后端。
  • 多 GPU： 目前已支持，未来还将有重大升级。

macOS、Linux、WSL：

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

使用相同的命令即可进行更新。

若要强制使用 Vulkan 版本的 llama.cpp 后端，请在安装或更新之前设置UNSLOTH_FORCE_VULKAN=1。该设置用于选择 llama.cpp 的二进制包，因此仅在启动 Studio 时进行设置无法替代已存在的 CPU 版本包：

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

Windows：

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

使用相同的命令进行更新。

若要强制使用 Vulkan 版本的 llama.cpp 后端，请在运行安装程序或更新工具之前设置环境变量：

$env:UNSLOTH_FORCE_VULKAN=1
irm https://unsloth.ai/install.ps1 | iex

当后端不同时，重新运行当前的安装程序会替换之前选定的 CPU 版本包。无需单独的 Vulkan SDK，只要 GPU 驱动能够提供可用的 Vulkan 运行时即可。

启动

unsloth studio -p 8888

对于局域网或云端访问，需添加-H 0.0.0.0（仅限原始端口；如需公共 URL，请添加--cloudflare）。默认情况下，Unsloth 仅能通过本地访问。

若要通过 HTTPS 访问 Unsloth，请使用unsloth studio --secure。Unsloth 仍绑定在 localhost 上，只能通过免费的 Cloudflare 隧道访问，该隧道会将其发布在公共的https://*.trycloudflare.com URL 下（如果隧道无法启动则连接会失败，因此原始端口永远不会暴露）。这样一来，Unsloth 就可以从互联网上访问，任何拥有该链接和 API 密钥的人都可以使用它并运行代码：请务必妥善保管 API 密钥（详见下文的远程访问部分）。

Docker

请使用我们的 Docker 镜像 unsloth/unsloth 容器]。运行命令：

docker run -d -e JUPYTER_PASSWORD="mypassword" \
  -p 8888:8888 -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth

开发者版、测试版及卸载

如需查看开发者版、测试版以及卸载等相关说明，请参阅高级安装。

Unsloth Core（基于代码）

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 unsloth --torch-backend=auto

在 Windows 系统上，只有安装了 PyTorch 才能使用 pip install unsloth。请阅读我们的 Windows 使用指南。 您可以使用与 Unsloth Studio 相同的 Docker 镜像。

AMD、Intel：

对于 RTX 50x、B200、6000 系列 GPU：uv pip install unsloth --torch-backend=auto。请参阅关于 Blackwell 和 DGX Spark 的指南。
若要在 AMD 和 Intel GPU 上安装 Unsloth，请遵循我们的 AMD 使用指南 和 Intel 使用指南。

📒 免费笔记本

您可以使用我们的笔记本免费进行训练。借助全新的 免费 Unsloth Studio 笔记本，您可以通过网页界面免费运行和训练模型。 请阅读我们的 指南。添加数据集、运行模型，随后即可部署您训练好的模型。

模型免费笔记本性能内存占用
Gemma 4 (E2B)▶️ 免费开始快 1.5 倍降低 50%
Qwen3.5 (4B)▶️ 免费开始快 1.5 倍降低 60%
gpt-oss (20B)▶️ 免费开始快 2 倍降低 70%
Qwen3.5 GSPO▶️ 免费开始快 2 倍降低 70%
gpt-oss (20B): GRPO▶️ 免费开始快 2 倍降低 80%
Qwen3: Advanced GRPO▶️ 免费开始快 2 倍降低 70%
embeddinggemma (300M)▶️ 免费开始快 2 倍降低 20%
Mistral Ministral 3 (3B)▶️ 免费开始快 1.5 倍降低 60%
Llama 3.1 (8B) Alpaca▶️ 免费开始快 2 倍降低 70%
Llama 3.2 Conversational▶️ 免费开始快 2 倍降低 70%
Orpheus-TTS (3B)▶️ 免费开始快 1.5 倍降低 50%

🦥 懒熊新闻

  • AMD 训练：在 Windows、WSL 以及 Linux 环境下的 AMD GPU 上进行训练、运行强化学习模型、开展对话以及部署应用。指南

  • GGUF 硬件控制：可选择 GPU/层的放置位置，将模型中的专家模块卸载到其他设备，同时支持多 GPU 运行或张量并行处理。#6414

  • 适用于各类智能体的本地模型：通过 Unsloth 兼容 OpenAI 与 Anthropic 的 API，结合 Claude Code、Codex、Hermes、OpenCode、OpenClaw 等工具使用 unsloth start 功能。指南

  • MCP 控制端点：让兼容的客户端能够管理模型、训练过程、配置方案、检查点以及导出文件。#7191

  • 本地推理的可靠性：更快地恢复长对话，修复卡住的下载任务，并重复使用现有的 GGUF 文件。#7204 • #6858 • #7209

  • 新模型：Qwen-AgentWorld、Ornith、Kimi K2.7 Code 以及 MiniMax M3

  • GLM-5.2：利用 Unsloth Dynamic GGUF 格式在本地运行 Z.ai 开发的拥有 7440 亿参数、支持 100 万上下文长度的开放模型。指南

  • DeepSeek-V4：在本地运行 DeepSeek-V4-Flash 版本，其多轮对话及工具调用功能已得到优化。指南

  • DiffusionGemma：在 Unsloth Studio 中运行并微调谷歌的扩散语言模型，推理速度可提升 1.8 倍。指南

  • Qwen3.6：通过 MTP 技术运行并训练 Qwen3.6，其推理速度可提升 1.4 到 2.2 倍；同时针对支持的 GPU 还提供了 NVFP4 量化格式。指南

  • Gemma 4：支持 QAT、MTP、GGUF 以及 MLX 格式，可运行并训练 Gemma 4 的文本、图像和音频模型。指南

  • MCP 服务器：通过模型上下文协议将本地模型连接到文件、应用程序、数据库以及外部工具。指南

  • 连接功能：在同一界面中即可将本地模型与 API 提供商（OpenAI、Anthropic）或服务器（vLLM、Ollama）相连接。指南

  • 隆重介绍 Unsloth Studio：我们专为运行和训练大语言模型而打造的全新网页用户界面。博客

  • 以更少的 VRAM 使用量，将 MoE 大语言模型的训练速度提升 12 倍——适用于 DeepSeek、GLM、Qwen 以及 gpt-oss 等模型。博客

  • 嵌入模型功能：Unsloth 现在可使嵌入微调的速度提升约 1.8 到 3.3 倍。博客 • 笔记本

  • 依托全新的批处理算法，其 上下文长度相关的强化学习性能 是其他所有方案的 7 倍。博客

  • 新型的 RoPE 与 MLP Triton 核心以及无填充 + 压缩技术：可使训练速度提升 3 倍，同时减少 30% 的 VRAM 使用量。博客

  • 50 万字符上下文支持：现在在 80GB 的 GPU 上即可训练上下文长度超过 50 万字符的 200 亿参数模型。博客

  • FP8 与视觉强化学习：现在在消费级 GPU 上即可实现 FP8 格式计算以及 VLM GRPO 算法。FP8 博客 • 视觉强化学习

📥 高级安装

以下高级安装指南适用于 Unsloth Studio。如需了解 Unsloth Core 的高级安装方法，请查看我们的文档。

开发者版 / 测试版 / 实验版安装：macOS、Linux、WSL：

开发者版是从 main 分支构建的，该分支代表最新的（测试版）源代码。

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

如需安装到独立位置（即拥有自己的虚拟环境auth/、studio.db、缓存以及 llama.cpp 构建文件），请设置 UNSLOTH_STUDIO_HOME，并在启动时再次传入该值：

UNSLOTH_STUDIO_HOME="$PWD/.studio" ./install.sh --local
UNSLOTH_STUDIO_HOME="$PWD/.studio" unsloth studio -p 8888

之后如需更新：

cd unsloth && git pull
./install.sh --local
unsloth studio -p 8888

开发者版 / 测试版 / 实验版安装：Windows PowerShell：

开发者版是从 main 分支构建的，该分支代表最新的（测试版）源代码。

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

如需安装到独立位置（即拥有自己的虚拟环境auth/、studio.db、缓存以及 llama.cpp 构建文件），请设置 UNSLOTH_STUDIO_HOME，并在启动时再次传入该值：

$env:UNSLOTH_STUDIO_HOME="$PWD\.studio"; .\install.ps1 --local
$env:UNSLOTH_STUDIO_HOME="$PWD\.studio"; unsloth studio -p 8888

之后如需更新：

cd unsloth; git pull
.\install.ps1 --local
unsloth studio -p 8888

远程访问：--secure（HTTPS 隧道）与直接端口

默认情况下，unsloth studio 会绑定到 127.0.0.1（仅限本机）。若要从其他设备访问它，请选择以下其中一种方式：

  • --secure（推荐）：仅通过免费的 Cloudflare HTTPS 链接提供服务。Unsloth 会绑定在本地主机上，隧道负责提供公共 URL；如果隧道无法建立，服务将无法启动，因此原始端口永远不会暴露在外。
unsloth studio --secure -p 8888
  • -H 0.0.0.0：在所有网络接口上绑定原始端口，使得网络中的任何位置都能访问（受防火墙设置限制）。此方式不会生成公共互联网 URL；若希望即使在防火墙后面也能发布可被互联网访问的 https://*.trycloudflare.com 链接，则需搭配使用 --cloudflare。仅在你信任的网络环境中使用此选项。
unsloth studio -H 0.0.0.0 -p 8888

Cloudflare 隧道默认处于关闭状态：-H 0.0.0.0仅会暴露原始端口，而不会提供公共互联网 URL。若想同时发布公共 https://*.trycloudflare.com 链接，可将通配符绑定与 --cloudflare（unsloth studio -H 0.0.0.0 --cloudflare）结合使用；或者选择更安全的 --secure（如上所述）方式，这样原始端口仍会保持私密。--cloudflare 对回环绑定没有影响。

在通配符绑定模式下，Unsloth 会先向 ifconfig.me 查询公共 IP 地址，再向 check-host.net 查询该端口是否可访问，以此判断是否存在防火墙阻隔。这两个查询都需要联系第三方服务。将 UNSLOTH_STUDIO_DISABLE_PUBLIC_CHECK=1 设置为跳过这些查询，此时界面将仅显示局域网地址，而不会显示可访问性信息。

当 Unsloth 首次在公共 URL（--secure 或 --cloudflare）上发布，且仍使用自动生成的管理员密码时，系统会在公共链接正式上线之前，在终端中要求输入新的管理员密码（输入内容会进行遮蔽并需再次确认）。如果没有连接的终端，系统会发出警告并保持启动截止时间：除非在网页界面中更改密码，否则 Unsloth 将在UNSLOTH_STUDIO_BOOTSTRAP_TIMEOUT时间后关闭（默认为 1 小时）。

对于无法响应该提示的无头部署环境，可使用--password以非交互方式设置初始管理员密码（此方式仅在尚未设置密码时有效；如果已存在密码，则会引发严重错误，此时需使用unsloth studio reset-password稍后更换密码）：

unsloth studio --secure --password 'your-strong-password'        # visible in `ps`/history
UNSLOTH_STUDIO_PASSWORD='your-strong-password' unsloth studio --secure   # via env var
printf '%s\n' 'your-strong-password' | unsloth studio --secure --password -   # via stdin

进程列表和 Shell 历史记录中会显示原始的--password VALUE值，因此为了自动化操作，建议使用UNSLOTH_STUDIO_PASSWORD环境变量或--password -（标准输入）。这适用于所有启动方式（公共访问或无头-H 0.0.0.0绑定），且密码是在服务器绑定之前在父进程中设置的，因此不会传递给重新执行的子进程。

服务器端工具（网页搜索、Python 代码执行及终端命令执行）均以您的用户身份运行，默认处于开启状态。任何拥有 API 密钥并能访问服务器的人都可以在这台机器上运行代码，因此请妥善保管 API 密钥，并在公开 Unsloth 时传递--disable-tools参数。

高级启动选项

安装程序的选项可以作为环境变量传递。在 macOS、Linux 和 WSL 系统中，需将变量放在管道之后，这样 Shell 才会将其传递给sh；在 Windows 系统中，则需先使用$env:设置该变量，然后再将其传递给iex。

跳过 PyTorch（仅支持 GGUF 模式）：

curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_NO_TORCH=1 sh
$env:UNSLOTH_NO_TORCH=1; irm https://unsloth.ai/install.ps1 | iex

跳过启动 Unsloth 的安装后提示（适用于自动化安装）：

curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_SKIP_AUTOSTART=1 sh
$env:UNSLOTH_SKIP_AUTOSTART=1; irm https://unsloth.ai/install.ps1 | iex

固定 Python 版本：

curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_PYTHON=3.12 sh
$env:UNSLOTH_PYTHON='3.12'; irm https://unsloth.ai/install.ps1 | iex

使用 UNSLOTH_STUDIO_HOME 安装到自定义位置：

curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_STUDIO_HOME=/abs/path sh
$env:UNSLOTH_STUDIO_HOME='C:\path'; irm https://unsloth.ai/install.ps1 | iex

在 macOS 上，安装程序默认使用系统证书存储库（UV_SYSTEM_CERTS=1），因此 uv 会信任 Keychain 中的证书颁发机构，而这在需要检查 TLS 的代理服务器（如 Cisco Umbrella、Zscaler 等）后端是必需的。如需取消此设置，请使用：

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

使用 UNSLOTH_NPM_REGISTRY 将前端构建指向企业级的 npm 镜像/代理服务器（适用于运行在会阻止 registry.npmjs.org 的防火墙后的开发者环境）：

UNSLOTH_NPM_REGISTRY=https://artifactory.example.com/api/npm/npm/ ./install.sh --local
$env:UNSLOTH_NPM_REGISTRY='https://artifactory.example.com/api/npm/npm/'; .\install.ps1 --local

该功能以 --registry 的形式集成到 Unsloth 前端 npm/bun 的安装过程中；供应链锁定机制（7 天min-release-age锁定、精确版本固定）依然有效。

在核心数较多的主机上限制 Unsloth 的原生 CPU 线程池数量：UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888。

卸载

彻底移除 Unsloth Studio 的推荐方法是使用对应操作系统的卸载脚本。该脚本会停止所有正在运行的服务器，删除安装目录、启动器数据目录、桌面快捷方式以及所有平台特定的条目（macOS 的.app捆绑包及 Mac 上的启动服务；Windows 的开始菜单、HKCU\Software\Unsloth注册表项以及用户PATH条目）：

  • ​ 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

如果您只想删除安装目录，以便日后重新安装时还能保留启动器/快捷方式，可以运行 rm -rf ~/.unsloth/studio（Mac/Linux/WSL）或 Remove-Item -Recurse -Force "$HOME\.unsloth\studio"（Windows）。这些脚本不会影响位于 ~/.cache/huggingface 的模型缓存。

如需更多信息，请查看我们的文档。

删除模型文件

您可以通过模型搜索界面中的“bin”图标来删除旧的模型文件，或者从默认的 Hugging Face 缓存目录中移除相应的缓存模型文件夹。默认情况下，Hugging Face 使用的路径为：

  • ​ MacOS、Linux、WSL： ~/.cache/huggingface/hub/
  • ​ Windows： %USERPROFILE%\.cache\huggingface\hub\

💚 社区与链接

类型链接
  Discord加入 Discord 服务器
  r/unsloth Reddit加入 Reddit 社区
📚 文档与 Wiki阅读我们的文档
  Twitter（又名 X）在 X 上关注我们
🔮 我们的模型Unsloth 产品目录
✍️ 博客阅读我们的博客

引用来源

您可以按如下方式引用 Unsloth 仓库：

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

如果您使用 🦥Unsloth 训练了模型，就可以使用这个超酷的贴纸！  

许可证

Unsloth 采用 Apache 2.0 和 AGPL-3.0 双许可证模式。核心的 Unsloth 包仍遵循 Apache 2.0 许可证，而某些可选组件，例如 Unsloth Studio UI，则遵循开源许可证 AGPL-3.0。

这种架构有助于持续推动 Unsloth 的开发，同时保持项目的开源性质，让更广泛的生态系统得以持续发展。

致谢

  • llama.cpp 库，它让用户能够使用 Unsloth 运行和保存模型
  • Hugging Face 团队及其相关库：transformers 和 TRL
  • Pytorch 及 Torch AO 团队为该项目做出的贡献
  • NVIDIA 提供的 NeMo DataDesigner 库及其贡献
  • 当然，还要感谢所有为 Unsloth 做出贡献或使用过它的每一个人！