## 项目概述

Unsloth 是一个本地优先的桌面应用，用于运行和微调大型语言模型（LLM）与扩散模型。它支持 Qwen、Gemma、DeepSeek、Kimi 等主流模型，提供 2 倍训练加速和 70% 显存节省，并集成 Agent、RAG、远程访问等功能。项目采用 Apache-2.0 与 AGPL-3.0 双许可证。

## 核心功能

- **模型运行与训练**：支持 LLM、扩散模型、嵌入模型、音频模型（如 Qwen3.8、Kimi K3、MiniMax-H3、Gemma 4、DeepSeek-V4、FLUX 等）的本地运行与微调。
- **Agent 与工具集成**：支持与 Claude Code、Codex、MCP 等工具集成，实现工具调用与代码执行。
- **搜索与 RAG**：提供私有、无限制的网页搜索、深度研究与 RAG 功能。
- **图像与视频**：支持图像、视频扩散模型及多模态模型的运行与训练。
- **硬件支持**：支持 CPU、Apple、NVIDIA、AMD、Intel 及多 GPU 配置。
- **远程访问**：通过 Cloudflare HTTPS 隧道安全地远程访问本地模型。
- **API 兼容**：提供 OpenAI 兼容 API，可连接 ChatGPT/Codex 订阅及云服务提供商。
- **微调与部署**：支持 LoRA、QLoRA、全量微调、预训练、强化学习（RL）、GRPO、DPO、FP8 等，并支持导出为 GGUF、NVFP4、FP8 等格式。
- **数据集构建**：通过 Data Recipes 从 PDF、CSV、DOCX 等文件构建数据集。

## 适用与不适用场景

**适用场景**：
- 需要在本地运行和微调 LLM 或扩散模型的个人开发者与研究人员。
- 希望将本地模型与 Claude Code、Codex 等 Agent 工具集成的用户。
- 需要私有搜索、RAG 或深度研究的场景。
- 需要远程安全访问本地模型的团队。

**不适用场景**：
- 需要大规模分布式训练或生产级部署的场景（Unsloth 主要面向本地与单机）。
- 对模型推理速度有极致要求的场景（Unsloth 更侧重训练加速）。
- 需要完整的企业级权限管理与审计功能的场景。

## 技术架构与依赖

- **桌面应用**：基于 Tauri 构建，支持 Windows、macOS、Linux。
- **Web UI**：Unsloth Studio，基于 Web 技术，支持浏览器访问。
- **核心库**：基于 PyTorch、Hugging Face Transformers、TRL、llama.cpp 等。
- **推理后端**：支持 CPU、CUDA、ROCm、Vulkan、Metal 等。
- **远程访问**：集成 Cloudflare 隧道。
- **依赖管理**：使用 uv 进行 Python 依赖管理。

## 安装与快速开始

### 桌面应用（推荐）

从 [GitHub Releases](https://github.com/unslothai/unsloth/releases) 下载对应平台的安装包（Windows、macOS、Linux）。

### 手动安装（macOS、Linux、WSL）

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

### 手动安装（Windows）

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

### Unsloth Core（代码方式）

```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
```

### Docker

```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
```

## 典型使用方法

### 启动 Unsloth Studio

```bash
unsloth studio -p 8888
```

### 连接本地模型到 Agent

```bash
unsloth start claude
```

支持 Claude Code、Codex、Hermes、OpenCode、OpenClaw 等。

### 远程访问（HTTPS 隧道）

```bash
unsloth studio --secure -p 8888
```

### 微调模型

使用免费 Notebook（如 Google Colab）进行微调，支持 Gemma、Qwen、Llama 等模型。

## 配置与部署要点

- **GGUF 推理后端**：可通过环境变量 `UNSLOTH_LLAMA_CPP_BACKEND` 或设置界面选择 CPU、CUDA、ROCm、Vulkan。
- **远程访问安全**：默认仅绑定 localhost，使用 `--secure` 或 `--cloudflare` 时需设置强密码，并注意 API 密钥保密。
- **工具执行**：服务器端工具（Web 搜索、Python 执行）默认开启，暴露服务时建议使用 `--disable-tools`。
- **环境变量**：支持 `UNSLOTH_NO_TORCH`、`UNSLOTH_SKIP_AUTOSTART`、`UNSLOTH_PYTHON`、`UNSLOTH_STUDIO_HOME` 等。
- **卸载**：使用官方卸载脚本或删除 `~/.unsloth/studio` 目录。

## 限制、风险与许可证

- **许可证**：核心包为 Apache-2.0，Unsloth Studio UI 为 AGPL-3.0。
- **风险**：远程访问时若 API 密钥泄露，他人可执行代码；`--password` 参数可能出现在进程列表或 shell 历史中。
- **限制**：部分 AMD GPU（如 Polaris、RDNA 1）不支持 ROCm PyTorch，训练与 GPU 推理不可用。

## 官方链接

- [GitHub 仓库](https://github.com/unslothai/unsloth)
- [官方文档](https://unsloth.ai/docs)
- [模型目录](https://unsloth.ai/docs/get-started/unsloth-model-catalog)
- [博客](https://unsloth.ai/blog)
- [Discord](https://discord.gg/unsloth)
- [Reddit](https://reddit.com/r/unsloth)

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CONTRIBUTING.md、最新 Release 信息。
- 分析时间：2026-08-20（基于最新 Release 日期）。