🎨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つのコンポーネントが必要です。画像ピクセル空間を潜在空間に変換するVariational AutoEncoder（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がある場合。