# 开始使用 Unsloth Studio

Unsloth Studio 是一个本地、基于浏览器的 GUI，可在不编写任何代码的情况下对 LLM 进行微调。它将训练流程封装在一个简洁的界面中，负责模型加载、数据集格式化、超参数配置以及实时训练监控。

<a href="/pages/12f6b822ad28322267b74accad74f665b341f5a4#studio-quickstart" class="button secondary" data-icon="bolt">工作室</a><a href="/pages/12f6b822ad28322267b74accad74f665b341f5a4#data-recipes-quickstart" class="button secondary" data-icon="hat-chef">数据配方</a><a href="/pages/12f6b822ad28322267b74accad74f665b341f5a4#export-quickstart" class="button secondary" data-icon="box-isometric">导出</a><a href="/pages/12f6b822ad28322267b74accad74f665b341f5a4#chat-quickstart" class="button secondary" data-icon="comment-dots">聊天</a>

#### 设置 Unsloth Studio

首先，使用本地安装或云端选项启动 Unsloth Studio。请按照 [安装说明](/docs/zh/xin/studio/install.md) 进行你的环境设置，或者使用我们的 [免费 Colab](/docs/zh/xin/studio.md#google-colab-notebook) 笔记本。对于本地安装，运行：

```bash
unsloth studio -H 0.0.0.0 -p 8888
```

{% columns %}
{% column %}
打开你常用的浏览器并输入 `http://127.0.0.1:8888`  到 URL 输入框中。

如果这是你第一次安装 Unsloth，你将被重定向到 `http://127.0.0.1:8888/change-password`  页面。你需要在这里创建一个新密码。之后你随时都可以更改密码。
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="/files/5fbb030955cfa5eff9a52777cb0d6918db45590a" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

## <i class="fa-comment-dots">:comment-dots:</i> 聊天 - 快速入门

[Unsloth Studio 聊天](/docs/zh/xin/studio/chat.md) 可让你在自己的电脑上 100% 离线运行模型。支持运行如 GGUF 和 safetensors 等模型格式，这些模型可以来自 Hugging Face 或本地文件。

* **下载 + 运行** 任意模型，例如 GGUF、微调后的适配器、safetensors 等。
* [**并排** 不同模型](#model-arena) 并排输出
* **上传** 在提示词中使用文档、图片和音频
* [**调节** 推理](#generation-settings) 设置，例如：temperature、top-p、top-k 和系统提示词

<div data-with-frame="true"><figure><img src="/files/10d30a37e0716fb8e4650f8d453f6997d90b295b" alt="" width="563"><figcaption></figcaption></figure></div>

你可以在这里阅读我们关于使用 Unsloth Studio 运行模型的详细教程 / 指南：

{% content-ref url="/pages/5c2325084ff65c0303d8ec102b689868935855d3" %}
[Studio Chat](/docs/zh/xin/studio/chat.md)
{% endcontent-ref %}

### 模型加载指南

在使用 API 之前，你需要先 **加载模型** ，即你想在 **Unsloth** 中使用的模型。打开聊天页面左上角的 **选择模型** 下拉菜单。

<figure><img src="/files/e7c1a267b0c4f58689066eddfc57a2c2211f1e13" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
在别的页面？使用左侧边栏并点击 `新建聊天` 返回聊天页面。
{% endhint %}

{% columns %}
{% column width="50%" %}

#### 选择模型

使用搜索栏查找你想加载到 Unsloth 中的模型。

浏览推荐模型、直接搜索 Hugging Face 模型，或设置自定义模型目录。

本地训练并导出的模型可以从 \`Fine-tuned\` 选项卡中加载。
{% endcolumn %}

{% column width="50%" %}

<figure><img src="/files/26d4fa903e5d4717c60e70b29ddc2d94710d3b65" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}

#### GGUF 选择

模型仓库包含多个量化版本。请选择最适合你可用 RAM / VRAM 的量化版本。\
\
在本指南中我们将使用 `unsloth/gemma-4-26B-A4B-it-GGUF` 并选择推荐的 `UD-Q4_K_XL` 变体
{% endcolumn %}

{% column %}

<figure><img src="/files/06455ac4cfca4a5bb39a17cdee347e37affec31e" alt="" width="375"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

#### 下载模型

{% columns %}
{% column %}
搜索你想使用的模型，然后 **点击它** 即可开始下载并加载。

选择某个模型变体后，Unsloth 将开始下载并将模型加载到内存中。

加载完成后，你会看到以下确认信息：
{% endcolumn %}

{% column %}

<figure><img src="/files/5558ed2425642f88ed2224712f2dc6e89deb03c1" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/c77ab9745dd7a92417e0be7fa7f47b06449b4d2a" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

模型已加载并可使用。你现在可以直接在 Unsloth 中与模型聊天，或将其连接到诸如 [Claude Code](/docs/zh/ji-chu/claude-code.md) 以及 [Codex](/docs/zh/ji-chu/codex.md).

<figure><img src="/files/16cd5c624d215906fa9d68a69a32e3e5c28d1730" alt=""><figcaption></figcaption></figure>

## <i class="fa-bolt">:bolt:</i> 工作室 - 快速入门

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 状态、图表、启动状态

<div data-with-frame="true"><figure><img src="/files/49659aafc9e7e375a6e4cb5de958fc9ef97c7811" alt="" width="563"><figcaption></figcaption></figure></div>

### 1. 选择模型和方法

#### **模型类型**

选择与你的使用场景相匹配的模态：

| 类型     | 使用场景         |
| ------ | ------------ |
| **文本** | 聊天、指令遵循、补全文本 |
| **视觉** | 图像 + 文本（VLM） |
| **音频** | 语音 / 音频理解    |
| **嵌入** | 句向量嵌入、检索     |

#### **训练方法**

共有三种方法，可通过胶囊选择器切换：

| 方法        | 说明                    | VRAM |
| --------- | --------------------- | ---- |
| **QLoRA** | 4 位量化的基础模型 + LoRA 适配器 | 最低   |
| **LoRA**  | 全精度基础模型 + LoRA 适配器    | 中等   |
| **完整微调**  | 所有权重都会被训练             | 最高   |

在组合框中输入任意 Hugging Face 模型名称，或直接搜索 Hub。存储在 `~/.unsloth/studio/models` 中的本地模型以及你的 Hugging Face 缓存也会出现在列表里。

{% hint style="warning" %}
GGUF 格式模型不参与训练——它们仅用于推理。
{% endhint %}

当你选择一个模型时，Studio 会自动从后端获取其配置，并为所有超参数预填合理的默认值。

**HuggingFace Token**

如果模型受限访问（例如 Llama、Gemma），请在此粘贴你的 Hugging Face 访问令牌。令牌会实时验证，如果无效会直接显示错误。

### 2. 数据集

{% columns %}
{% column %}
在两个选项卡之间切换，以选择数据来源：

* **HuggingFace Hub** - 对 Hub 进行实时搜索。每个结果都会显示最后更新时间。
* **本地** - 拖放或点击以上传文件，支持非结构化或结构化文件，例如： `PDF`, `DOCX`, `JSONL`, `JSON`, `CSV`，或 `Parquet` 格式。此前上传的数据集会出现在列表中，并会自动刷新。

你可以在这里查看我们详细的 [数据集指南](/docs/zh/kai-shi-shi-yong/fine-tuning-llms-guide/datasets-guide.md).

Prompt Studio 如何理解并格式化你的数据：
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="/files/7966f91485eded252bb438a391dc727b5828a20c" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

| 格式         | 适用场景                 |
| ---------- | -------------------- |
| `auto`     | 让 Unsloth 自动检测格式     |
| `alpaca`   | `指令` / `输入` / `输出` 列 |
| `chatml`   | OpenAI 风格 `消息` 数组    |
| `sharegpt` | ShareGPT 风格对话        |

**切分与裁剪**

* **子集** - 自动从数据集卡中填充。
* **训练切分 / 评估切分** - 选择要使用的切分。设置评估切分会在训练期间启用 **评估损失** 图表。
* **数据集切片** - 可选择将训练限制在某一行范围内（起始索引 / 结束索引），用于快速实验。

**列映射**

如果 Studio 无法自动将你的数据集列映射到正确角色， **数据集预览对话框** 会打开。它会显示示例行，并让你将每一列分配给 `指令`, `输入`, `输出`, `图像`等。建议的映射会在可行时预先填充。

### 3. 超参数

参数按可折叠分组组织。你可以查看我们详细的 [LoRA 超参数指南](/docs/zh/kai-shi-shi-yong/fine-tuning-llms-guide/lora-hyperparameters-guide.md) 于此：

{% content-ref url="/pages/0c67f9d3a44c115b4fda319de5774cc3513ea3a3" %}
[Hyperparameters Guide](/docs/zh/kai-shi-shi-yong/fine-tuning-llms-guide/lora-hyperparameters-guide.md)
{% endcontent-ref %}

| 参数        | 默认值    | 说明              |
| --------- | ------ | --------------- |
| **最大步数**  | `0`    | `0` 表示改用 Epochs |
| **上下文长度** | `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="优化" %}

| 参数     | 默认值         |
| ------ | ----------- |
| Epochs | 3           |
| 批量大小   | 4           |
| 梯度累积   | 8           |
| 权重衰减   | 0.01        |
| 优化器    | AdamW 8-bit |

{% endtab %}

{% tab title="调度" %}

| 参数           | 默认值     |
| ------------ | ------- |
| 学习率调度器       | linear  |
| 预热步数         | 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 %}
当你点击 **开始训练**后，后端准备一切内容时会出现一个全页遮罩层。

<div data-with-frame="true"><figure><img src="/files/662fbde8a37616f18fc3b384a00b71f8ec9f788e" alt="" width="375"><figcaption></figcaption></figure></div>
{% endcolumn %}

{% column %}
该遮罩层会显示一个带有实时阶段更新的动画终端：

* 蓝色：下载模型 / 数据集
* 琥珀色：加载模型 / 数据集
* 蓝色：配置中
* 绿色：训练中

你可以随时使用角落里的 **×** 按钮取消。在停止任何内容之前都会先弹出确认对话框。
{% endcolumn %}
{% endcolumns %}

### 训练进度与可观测性

当第一步训练到来后，遮罩层会消失，并显示实时训练视图。当进度条上的步数达到 100% 时，微调过程即完成。你可以查看已用时间和 token 数。&#x20;

<div data-with-frame="true"><figure><img src="/files/a5d5ea5de1655458b8dbb88c678615bd6a74c414" alt="" width="563"><figcaption></figcaption></figure></div>

{% columns %}
{% column %}

#### 状态面板

左侧列显示：

* **Epoch** - 当前的分数 epoch（例如 `Epoch 1.23`)
* **进度条** - 基于步数，并显示百分比
* **关键指标**:
  * **Loss** - 训练损失，精确到 4 位小数
  * **LR** - 当前学习率，使用科学计数法
  * **Grad Norm** - 梯度范数
  * **模型** - 正在训练的模型
  * **方法** - `QLoRA` / `LoRA` / `完整`
* **时间行** - 已用时间、ETA、每秒步数，以及已处理的总 token 数
  {% endcolumn %}

{% column %}

#### GPU 监控

右侧列显示每隔几秒轮询一次的实时 GPU 状态：

* **利用率** - 百分比条
* **温度** - °C 条
* **VRAM** - 已用 / 总 GB
* **功耗** - 瓦特数 / 上限

#### 停止训练

使用 **停止训练** 按钮，位于进度卡片右上角。对话框会给出两个选择：

* **停止并保存** - 在停止前保存一个检查点
* **取消** - 立即停止，不保存检查点
  {% endcolumn %}
  {% endcolumns %}

{% columns %}
{% column %}

#### 图表

随着训练推进，四个实时图表会更新：

1. **训练损失** - 原始值，加上 EMA 平滑线和运行平均参考线
2. **学习率** - 学习率调度曲线
3. **梯度范数** - 随步数变化的梯度范数
4. **评估损失** - 仅在你配置了评估切分时显示
   {% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="/files/309a791280976cf0ee6c326686d5ef489031a089" alt="" width="278"><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}
每个图表都有设置（齿轮图标），包括：

| 选项              | 默认值             |
| --------------- | --------------- |
| 查看窗口            | 最近 N 步滑块        |
| EMA 平滑          | `0.6`           |
| 显示原始值           | 开启              |
| 显示平滑值           | 开启              |
| 显示平均线           | 开启              |
| 缩放（按系列）         | 线性 / 对数         |
| 离群值裁剪           | 不裁剪 / p99 / p95 |
| {% endcolumn %} |                 |

{% column %}

<div data-with-frame="true"><figure><img src="/files/8f02564c6d6a03400d2a750da2bc62686bfefaf5" alt="" width="276"><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

#### 配置文件

{% columns %}
{% column %}
所有训练配置都可以保存并重新加载为 YAML 文件。文件会自动命名为：

```
{model}_{method}_{dataset}_{timestamp}.yaml
```

{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="/files/2bafa366e1da360c94defd755cf6b9b12ea30644" alt="" width="178"><figcaption></figcaption></figure></div>
{% 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 %}

这使得复现实验、共享配置或对实验进行版本控制都非常容易。

## <i class="fa-hat-chef">:hat-chef:</i> 数据配方 - 快速入门

[Unsloth 数据配方](/docs/zh/xin/studio/data-recipe.md) 可让你上传 PDF 或 CSV 等文档，并将其转换为可用的数据集。通过图节点工作流以可视化方式创建和编辑数据集。

配方页面是主要入口。配方会本地存储在浏览器中，因此你之后可以回来继续处理已保存的内容。从这里，你可以创建一个空白配方，或打开一个引导式学习配方。

<div data-with-frame="true"><figure><img src="/files/d7a623c1009dd96e330afd7e279e05a2e03ae91b" alt="" width="563"><figcaption></figcaption></figure></div>

数据配方遵循相同的基本流程：打开配方页面，创建或选择一个配方，在编辑器中构建工作流，验证并运行预览，然后在输出看起来正确后运行完整数据集。添加种子数据和生成块，验证工作流，预览样本输出，然后运行完整的数据集构建。Unsloth Data Recipes 由 NVIDIA 提供支持 [DataDesigner](https://github.com/NVIDIA-NeMo/DataDesigner).

从整体来看，常见工作流应如下所示：

1. 打开配方页面。
2. 创建一个新配方或打开现有配方。
3. 添加区块以定义你的数据集工作流。
4. 点击 **验证** 以便尽早发现配置问题。
5. 运行预览以快速检查样本行。
6. 当配方准备就绪后，运行完整数据集构建。
7. 在图中或在 **执行** 视图中查看进度和输出详情。
8. 在 **工作室** 中选择生成的数据集并微调模型。

## <i class="fa-box-isometric">:box-isometric:</i> 导出 - 快速入门

使用 Unsloth Studio 的“导出”功能，可将模型导出、保存或转换为 GGUF、Safetensors 或 LoRA，用于部署、共享，或在 Unsloth、llama.cpp、Ollama、vLLM 等环境中进行本地推理。导出已训练的检查点，或转换任何现有模型。

<div data-with-frame="true"><figure><img src="/files/fd56198d7b81c8cae1273c224ce7afa25b077dde" alt="" width="563"><figcaption></figcaption></figure></div>

你可以在这里阅读我们关于使用 Unsloth Studio 导出模型的详细教程 / 指南：

{% content-ref url="/pages/f7c3389bdba9af3050e66a941596d827cdb11e0b" %}
[Model Export](/docs/zh/xin/studio/export.md)
{% endcontent-ref %}

## <i class="fa-video">:video:</i> 视频教程

{% hint style="warning" %}
视频中展示的 Unsloth Studio 版本较旧，不反映当前版本。
{% endhint %}

{% columns fullWidth="true" %}
{% column %}
{% embed url="<https://www.youtube.com/watch?v=mmbkP8NARH4>" %}

以下是由 NVIDIA 制作的视频教程，可帮助你开始使用 Studio：
{% endcolumn %}

{% column %}
{% embed url="<https://youtu.be/1lEDuRJWHh4?si=GHaS77ZZPOGjn3GJ>" %}

如何安装 Unsloth Studio 视频教程
{% endcolumn %}
{% endcolumns %}

## 高级设置

### CLI 命令

Unsloth CLI（`cli.py`）提供以下命令：

```
用法：cli.py [COMMAND]

命令：
  train             微调模型
  inference         对已训练模型运行推理
  export            导出已训练的适配器
  list-checkpoints  列出已保存的检查点
  ui                启动 Unsloth Studio Web UI
  studio            启动 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 请求/响应模式
    │   ├── core/              # 训练引擎与配置
    │   ├── utils/             # 硬件检测、辅助工具
    │   └── requirements.txt
    ├── frontend/
    │   ├── src/
    │   │   ├── features/      # 功能模块
    │   │   │   ├── auth/      # 登录 / 注册流程
    │   │   │   ├── training/  # 训练配置与监控
    │   │   │   ├── studio/    # Studio 主工作区
    │   │   │   ├── chat/      # 推理聊天界面
    │   │   │   ├── export/    # 模型导出流程
    │   │   │   └── onboarding/# 上手引导向导
    │   │   ├── components/    # 共享 UI 组件（shadcn）
    │   │   ├── hooks/         # 自定义 React hooks
    │   │   ├── stores/        # Zustand 状态存储
    │   │   └── types/         # TypeScript 类型定义
    │   ├── package.json
    │   └── vite.config.ts
    └── tests/                 # 后端测试套件
```

{% endcode %}

### API 参考

所有端点都需要有效的 JWT `Authorization: Bearer <token>` 请求头（除 `/api/auth/*` 以及 `/api/health`).

| 方法     | 端点                    | 说明                |
| ------ | --------------------- | ----------------- |
| `GET`  | `/api/health`         | 健康检查              |
| `GET`  | `/api/system`         | 系统信息（GPU、CPU、内存）  |
| `POST` | `/api/auth/signup`    | 创建账户（首次运行需要设置令牌）  |
| `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: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://unsloth.ai/docs/zh/xin/studio/start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.