> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/xin/studio/start.md).
# 开始使用 Unsloth Studio
一份关于开始使用微调工作室、数据配方、模型导出和聊天的指南。
Unsloth Studio 是一个本地、基于浏览器的 GUI，可在不编写任何代码的情况下微调 LLM。它将训练流水线封装在一个简洁的界面中，负责模型加载、数据集格式化、超参数配置和实时训练监控。
Unsloth数据配方导出聊天
#### 设置 Unsloth Studio
**使用 Unsloth Desktop 安装。** 安装 Unsloth Studio 最简单的方法是使用原生桌面应用。为你的操作系统下载：
* :apple: [下载 macOS 版](https://unsloth.ai/download/mac)
* :windows: [下载 Windows 版](https://unsloth.ai/download/windows)
* :linux: [下载 Linux 版](https://unsloth.ai/download/linux)
如需手动安装 Unsloth Studio，请使用下面的命令：
{% tabs %}
{% tab title="macOS、Linux、WSL" %}
**安装 Unsloth：**
```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```
使用相同的命令进行更新。
{% endtab %}
{% tab title="Windows" %}
**安装 Unsloth：**
```powershell
irm https://unsloth.ai/install.ps1 | iex
```
使用相同的命令进行更新。
{% endtab %}
{% tab title="Docker" %}
该 [Unsloth Docker 镜像](https://hub.docker.com/r/unsloth/unsloth) `unsloth/unsloth` 可在 Docker 上使用。 [阅读指南。](https://unsloth.ai/docs/get-started/install/docker)
{% endtab %}
{% tab title="Homebrew" %}
安装 Unsloth Desktop：
{% code collapsedlinecount="10" %}
```bash
brew install --cask unsloth
```
{% endcode %}
更新 Unsloth Desktop：
```bash
brew upgrade --cask unsloth
```
{% endtab %}
{% tab title="WinGet" %}
安装 Unsloth Desktop：
```powershell
winget install --id UnslothAI.Unsloth -e
```
更新 Unsloth Desktop：
```powershell
winget upgrade --id UnslothAI.Unsloth -e
```
{% endtab %}
{% endtabs %}
首先，使用本地安装或云端选项启动 Unsloth Studio。请按照 [安装说明](/docs/zh/xin/studio/install.md) 为你的设置，或使用我们的 [免费 Colab](/docs/zh/xin/studio.md#google-colab-notebook) 笔记本。对于本地设置，请运行：
```bash
unsloth studio
```
{% columns %}
{% column width="50%" %}
在你常用的浏览器中打开并前往 `http://127.0.0.1:8888`。你需要创建一个新密码。
**使用 HTTPS 和 Cloudflare 安全地启动 Unsloth。** Unsloth 现在提供了一种通过免费的 Cloudflare 隧道，以 HTTPS 方式安全启动 Unsloth 的方法。使用下面的方法（适用于 Windows、Mac 和 Linux）：
```bash
unsloth studio --secure
```
{% endcolumn %}
{% column width="50%" %}
{% endcolumn %}
{% endcolumns %}
## 聊天 - 快速开始
[Unsloth Studio 聊天](/docs/zh/xin/studio/chat.md) 让你在电脑上 100% 离线运行模型。可运行 GGUF 和 safetensors 等模型格式，这些模型可以来自 Hugging Face 或你的本地文件。
* **下载 + 运行** 任何模型，例如 GGUF、微调适配器、safetensors 等。
* [**比较** 不同的模型](#model-arena) 并排输出
* **上传** 提示词中的文档、图像和音频
* [**调节** 推理](#generation-settings) 设置，例如：temperature、top-p、top-k 和系统提示词
你可以在这里阅读我们关于使用 Unsloth Studio 运行模型的详细教程/指南：
{% content-ref url="/pages/5c2325084ff65c0303d8ec102b689868935855d3" %}
[Chat with models](/docs/zh/xin/studio/chat.md)
{% endcontent-ref %}
### 模型加载指南
在使用 API 之前，你需要先 **加载模型** 到你想在 **Unsloth 中使用的模型。** 打开 **选择模型** 聊天页面左上角的下拉菜单。
{% hint style="info" %}
在其他页面？使用左侧边栏并点击 `新建聊天` 返回聊天页面。
{% endhint %}
{% columns %}
{% column width="50%" %}
#### 选择模型
使用搜索栏查找你想加载到 Unsloth 中的模型。
浏览推荐模型，直接搜索 Hugging Face 模型，或设置自定义模型目录。
本地训练并导出的模型可以从 \`Fine-tuned\` 标签页加载。
{% endcolumn %}
{% column width="50%" %}
{% endcolumn %}
{% endcolumns %}
{% columns %}
{% column %}
#### GGUF 选择
模型仓库包含多种量化版本。请选择最适合你可用 RAM / VRAM 的量化版本。\
\
在本指南中，我们将使用 `unsloth/gemma-4-26B-A4B-it-GGUF` 并选择推荐的 `UD-Q4_K_XL` 变体
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
#### 下载模型
{% columns %}
{% column %}
搜索你想使用的模型，然后 **点击它** 开始下载并加载。
选择模型变体后，Unsloth 将开始下载并将模型加载到内存中。
加载完成后，你会看到以下确认信息：
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
模型已加载并可立即使用。你现在可以直接在 Unsloth 中与模型聊天，或将其连接到以下工具： [Claude Code](/docs/zh/ji-chu-zhi-shi/claude-code.md) 和 [Codex](/docs/zh/ji-chu-zhi-shi/codex.md).
## :bolt: Unsloth - 快速开始
Unsloth Studio 首页有 4 个主要区域： [模型](#id-1.-select-model-and-method), [数据集](#id-2.-dataset), [参数](#id-3.-hyperparameters)，以及 [训练/配置](#id-4.-training-and-config)
* **模型和数据的简易设置** 来自 Hugging Face 或本地文件
* **灵活的训练选择** 例如 QLoRA、LoRA 或全量微调，并已填入默认值
* **实用的配置工具** 用于切分、列映射、超参数和 YAML 配置
* **出色的训练可视化** 带有实时进度、GPU 状态、图表、启动状态
### 1. 选择模型和方法
#### **模型类型**
选择与你的使用场景匹配的模态：
| 类型 | 使用场景 |
| ------ | ------------ |
| **文本** | 聊天、指令跟随、补全文本 |
| **视觉** | 图像 + 文本（VLM） |
| **音频** | 语音/音频理解 |
| **嵌入** | 句子嵌入、检索 |
#### **训练方法**
共有三种方法，可通过胶囊式选择器切换：
| 方法 | 说明 | VRAM |
| --------- | -------------------- | ---- |
| **QLoRA** | 4 位量化基础模型 + LoRA 适配器 | 最低 |
| **LoRA** | 全精度基础模型 + LoRA 适配器 | 中等 |
| **全量微调** | 所有权重都会被训练 | 最高 |
在组合框中输入任意 Hugging Face 模型名称，或直接搜索 Hub。存储在 `~/.unsloth/studio/models` 中的本地模型以及你的 Hugging Face 缓存也会显示在列表中。
{% hint style="warning" %}
GGUF 格式模型不参与训练——它们仅用于推理。
{% endhint %}
当你选择一个模型时，Unsloth 会自动从后端获取其配置，并为所有超参数预填合理的默认值。
**HuggingFace 令牌**
如果模型受限（例如 Llama、Gemma），请在此粘贴你的 Hugging Face 访问令牌。令牌会实时验证，如果无效会在此处显示错误。
### 2. 数据集
{% columns %}
{% column %}
在两个选项卡之间切换，以选择数据来源：
* **HuggingFace Hub** - 对 Hub 进行实时搜索。每个结果都会显示最后更新时间。
* **本地** - 拖放或点击上传文件，无论是非结构化还是结构化文件，例如： `PDF`, `DOCX`, `JSONL`, `JSON`, `CSV`，或 `Parquet` 格式。之前上传的数据集会显示在一个会自动刷新的列表中。
你可以在这里查看我们详细的 [数据集指南](/docs/zh/kuai-su-kai-shi/fine-tuning-llms-guide/datasets-guide.md).
提示 Unsloth 如何解释并格式化你的数据：
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
| 格式 | 适用时机 |
| ---------- | ------------------------------------------ |
| `auto` | 让 Unsloth 自动检测格式 |
| `alpaca` | `instruction` / `input` / `output` columns |
| `chatml` | OpenAI 风格 `messages` 数组 |
| `sharegpt` | ShareGPT 风格对话 |
**切分与裁剪**
* **子集** - 自动从数据集卡中填充。
* **训练切分 / 评估切分** - 选择要使用的切分。设置评估切分会启用 **评估损失** 训练期间的图表。
* **数据集切片** - 可选地将训练限制在某个行范围（起始索引 / 结束索引），用于快速实验。
**列映射**
如果 Unsloth 无法自动将你的数据集列映射到正确角色，就会打开一个 **数据集预览对话框** 。它会显示示例行，并让你将每一列分配为 `instruction`, `input`, `output`, `图像`等。建议的映射会在可行时预先填好。
### 3. 超参数
参数被分组在可折叠的部分中。你可以查看我们详细的 [LoRA 超参数指南](/docs/zh/kuai-su-kai-shi/fine-tuning-llms-guide/lora-hyperparameters-guide.md) 这里：
{% content-ref url="/pages/0c67f9d3a44c115b4fda319de5774cc3513ea3a3" %}
[Hyperparameters Guide](/docs/zh/kuai-su-kai-shi/fine-tuning-llms-guide/lora-hyperparameters-guide.md)
{% endcontent-ref %}
| 参数 | 默认值 | 备注 |
| --------- | ------ | -------------- |
| **最大步数** | `0` | `0` 表示改用 Epoch |
| **上下文长度** | `2048` | 选项：512 → 32768 |
| **学习率** | `2e-4` | |
**LoRA 设置**
*（选择全量微调时隐藏）*
| 参数 | 默认值 | 备注 |
| ----------- | ------ | --------------------------------------------------------------------------- |
| **秩** | `16` | 滑块 4–128 |
| **Alpha** | `32` | 滑块 4–256 |
| **Dropout** | `0.05` | |
| **LoRA 变体** | `LoRA` | `LoRA` / `RS-LoRA` / `LoftQ` |
| **目标模块** | 全部开启 | `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj` |
对于 **视觉** 对于带有图像数据集的模型，会额外出现四个复选框。微调：
| 视觉层 | 语言层 | 注意力模块 | MLP 模块 |
| --- | --- | ----- | ------ |
**训练超参数**
分为三个选项卡：
{% tabs %}
{% tab title="优化" %}
| 参数 | 默认值 |
| ----- | --------- |
| Epoch | 3 |
| 批次大小 | 4 |
| 梯度累积 | 8 |
| 权重衰减 | 0.01 |
| 优化器 | AdamW 8 位 |
{% endtab %}
{% tab title="调度" %}
| 参数 | 默认值 |
| ------------ | ------- |
| 学习率调度器 | 线性 |
| 预热步数 | 5 |
| 梯度检查点 | unsloth |
| 随机种子 | 3407 |
| 保存步数 | 0 |
| 评估步数 | 0 |
| 打包 | false |
| 在补全上训练 | false |
| {% endtab %} | |
{% tab title="日志记录" %}
| 参数 | 默认值 |
| -------------- | -------------- |
| 启用 W\&B | false |
| W\&B 项目 | llm-finetuning |
| 启用 TensorBoard | false |
| TensorBoard 目录 | runs |
| 日志频率 | 10 |
| {% endtab %} | |
| {% endtabs %} | |
{% hint style="info" %}
[**Unsloth 梯度检查点**](/docs/zh/bo-ke/500k-context-length-fine-tuning.md#unsloth-gradient-checkpointing-enhancements)**: `unsloth`** 使用 Unsloth 的自定义内存高效实现，与标准 PyTorch 选项相比，可显著减少 VRAM 使用。这是推荐的默认值。
{% endhint %}
### 4. 训练与配置
右下角卡片包含三个配置管理按钮和 **开始训练** 按钮。
| 按钮 | 操作 |
| ------ | -------------------- |
| **上传** | 加载之前保存的 `.yaml` 配置文件 |
| **保存** | 将当前配置导出为 YAML |
| **重置** | 将所有参数恢复为模型默认值 |
只有在模型和数据集都配置好后，“开始训练”按钮才会可用。验证错误会以内联方式显示——例如，在未选择评估切分的情况下设置评估步数，或将仅文本模型与视觉数据集配对。
#### 加载界面
{% columns %}
{% column %}
当你点击 **开始训练**后，在后端准备好一切时，会出现一个全屏遮罩层。
{% endcolumn %}
{% column %}
遮罩层会显示一个带实时阶段更新的动画终端：
* 蓝色：下载模型 / 数据集
* 琥珀色：加载模型 / 数据集
* 蓝色：配置中
* 绿色：训练中
你可以随时使用角落里的 **×** 按钮取消。在停止之前会先弹出确认对话框。
{% endcolumn %}
{% endcolumns %}
### 训练进度与可观测性
一旦开始第一个训练步骤，遮罩层就会消失，并显示实时训练视图。当进度条上的步数达到 100% 时，微调过程完成。你可以查看已用时间和 token 数。
{% columns %}
{% column %}
#### 状态面板
左侧栏显示：
* **轮次** - 当前小数轮次（例如 `Epoch 1.23`)
* **进度条** - 基于步数，并显示百分比
* **关键指标**:
* **损失** - 四位小数的训练损失
* **学习率** - 当前学习率，科学计数法显示
* **梯度范数** - 梯度范数
* **模型** - 正在训练的模型
* **方法** - `QLoRA` / `LoRA` / `完整`
* **时间行** - 已用时间、ETA、每秒步数和已处理 token 总数
{% endcolumn %}
{% column %}
#### GPU 监视器
右侧栏每隔几秒轮询一次，显示实时 GPU 状态：
* **利用率** - 百分比条
* **温度** - °C 条
* **VRAM** - 已用 / 总计 GB
* **功耗** - 瓦特消耗 / 上限
#### 停止训练
使用 **停止训练** 进度卡片右上角的按钮。对话框会给你两个选项：
* **停止并保存** - 在停止前保存检查点
* **取消** - 立即停止，不保存检查点
{% endcolumn %}
{% endcolumns %}
{% columns %}
{% column %}
#### 图表
训练进展时会更新四个实时图表：
1. **训练损失** - 原始值、EMA 平滑线和运行平均参考线
2. **学习率** - 学习率调度曲线
3. **梯度范数** - 随步骤变化的梯度范数
4. **评估损失** - 仅在你配置了评估切分时显示
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
{% columns %}
{% column %}
每个图表都有设置（齿轮图标），包括：
| 选项 | 默认值 |
| --------------- | --------------- |
| 查看窗口 | 最近 N 步滑块 |
| EMA 平滑 | `0.6` |
| 显示原始值 | 开启 |
| 显示平滑值 | 开启 |
| 显示平均线 | 开启 |
| 缩放（按系列） | 线性 / 对数 |
| 异常值裁剪 | 不裁剪 / p99 / p95 |
| {% endcolumn %} | |
{% column %}
{% endcolumn %}
{% endcolumns %}
#### 配置文件
{% columns %}
{% column %}
所有训练配置都可以保存并重新加载为 YAML 文件。文件会自动命名为：
```
{model}_{method}_{dataset}_{timestamp}.yaml
```
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
YAML 结构分为三个部分：
{% code expandable="true" %}
```yaml
training:
max_steps: 0
num_train_epochs: 3
per_device_train_batch_size: 4
...
lora:
r: 16
lora_alpha: 32
...
logging:
report_to: none
...
```
{% endcode %}
这使得复现实验、共享配置或对实验进行版本控制变得很容易。
## :hat-chef: 数据食谱 - 快速入门
[Unsloth 数据食谱](/docs/zh/xin/studio/data-recipe.md) 让你上传 PDF 或 CSV 文件等文档，并将它们转换为可用的数据集。通过图节点工作流以可视化方式创建和编辑数据集。
食谱页面是主要入口。食谱保存在浏览器本地，因此你之后可以回来继续处理已保存的工作。在这里，你可以创建一个空白食谱，或者打开一个引导式学习食谱。
数据食谱遵循相同的基本路径。你打开食谱页面，创建或选择一个食谱，在编辑器中构建工作流，进行验证并运行预览，然后在输出看起来正确后运行完整数据集。添加种子数据和生成模块，验证工作流，预览示例输出，然后运行完整数据集构建。Unsloth 数据食谱由 NVIDIA 提供支持 [DataDesigner](https://github.com/NVIDIA-NeMo/DataDesigner).
从整体上看，通常的工作流程应如下所示：
1. 打开食谱页面。
2. 创建一个新食谱或打开一个现有食谱。
3. 添加模块以定义你的数据集工作流。
4. 点击 **验证** 以便尽早发现配置问题。
5. 运行预览以快速检查示例行。
6. 当食谱准备就绪时，运行完整的数据集构建。
7. 在图表中或在 **执行** 视图中实时查看进度和输出，以查看更多详情。
8. 在 **Unsloth** 中选择生成的数据集并微调模型。
## :box-isometric: 导出 - 快速入门
使用 Unsloth Studio 的“导出”功能，将模型导出、保存或转换为 GGUF、Safetensors 或 LoRA，以便在 Unsloth、llama.cpp、Ollama、vLLM 等环境中部署、共享或进行本地推理。导出已训练的检查点或转换任何现有模型。
你可以在这里阅读我们关于使用 Unsloth Studio 导出模型的详细教程/指南：
{% content-ref url="/pages/f7c3389bdba9af3050e66a941596d827cdb11e0b" %}
[Model Export](/docs/zh/xin/studio/export.md)
{% endcontent-ref %}
## :video: 视频教程
{% hint style="warning" %}
视频中展示的 Unsloth Studio 版本较旧，不代表当前版本。
{% endhint %}
{% columns %}
{% column %}
{% embed url="" %}
以下是 NVIDIA 制作的视频教程，帮助你开始使用 Unsloth：
{% endcolumn %}
{% column %}
{% embed url="" %}
如何安装 Unsloth Studio 视频教程
{% endcolumn %}
{% endcolumns %}
## 高级设置
### CLI 命令
Unsloth CLI（`cli.py`）提供以下命令：
```
用法：cli.py [命令]
命令：
train 微调模型
inference 在训练好的模型上运行推理
export 导出已训练的适配器
list-checkpoints 列出已保存的检查点
ui 启动 Unsloth Studio Web UI
studio 启动工作室（别名）
```
### 项目结构
{% code expandable="true" %}
```
new-ui-prototype/
├── cli.py # CLI 入口
├── cli/ # Typer CLI 命令
│ └── commands/
│ ├── train.py
│ ├── inference.py
│ ├── export.py
│ ├── ui.py
│ └── studio.py
├── setup.sh # 引导脚本（Linux / WSL / Colab）
├── setup.ps1 # 引导脚本（Windows 原生）
├── setup.bat # 通过双击启动 setup.ps1 的包装脚本
├── install_python_stack.py # 跨平台 Python 依赖安装器
└── studio/
├── backend/
│ ├── main.py # FastAPI 应用与中间件
│ ├── run.py # 服务器启动器（uvicorn）
│ ├── auth/ # 认证存储与 JWT 逻辑
│ ├── routes/ # API 路由处理器
│ │ ├── training.py
│ │ ├── models.py
│ │ ├── inference.py
│ │ ├── datasets.py
│ │ └── auth.py
│ ├── models/ # Pydantic 请求/响应 schema
│ ├── core/ # 训练引擎与配置
│ ├── utils/ # 硬件检测、辅助工具
│ └── requirements.txt
├── frontend/
│ ├── src/
│ │ ├── features/ # 功能模块
│ │ │ ├── auth/ # 登录 / 注册流程
│ │ │ ├── training/ # 训练配置与监控
│ │ │ ├── studio/ # 主工作区
│ │ │ ├── chat/ # 推理聊天界面
│ │ │ ├── export/ # 模型导出流程
│ │ │ └── onboarding/# 新手引导向导
│ │ ├── components/ # 共享 UI 组件（shadcn）
│ │ ├── hooks/ # 自定义 React Hook
│ │ ├── stores/ # Zustand 状态存储
│ │ └── types/ # TypeScript 类型定义
│ ├── package.json
│ └── vite.config.ts
└── tests/ # 后端测试套件
```
{% endcode %}
### API 参考
所有端点都需要有效的 JWT `Authorization: Bearer ` 标头（除 `/api/auth/*` 和 `/api/health`).
| 方法 | 端点 | 说明 |
| ------ | --------------------- | ------------------------- |
| `GET` | `/api/health` | 健康检查 |
| `GET` | `/api/system` | 系统信息（GPU、CPU、内存） |
| `POST` | `/api/auth/signup` | 创建账户（首次运行时需要 setup token） |
| `POST` | `/api/auth/login` | 登录并接收 JWT 令牌 |
| `POST` | `/api/auth/refresh` | 刷新已过期的访问令牌 |
| `GET` | `/api/auth/status` | 检查认证是否已初始化 |
| `POST` | `/api/train/start` | 启动训练任务 |
| `POST` | `/api/train/stop` | 停止正在运行的训练任务 |
| `POST` | `/api/train/reset` | 重置训练状态 |
| `GET` | `/api/train/status` | 获取当前训练状态 |
| `GET` | `/api/train/metrics` | 获取训练指标（损失、学习率、步数） |
| `GET` | `/api/train/stream` | 实时训练进度的 SSE 流 |
| `GET` | `/api/models/` | 列出可用模型 |
| `POST` | `/api/inference/chat` | 发送聊天消息进行推理 |
| `GET` | `/api/datasets/` | 列出 / 管理数据集 |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://unsloth.ai/docs/zh/xin/studio/start.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
