> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/unslothai/unsloth) · [上游 README](https://github.com/unslothai/unsloth/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Unsloth logo

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

功能 • 快速开始 • Notebooks • 文档


unsloth studio ui homepage ## ⚡ 快速开始 #### macOS、Linux、WSL： ```bash curl -fsSL https://unsloth.ai/install.sh | sh ``` #### Windows： ```powershell irm https://unsloth.ai/install.ps1 | iex ``` #### 社区： - [Discord](https://discord.gg/unsloth) - [𝕏 (Twitter)](https://x.com/UnslothAI) - [Reddit](https://reddit.com/r/unsloth) ## ⭐ 功能 Unsloth Studio（Beta）让你在 Windows、Linux 和 macOS 上运行和训练文本、[音频](https://unsloth.ai/docs/basics/text-to-speech-tts-fine-tuning), [嵌入](https://unsloth.ai/docs/new/embedding-finetuning), [视觉](https://unsloth.ai/docs/basics/vision-fine-tuning) 模型。 ### 推理 * **搜索、下载并运行模型**，包括 GGUF、LoRA adapters、safetensors * **导出模型**：[保存或导出](https://unsloth.ai/docs/new/studio/export) 模型为 GGUF、16-bit safetensors 及其他格式。 * **工具调用（Tool calling）**：支持 [自愈式工具调用](https://unsloth.ai/docs/new/studio/chat#auto-healing-tool-calling) 与网页搜索 * **[代码执行](https://unsloth.ai/docs/new/studio/chat#code-execution)**: 让 LLM 在 Claude artifacts 和沙箱环境中测试代码 * **[API 推理端点](https://unsloth.ai/docs/basics/api)**: 部署并在 Claude Code、Codex 工具中运行本地 LLM，配合 Unsloth 使用 * [自动设置推理参数](https://unsloth.ai/docs/new/studio/chat#auto-parameter-tuning) 并自定义聊天模板。 * 我们与 [gpt-oss](https://docs.unsloth.ai/new/gpt-oss-how-to-run-and-fine-tune#unsloth-fixes-for-gpt-oss), [Qwen3](https://www.reddit.com/r/LocalLLaMA/comments/1kaodxu/qwen3_unsloth_dynamic_ggufs_128k_context_bug_fixes/), [Llama 4](https://github.com/ggml-org/llama.cpp/pull/12889), [Mistral](https://huggingface.co/mistralai/Mistral-Medium-3.5-128B/discussions/18), [Gemma 1-3](https://news.ycombinator.com/item?id=39671146), 和 [Phi-4](https://unsloth.ai/blog/phi4), 背后的团队直接合作，修复了可提升模型准确性的 bug。 * 支持图片、音频、PDF、代码、DOCX 等聊天。[连接 API 提供商](https://unsloth.ai/docs/integrations/connections)（OpenAI、Anthropic）或服务器（vLLM、Ollama）。 ### 训练 * 训练与 RL **500+ 模型**，速度最高可达 **2 倍**，显存占用最多减少 **70%**，且不损失精度。 * 自定义 Triton 与数学 **kernels**。查看我们与 [PyTorch](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide/fp8-reinforcement-learning) 和 [Hugging Face](https://unsloth.ai/docs/new/faster-moe). 的部分合作 * **Data Recipes**：从 **PDF、CSV、DOCX** 等 [自动创建数据集](https://unsloth.ai/docs/new/studio/data-recipe)。在可视化节点工作流中编辑数据。 * **[强化学习](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide)**（Reinforcement Learning，RL）：最高效的 [RL](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide) 库，GRPO、[FP8](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide/fp8-reinforcement-learning) 等场景显存占用减少 **80%**。 * 支持全量微调、RL、预训练，以及 4-bit、16-bit 和 FP8 训练。 * **可观测性（Observability）**：实时监控训练，跟踪 loss 与 GPU 使用情况，并自定义图表。 * 支持 [多 GPU](https://unsloth.ai/docs/basics/multi-gpu-training-with-unsloth) 训练，重大改进即将推出。 ## 📥 安装 Unsloth 有两种使用方式：通过 **[Unsloth Studio](https://unsloth.ai/docs/new/studio/)**, 网页 UI，或通过 **Unsloth Core** 代码版。两者要求不同。 ### Unsloth Studio（网页 UI） Unsloth Studio（Beta）支持 **Windows、Linux、WSL** 和 **macOS**。 * **CPU：** 当前支持 Chat 与 Data Recipes * **NVIDIA：** 训练支持 RTX 30/40/50、Blackwell、DGX Spark、Station 等 * **macOS：** 训练、MLX 与 GGUF 推理均支持。 * **AMD：** 支持 Chat + Data。训练请使用 [Unsloth Core](#unsloth-core-code-based)。Studio 支持即将推出。 * **Multi-GPU：** 现已可用，重大升级即将到来 #### macOS、Linux、WSL： ```bash curl -fsSL https://unsloth.ai/install.sh | sh ``` 使用相同命令进行更新。 #### Windows： ```powershell irm https://unsloth.ai/install.ps1 | iex ``` 使用相同命令进行更新。 #### 启动 ```bash unsloth studio -p 8888 ``` 如需云访问或全球访问，请添加 `-H 0.0.0.0`。默认情况下，Unsloth 仅在本地可访问。 要通过 HTTPS 访问 Studio，请使用 `unsloth studio --secure`。Studio 仍绑定在 localhost 上，仅通过免费的 Cloudflare 隧道（tunnel）访问，该隧道会将其发布到公开的 `https://*.trycloudflare.com` URL（如果隧道无法启动则会安全失败，因此原始端口绝不会暴露）。这使得 Studio 可从互联网访问，因此任何拥有链接和 API key 的人都可以使用并运行代码：请妥善保管你的 API key（见下文「远程访问」）。 #### Docker 使用我们的 [Docker 镜像](https://hub.docker.com/r/unsloth/unsloth) ```unsloth/unsloth``` 容器。运行： ```bash 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 ``` #### Developer, Nightly, Uninstall To see developer, nightly and uninstallation etc. instructions, see [advanced installation](#-advanced-installation). ### Unsloth Core (code-based) #### Linux, WSL: ```bash 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： ```powershell 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 指南](https://unsloth.ai/docs/get-started/install/windows-installation). 你可以使用与 Unsloth Studio 相同的 Docker 镜像。 #### AMD、Intel： 对于 RTX 50x、B200、6000 GPU：`uv pip install unsloth --torch-backend=auto`。请参阅我们的指南：[Blackwell](https://unsloth.ai/docs/blog/fine-tuning-llms-with-blackwell-rtx-50-series-and-unsloth) 和 [DGX Spark](https://unsloth.ai/docs/blog/fine-tuning-llms-with-nvidia-dgx-spark-and-unsloth).
若要在 **AMD** 和 **Intel** GPU 上安装 Unsloth，请参阅我们的 [AMD 指南](https://unsloth.ai/docs/get-started/install/amd) 和 [Intel 指南](https://unsloth.ai/docs/get-started/install/intel). ## 📒 免费 Notebooks 使用我们的 notebooks 免费训练。你可以使用全新的 [免费 Unsloth Studio notebook](https://colab.research.google.com/github/unslothai/unsloth/blob/main/studio/Unsloth_Studio_Colab.ipynb) 在 Web UI 中免费运行并训练模型。 阅读我们的[指南](https://unsloth.ai/docs/get-started/fine-tuning-llms-guide). 添加数据集、运行，然后部署你训练好的模型。 | 模型 | 免费 Notebooks | 性能 | 内存占用 | |-----------|---------|--------|----------| | **Gemma 4 (E2B)** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma4_(E2B)-Vision.ipynb) | 快 1.5 倍 | 减少 50% | | **Qwen3.5 (4B)** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_5_(4B)_Vision.ipynb) | 快 1.5 倍 | 减少 60% | | **gpt-oss (20B)** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/gpt-oss-(20B)-Fine-tuning.ipynb) | 快 2 倍 | 减少 70% | | **Qwen3.5 GSPO** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_5_(4B)_Vision_GRPO.ipynb) | 快 2 倍 | 减少 70% | | **gpt-oss (20B): GRPO** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/gpt-oss-(20B)-GRPO.ipynb) | 快 2 倍 | 减少 80% | | **Qwen3: Advanced GRPO** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_(4B)-GRPO.ipynb) | 快 2 倍 | 减少 70% | | **embeddinggemma (300M)** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/EmbeddingGemma_(300M).ipynb) | 快 2 倍 | 减少 20% | | **Mistral Ministral 3 (3B)** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Ministral_3_VL_(3B)_Vision.ipynb) | 快 1.5 倍 | 减少 60% | | **Llama 3.1 (8B) Alpaca** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Llama3.1_(8B)-Alpaca.ipynb) | 快 2 倍 | 减少 70% | | **Llama 3.2 Conversational** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Llama3.2_(1B_and_3B)-Conversational.ipynb) | 快 2 倍 | 减少 70% | | **Orpheus-TTS (3B)** | [▶️ 免费开始](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Orpheus_(3B)-TTS.ipynb) | 快 1.5 倍 | 减少 50% | - 查看我们所有相关 Notebook：[Kaggle](https://github.com/unslothai/notebooks?tab=readme-ov-file#-kaggle-notebooks), [GRPO](https://unsloth.ai/docs/get-started/unsloth-notebooks#grpo-reasoning-rl-notebooks), [TTS](https://unsloth.ai/docs/get-started/unsloth-notebooks#text-to-speech-tts-notebooks), [embedding](https://unsloth.ai/docs/new/embedding-finetuning) 与 [Vision](https://unsloth.ai/docs/get-started/unsloth-notebooks#vision-multimodal-notebooks) - 查看[我们所有模型](https://unsloth.ai/docs/get-started/unsloth-model-catalog) 以及[我们所有 Notebook](https://unsloth.ai/docs/get-started/unsloth-notebooks) - 查看 Unsloth 详细文档请[点击此处](https://unsloth.ai/docs) ## 🦥 Unsloth 动态 - **Connections（连接）**：连接任意 API 提供商（OpenAI、Anthropic）或服务器（vLLM、Ollama）。[指南](https://unsloth.ai/docs/integrations/connections) - **MTP**：在 Unsloth 中运行 Qwen3.6 MTP。MTP 设置会根据你的硬件自动配置。[指南](https://unsloth.ai/docs/models/qwen3.6#mtp-guide) - **API 推理端点**：在 Claude Code、Codex 工具中部署并运行本地 LLM。[指南](https://unsloth.ai/docs/basics/api) - **Qwen3.6**：现可在 Unsloth Studio 中训练和运行 Qwen3.6-35B-A3B。[博客](https://unsloth.ai/docs/models/qwen3.6) - **Gemma 4**：直接在 Unsloth 中运行和训练 Google 的新模型。[博客](https://unsloth.ai/docs/models/gemma-4) - **推出 Unsloth Studio**：我们用于运行和训练 LLM 的全新 Web UI。[博客](https://unsloth.ai/docs/new/studio) - **Qwen3.5** - 现已支持 0.8B、2B、4B、9B、27B、35-A3B、112B-A10B。[指南 + Notebook](https://unsloth.ai/docs/models/qwen3.5/fine-tune) - 训练 **MoE LLM 速度提升 12 倍**，VRAM 减少 35%——支持 DeepSeek、GLM、Qwen 和 gpt-oss。[博客](https://unsloth.ai/docs/new/faster-moe) - **Embedding 模型**：Unsloth 现支持快约 1.8–3.3 倍的 embedding 微调。[博客](https://unsloth.ai/docs/new/embedding-finetuning) • [Notebook](https://unsloth.ai/docs/get-started/unsloth-notebooks#embedding-models) - 通过全新批处理算法，**上下文 RL 长度可达其他方案的 7 倍**。[博客](https://unsloth.ai/docs/new/grpo-long-context) - 全新 RoPE 与 MLP **Triton Kernel**，以及 **Padding Free + Packing**：训练速度提升 3 倍，VRAM 减少 30%。[博客](https://unsloth.ai/docs/new/3x-faster-training-packing) - **500K 上下文**：现可在 80GB GPU 上训练上下文超过 500K 的 20B 模型。[博客](https://unsloth.ai/docs/blog/500k-context-length-fine-tuning) - **FP8 与 Vision RL**：现可在消费级 GPU 上进行 FP8 和 VLM GRPO。[FP8 博客](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide/fp8-reinforcement-learning) • [Vision RL](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide/vision-reinforcement-learning-vlm-rl) ## 📥 高级安装 以下高级安装说明适用于 Unsloth Studio。有关 Unsloth Core 的高级安装，请[查看我们的文档](https://unsloth.ai/docs/get-started/install/pip-install#advanced-pip-installation). #### 开发者 / Nightly / 实验性安装：macOS、Linux、WSL： 开发者安装从 `main` 分支构建，该分支为最新（nightly）源码。 ```bash git clone https://github.com/unslothai/unsloth cd unsloth ./install.sh --local unsloth studio -p 8888 ``` 若要安装到独立位置（拥有独立的虚拟环境、`auth/`、`studio.db`、缓存和 llama.cpp 构建），请设置 `UNSLOTH_STUDIO_HOME`，并在启动时再次传入： ```bash UNSLOTH_STUDIO_HOME="$PWD/.studio" ./install.sh --local UNSLOTH_STUDIO_HOME="$PWD/.studio" unsloth studio -p 8888 ``` 然后更新： ```bash cd unsloth && git pull ./install.sh --local unsloth studio -p 8888 ``` #### 开发者 / Nightly / 实验性安装：Windows PowerShell： 开发者安装从 `main` 分支构建，该分支为最新（nightly）源码。 ```powershell 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`，并在启动时再次传入： ```powershell $env:UNSLOTH_STUDIO_HOME="$PWD\.studio"; .\install.ps1 --local $env:UNSLOTH_STUDIO_HOME="$PWD\.studio"; unsloth studio -p 8888 ``` 然后更新： ```powershell cd unsloth; git pull .\install.ps1 --local unsloth studio -p 8888 ``` #### 远程访问：`--secure`（HTTPS 隧道）与原始端口 默认情况下，`unsloth studio` 绑定到 `127.0.0.1`（仅本机可访问）。若要从其他设备访问，请选择以下方式之一： - `--secure`（推荐）：**仅**通过免费的 Cloudflare HTTPS 链接提供服务。Studio 仍绑定到 localhost，隧道提供公共 URL；若隧道无法建立则失败关闭（不会启动），因此原始端口永远不会暴露。 ```bash unsloth studio --secure -p 8888 ``` - `-H 0.0.0.0`：在所有网络接口上绑定原始端口，可从网络中任意位置访问。默认情况下还会启动公共 Cloudflare 快速隧道，即使在防火墙后也会发布可通过互联网访问的 `https://*.trycloudflare.com` URL。原始端口和隧道都会将 Studio 暴露在本机之外，因此仅在你信任的网络中使用；传入 `--no-cloudflare` 可移除公共链接，同时保留网络绑定。 ```bash unsloth studio -H 0.0.0.0 -p 8888 ``` 服务端工具（网页搜索、Python 与终端代码执行）以你的用户身份运行，且默认开启。任何能使用 API 密钥访问服务器的人都可以在这台机器上运行代码，因此请妥善保管 API 密钥，在暴露 Studio 时传入 `--disable-tools`。 #### 高级启动选项 安装器选项可通过环境变量传入。在 macOS、Linux 和 WSL 上，将变量放在管道符之后，以便 shell 将其传递给 `sh`；在 Windows 上，在管道传递给 `iex` 之前使用 `$env:` 设置。 跳过 PyTorch（仅 GGUF 模式）： ```bash curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_NO_TORCH=1 sh ``` ```powershell $env:UNSLOTH_NO_TORCH=1; irm https://unsloth.ai/install.ps1 | iex ``` 跳过安装后启动 Studio 的提示（适用于自动化安装）： ```bash curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_SKIP_AUTOSTART=1 sh ``` ```powershell $env:UNSLOTH_SKIP_AUTOSTART=1; irm https://unsloth.ai/install.ps1 | iex ``` 固定 Python 版本： ```bash curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_PYTHON=3.12 sh ``` ```powershell $env:UNSLOTH_PYTHON='3.12'; irm https://unsloth.ai/install.ps1 | iex ``` 使用 `UNSLOTH_STUDIO_HOME` 安装到自定义位置： ```bash curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_STUDIO_HOME=/abs/path sh ``` ```powershell $env:UNSLOTH_STUDIO_HOME='C:\path'; irm https://unsloth.ai/install.ps1 | iex ``` 在 macOS 上，安装器默认使用系统证书存储（`UV_SYSTEM_CERTS=1`），以便 uv 信任 Keychain 中的 CA，这在 TLS 检查代理（Cisco Umbrella、Zscaler 等）后是必要的。如需退出，请使用： ```bash curl -fsSL https://unsloth.ai/install.sh | UV_SYSTEM_CERTS=0 sh ``` 使用 `UNSLOTH_NPM_REGISTRY` 将前端构建指向企业 npm 镜像/代理（适用于防火墙阻止 `registry.npmjs.org` 的开发者安装）： ```bash UNSLOTH_NPM_REGISTRY=https://artifactory.example.com/api/npm/npm/ ./install.sh --local ``` ```powershell $env:UNSLOTH_NPM_REGISTRY='https://artifactory.example.com/api/npm/npm/'; .\install.ps1 --local ``` 它会作为 `--registry` 传入 Studio 前端 `npm`/`bun` 安装；供应链锁定（7 天 `min-release-age`、精确版本固定）仍然有效。 在高核心数主机上限制 Studio 原生 CPU 线程池：`UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888`。 #### 卸载 完全移除 Unsloth Studio 的推荐方式是使用与你操作系统匹配的卸载脚本。它会停止所有正在运行的服务器，移除安装目录、启动器数据目录、桌面快捷方式，以及任何平台特定条目（macOS 上的 `.app` 包与 Launch Services；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` 的模型缓存。 更多信息请参阅[我们的文档](https://unsloth.ai/docs/new/studio/install#uninstall). #### 删除模型文件 你可以通过在模型搜索中的垃圾桶图标删除旧模型文件，也可以从默认 Hugging Face 缓存目录中移除相应的已缓存模型文件夹。默认情况下，HF 使用： * ​ **MacOS、Linux、WSL：** `~/.cache/huggingface/hub/` * ​ **Windows：** `%USERPROFILE%\.cache\huggingface\hub\` ## 💚 社区与链接 | 类型 | 链接 | | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | |   **Discord** | [加入 Discord 服务器](https://discord.com/invite/unsloth) | |   **r/unsloth Reddit** | [加入 Reddit 社区](https://reddit.com/r/unsloth) | | 📚 **文档与 Wiki** | [阅读我们的文档](https://unsloth.ai/docs) | |   **Twitter（又名 X）** | [在 X 上关注我们](https://twitter.com/unslothai) | | 🔮 **我们的模型** | [Unsloth 目录](https://unsloth.ai/docs/get-started/unsloth-model-catalog) | | ✍️ **博客** | [阅读我们的博客](https://unsloth.ai/blog) | ### 引用 你可以按如下方式引用 Unsloth 仓库： ```bibtex @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](https://github.com/unslothai/unsloth?tab=Apache-2.0-1-ov-file)**, 许可，而部分可选组件（例如 Unsloth Studio UI）则采用开源许可 **[AGPL-3.0](https://github.com/unslothai/unsloth?tab=AGPL-3.0-2-ov-file)**. 这一结构有助于支持 Unsloth 的持续开发，同时保持项目开源，并让更广泛的生态得以继续发展。 ### 致谢 - [llama.cpp 库](https://github.com/ggml-org/llama.cpp)，让用户能够使用 Unsloth 运行并保存模型 - Hugging Face 团队及其库：[transformers](https://github.com/huggingface/transformers) 与 [TRL](https://github.com/huggingface/trl) - PyTorch 与 [Torch AO](https://github.com/unslothai/unsloth/pull/3391) 团队所作的贡献 - NVIDIA 的 [NeMo DataDesigner](https://github.com/NVIDIA-NeMo/DataDesigner) 库及其贡献 - 当然，还要感谢每一位曾为 Unsloth 贡献代码或使用过它的人！