> 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** 和 **Qwen-Image-2.1-Turbo** 生成和 [编辑图像](#image-editing)。Qwen-Image-2.1 有 70 亿参数，需要 **11GB 显存** 使用 GGUF 版本，或使用 INT8/FP8 需要 24GB 显存。

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

量化版本使用 [Unsloth Dynamic](https://unsloth.ai/docs/basics/dynamic-3.0-ggufs) ，它会将重要层提升到更高精度以获得更高准确度。可在 [Unsloth Desktop](/docs/zh/desktop.md)、diffusers、stable-diffusion.cpp 等中运行。

* Qwen-Image-2.1**:** [GGUF](https://huggingface.co/unsloth/Qwen-Image-2.1-GGUF) • [FP8](https://huggingface.co/unsloth/Qwen-Image-2.1-FP8)
* Qwen-Image-2.1-**Turbo**: [GGUF](https://huggingface.co/unsloth/Qwen-Image-2.1-Turbo-GGUF) • [FP8](https://huggingface.co/unsloth/Qwen-Image-2.1-Turbo-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 内存，主要使用 GGUF 模型；或者使用统一内存系统，例如 Mac。

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

| 可用硬件                              | 起始配置                                                                                       |
| --------------------------------- | ------------------------------------------------------------------------------------------ |
| **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 内存**             | 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/kuai-su-kai-shi/install/mac.md), [Windows](/docs/zh/kuai-su-kai-shi/install/windows-installation.md)，以及 [Linux](/docs/zh/kuai-su-kai-shi/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 中仅支持文生图生成。

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

在其中打开“选择图像模型”，或者前往 Model hub，并在选择器中搜索你想要的 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 中选择 Edit 选项卡并输入提示词。

<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** | 保留管线的调度器配置                 | **自动；省略 `--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 令牌。

</details>

<details>

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

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

你也可以：

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

一个 **TIGHT** 模型可能会使用系统内存并运行得更慢。标记为 **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 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/mo-xing/qwen-image-2.1.md?ask=<question>&goal=<user_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.