🎨在 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，只需一台有足够内存（RAM）的 CPU 即可。为了获得最佳效果，请确保你的总可用内存（RAM + VRAM/统一内存）大于 GGUF 文件大小；例如 4 位（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

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