File size: 5,512 Bytes
ebf1c59 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | ---
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.
|