| --- |
| license: apache-2.0 |
| base_model: |
| - Tongyi-MAI/Z-Image |
| - Tongyi-MAI/Z-Image-Turbo |
| base_model_relation: adapter |
| pipeline_tag: text-to-image |
| library_name: diffusers |
| tags: |
| - lora |
| - text-to-image |
| - z-image |
| - comfyui |
| - realism |
| --- |
| |
| # RealGen-V2 — ComfyUI-ready LoRA for Z-Image |
|
|
| A drop-in [ComfyUI](https://github.com/comfyanonymous/ComfyUI) build of |
| [Yunncheng/RealGen-V2](https://huggingface.co/Yunncheng/RealGen-V2). Same |
| weights as upstream, repackaged so ComfyUI's stock `LoraLoader` can load it |
| without a custom node. Works on both Z-Image base and Z-Image-Turbo. |
|
|
| ## Examples |
|
|
| Each row is the **same prompt and seed**, rendered with and without the LoRA |
| at strength `1.0`. |
|
|
| ### [Z-Image (base)](https://huggingface.co/Tongyi-MAI/Z-Image) |
|
|
| | Without LoRA | With RealGen-V2 | |
| | --- | --- | |
| |  |  | |
| |  |  | |
| |  |  | |
| |  |  | |
| |  |  | |
|
|
| ### [Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) |
|
|
| | Without LoRA | With RealGen-V2 | |
| | --- | --- | |
| |  |  | |
| |  |  | |
| |  |  | |
| |  |  | |
| |  |  | |
|
|
| Note: on Turbo the LoRA still affects the image even though negative prompts |
| don't — CFG=1 disables the negative branch, not the LoRA patch. |
|
|
| ## Why this repo exists |
|
|
| The upstream release ships the adapter in [PEFT](https://github.com/huggingface/peft) |
| format (`base_model.model.<path>.lora_A.<adapter>.weight` keys, with |
| `lora_alpha` living separately in `adapter_config.json`). ComfyUI's stock |
| `LoraLoader` doesn't understand that layout, so this repo provides: |
|
|
| - the **same weights, repackaged** with diffusers-style keys |
| (`<path>.lora_down.weight`, `<path>.lora_up.weight`) and |
| - per-module `alpha` tensors baked into the file so the `alpha/rank` scaling |
| ComfyUI applies matches what PEFT would have applied at runtime. |
|
|
| No retraining, no quantisation, no surgery beyond key renaming and alpha |
| injection — the math is identical to running the original adapter through PEFT. |
|
|
| ## Files |
|
|
| | File | Purpose | |
| | --- | --- | |
| | `realgen_v2.safetensors` | The repackaged LoRA. Drop into `ComfyUI/models/loras/`. | |
| | `scripts/convert_realgen_v2.py` | The script used to produce it from the upstream PEFT adapter. Re-runnable for transparency. | |
| | `examples/` | Side-by-side renders, with and without the LoRA, on both Z-Image base and Z-Image-Turbo. | |
| | `LICENSE` | Apache 2.0 (matches both RealGen-V2 and Z-Image upstream). | |
|
|
| ## Usage in ComfyUI |
|
|
| 1. Download `realgen_v2.safetensors` and place it in `ComfyUI/models/loras/`. |
| 2. Build a graph: `Load Diffusion Model` (Z-Image) → `LoraLoader` → sampler. |
| - Select `realgen_v2.safetensors` in the loader. |
| - **Strength `1.0`** reproduces the upstream training intent |
| (`alpha=128, rank=64 → scale=2.0`). |
| - Lower (e.g. `0.5–0.8`) for a softer effect; the LoRA scales linearly. |
| |
| That's it — there is no custom node to install. |
|
|
| ## Reproducing the conversion |
|
|
| If you'd rather convert the upstream weights yourself: |
|
|
| ```bash |
| # from a Python env with torch + safetensors + packaging: |
| python scripts/convert_realgen_v2.py adapter_model.safetensors realgen_v2.safetensors |
| ``` |
|
|
| The script reads `lora_alpha` from `adapter_config.json` (sitting next to the |
| adapter), strips the `base_model.model.` prefix, rewrites |
| `lora_A`/`lora_B` → `lora_down`/`lora_up`, and writes one `<module>.alpha` |
| tensor per LoRA module. See the source for the full mapping. |
|
|
| ## Credits |
|
|
| - Original RealGen-V2 weights: [Yunncheng/RealGen-V2](https://huggingface.co/Yunncheng/RealGen-V2) |
| - RealGen training code: [yejy53/RealGen](https://github.com/yejy53/RealGen) (`RealGen_v2/`) |
| - Base models: [Tongyi-MAI/Z-Image](https://huggingface.co/Tongyi-MAI/Z-Image) and [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) |
|
|
| This repo redistributes the weights under their original Apache 2.0 license; |
| all credit for the LoRA itself belongs to the upstream authors. |
|
|
