> 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。它将训练流程封装在一个简洁的界面中，负责模型加载、数据集格式化、超参数配置以及实时训练监控。

<a href="https://unsloth.ai/docs/new/studio/start#unsloth-quickstart" class="button secondary" data-icon="bolt">Unsloth</a><a href="/docs/zh/xin/studio/start.md#data-recipes-quickstart" class="button secondary" data-icon="hat-chef">数据食谱</a><a href="/docs/zh/xin/studio/start.md#export-quickstart" class="button secondary" data-icon="box-isometric">导出</a><a href="/docs/zh/xin/studio/start.md#chat-quickstart" class="button secondary" data-icon="comment-dots">聊天</a>

#### 设置 Unsloth Studio

**使用 Unsloth Desktop 安装。** 安装 Unsloth Studio 最简单的方法是使用原生桌面应用。为你的操作系统下载：

* <i class="fa-apple">:apple:</i> [下载适用于 macOS](https://unsloth.ai/download/mac)
* <i class="fa-windows">:windows:</i> [下载适用于 Windows](https://unsloth.ai/download/windows)
* <i class="fa-linux">:linux:</i> [下载适用于 Linux](https://unsloth.ai/download/linux)

首先，使用本地安装或云选项启动 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 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%" %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FZPtRrwafzmVX54HhyyBD%2FScreenshot%202026-03-16%20at%2011.25.22%E2%80%AFPM.png?alt=media&amp;token=9153c153-ec61-4fff-b1b9-db7f70ac2936" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

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

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

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

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FRCnTAZ6Uh88DIlU3g0Ij%2Fmainpage%20unsloth.png?alt=media&amp;token=837c96b6-bd09-4e81-bc76-fa50421e9bfb" alt="" width="563"><figcaption></figcaption></figure>

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

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

### 模型加载指南

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

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FuZqd6tcZ5LgMSh4ZND5x%2Fexport-1778505117710-24fps.gif?alt=media&amp;token=9defec95-5404-4654-9c33-67be967c9820" alt=""><figcaption></figcaption></figure>

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

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

#### 选择模型

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

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

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

{% column width="50%" %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FxZs1wCOyXbAeKVCjSMff%2Fimage.png?alt=media&amp;token=49812361-d723-4286-93c6-7df6989c33c5" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column %}

#### GGUF 选择

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

{% column %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FlNXz1I4EhHUFB5zihpSk%2Fimage.png?alt=media&amp;token=44733b70-9c03-4371-a836-9401b2748a0d" alt="" width="375"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

#### 下载模型

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

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

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

{% column %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FzodWb7AaZH6HtE4lXopz%2Fimage.png?alt=media&amp;token=6f3ba3c1-54e2-4077-a1e7-11a9bebd820c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FsF5iWCQrYTBi6xcHxoUM%2Fimage.png?alt=media&amp;token=ed16b837-497a-48b5-9019-724f317f71dd" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FKoonE97b0H3RioMwVohd%2Fstudio%20new%20ui.gif?alt=media&amp;token=e37f2839-914e-48b8-8c81-2dac3ade9408" alt=""><figcaption></figcaption></figure>

## <i class="fa-bolt">:bolt:</i> 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 状态、图表、启动状态

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FxV1PO5DbF3ksB51nE2Tw%2Fmore%20cropped%20ui%20for%20homepage.png?alt=media&amp;token=f75942c9-3d8d-4b59-8ba2-1a4a38de1b86" 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 %}

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

**HuggingFace 令牌**

如果模型是受限访问的（例如 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).

提示 Unsloth 如何解释并格式化你的数据：
{% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FCtWUm7GdHnKbe14fUQyT%2Fupdated_dataset.webp?alt=media&amp;token=3fcefe8d-b6a4-44c2-be9b-6dc282166095" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

| 格式         | 何时使用                                 |
| ---------- | ------------------------------------ |
| `auto`     | 让 Unsloth 自动检测格式                     |
| `alpaca`   | `instruction` / `input` / `output` 列 |
| `chatml`   | OpenAI 风格 `messages` 数组              |
| `sharegpt` | ShareGPT 风格对话                        |

**划分与切片**

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

**列映射**

如果 Unsloth 无法自动将你的数据集列映射到正确的角色，将会打开一个 **数据集预览对话框** 。它会显示示例行，并允许你将每一列分配给 `instruction`, `input`, `output`, `图像`，等。建议的映射会尽可能预先填充。

### 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` 表示改用 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 %}
在你点击 **开始训练**之后，在后端准备好一切时会出现一个整页覆盖层。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FYtsUxHI0szGw8ZPxCHep%2Fimage.png?alt=media&amp;token=1701f4af-ef35-48da-80e7-4aba4e80f4d4" alt="" width="375"><figcaption></figcaption></figure></div>
{% endcolumn %}

{% column %}
覆盖层显示一个带有实时阶段更新的动画终端：

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

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

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

一旦第一步训练开始，覆盖层就会消失，并显示实时训练视图。当进度条上的步数达到 100% 时，微调过程完成。你可以查看已用时间和 tokens。&#x20;

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fah3G1rYgRaDNY8Ay6Uw7%2Fimage.png?alt=media&amp;token=0528c15e-7a4b-4028-8070-95dc0871da5d" alt="" width="563"><figcaption></figcaption></figure></div>

{% columns %}
{% column %}

#### 状态面板

左侧列显示：

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

{% column %}

#### GPU 监视器

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

* **利用率** - 百分比条
* **温度** - 摄氏度条
* **VRAM** - 已用 / 总 GB
* **功耗** - 瓦特消耗 / 限额

#### 停止训练

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

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

{% columns %}
{% column %}

#### 图表

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

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

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FRgXfe3sobdQWxha8yslr%2Fimage.png?alt=media&amp;token=b3aa9004-778b-4e3d-85b1-40a205ad0602" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FFJtjQpAgOFaieyQCYhkq%2Fimage.png?alt=media&amp;token=4da9cdc2-c088-4ab8-8d0d-40d8d392ee03" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FuGAKdGkANbh2wIENA9X7%2Fimage.png?alt=media&amp;token=9553db5b-5c88-4556-be49-fe61035edf11" 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
  ...

日志记录：
  report_to：无
  ...
```

{% 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FQ6e19jESrJg0VjHnX58c%2Fdata%20recipes%20final.png?alt=media&amp;token=8d74e453-815d-4790-83d1-76d0bc80a3ce" alt="" width="563"><figcaption></figcaption></figure></div>

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

一眼看去，常见工作流应如下所示：

1. 打开食谱页面。
2. 创建一个新食谱或打开一个现有食谱。
3. 添加模块来定义您的数据集工作流。
4. 点击 **验证** 以便尽早发现配置问题。
5. 运行预览，快速检查示例行。
6. 当食谱准备就绪时，运行完整数据集构建。
7. 在图中或在 **执行** 视图中查看更多细节。
8. 在 **Unsloth** 中选择生成的数据集并微调模型。

## <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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FrrFY8YczW3dDpfYi1k9f%2FScreenshot%202026-03-15%20at%209.28.19%E2%80%AFPM.png?alt=media&amp;token=d2729e16-799f-48f0-8b07-0248b93fa599" 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 %}
{% column %}
{% embed url="<https://www.youtube.com/watch?v=mmbkP8NARH4>" %}

以下是 NVIDIA 制作的视频教程，可帮助您开始使用 Unsloth：
{% 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/    # 主工作区
    │   │   │   ├── chat/      # 推理聊天 UI
    │   │   │   ├── 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
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 dynamically by asking a question.

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

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.