🎨在 stable-diffusion.cpp 中运行 Qwen-Image-2512 教程

在 stable-diffusion.cpp 中使用 Qwen-Image-2512 的教程。

Qwen-Image-2512 是 Qwen 的新文本生成图像基础模型，你现在可以通过 stable-diffusion.cpp 在本地设备上运行它。说明如下：

📖 stable-diffusion.cpp 教程

stable-diffusion.cpp 是一个开源库，用纯 C/C++ 编写，可高效在本地推理扩散图像模型。

运行时不需要 GPU，只要有带内存的 CPU 就可以。为获得最佳效果，请确保你的总可用内存（RAM + VRAM / 统一内存）大于 GGUF 大小；例如 4-bit（Q4_K_M） unsloth/Qwen-Image-Edit-2512-GGUF 是 13.1 GB，因此你应该至少有 13.2+ GB 的合并内存。

本教程将重点介绍可用 CUDA 的机器，但在 Apple 或仅 CPU 上构建的说明也类似，并且可在仓库中找到。

#1. 配置环境

我们将从源代码构建，因此首先需要确认已安装构建所需的软件

sudo apt update
sudo apt install -y git cmake build-essential pkg-config

发布页面 如果你不想经历构建过程，可能会有适用于你的硬件的预编译二进制文件。

确保已设置 CUDA 环境变量：

export CUDA_HOME=/usr/local/cuda
export PATH="$CUDA_HOME/bin:$PATH"
export LD_LIBRARY_PATH="$CUDA_HOME/lib64:${LD_LIBRARY_PATH:-}"

你可以通过运行以下命令确认是否设置正确：

nvcc --version  // 如果找不到，请安装 nvidia-cuda-toolkit
ldconfig -p | grep -E 'libcudart\.so|libcublas\.so'

现在我们可以克隆仓库并构建：

git clone --recursive https://github.com/leejet/stable-diffusion.cpp
cd stable-diffusion.cpp

mkdir -p build
cd build

cmake .. -DCMAKE_BUILD_TYPE=Release -DSD_CUDA=ON
cmake --build . -j"$(nproc)"

确认 sd-cli 已构建：

ls bin/sd-cli

#2. 下载模型

扩散模型通常需要 3 个组件：一种将图像像素空间编码到潜空间的变分自编码器（VAE），一种将文本转换为输入嵌入的文本编码器，以及实际的扩散变换器。扩散模型和文本编码器都可以使用 GGUF 格式，而 VAE 通常使用 safetensors。让我们下载将要使用的模型：

cd .. 
mkdir models
mkdir outputs

## 扩散模型
curl -L -C - -o models/qwen-image-2512-Q4_K_M.gguf \\
  https://huggingface.co/unsloth/Qwen-Image-2512-GGUF/resolve/main/qwen-image-2512-Q4_K_M.gguf
curl -L -C - -o models/qwen-image-edit-2511-Q4_K_M.gguf \\
  https://huggingface.co/unsloth/Qwen-Image-Edit-2511-GGUF/resolve/main/qwen-image-edit-2511-Q4_K_M.gguf
 
## 文本编码器 + VAE   
curl -L -C - -o models/Qwen2.5-VL-7B-Instruct-UD-Q4_K_XL.gguf \\
  https://huggingface.co/unsloth/Qwen2.5-VL-7B-Instruct-GGUF/resolve/main/Qwen2.5-VL-7B-Instruct-UD-Q4_K_XL.gguf
curl -L -C - -o models/qwen_image_vae.safetensors \\
  https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/resolve/main/split_files/vae/qwen_image_vae.safetensors

我们使用的是 Q4 GGUF 变体，但你可以根据自己的 VRAM/RAM 多少尝试更小或更大的量化类型。

vae 和扩散模型的格式可能与 diffusers 检查点不同。只使用与 stable-diffusion.cpp 和 ComfyUI 兼容的检查点。

工作流和超参数

你可以查看我们详细的 Run GGUFs in ComfyUI 指南。

#3. 推理

现在我们可以运行刚刚构建的二进制文件。以下是一个基础文本生成图像命令示例：

./build/bin/sd-cli --diffusion-model models/qwen-image-2512-Q4_K_M.gguf \\
    --vae models/qwen_image_vae.safetensors \\
    --llm models/Qwen2.5-VL-7B-Instruct-UD-Q4_K_XL.gguf \\
    --cfg-scale 2.5 --sampling-method euler -v --steps 40 \\
    -H 1024 -W 1024 --diffusion-fa --flow-shift 3 \\
    -p '一张航拍照片，展示一大片明亮的黄色野花田，文字“Unsloth + Diffusion”由深紫色薰衣草花拼成，黄色与紫色形成鲜明对比，花坛构成自然有机的字形，黄金时刻光线，起伏的乡间景观，从高空垂直向下的视角，照片级真实感，8K 分辨率'  \\
    --offload-to-cpu -o outputs/unsloth_diffusion.png

无需使用 --offload-to-cpu 如果你有足够的 VRAM。