> 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/mo-xing/qwen-image-2.1.md).

# Qwen-Image-2.1：如何在本地运行

使用 Unsloth FP8 和 GGUF 量化在本地运行 Qwen-Image-2.1。

**Qwen-Image-2.1** 是一个新的 **70亿参数** 文本生成图像和 [图像编辑](#image-editing) 由 Qwen 提供、可在本地运行于 **11GB 显存** 的模型，使用 GGUF 时；使用 INT8/FP8 时则需 24GB。本指南将向你展示如何运行 Qwen-Image-2.1 进行图像生成，以及内存需求、推荐设置等内容。

{% columns %}
{% column width="50%" %}
Qwen-Image-2.1 将一个 70 亿参数的图像生成器与 **Qwen3-VL 80亿编码器**相结合。该模型支持原生 2K 生成、文本渲染、透明图像，以及最多 10 张参考图像的编辑。

这些量化版本使用 [Unsloth Dynamic](https://unsloth.ai/docs/basics/dynamic-3.0-ggufs) 方法，将重要层提升到更高精度以获得更高准确度。可在 [Unsloth Desktop](/docs/zh/desktop.md)、diffusers、stable-diffusion.cpp 等中运行。 **Unsloth 上传：** [GGUF](https://huggingface.co/unsloth/Qwen-Image-2.1-GGUF) • [FP8](https://huggingface.co/unsloth/Qwen-Image-2.1-FP8)
{% endcolumn %}

{% column width="50%" %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F8E4zaQZmeYBhYIXkvveM%2F01-2edit-multi-image.webp?alt=media&amp;token=ad7d102c-b304-4c75-b66d-4a68cd518a37" alt=""><figcaption><p>通过 Unsloth 使用 FP8 Qwen-Image-1.2 进行图像编辑</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

### 🖥️  内存需求

使用下表为你的硬件选择一个起始配置。先按列出的分辨率生成一张图像，如果内存允许，再提高分辨率。

对于显存为 24 GB 或更高的 GPU，推荐使用 FP8 量化。对于任何带 GPU 的配置，它也可能更合适，因为即使启用卸载，它也能比 GGUF 模型提供更快的推理速度。只需确保你有足够的 RAM 供卸载使用。

如果你有 CPU RAM，或使用诸如 Mac 之类的统一内存系统，则主要使用 GGUF 模型。

**内存数据为估算值，并非经过测试的最低要求。** 内存占用会因分辨率和卸载设置而变化。

| 可用硬件                             | 起始配置                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------ |
| **12–16 GB 显存**                  | GGUF **Q4\_K\_M**，1024×1024，批量 1                                                           |
| **24 GB 显存**                     | <p><strong>INT8/FP8：</strong> 512 × 512<br><strong>GGUF Q4\_K\_M：</strong> 1024 × 1024</p> |
| **6GB 显存**                       | 你可以运行 FP8 **，仅使用 6GB 显存并通过卸载**。推理速度会慢不到 2 倍。                                               |
| **仅 CPU：12–16 GB RAM**           | GGUF **Q4\_K\_M** 配合 Q4\_K\_XL 文本编码器                                                       |
| **Apple Silicon：12–16 GB+ 统一内存** | 带兼容原生后端的 GGUF                                                                              |

当显存有限时，CPU 卸载会有帮助，但需要额外的系统 RAM，并且可能会减慢生成速度。

### 量化分析

我们展示了 INT8 的合理 LPIPS 最低（越低越好），甚至优于 FP8，因此我们默认使用 INT8。

| 方案   | 文件大小    | LPIPS 平均值 | LPIPS 最大值 | SSIM 平均值 |
| ---- | ------- | --------: | --------: | -------: |
| int8 | 7.26 GB |     0.064 |     0.167 |    0.936 |
| fp8  | 7.12 GB |     0.112 |     0.329 |    0.899 |

### ⚡ 快速开始

{% stepper %}
{% step %}

#### 设置 Unsloth

最简单的上手方式是下载 [Unsloth Desktop 应用](/docs/zh/desktop.md)。支持 [macOS](/docs/zh/kai-shi-shi-yong/install/mac.md), [Windows](/docs/zh/kai-shi-shi-yong/install/windows-installation.md)，以及 [Linux](/docs/zh/kai-shi-shi-yong/install/linux.md).

<a href="https://unsloth.ai/download" class="button primary" data-icon="down-to-bracket">下载 Unsloth</a>

* <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)

或者，如果你更喜欢手动安装：

MacOS、Linux、WSL：

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

Windows PowerShell：

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

{% endstep %}

{% step %}

#### 设置 Qwen-Image-2.1

在此版本中，Qwen-Image-2.1 在 Unsloth 中仅支持文本生成图像。

选择 **图像** ，从侧边栏中。默认会打开 **创建** 图像工作流。

在其中打开“选择图像模型”，或者转到模型中心，并通过选择器搜索你想要的 Qwen-Image-2.1 GGUF 或 FP8 量化版本，这将下载该模型。

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FEFCApsTzrL81lOcdd298%2Fimage.png?alt=media&amp;token=07fa0438-55f4-46ec-b055-2f4b6532df96" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FHjN84g8IYe9eRSRO4wGe%2Fqwenimage2.1.png?alt=media&amp;token=73f99133-f0d0-47c8-aaa4-a0097b5ff7b4" alt="" width="563"><figcaption></figcaption></figure></div>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FuWMvSNEkp7lnr2es7v32%2FScreenshot%202026-09-22%20at%206.23.20%E2%80%AFAM.png?alt=media&amp;token=570e743c-b6b9-4fa2-b06d-b6e4c955424a" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### 生成你的图像

描述你想生成的图像。你可以为第一张图保留推荐设置。

点击 **生成**。第一次生成可能会花更长时间，因为模型正在下载和加载。结果会显示在图库中，你可以在那里查看其设置或下载它。

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FrX8YDJ91NTwNVtFpERXX%2Fimage.png?alt=media&amp;token=fee9d4b5-cca3-4054-ad50-6aa1beba5a50" alt="" width="563"><figcaption></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F0JAa73bhb2PAD0692XqI%2F1000007556.jpg?alt=media&amp;token=c725d011-01c2-4a56-96bb-31034ecb77cf" alt="" width="375"><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### 图像编辑

你也可以轻松使用 Qwen-Image-2.1 编辑带透明背景的照片。移除元素、添加元素、改变氛围，同时保持相同的基础/结构。只需在 Unsloth 中选择“编辑”选项卡并输入你的提示词。

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FNA6VP3yqmBZhR4qVE90I%2F02-localized-annotation.webp?alt=media&amp;token=a42e809a-f4ea-4779-9213-606c772e9422" alt=""><figcaption></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FS0j84jGUey0dnoQgEQzm%2F03-transparent-edit.webp?alt=media&amp;token=ce337489-f698-4c25-9c3b-3fd77bc2e48d" alt=""><figcaption></figcaption></figure></div>

### ⚙️ 推荐设置

**请使用实际运行该模型的后端所对应的方案**，而不只是它的 FP8/GGUF 文件扩展名。

| 设置            | Unsloth GPU / Diffusers    | 原生 stable-diffusion.cpp         |
| ------------- | -------------------------- | ------------------------------- |
| **步骤**        | **40** - Qwen/Diffusers 基线 | **20** - CLI 默认值和 Unsloth 记录的测试 |
| **引导 / CFG**  | **1.0** - CFG 已禁用          | **6.0** - 上游 sd.cpp 示例          |
| **负面提示词**     | 留空；将引导设为 `1.0` 明确地         | 留空以复现示例                         |
| **采样器 / 调度器** | 保持模型的管线调度器                 | **Euler**                       |
| **流偏移**       | 保持管线的调度器配置                 | **自动；省略 `--flow-shift`**        |
| **首次运行分辨率**   | `1024×1024`                | `1024×1024`                     |
| **批量大小**      | `1`                        | `1`                             |
| **随机种子**      | `42`，或其他固定的对比种子            | `42`，或其他固定的对比种子                 |

#### 分辨率和宽高比

使用可被 **32**整除的尺寸。Qwen 的 [原生预设](https://huggingface.co/Qwen/Qwen-Image-2.1#supported-aspect-ratios) 包括：

| 形状          | 较小的测试尺寸     | Qwen 原生预设   |
| ----------- | ----------- | ----------- |
| **正方形**     | `1024×1024` | `2048×2048` |
| **横向 4:3**  | `1152×864`  | `2400×1792` |
| **纵向 3:4**  | `864×1152`  | `1792×2400` |
| **照片 3:2**  | `1248×832`  | `2528×1696` |
| **纵向 2:3**  | `832×1248`  | `1696×2528` |
| **宽屏 16:9** | `1536×864`  | `2752×1536` |
| **竖屏 9:16** | `864×1536`  | `1536×2752` |

Unsloth 支持最高尺寸为 **每边 2048 像素**。从 **1024 × 1024** 开始，如果内存允许再提高分辨率。降低步数会加快生成速度，但可能无法解决内存限制问题。

#### LoRA 和 ControlNet

加载兼容的 LoRA，可为你的生成结果加入角色、主体或视觉风格。调整 LoRA 权重以控制其对结果的影响程度。

受支持的模型也可以使用 ControlNet 来引导图像结构。调整其强度以控制结果与引导图像的贴合程度。

#### 图库

生成的图像会保存在本地图库中。打开某个结果可查看其提示词和设置，选择 **方案** 以恢复其生成设置，或下载图像。

### 受支持的模型和工作流

| 你想做什么   | 可从以下模型开始                       |
| ------- | ------------------------------ |
| 生成或转换图像 | Z-Image、Qwen-Image、FLUX.1、SDXL |
| 使用指令编辑  | Qwen-Image-Edit、FLUX.1 Kontext |
| 使用参考图像  | FLUX.2 klein                   |

模型选择器中还有更多模型可用。格式和工作流因模型而异，不支持的工作流会自动隐藏。

### 生成设置

默认设置是一个不错的起点。不过，你也可以调整设置以获得最佳结果，以下是你可能想更改的主要参数：

| 设置          | 它会改变什么                          |
| ----------- | ------------------------------- |
| **提示词**     | 描述你想创建的图像。在 **编辑**中，这会变成要遵循的指令。 |
| **宽高比和分辨率** | 设置图像的形状和大小。更大的图像会占用更多内存并耗时更长。   |
| **步骤**      | 控制模型生成所花费的时间。更多步数并不总是能提升结果。     |
| **引导**      | 控制提示词对结果的引导强度。某些模型在 `0`.        |
| **随机种子**    | 有助于复现结果。留空可使用随机种子。              |

<details>

<summary>高级生成设置</summary>

这些控制项会改变模型在你的设备上的运行方式。可通过调整它们来减少内存占用、提升性能或排查生成问题。

| 设置         | 它会改变什么                                           |
| ---------- | ------------------------------------------------ |
| **速度**     | 控制编译和性能优化。编译模式在第一次生成时可能会更慢。                      |
| **精度**     | 更改用于运行模型的数值格式。更低精度可以减少内存占用。可用选项取决于模型和硬件。         |
| **注意力**    | 选择生成过程中使用的注意力实现。                                 |
| **内存**     | 在生成速度和 GPU 内存占用之间取得平衡。可尝试 **低显存** ，如果模型接近你的内存上限。 |
| **步缓存**    | 在扩散步之间复用部分计算，以提升生成速度。                            |
| **CPU 卸载** | 将模型的部分内容移到系统内存中。这样会减少 GPU 内存占用，但可能会让生成变慢。        |

</details>

### ⚠️ 故障排查

<details>

<summary>图像未显示</summary>

更新到最新版本，然后重启应用。参见 [更新 Unsloth](https://unsloth.ai/docs/get-started/install/updating) 获取说明。

</details>

<details>

<summary>模型无法下载或加载</summary>

某些图像模型体积很大，下载需要时间。请检查是否有足够的可用存储空间以及稳定的网络连接。

某些模型还要求你在 Hugging Face 上接受其许可，并在下载前添加 Hugging Face token。

</details>

<details>

<summary>模型内存不足</summary>

尝试使用更小的 GGUF 量化版本或模型的 4-bit 版本。对于 GGUF 模型，请从标记为 **推荐**.

的尺寸开始。

* 降低图像分辨率。
* 将批量大小保持为 `1`.
* 关闭其他正在使用 GPU 的应用。
* 选择更小的模型。

一个 **极紧张** 的模型可能会使用系统内存并运行得更慢。标记为 **OOM** 的模型不太可能适配。

</details>

<details>

<summary>缺少某个工作流</summary>

可用的工作流取决于已加载的模型。不支持的工作流不会显示。

例如，基于指令的编辑需要像 Qwen-Image-Edit 或 FLUX.1 Kontext 这样的模型。

</details>

### ❓ 常见问题

<details>

<summary>图像生成是否在本地运行？</summary>

是的。一旦模型下载完成，图像生成就会在你的设备上运行。

</details>

<details>

<summary>Transform 和 Edit 有什么区别？</summary>

**Transform** 会根据描述完整结果的提示词重新绘制已有图像。

**编辑** 会遵循诸如更改背景或添加物体之类的指令。它需要兼容的编辑模型。

</details>

<details>

<summary>我可以训练自己的图像 LoRA 吗？</summary>

可以。先在你自己的图像上对受支持的模型进行微调，然后在 **创建**.

查看“微调图像模型”以了解更多信息。

</details>


---

# 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/mo-xing/qwen-image-2.1.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.