> 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/flux-3.md).

# FLUX 3 Image：如何在本地运行

使用 Unsloth FP8 和 GGUF 量化版本在本地运行并微调 FLUX.3 Image Klein，还可增强提示词、编辑图像和训练 LoRA。

**FLUX.3 Image Klein** 是 Black Forest Labs 推出的 5.6B 文生图与图像编辑模型，采用 Qwen3-VL-4B 文本编码器， **16 步**。在 Unsloth 中，生成一张 1024 × 1024 图像约需 **3 到 5 秒** ，使用 40 GB A100。

{% columns %}
{% column width="50%" %}
Klein 适合使用长而详细的提示词； **提示词增强器** 可以根据简短的想法撰写提示词。

这些量化模型采用 [Unsloth Dynamic](https://unsloth.ai/docs/basics/dynamic-3.0-ggufs)，可让重要层保持较高精度。可在 [Unsloth](https://unsloth.ai/docs/zh/desktop.md)、stable-diffusion.cpp 等工具中运行。

* FLUX.3 Image Klein： [GGUF](https://huggingface.co/unsloth/flux-3-image-klein-GGUF) • [FP8](https://huggingface.co/unsloth/flux-3-image-klein-FP8)
* FLUX.3 Image Klein Base： [GGUF](https://huggingface.co/unsloth/flux-3-image-klein-base-GGUF) • [FP8](https://huggingface.co/unsloth/flux-3-image-klein-base-FP8)
* 提示词增强器： [GGUF](https://huggingface.co/unsloth/flux-3-image-klein-pup-GGUF)

已在 NVIDIA A100（40 GB）上使用 Unsloth 2026.11.4 进行测试。
{% endcolumn %}

{% column width="50%" %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FQTjIpy3wMaxquGwfFjXu%2Fflux-3-image-klein-out-lighthouse-enhanced.webp?alt=media" alt="Photo of a white lighthouse with a lit lamp and a keeper&#x27;s cottage on a rocky coast at sunset"><figcaption><p>UD-Q4_K_XL，已启用增强器。提示词：“黄金时刻，海岸悬崖上的灯塔”</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FAUr9I8myeHeT9jCPPdV3%2Fflux-3-image-klein-out-bison.webp?alt=media" alt="A bison in a misty geothermal landscape at dawn"><figcaption><p>GGUF UD-Q4_K_XL</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fv7aDDYG13wwm4n2gTUCX%2Fflux-3-image-klein-out-cafe.webp?alt=media" alt="A chalkboard sign that reads Unsloth Coffee outside a cafe"><figcaption><p>FP8 仓库，bf16</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FpqnjARNGI1y6IQ7dB6k5%2Fflux-3-image-klein-out-robot.webp?alt=media" alt="A small knitted robot next to a houseplant on a windowsill"><figcaption><p>FP8 仓库，INT8</p></figcaption></figure></div>

### 选择 Klein 还是 Klein Base？ <a href="#klein-or-klein-base" id="klein-or-klein-base"></a>

| 模型                          | 步数与引导系数       | 适用场景                         |
| --------------------------- | ------------- | ---------------------------- |
| **FLUX.3 Image Klein**      | 16 步，引导系数 1   | 图像生成与编辑。 **从这里开始。**          |
| **FLUX.3 Image Klein Base** | 50 步，引导系数 3.5 | [LoRA 训练](#train-a-lora) 与研究 |

Klein 是从 Base 蒸馏而来；Unsloth 会为两者设置步数和引导系数。此处仅测试了 Klein。

### 内存要求 <a href="#memory-requirements" id="memory-requirements"></a>

| 你的硬件                    | 建议从以下配置开始：                                       |
| ----------------------- | ------------------------------------------------ |
| **显存 24 GB 或更高的 GPU**   | **FLUX.3 Image Klein（快速 FP8）**。Unsloth 会选择适合的精度。 |
| **显存 12 至 16 GB 的 GPU** | GGUF **UD-Q4\_K\_XL**。你可能需要关闭增强器。                |
| **显存不超过 8 GB 的 GPU**    | GGUF **UD-Q3\_K\_XL** 或 **UD-Q2\_K\_XL**，关闭增强器   |
| **内存不低于 16 GB 的 Mac**   | GGUF **UD-Q4\_K\_XL**                            |
| **仅使用 CPU，内存不低于 16 GB** | GGUF **UD-Q4\_K\_XL** （较慢）                       |

其他行是估算值。使用 40 GB A100 测量（`nvidia-smi`，上限）：

| 已加载内容                              | GPU 显存占用 |
| ---------------------------------- | -------- |
| GGUF UD-Q4\_K\_XL + INT8 文本编码器，已就绪 | 9.3 GB   |
| 相同配置，另加提示词增强器                      | 约 17 GB  |
| 相同配置，生成过程中                         | 约 22 GB  |
| 快速 FP8 配置（bf16 权重）+ 增强器，编辑过程中      | 约 27 GB  |

使用 stable-diffusion.cpp 时，UD-Q4\_K\_XL + Q8\_0 文本编码器 + VAE 占用 **8.0 GB 显存** （L4）。

#### FP8、INT8 和 GGUF <a href="#fp8-int8-and-gguf" id="fp8-int8-and-gguf"></a>

* **FLUX.3 Image Klein（快速 FP8）** 会下载 [FP8 仓库](https://huggingface.co/unsloth/flux-3-image-klein-FP8) （约 17 GB），其中包含 bf16、FP8 和 INT8 权重。在 **精度** 设为 **自动**时，Unsloth 会选择适配当前资源的格式：在我们的 40 GB A100 上，它使用了 **bf16**. **INT8** 会加载 INT8-ConvRot 文件。文本编码器始终以 INT8-ConvRot 运行。 **FP8** 需要支持 FP8 的 GPU（未经测试）。
* **flux-3-image-klein-GGUF（较慢）** 只下载所选的量化版本，也可在 Mac 和 CPU 上运行。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FyPEeQllb7XKpoHewivZV%2Fflux-3-image-klein-precision.png?alt=media" alt="The Advanced settings with the Precision menu open, showing Auto, Off, FP8, INT8 and MXFP8" width="352"><figcaption><p>高级 → 精度（关闭 = bf16）</p></figcaption></figure>

| GGUF 文件          | 大小     | 备注        |
| ---------------- | ------ | --------- |
| **BF16**         | 11 GB  | 全精度       |
| **Q8\_0**        | 6.1 GB | 最接近 BF16  |
| **UD-Q5\_K\_XL** | 4.5 GB |           |
| **UD-Q4\_K\_XL** | 3.9 GB | **推荐**    |
| **UD-Q3\_K\_XL** | 3.3 GB | 适用于小型 GPU |
| **UD-Q2\_K\_XL** | 2.6 GB | 最小        |

#### 硬件说明 <a href="#hardware-notes" id="hardware-notes"></a>

需要使用 Unsloth 2026.11.5 或更高版本。

* **T4 和其他不支持 bf16 的 GPU：** Klein 和 Klein Base 使用 fp16 和 INT8 权重运行。在配备 15 GB 显存的 Colab T4 上，分辨率为 1024 x 1024 时：

  | 任务                  | 每张图像耗时    |
  | ------------------- | --------- |
  | Klein，文生图           | 34 至 38 秒 |
  | Klein Base，文生图，12 步 | 约 54 秒    |
  | Klein 图像编辑          | 约 96 秒    |
  | Klein Base 图像编辑     | 约 130 秒   |

  图像编辑时，GPU 显存峰值约为 9.1 GB。 **默认** 速度模式在这些显卡上的运行速度不再慢于 **关闭** 。LoRA 可以加载并进行渲染。训练需要支持 bf16 的 GPU（Ampere 或更新架构）；在 T4 上，Unsloth 会报错并拒绝运行：“This trainer requires a bfloat16-capable GPU”。
* **Linux 上的 AMD** （Radeon 8060S，gfx1151）：使用 **bf16** 和 **nf4** 基座训练 Klein Base LoRA、重新加载、在 Klein 上使用 LoRA 进行渲染以及导出，均可正常运行。 **int8**, **fp8** 和 **mxfp8** 基座仅支持 NVIDIA。
* **Windows 上的 AMD** （gfx1151）：LoRA 训练正常；如果没有 C++ 编译器，训练时不会使用 torch.compile，并会显示警告。现在以 512 px 分辨率渲染的图像可以正常生成；在较早版本中，这种分辨率生成的图像曾是一片噪点。

### 快速入门 <a href="#quickstart" id="quickstart"></a>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FGg2Q8Jd4doV8TVHuEbdL%2Fflux-3-image-klein-flow.webp?alt=media" alt="Animation: pick FLUX.3 Image Klein (Fast FP8), type a prompt, click Generate and get a lighthouse on a cliff"><figcaption><p>加速后的 Unsloth 工作流</p></figcaption></figure>

{% stepper %}
{% step %}

#### 安装 Unsloth <a href="#install-unsloth" id="install-unsloth"></a>

获取 [Unsloth 桌面应用](https://unsloth.ai/docs/zh/desktop.md) ，适用于 [macOS](https://unsloth.ai/docs/zh/kuai-su-kai-shi/install/mac.md), [Windows](https://unsloth.ai/docs/zh/kuai-su-kai-shi/install/windows-installation.md) 或 [Linux](https://unsloth.ai/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>

也可以在终端中运行。适用于 MacOS、Linux、WSL：

{% code collapsedlinecount="10" %}

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

{% endcode %}

Windows PowerShell：

{% code collapsedlinecount="10" %}

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

{% endcode %}

然后启动 Unsloth 并打开 `http://localhost:8888`:

{% code collapsedlinecount="10" %}

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

{% endcode %}
{% endstep %}

{% step %}

#### 打开 Images <a href="#open-images" id="open-images"></a>

在侧边栏中选择 **Images** 。 **Create** 默认会打开。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F8VA0qli15m452CIo2DeL%2Fflux-3-image-klein-images-page.png?alt=media" alt="The Unsloth Images page with the Create workflow open and no model loaded"><figcaption><p>Images 页面</p></figcaption></figure>
{% endstep %}

{% step %}

#### 选择 FLUX.3 Image Klein <a href="#pick-flux.3-image-klein" id="pick-flux.3-image-klein"></a>

点击 **Select image model**，搜索 `flux-3-image-klein` 并选择：

* **FLUX.3 Image Klein (Fast FP8)**：适用于显存为 24 GB 或更高的 NVIDIA GPU。
* **flux-3-image-klein-GGUF (Slow)**：选择一个量化版本。 **UD-Q4\_K\_XL** 为推荐选项。

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F7ld8GwJlyKwIf9n0WXy2%2Fflux-3-image-klein-picker-search.png?alt=media" alt="Model picker search results for flux-3-image-klein with the Fast FP8, GGUF and Base entries"><figcaption><p>搜索结果</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FuwZH1ghawU9coIRFFfQE%2Fflux-3-image-klein-gguf-quants.png?alt=media" alt="The GGUF entry expanded to show its quants, with UD-Q4_K_XL marked recommended"><figcaption><p>GGUF 量化版本</p></figcaption></figure></div>

首次加载时会下载模型、Qwen3-VL-4B 文本编码器和 VAE。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FpGtiaObZ9zOIVlRFb72x%2Fflux-3-image-klein-download.png?alt=media" alt="Download panel showing unsloth/flux-3-image-klein-FP8 at 16 of 17 GB" width="400"><figcaption><p>首次下载 Fast FP8 选项</p></figcaption></figure>
{% endstep %}

{% step %}

#### 下载提示词增强器 <a href="#download-the-prompt-enhancer" id="download-the-prompt-enhancer"></a>

**增强提示词** 默认已启用，但增强器需要单独下载。点击 **Download (6.9 GB)**。下载完成前，提示词会按输入内容直接运行。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F3ImhyuNDB6ajCvlyIvHy%2Fflux-3-image-klein-enhance-download.png?alt=media" alt="Enhance prompt switch with the message that the 6.9 GB prompt upsampler is not downloaded and a Download button" width="400"><figcaption><p>增强器尚未下载</p></figcaption></figure>
{% endstep %}

{% step %}

#### 编写提示词并生成 <a href="#write-your-prompt-and-generate" id="write-your-prompt-and-generate"></a>

Unsloth 设置为 **16 步** 并 **引导强度 1**；保留这些设置。设置种子即可重复生成结果。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FMnY6sWJJfDmxiIVJ4xSq%2Fflux-3-image-klein-settings.png?alt=media" alt="Create panel with the lighthouse prompt, Enhance prompt on, 1024 by 1024 size, 16 steps and guidance 1" width="432"><figcaption><p>Klein 默认设置</p></figcaption></figure>

**预览** 会显示增强后的提示词； **用作提示词** 会将其复制到输入框中以供编辑。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FYYLjG5FX73Houj4AuVCE%2Fflux-3-image-klein-enhanced-prompt.png?alt=media" alt="The short lighthouse prompt and, below it, the long enhanced prompt written by the prompt enhancer" width="338"><figcaption><p>增强后的提示词预览</p></figcaption></figure>

点击 **生成**. **配方** 会显示所有设置，包括 **增强后的提示词**.

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FYBY7Z8KuulG11IHwzyEa%2Fflux-3-image-klein-result.png?alt=media" alt="Finished image of a lighthouse on a rocky coast at sunset, with the enhanced prompt on the left"><figcaption><p>UD-Q4_K_XL，种子 42</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F6pEui5DMl0ErLuhr9aPu%2Fflux-3-image-klein-recipe.png?alt=media" alt="Recipe card showing the prompt, the enhanced prompt, model, GGUF file, size, time, steps, guidance and seed" width="320"><figcaption><p>配方卡片</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

#### 提示词增强器 <a href="#prompt-enhancer" id="prompt-enhancer"></a>

增强器是 [flux-3-image-klein-pup](https://huggingface.co/unsloth/flux-3-image-klein-pup-GGUF)，这是一个 9B 模型（UD-Q4\_K\_XL 6.0 GB + 视觉文件 0.9 GB），可与 Klein 一起在 GPU 上运行。它会额外占用约 **7.5 GB** GPU 内存，并使每张图像的生成时间增加几秒；首次使用它生成图像耗时 23.5 秒。内存不足？关闭它并编写较长的提示词：场景、主体、动作、光线和风格。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FGY1Tu4gOxIg3INJktImx%2Fflux-3-image-klein-out-lighthouse-plain.webp?alt=media" alt="Simpler photo of a lighthouse at the end of a grassy cliff path at golden hour" width="400"><figcaption><p>相同提示词和种子，关闭增强器（4.3 秒）</p></figcaption></figure>

### 图像编辑 <a href="#image-editing" id="image-editing"></a>

在侧边栏中选择 **编辑** ，上传图像，写下指令，然后点击 **生成**。保持 16 步和引导强度 1。 **添加图像** 可添加更多参考图像。开启 **增强提示词** 后，增强器也会读取你的图像。简短、具体的指令效果最好。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FWnpm5byWe25kaz6AI8ad%2Fflux-3-image-klein-edit.png?alt=media" alt="Edit workflow with the lighthouse image as the source, the instruction to paint red and white stripes and add a sailboat, the enhanced edit prompt and the result"><figcaption><p>快速 FP8 入口（bf16）：8.9 秒，另加增强器耗时</p></figcaption></figure>

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fbzd0jcFnSE1JWobeV6R4%2Fflux-3-image-klein-edit-before.webp?alt=media" alt="Original image of a white lighthouse on a grassy cliff at golden hour"><figcaption><p>之前</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FJHm0cjexC7FEH2RcY0g0%2Fflux-3-image-klein-edit-after.webp?alt=media" alt="Edited image where the lighthouse has red and white stripes and a small sailboat is on the sea"><figcaption><p>“把灯塔漆成红白相间的条纹，并在海面上添加一艘小帆船”</p></figcaption></figure></div>

### 训练 LoRA <a href="#train-a-lora" id="train-a-lora"></a>

请参阅 [微调 FLUX 3](https://unsloth.ai/docs/zh/mo-xing/flux-3/fine-tune-flux-3.md)

#### 前后对比 <a href="#before-and-after" id="before-and-after"></a>

在 Klein 上使用相同提示词和种子，未使用（左）和使用（右）LoRA： `a trtcrd of a cat sitting on a throne holding a golden cup, "queen of cats"`.

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FWcXrlSDBcGYYD6BVE7Uj%2Fflux-3-image-klein-lora-before-after.webp?alt=media" alt="A photo-style cat on a throne without the LoRA, and a tarot card cat with the LoRA"><figcaption><p>16 步，种子 42</p></figcaption></figure>

不含触发词的提示词变化要小得多。Stable-diffusion.cpp 目前还不能加载 FLUX.3 LoRA。

[继续阅读微调指南](https://unsloth.ai/docs/zh/mo-xing/flux-3/fine-tune-flux-3.md#before-and-after)

### 通过代码运行 <a href="#run-from-code" id="run-from-code"></a>

#### Unsloth API <a href="#unsloth-api" id="unsloth-api"></a>

Unsloth 提供兼容 OpenAI 的 `POST /v1/images/generations` 端点。请先在“图像”页面加载 Klein：请求会使用已加载的模型，除非 **按请求切换图像和视频模型** 已在 **设置 → API**。也在那里创建 API 密钥（参见 [Unsloth API](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/api.md)）；示例从 `UNSLOTH_API_KEY`.

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FaVPPWWZ0eRFi4YI6Lgyb%2Fflux-3-image-klein-api-settings.png?alt=media" alt="Settings, API page with the Images and Video quickstart and the switch for loading models by request" width="563"><figcaption><p>设置 → API</p></figcaption></figure>

使用 `openai` (`pip install openai`):

{% code collapsedlinecount="10" %}

```python
import base64
import os

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8888/v1", api_key=os.environ["UNSLOTH_API_KEY"])

result = client.images.generate(
    model="unsloth/flux-3-image-klein-FP8",
    prompt="A lighthouse on a coastal cliff at golden hour",
    size="1024x1024",
    response_format="b64_json",
    extra_body={"steps": 16, "guidance": 1.0, "seed": 42},
)

with open("lighthouse.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
```

{% endcode %}

使用 `curl`:

{% code collapsedlinecount="10" %}

```bash
curl -s http://localhost:8888/v1/images/generations \
  -H "Authorization: Bearer $UNSLOTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "unsloth/flux-3-image-klein-FP8",
    "prompt": "A lighthouse on a coastal cliff at golden hour",
    "size": "1024x1024",
    "response_format": "b64_json",
    "seed": 7
  }' \
  | python3 -c "import sys, json, base64; open('lighthouse-curl.png', 'wb').write(base64.b64decode(json.load(sys.stdin)['data'][0]['b64_json']))"
```

{% endcode %}

`size` 为 `WIDTHxHEIGHT`，范围为 256 到 2048，且必须是 16 的倍数。 `steps` 和 `guidance` 默认值分别为 16 和 1。

**通过 API 使用 LoRA** （Unsloth 2026.11.5 或更高版本）：在请求中添加 `"loras": [{"id": "my-lora", "weight": 1.0}]` ，其中 `id` 是 LoRA 列表中的名称；若不使用任何 LoRA，则添加 `"loras": []` 。如果没有 `loras`，FP8 和 INT8 加载会保留加载时指定的 LoRA，例如在 **部署到 Create**.

FP8 和 INT8 加载仅在模型加载时载入 LoRA。使用此类加载方式发出的请求可以使用已载入的 LoRA（或其中一部分），但如果使用未载入的 LoRA，则会返回 400 错误。请先加载包含该 LoRA 的模型：在 Images 页面中选择它，然后点击 **重新应用**，或者在加载模型时将其作为 `loras` 传入。bf16 加载（**精度** 设为 **关闭**）则支持按请求使用任意 LoRA。

{% hint style="info" %}
API 不会运行提示词增强器。请发送详细的提示词，或在 Images 页面使用 **预览** 编写提示词。
{% endhint %}

#### 使用 stable-diffusion.cpp 运行 GGUF <a href="#gguf-with-stable-diffusion.cpp" id="gguf-with-stable-diffusion.cpp"></a>

使用 `sd-cli` （来自 [stable-diffusion.cpp](https://github.com/unslothai/stable-diffusion.cpp) ）运行 GGUF（Unsloth 固定版本；不含提示词增强器）。

**1. 获取 `sd-cli`** （Linux，CUDA 13）。 [发布页面](https://github.com/unslothai/stable-diffusion.cpp/releases/tag/master-982-0518b34-u27b9ddc) 还提供 CUDA 12、Vulkan、CPU、macOS 和 Windows 版本。

{% code collapsedlinecount="10" %}

```bash
curl -L -o sd.zip https://github.com/unslothai/stable-diffusion.cpp/releases/download/master-982-0518b34-u27b9ddc/sd-master-982-0518b34-u27b9ddc-bin-Linux-Ubuntu-22.04-x86_64-cuda13.zip
unzip -o sd.zip
mv sd-master-982-0518b34-u27b9ddc-bin-Linux-Ubuntu-22.04-x86_64-cuda13 sd
./sd/sd-cli --version
```

{% endcode %}

**2. 下载模型、文本编码器和 VAE** （约 8.5 GB）：

{% code collapsedlinecount="10" %}

```bash
pip install -U huggingface_hub
hf download unsloth/flux-3-image-klein-GGUF flux-3-image-klein-UD-Q4_K_XL.gguf --local-dir models
hf download unsloth/Qwen3-VL-4B-Instruct-GGUF Qwen3-VL-4B-Instruct-Q8_0.gguf --local-dir models
hf download unsloth/flux-3-image-klein-FP8 vae/diffusion_pytorch_model.safetensors --local-dir models
```

{% endcode %}

**3. 生成图像** （在 A100 上约需 14 秒，包括加载时间）：

{% code collapsedlinecount="10" %}

```bash
./sd/sd-cli \
  --diffusion-model models/flux-3-image-klein-UD-Q4_K_XL.gguf \
  --llm models/Qwen3-VL-4B-Instruct-Q8_0.gguf \
  --vae models/vae/diffusion_pytorch_model.safetensors \
  -p "A white lighthouse on a grassy coastal cliff at golden hour, waves breaking on the rocks below, warm low sunlight, soft clouds over the sea, detailed landscape photo" \
  --steps 16 --cfg-scale 1.0 --sampling-method euler \
  -W 1024 -H 1024 --diffusion-fa --seed 42 \
  -o lighthouse-sdcpp.png
```

{% endcode %}

**4. 编辑图像** （24 秒）。使用 `-r`传入最多 10 张参考图。请描述编辑后图像的整体内容，而不只是改动之处。

{% code collapsedlinecount="10" %}

```bash
./sd/sd-cli \
  --diffusion-model models/flux-3-image-klein-UD-Q4_K_XL.gguf \
  --llm models/Qwen3-VL-4B-Instruct-Q8_0.gguf \
  --vae models/vae/diffusion_pytorch_model.safetensors \
  -r lighthouse-sdcpp.png \
  -p "同一座灯塔矗立在同一处海岸悬崖上，正值黄金时刻；如今灯塔漆上了醒目的红白横条纹，海面上还有一艘白色小帆船" \
  --steps 16 --cfg-scale 1.0 --sampling-method euler \
  -W 1024 -H 1024 --diffusion-fa --seed 42 \
  -o lighthouse-sdcpp-edit.png
```

{% endcode %}

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FvzWfsBB5NEx4aj1sJZxK%2Fflux-3-image-klein-sdcpp-lighthouse.webp?alt=media" alt="White lighthouse on a grassy cliff above breaking waves at golden hour, made with sd-cli"><figcaption><p>sd-cli，种子 42</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FcDFt1OjcIM85yHspkii0%2Fflux-3-image-klein-sdcpp-edit.webp?alt=media" alt="The same lighthouse painted with red and white stripes, with a small sailboat on the sea"><figcaption><p>sd-cli 编辑</p></figcaption></figure></div>

在 Mac 或 CPU 上，可在应用中使用 GGUF 量化版本，或使用 `Darwin-macOS-arm64` / CPU `sd-cli` 构建版本（未经我们测试）。

### 推荐设置 <a href="#recommended-settings" id="recommended-settings"></a>

| 设置           | Unsloth（FP8 或 GGUF）            | stable-diffusion.cpp      |
| ------------ | ------------------------------ | ------------------------- |
| **步数**       | **16**                         | `--steps 16`              |
| **引导 / CFG** | **1**                          | `--cfg-scale 1.0`         |
| **采样器**      | 由 Unsloth 设置                   | `--sampling-method euler` |
| **负面提示词**    | 不使用                            | 不使用                       |
| **大小**       | `1024×1024` 建议从此尺寸开始，最高可达 2048 | `-W 1024 -H 1024`         |
| **提示词增强器**   | 开启（下载 6.9 GB）                  | 不可用                       |
| **种子**       | 使用任意数字即可重现结果                   | `--seed 42`               |

### 输出示例 <a href="#example-outputs" id="example-outputs"></a>

A100 40 GB，1024 × 1024，16 步，引导值 1，种子 42。

| 提示词                              | 模型                | 增强器     | 耗时           |
| -------------------------------- | ----------------- | ------- | ------------ |
| 黄金时刻，一座灯塔矗立在海岸悬崖上                | GGUF UD-Q4\_K\_XL | 开启      | 23.5 秒（首张图像） |
| 黄金时刻，一座灯塔矗立在海岸悬崖上                | GGUF UD-Q4\_K\_XL | 关闭      | 4.3 秒        |
| 黎明时分，薄雾笼罩的地热景观中，一头野牛             | GGUF UD-Q4\_K\_XL | 关闭（API） | 4.5 秒        |
| 小咖啡馆外的黑板菜单上写着“Unsloth Coffee”，晨光 | 快速 FP8、bf16       | 关闭（API） | 3.4 秒        |
| 窗台上的一盆室内植物旁，有个正在浇水的迷你针织机器人       | 快速 FP8、INT8       | 关闭（API） | 2.7 秒        |

加载后首次生成 Fast FP8 图像大约需要 16 秒，这是因为 Unsloth 正在编译模型。

### 故障排除 <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>模型选择器中没有 FLUX.3 Image Klein</summary>

[更新 Unsloth](https://unsloth.ai/docs/get-started/install/updating) 并重启。如果已加载模型，选择器会默认打开 **On Device**：点击 **Recommended**.

</details>

<details>

<summary>已开启“增强提示词”，但提示词没有得到增强</summary>

点击 **Download** 下方的 **Enhance prompt**。运行后，Recipe 中会显示一行 **Enhanced prompt** 。API 不会运行此功能。

</details>

<details>

<summary>GPU 内存不足</summary>

关闭 **Enhance prompt** ，或使用更小的量化版本，例如 UD-Q3\_K\_XL。

</details>

<details>

<summary>API 忽略了我指定的模型</summary>

在 Images 页面加载 Klein，或在 **Switch image and video model by request** 中 **Settings → API**.

</details>

<details>

<summary>sd-cli 提示缺少 libcudart.so.12 或 libcudart.so.13</summary>

使用 `cuda13` 压缩包（使用 CUDA 13）、 `cuda12` （使用 CUDA 12），或 Vulkan 构建版本。

</details>

另请参阅 [如何在本地运行图像扩散模型](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/diffusion-image.md).


---

# 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/flux-3.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.
