DiffusersWEBUI

A single FastAPI server + web UI that runs multiple state-of-the-art image and video diffusion model families (Qwen-Image family, FLUX.2, Z-Image-Turbo, LTX-2.3 video+audio, JoyAI-Edit-Plus) side by side, with automatic VRAM management, quantization, and a shared comparison UI — built to run comfortably on a single 48GB-class GPU.

(リポジトリ/ディレクトリ名: diffusers-server)

概要

複数のモデルファミリー(Qwen-Image 系 / FLUX.2 / Z-Image-Turbo / LTX-2.3 動画+音声 / JoyAI-Edit-Plus)を単一の FastAPI サーバ + 単一の Web UI で動かす統合画像・動画生成サーバ。 VRAM に同時常駐できないモデル同士は自動でアンロード(排他制御)しながら切り替えるため、 1枚の GPU で複数系統のモデルを使い分けられる。

動画生成の最新版は diffusers-movie-server にあります(2026-08-26 方針決定)

本サーバが持つ動画機能は LTX-2.3(families/ltx2)です。 LTX-2.5 と MiniMax-H3(リップシンク)は本サーバには入っていません — これらは別リポジトリ diffusers-movie-server(gateway: ポート 8630)に集約しています。

	このサーバ(8601)	diffusers-movie-server(8630)
画像系(T2I/I2I/Edit/ControlNet/Layered/Tポーズ 等)	あり	なし
動画	LTX-2.3	LTX-2.5 / MiniMax-H3
リップシンク(歌唱の口パク)	なし	あり(vocal_lock)

両方を追従して保守するのは手間に見合わないため、動画系の新規開発・追従は diffusers-movie-server 側のみで行います。本サーバの LTX-2.3 は現状維持 (動くものはそのまま残す)で、LTX-2.5 / H3 への更新予定はありません。

アプリ側の使い分け: LTX-2.5 や H3(リップシンク)が必要な場合は、 アプリの接続先サーバを diffusers-movie-server(8630)へ切り替えてください。 画像生成はこのサーバ(8601)、動画は 8630、という併用が想定構成です (実例: mv_studio_V3 は画像 8620 / 動画 8630 の2サーバ構成で動いています)。

主な機能

• T2I(Text-to-Image) — Qwen-Image / Qwen-Image-2512 / FLUX.2-dev / Z-Image-Turbo
• I2I(Image-to-Image) — 上記モデル共通
• Edit(参照画像編集) — Qwen-Image-Edit-Plus(2511)/ JoyAI-Edit-Plus(複数参照画像合成)
• ControlNet(Canny 等)、Inpaint(マスク指定領域の再生成)
• Layered(RGBA レイヤー分解生成)
• アウトペイント(画角拡張。既存 Inpaint 機構の流用で、中央部は元画像のピクセルを保証)
• 背景削除(rembg / anime-segmentation / BiRefNet HR Mattingを選択可、独立タブ + 各結果パネルへのインスタントボタン)
• キャラクターシート生成(1枚の画像から8方向のキャラクター画像を自動生成)
• シーンアングル生成(1枚のシーン画像からカメラ8アングルを生成)
• Tポーズ4ビュー生成(1枚の画像から正面/背面/真横左右 + 参考の左前45度。 T / A / 入力ポーズ維持を選択可。 背景透過版・透過版の白残り補正・2048アップスケール・生成後の追加編集に対応)
• Mage-Flow(Microsoft、軽量4.1B の T2I / Edit。専用venvの別プロセスへプロキシ)
• 動画生成(LTX-2.3) — Text-to-Video / Image-to-Video / First-Last-Frame 補間 / リップシンク(Image+Audio-to-Video)/ 任意キーフレーム条件付け / Video-to-Audio / IC-LoRA による動画編集 / 潜在空間アップスケール(2x)
• LLM プロンプト支援(任意の OpenAI 互換ローカル LLM サーバと連携した英語強化・和文英訳)
• 比較ギャラリー(生成結果を並べて比較・ダウンロード)

動作要件

• Python 3.12
• CUDA 対応 GPU、VRAM 48GB 推奨(全機能を使う場合。16GB / 24GB 級でも一部機能は 動作します。何がどこまで動くかは後述の 「16GB / 24GB VRAM 環境での動作」を参照)
• RAM 64GB 推奨(group offload 系のオフロードモードがホスト RAM に重みを保持するため。 VRAM が少ない環境ほど group offload に頼るので、RAM の要件はむしろ厳しくなります)
• ffmpeg(任意。動画生成時の音声 mux に使用。無い場合は映像のみ mp4 + 音声 wav の 別ファイルにフォールバック)

機能別のおおよその VRAM 目安(実測ベース、48GB GPU 環境)

実際の値は解像度・ステップ数・オフロード設定によって変動します。詳細な実測値は API_SPEC.md および各エンドポイントのレスポンスに含まれる peak_vram_gb を参照してください。

注意: レスポンスの peak_vram_gb は 生成フェーズの PyTorch アロケート量であり、 モデルロード中の一時ピークは含みません。ロード時のほうが大きくなるモデルがあるため (LTX-2.3 は生成 17.7GB に対しロード時 約29GB)、必要 VRAM の見積もりには peak_vram_gb だけを使わないでください。

16GB / 24GB VRAM 環境での動作

48GB 未満の GPU でも、一部の機能は group offload(transformer をブロック単位で GPU⇔ホストRAM に流す方式)を使えば動作します。以下は実機検証の結果です (RTX 4000 SFF Ada Generation 20GB 実機、および 16GB / 24GB は同一機で GPU メモリを バラスト確保して空き容量を制限して再現。2026-08-03 実測)。

要点は text_encoder(Qwen2.5-VL 7B、bf16 で約16GB)をどう扱うかです。 DS_QWEN_TE_QUANT=fp8 を指定すると 15.45GB → 8.74GB に圧縮され(実測)、 16GB カードでも Qwen-Image の T2I / I2I / Edit / ControlNet / Inpaint が動きます。

✅ = 実機で生成成功を確認 / ✗ = OOM を実機確認、または構成上明らかに不足 / ？ = 未検証

起動コマンド

16GB / 20GB(Qwen-Image の T2I / I2I / Edit)

DS_T2I_MODEL=qwen-image DS_QUANT=none DS_OFFLOAD=group DS_QWEN_TE_QUANT=fp8 \
  venv/bin/python -m uvicorn app:app --host 0.0.0.0 --port 8601

16GB / 20GB で ControlNet / Inpaint / アウトペイントも使う場合(group_lowvram に変更)

DS_T2I_MODEL=qwen-image DS_QUANT=none DS_OFFLOAD=group_lowvram DS_QWEN_TE_QUANT=fp8 \
  venv/bin/python -m uvicorn app:app --host 0.0.0.0 --port 8601

24GB(TE を bf16 のままにでき、group で速度も稼げる)

DS_T2I_MODEL=qwen-image DS_QUANT=none DS_OFFLOAD=group \
  venv/bin/python -m uvicorn app:app --host 0.0.0.0 --port 8601

Z-Image-Turbo だけを使うなら DS_OFFLOAD=group のみで動きます(text_encoder が bf16 約8GB と小さく、transformer 11.5GB を group offload できるため 16GB に収まります)。

各設定の意味

• DS_T2I_MODEL=qwen-image — 既定の 2512 は fp8-lightning 方式専用で、bf16 transformer (約40GB)を GPU 上で fuse するため 48GB 未満では不可
• DS_QUANT=none — 同上(fp8-lightning は選べない)
• DS_OFFLOAD=group — transformer のみブロック単位でオフロード。Lightning LoRA は この構成でも有効(4steps / 8steps とも利用可)
• DS_QWEN_TE_QUANT=fp8 — 共有 text_encoder を fp8_e4m3fn ストレージ + bf16 compute の layerwise casting で圧縮(15.45GB → 8.74GB 実測)。GPU へ載せる前に CPU 上で圧縮するため、 bf16 の16GBが GPU 上に一度も存在しません。同一 seed の bf16 出力と比較して構図・陰影は ほぼ一致(PSNR 32.3dB、目視で差はごくわずか)。既定は none なので 48GB 運用は無変更です
• DS_OFFLOAD=group_lowvram — group に加えて denoise 中は text_encoder も CPU へ退避。 ControlNet / Inpaint のように denoise 側が重い処理で効きます(Inpaint 1024²: TE fp8 + group は 15.3GB で OOM → group_lowvram なら 13.1GB で成功)。 ただし GPU⇔CPU 往復のぶん遅くなります(同条件で 102.4s → 241.3s)

VRAM 別のまとめ

いずれの場合も 2512 / fp8-lightning、キャラシート系、LTX-2.3(動画)は使えません。

制約と注意点

• 生成速度は大きく低下します。 group offload は毎ステップ全ブロックが PCIe を通るため、 上記 Qwen-Image は 1ステップあたり約13.7秒(48GB 環境の fp8-lightning は 1〜2秒程度)。 このコストはステップごとにほぼ固定で、解像度を下げてもあまり速くなりません (512² 110.5s / 1024² 119.4s とほとんど変わらない)。短時間で多数生成する用途には向きません。
• ホスト RAM が別途必要です。 group offload は重みをホスト RAM に常駐させます。 Qwen-Image は bf16 transformer 約40GB を RAM に置くため、空き RAM 48GB 以上(実質 RAM 64GB 以上の搭載)が必要です。不足するとスワップに突入してシステム全体が停止する おそれがあります。Z-Image-Turbo は約12GB なので RAM 要件も緩やかです。
• ファミリー切替(Z-Image ⇔ Qwen-Image)は自動アンロードで動作しますが、切替のたびに 再ロード(数十秒)が発生します。

セットアップ

1. Python 仮想環境の作成

python3.12 -m venv venv
source venv/bin/activate

2. 依存パッケージのインストール

pip install -r requirements.txt

重要: diffusers は PyPI のリリース版ではなく git 版が必要です(本リポジトリは 0.40.0.dev0 で動作確認済み)。理由: Z-Image / LTX-2.3 / Layered など一部パイプラインが リリース版にまだ含まれていない実装に依存しているため。

pip install "git+https://github.com/huggingface/diffusers"

git 版は日々更新されるため、動作確認済みのコミットと異なる場合があります。問題が 発生した場合は requirements.txt に記載のバージョンや、diffusers のコミット履歴から 近い時期のコミットを試してください。

transformers は 5.x 系列を使用します(AutoProcessor が一部モデルで正しく解決できない 既知の問題があるため、Qwen2VLProcessor 等クラスを明示指定するコードになっています)。

CUDA 対応の PyTorch(cu128 系でビルド済みのものを推奨)を GPU 環境に合わせて別途 インストールしてください:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

一部の付随機能は追加パッケージを必要とします(本体の生成機能には不要です。開発環境では ComfyUI 側の site-packages を継承していたため長らく明示されていませんでした):

pip install timm spandrel   # timm: 背景除去 BiRefNet HR Matting の remote code が import する
                            # spandrel: Tポーズの2048アップスケール(Real-ESRGAN x2)

3. モデルの取得

モデルの重みは本リポジトリに含まれません。初回リクエスト時に Hugging Face Hub から 自動ダウンロードされ、通常の HF キャッシュ(~/.cache/huggingface)に保存されます。

既に ComfyUI 環境をお持ちの場合、 DS_COMFYUI_DIR 環境変数(既定 ~/ComfyUI)配下の models/diffusion_models/ や models/loras/ 等を優先的に参照し、無ければ Hugging Face Hub からダウンロードします。 LTX-2.3(動画生成)は ComfyUI 形式のチェックポイントを前提とするため、 DS_LTX2_CKPT_PATH 等でファイルパスを指定する必要があります(詳細は環境変数表参照)。

4. Mage-Flow セットアップ(任意、別プロセス・専用venv)

Mage-Flow(Microsoft、軽量4.1B T2I/Edit、MIT)は torch 2.13 / transformers 5.5 / flash-attn 2.8.3 を要求し、本体venvとバージョン衝突するため完全隔離の専用venvで 動かします(--system-site-packages は使わない。comfy-env にもインストールしない)。

# 1) Mage リポジトリの取得
mkdir -p third_party && git clone --depth 1 https://github.com/microsoft/Mage.git third_party/Mage

# 2) 専用venv(完全隔離)
python3.12 -m venv venv-mageflow

# 3) torch は cu130 系(sm_120/Blackwell のカーネルは cu129 以降にしか入っていない。
#    cu126/cu128 wheel は sm_120 非対応なので不可)
venv-mageflow/bin/pip install --index-url https://download.pytorch.org/whl/cu130 \
    torch==2.13.0 torchvision==0.28.0

# 4) 残りの依存 + ラッパーサービス用パッケージ
venv-mageflow/bin/pip install diffusers==0.38.0 transformers==5.5.0 \
    "accelerate>=1.0.0" "safetensors>=0.8.0" einops pydantic pillow loguru \
    fastapi uvicorn python-multipart requests ninja

# 5) flash-attn 2.8.3 をソースビルド(必須。varlen packing が唯一のattention経路)。
#    nvcc は torch の CUDA メジャーと一致させる(cu130 → /usr/local/cuda-13.0)。
#    ★並列数を必ず制限すること(無制限だと 20並列nvcc がホストRAMを食い潰し
#      システム全体を巻き込むOOMになった実績あり。CLAUDE.md 50番)
systemd-run --user --scope -p MemoryMax=45G -p MemorySwapMax=0 \
    env PATH=/usr/local/cuda-13.0/bin:$PATH CUDA_HOME=/usr/local/cuda-13.0 \
    MAX_JOBS=4 NVCC_THREADS=2 TORCH_CUDA_ARCH_LIST="12.0" \
    venv-mageflow/bin/pip install --no-build-isolation flash-attn==2.8.3

# 6) mage_flow パッケージ(依存は上で導入済みなので --no-deps)
venv-mageflow/bin/pip install -e third_party/Mage/mage_flow --no-deps

モデル(HF Hub、各リポジトリ自己完結型 diffusers-style)は初回リクエスト時に自動 ダウンロードされます(T2I/Edit 各 base/rl/turbo の6リポジトリ。既定の rl は microsoft/Mage-Flow + microsoft/Mage-Flow-Edit)。

起動方法

python -m uvicorn app:app --host 0.0.0.0 --port 8601

起動後、ブラウザで http://localhost:8601/ を開くと Web UI が表示されます。

Mage-Flow を使う場合はラッパーサービスも起動します(別プロセス、既定ポート8602):

./run_mageflow.sh                      # ポートは DS_MAGEFLOW_PORT で変更可
# 本体側はラッパーへ DS_MAGEFLOW_URL(既定 http://127.0.0.1:8602)で接続する。
# ポートを変えた場合は本体起動時に DS_MAGEFLOW_URL を合わせること。

UI 構成

タブ構成: T2I / I2I / Edit / ControlNet / Inpaint / Layered / 背景削除 / キャラシート / シーンアングル / Tポーズ4ビュー / 動画(LTX-2.3)/ Mage-Flow。

• T2I / I2I タブ: モデル選択で Qwen-Image-2512 / Qwen-Image(無印) / FLUX.2-dev / Z-Image-Turbo を切り替え
• Edit タブ: Qwen-Image-Edit-Plus(2511)/ JoyAI-Edit-Plus(複数参照画像合成)を切替
• Inpaint タブ: Qwen ControlNet / Z-Image-Turbo を切替
• シーンアングル / Tポーズ4ビュー タブ: 生成するアングル・ビューをチェックボックスで 選択。Tポーズタブは生成後の追加編集(色調整・部分修正)・取り消し・2048アップスケール・ ビュー個別/ZIP ダウンロードに対応
• 動画タブ: T2V / I2V / FLF(First-Last-Frame)等のサブタブ
• Mage-Flow タブ: T2I / Edit のサブタブ(base/rl/turbo バリアント選択、 「排他制御」チェックボックス既定ON。別プロセスのラッパーサービス経由、 未起動時は起動コマンド入りのエラーメッセージを表示)

各生成結果パネル・比較ギャラリーカードには、ダウンロードボタンとインスタント背景削除 ボタンが付いています。

API

主要なエンドポイント:

生成系エンドポイントは GPU を同時1件のみ使用するグローバルロックで排他され、実行中は 409 を返します。レスポンスには所要時間・ピークVRAM・使用パラメータ・seed 等の統一 メタデータが含まれます。

詳細なパラメータ・レスポンス例・curl サンプルは API_SPEC.md を参照してください。

環境変数

環境変数名は DS_* に統一されています(主要なもののみ抜粋。全項目は API_SPEC.md / core/config.py 参照)。

VRAM しきい値はお使いの GPU の空き VRAM に合わせて調整してください。値を大きくしすぎると 本来オフロード不要な構成までオフロードされ低速になり、小さくしすぎると OOM のリスクが 上がります。

LTX-2.3 group オフロードのホスト RAM ガードについて: group モード(既定)は transformer(bf16 約35.4GB)を一時的にホスト RAM 上に構築してから GPU への block-level 転送に登録する設計のため、パイプラインの初回ロード時(サーバ起動後の最初のLTX-2.3 生成リクエスト、または /api/unload や他ファミリーへの切替でLTX-2.3が一度アンロード された後の次回ロード時)に、空きホスト RAM(/proc/meminfo の MemAvailable)が DS_LTX2_GROUP_OFFLOAD_MIN_RAM_GB(既定 40.0GB)を下回っていると、システムフリーズを 避けるためロード自体を明確なエラーメッセージ付きで中止します(旧実装がこのガードを 持たず実際にフリーズ・強制終了を招いた経緯は CLAUDE.md 17番参照)。このガードは 動画の解像度・フレーム数・アップスケール有無とは無関係です(一度ロードされた パイプラインはそれ以降のリクエストで再チェックされません)。ブラウザ・IDE 等 他アプリのメモリ使用量が大きいマシンでは、LTX-2.3 生成の最初の1回目がこのエラーで 失敗することがあります。その場合は他アプリを閉じるかホストRAMの空きを確保してから 再試行してください(free -h の available 列で確認可能)。閾値を下げる (DS_LTX2_GROUP_OFFLOAD_MIN_RAM_GB)ことも可能ですが、フリーズのリスクとのトレード オフのため推奨しません。

使用モデルとライセンス

モデルの重みは本リポジトリに含まれません。 各モデルは初回利用時に Hugging Face Hub 等から取得され、それぞれ配布元が定めるライセンス・利用規約に従います。以下は本サーバが 呼び出すモデルの一覧です。正確な最新のライセンス条項は必ず各モデルカードを参照して ください(下表は本ドキュメント作成時点の確認結果であり、将来変更される可能性があります)。

本リポジトリ自体(コード)は Apache License 2.0 で公開していますが、上記モデルの 重みを利用して生成したコンテンツやモデルの再配布については、各モデルのライセンス条項が 別途適用されます。特に FLUX.2-dev は非商用ライセンスである点にご注意ください。 商用利用を検討する場合は、Qwen-Image 系・Z-Image-Turbo・JoyAI-Edit-Plus 等の Apache 2.0 モデルの使用を推奨します。

既知の制約

• 生成系エンドポイントは GPU 排他制御のため同時に1件しか実行できません(実行中は 409 を返します)。
• 一部のモデルファミリー(Qwen-Image系 / FLUX.2 / Z-Image-Turbo / LTX-2.3 / JoyAI-Edit-Plus)は VRAM 同時常駐不可とみなし、ファミリー切替時に自動アンロードします。 切替には数十秒程度かかる場合があります。
• GGUF 量子化された T2I/Edit transformer への Lightning LoRA 適用は transformer-level API(load_lora_adapter())経由で利用できます。 旧来の pipe.load_lora_weights() 経路は GGUFLinear をPEFTが認識できず失敗しますが、 Edit(2026-08-16、CLAUDE.md 59番・62番)に続き T2I/I2I(2026-08-17、CLAUDE.md 66番) も同方式に統一したため、GGUF 量子化のまま Lightning 4steps が使えます(8steps用の Lightning LoRA は無印/2512とも配布されていないため4stepsのみ対応。8steps要求時は 30steps/cfg4.0へ自動フォールバックします)。
• GGUF Edit(DS_QUANT=gguf-q4_k_m 等)は空きVRAMに応じて自動的に3段階 (48GB級: 全常駐 / 24GB級: text_encoderのみ量子化(既定nf4) / 20GB未満: enable_model_cpu_offload())に分かれます。2026-08-16に48GB級・24GB級(fp8)も 実機検証済みで、1024²・目視で破綻なく完走することを確認しました(48GB級ピークVRAM 29.94GB / 24GB級(fp8)23.27GB、いずれもLightning 4steps/cfg1.0込み)。ただし24GB級を fp8のまま使うと境界値付近(空きVRAMが閾値ちょうど)で1024²のVAE decodeでOOMする ことがある(実測: 空き23.7GBでOOM)ため、24GB級のtext_encoder量子化は既定を nf4(bnb 4bit)に変更しました(DS_EDIT_GGUF_MID_TE_QUANT、既定nf4)。 nf4はロード常駐が5.54GiBまで縮む(fp8は8.74GiB)ため、実24GBカード相当 (空き~23.5GB、旧fp8構成のOOM条件より厳しい設定)でも1024²が200 OKで完走し (ピークVRAM 20.62GB)、full tierとの画素比較でも実質同一(平均絶対差<1/255)を 実機確認しました。fp8構成(26GB以上の空きがある環境向けの逃げ道)を使いたい場合は DS_EDIT_GGUF_MID_TE_QUANT=fp8 を明示指定してください。詳細は CLAUDE.md 59番参照。 20GB未満の構成(enable_model_cpu_offload()使用時)も動作・品質とも問題ありません: 当初「解像度依存で出力が破綻する」と記録していましたが、2026-08-16の再調査で model_cpu と全常駐(full)の出力がピクセル完全一致**することを確認し、観測された 劣化の正体は Lightning の scheduler shift × 入力条件による品質限界(quant/offload 方式に一切依存せず、既定の fp8-lightning 構成でも同条件で再現)と確定しました。 高解像度 Edit でプロンプト追従が悪い場合は lightning=false(30steps/cfg4.0)を 試してください。詳細は CLAUDE.md 59番の訂正ブロック参照。 品質を上げたい場合の quant 選択目安(2026-08-17 実測、CLAUDE.md 62番): Q4_K_M / Q5_K_M / Q8_0 の出力品質は 30steps/cfg4.0 で実質同等(粒状感の差なし)の ため、品質目的で高精度 quant を選ぶ意味はありません。24GBカードの 1024² 実用上限は Q4_K_M(Q5_K_M はテキストのみ生成限定・Q8_0 はロード不可)、96GB級で速度優先なら Q8_0(30steps が Q4 比約26%高速)が目安です。なお GGUF Edit の Lightning 4steps が 生成時に効かないバグ(粒状感の真因)は 2026-08-17 に修正済みです(CLAUDE.md 62番。 修正後は Q4_K_M + Lightning 4steps で fp8-lightning と同水準のシャープさになります)。
• GGUF Edit 48GB級(full tier)の最速構成は 2026-08-16 にデフォルトで有効になりました (CLAUDE.md 60番): full tier(transformer+TE合計 ~30GB常駐)では DS_EDIT_TE_OFFLOAD=auto の text_encoder CPU⇔GPU退避が無駄なオーバーヘッドだったため(実測 gen 14.4-14.9s → 9.1-9.4s、約38%高速化)、full tier では auto モード時に退避を自動的に無効化するよう 修正しました。24GB級(te_fp8 tier、nf4 既定)は元々このオーバーヘッドが無く同等の速度 (gen 9.14s)です。48GB環境で明示的に24GB級構成(DS_OFFLOAD=gguf_te_fp8)を選ぶ実益は ピークVRAMを更に抑えたい場合(20.62GB vs 29.94GB)のみで、速度面のメリットはありません。
• Qwen-Image-2512 を GGUF 量子化(unsloth/Qwen-Image-2512-GGUF)でロードできるように なりました(2026-08-17追加、CLAUDE.md 66番)。 従来 2512 は fp8-lightning fuse方式 (bf16 transformer 約40GBをGPU上でfuse)のみで48GB未満では利用不可でしたが、GGUF量子化 (DS_QUANT=gguf-q4_k_m 等)なら24GB/20GB級カードでも使えます。Edit の3段階構成 (59番)を簡略化した2段階(full/gguf_te_fp8。model_cpu層は本タスクでは未実装、 20GB級カードでの動作は未検証)を Edit と同じ環境変数(DS_EDIT_GGUF_FULL_VRAM_ FREE_THRESHOLD_GB / DS_EDIT_GGUF_MID_VRAM_FREE_THRESHOLD_GB / DS_EDIT_GGUF_MID_TE_QUANT)で共有します。実機検証(RTX PRO 4000 Blackwell 24GB、 CUDA_VISIBLE_DEVICES=1 DS_QUANT=gguf-q4_k_m DS_T2I_MODEL=2512、空きVRAM 23.2GB): /api/t2i(1024²・4steps・lightning）が gguf_te_fp8(nf4 TE)tierへ正しく振り分けられ、 ピークVRAM 20.49GB・生成10.9秒でHTTP 200、/api/i2i(同モデル、strength=0.5)も ピークVRAM 20.50GB・6.9秒で成功。同サーバで /api/edit(Edit-2511 GGUF)へ切替→ T2I(2512)へ戻す往復もOOMなく動作(下記の家族内相互排他バグ修正が必要だった、後述)。 96GB機(空き92.4GB)では full tierへ正しく振り分けられ、ピークVRAM 35.34GB・ 生成2.96秒で完走。品質はfp8-lightning版と目視・ラプラシアン分散比較で同等(GGUF側が むしろシャープ、725.9 vs 498.4)。無印T2IのGGUF経路(DS_T2I_MODEL=qwen-image)も 回帰確認済み(96GB機、quant=Q4_K_M・full tier・HTTP 200・目視で異常なし)。 本タスクで発見・修正した既存バグ: families/qwen_image/family.py の Edit切替ロジックは従来 DS_QUANT=fp8-lightning のときのみT2Iグループを事前解放 していましたが、T2IがGGUFで常駐可能になったことで「T2I GGUF(~20GB)+ 共有 (~15.7GB)常駐のままEdit GGUFをロード」という新しい組み合わせが発生し、24GB級 カードで実機OOM(Tried to allocate 30.00 MiB、空き2.69MiB)を確認しました。 GGUF量子化時もT2I事前解放の対象に含めるよう修正し、往復切替が正常動作することを 実機確認済みです。
• /api/edit は参照画像なし(0枚)でも生成できます(2026-08-17追加、テキストのみ 生成、T2I相当)。 diffusers 本体は無改変で、families/qwen_image/edit_text_only.py が QwenImageEditPlusPipeline.__call__ のソースをランタイムパッチする方式です (画像ありの通常経路は完全に無変更)。レスポンスに text_to_image: true/false が 含まれます。24GB実機カード(RTX PRO 4000 Blackwell、DS_QUANT=gguf-q4_k_m)で gguf_te_fp8(nf4)tier・1024²・200 OK・ピークVRAM 20.34GBを確認済みで、これは 59番・60番で「未検証」としていた「実24GBカードでの gguf_te_fp8(nf4)tier」の 初めての実カード検証も兼ねています(従来はダミーVRAM確保によるバラスト模擬のみ)。 詳細は CLAUDE.md 61番参照。
• /api/edit に strength(0〜1)パラメータで I2I モードを追加しました (2026-08-17追加)。 Edit(2511)transformer を参照共有した QwenImageImg2ImgPipeline を構築するため追加VRAMはゼロです。画像はちょうど1枚必須(0枚・2枚以上・範囲外の strengthは400)。レスポンスに edit_i2i: true が含まれます。事前A/B(1画像1seedの 限定検証)では無印 Qwen-Image I2I と同等のstrength応答カーブ・同等品質で、被写体保持は むしろ優位な場面もありました。GGUF Edit(3段階構成)・fp8-lightning既定構成のどちらでも 動作し、実測(24GB実機カード/96GB機とも)で通常I2I相当の生成時間(~3〜9秒)でした。 詳細は CLAUDE.md 64番参照。
• JoyAI-Edit-Plus を GGUF 量子化(DS_JOYAI_QUANT=gguf-q4_k_m 等)でロードできます (2026-08-18追加、CLAUDE.md 68番)。 従来は bf16 のみ(~33GB常駐)でしたが、GGUF 量子化なら実24GBカードでも使えます(実測ピーク20.81GB、Q4_K_M)。品質はbf16と 実質同一(平均差0.77/255)であることを確認済みです。JoyImageEditPlusTransformer3DModel は from_single_file() 未対応のため手動ロード方式(init_empty_weights() + DiffusersAutoQuantizer + load_gguf_checkpoint())を使っています。空きVRAM閾値 ベースの自動tier判定(qwen_image Editの59番のような3段階自動選択)は未実装で、 quant はユーザーが明示指定する方式のみです。16GB/20GBカードでの動作は未検証です。
• bf16/fp8-lightning ⇔ GGUF の切替を、起動時環境変数だけでなく /api/t2i / /api/i2i / /api/edit / /api/joyai/edit の任意 quant パラメータ、および UI のモデルセレクタ(-gguf 付き選択肢)から選べるようにしました(2026-08-18追加、 CLAUDE.md 69番)。 24番(T2Iモデル切替)と同じパターンで、要求された quant が 現在アクティブな量子化方式と異なれば該当グループを自動 unload → 再ロードします。 quant 未指定/"default"は現状維持(完全後方互換)。fp8-lightning(bf16 40GB transformerの直接fuse)への切替は、空きVRAMが DS_VRAM_FREE_THRESHOLD_GB (既定44.0GB)未満だとロード前に400を返します(OOMさせずに明確なエラーメッセージで 拒否)。実機検証(96GB機・24GB実機カード)で t2i/edit/joyai の往復切替・24GBカードでの 400ガード発火・GGUF単体動作を確認済みです(unloadリークなし)。
• LTX-2.3(動画生成)はローカルにチェックポイントファイルが配置されている前提です (Hugging Face Hub からの自動ダウンロードは行いません。config/tokenizer のみ Hub から 取得します)。
• 48GB クラスの VRAM でも、オフロード設定・解像度・生成モードの組み合わせによっては OOM が発生する場合があります。環境変数のオフロード関連しきい値を調整してください。
• DS_OFFLOAD=group_lowvram(text_encoder も denoise 中は CPU へ退避する設定)は、 denoise 側が重い処理(ControlNet / Inpaint)では効果が大きい一方、T2I のように プロンプトのエンコード時がピークになる処理ではピークがほとんど下がりません。詳細は 「16GB / 24GB VRAM 環境での動作」を参照。
• DS_QWEN_TE_QUANT=fp8 の品質影響は T2I 1024²(同一 seed)での比較しか行っていません (PSNR 32.3dB、目視で差はごくわずか)。長文プロンプトや多言語プロンプトでの追従性は 未検証です。既定は none(bf16)のままなので、48GB 環境の挙動は変わりません。
• FLF(First-Last-Frame)補間の滑らかさは入力2枚の意味的な近さに強く依存します。

ドキュメント

• API_SPEC.md — 全エンドポイントの詳細なパラメータ・レスポンス例・curl サンプル
• LICENSE — 本リポジトリのライセンス(Apache License 2.0)