docs: add Troubleshooting section
#21
by
ThanhNguyxn
- opened
README.md
CHANGED
|
@@ -1,112 +1,118 @@
|
|
| 1 |
-
---
|
| 2 |
-
license: apache-2.0
|
| 3 |
-
language:
|
| 4 |
-
- en
|
| 5 |
-
pipeline_tag: text-to-image
|
| 6 |
-
library_name: diffusers
|
| 7 |
-
---
|
| 8 |
-
|
| 9 |
-
<h1 align="center">⚡️- Image<br><sub><sup>An Efficient Image Generation Foundation Model with Single-Stream Diffusion Transformer</sup></sub></h1>
|
| 10 |
-
|
| 11 |
-
<div align="center">
|
| 12 |
-
|
| 13 |
-
[](https://tongyi-mai.github.io/Z-Image-blog/) 
|
| 14 |
-
[](https://github.com/Tongyi-MAI/Z-Image) 
|
| 15 |
-
[](https://huggingface.co/Tongyi-MAI/Z-Image) 
|
| 16 |
-
[](https://huggingface.co/spaces/Tongyi-MAI/Z-Image) 
|
| 17 |
-
[](https://www.modelscope.cn/models/Tongyi-MAI/Z-Image) 
|
| 18 |
-
[](https://www.modelscope.cn/aigc/imageGeneration?tab=advanced&versionId=569345&modelType=Checkpoint&sdVersion=Z_IMAGE&modelUrl=modelscope%3A%2F%2FTongyi-MAI%2FZ-Image%3Frevision%3Dmaster) 
|
| 19 |
-
<a href="https://arxiv.org/abs/2511.22699" target="_blank"><img src="https://img.shields.io/badge/Report-b5212f.svg?logo=arxiv" height="21px"></a>
|
| 20 |
-
|
| 21 |
-
Welcome to the official repository for the Z-Image（造相）project!
|
| 22 |
-
|
| 23 |
-
</div>
|
| 24 |
-
|
| 25 |
-
## 🎨 Z-Image
|
| 26 |
-
|
| 27 |
-
|
| 28 |
-
|
| 29 |
-
|
| 30 |
-
|
| 31 |
-
|
| 32 |
-
**Z-Image** is the foundation model of the ⚡️- Image family, engineered for good quality, robust generative diversity, broad stylistic coverage, and precise prompt adherence.
|
| 33 |
-
While Z-Image-Turbo is built for speed,
|
| 34 |
-
Z-Image is a full-capacity, undistilled transformer designed to be the backbone for creators, researchers, and developers who require the highest level of creative freedom.
|
| 35 |
-
|
| 36 |
-
|
| 37 |
-
|
| 38 |
-
### 🌟 Key Features
|
| 39 |
-
|
| 40 |
-
- **Undistilled Foundation**: As a non-distilled base model, Z-Image preserves the complete training signal. It supports full Classifier-Free Guidance (CFG), providing the precision required for complex prompt engineering and professional workflows.
|
| 41 |
-
- **Aesthetic Versatility**: Z-Image masters a vast spectrum of visual languages—from hyper-realistic photography and cinematic digital art to intricate anime and stylized illustrations. It is the ideal engine for scenarios requiring rich, multi-dimensional expression.
|
| 42 |
-
- **Enhanced Output Diversity**: Built for exploration, Z-Image delivers significantly higher variability in composition, facial identity, and lighting across different seeds, ensuring that multi-person scenes remain distinct and dynamic.
|
| 43 |
-
- **Built for Development**: The ideal starting point for the community. Its non-distilled nature makes it a good base for LoRA training, structural conditioning (ControlNet) and semantic conditioning.
|
| 44 |
-
- **Robust Negative Control**: Responds with high fidelity to negative prompting, allowing users to reliably suppress artifacts and adjust compositions.
|
| 45 |
-
|
| 46 |
-
### 🆚 Z-Image vs Z-Image-Turbo
|
| 47 |
-
|
| 48 |
-
| Aspect | Z-Image | Z-Image-Turbo |
|
| 49 |
-
|------|------|------|
|
| 50 |
-
| CFG | ✅ | ❌ |
|
| 51 |
-
| Steps | 28~50 | 8 |
|
| 52 |
-
| Fintunablity | ✅ | ❌ |
|
| 53 |
-
| Negative Prompting | ✅ | ❌ |
|
| 54 |
-
| Diversity | High | Low |
|
| 55 |
-
| Visual Quality | High | Very High |
|
| 56 |
-
| RL | ❌ | ✅ |
|
| 57 |
-
|
| 58 |
-
## 🚀 Quick Start
|
| 59 |
-
|
| 60 |
-
### Installation & Download
|
| 61 |
-
|
| 62 |
-
Install the latest version of diffusers:
|
| 63 |
-
```bash
|
| 64 |
-
pip install git+https://github.com/huggingface/diffusers
|
| 65 |
-
```
|
| 66 |
-
|
| 67 |
-
Download the model:
|
| 68 |
-
```bash
|
| 69 |
-
pip install -U huggingface_hub
|
| 70 |
-
HF_XET_HIGH_PERFORMANCE=1 hf download Tongyi-MAI/Z-Image
|
| 71 |
-
```
|
| 72 |
-
|
| 73 |
-
### Recommended Parameters
|
| 74 |
-
|
| 75 |
-
- **Resolution:** 512×512 to 2048×2048 (total pixel area, any aspect ratio)
|
| 76 |
-
- **Guidance scale:** 3.0 – 5.0
|
| 77 |
-
- **Inference steps:** 28 – 50
|
| 78 |
-
|
| 79 |
-
### Usage Example
|
| 80 |
-
|
| 81 |
-
```python
|
| 82 |
-
import torch
|
| 83 |
-
from diffusers import ZImagePipeline
|
| 84 |
-
|
| 85 |
-
# Load the pipeline
|
| 86 |
-
pipe = ZImagePipeline.from_pretrained(
|
| 87 |
-
"Tongyi-MAI/Z-Image",
|
| 88 |
-
torch_dtype=torch.bfloat16,
|
| 89 |
-
low_cpu_mem_usage=False,
|
| 90 |
-
)
|
| 91 |
-
pipe.to("cuda")
|
| 92 |
-
|
| 93 |
-
# Generate image
|
| 94 |
-
prompt = "两名年轻亚裔女性紧密站在一起，背景为朴素的灰色纹理墙面，可能是室内地毯地面。左侧女性留着长卷发，身穿藏青色毛衣，左袖有奶油色褶皱装饰，内搭白色立领衬衫，下身白色裤子；佩戴小巧金色耳钉，双臂交叉于背后。右侧女性留直肩长发，身穿奶油色卫衣，胸前印有“Tun the tables”字样，下方为“New ideas
|
| 95 |
-
negative_prompt = "" # Optional, but would be powerful when you want to remove some unwanted content
|
| 96 |
-
|
| 97 |
-
image = pipe(
|
| 98 |
-
prompt=prompt,
|
| 99 |
-
negative_prompt=negative_prompt,
|
| 100 |
-
height=1280,
|
| 101 |
-
width=720,
|
| 102 |
-
cfg_normalization=False,
|
| 103 |
-
num_inference_steps=50,
|
| 104 |
-
guidance_scale=4,
|
| 105 |
-
generator=torch.Generator("cuda").manual_seed(42),
|
| 106 |
-
).images[0]
|
| 107 |
-
|
| 108 |
-
image.save("example.png")
|
| 109 |
-
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 110 |
|
| 111 |
## 📜 Citation
|
| 112 |
|
|
@@ -119,4 +125,4 @@ If you find our work useful in your research, please consider citing:
|
|
| 119 |
journal={arXiv preprint arXiv:2511.22699},
|
| 120 |
year={2025}
|
| 121 |
}
|
| 122 |
-
```
|
|
|
|
| 1 |
+
---
|
| 2 |
+
license: apache-2.0
|
| 3 |
+
language:
|
| 4 |
+
- en
|
| 5 |
+
pipeline_tag: text-to-image
|
| 6 |
+
library_name: diffusers
|
| 7 |
+
---
|
| 8 |
+
|
| 9 |
+
<h1 align="center">⚡️- Image<br><sub><sup>An Efficient Image Generation Foundation Model with Single-Stream Diffusion Transformer</sup></sub></h1>
|
| 10 |
+
|
| 11 |
+
<div align="center">
|
| 12 |
+
|
| 13 |
+
[](https://tongyi-mai.github.io/Z-Image-blog/) 
|
| 14 |
+
[](https://github.com/Tongyi-MAI/Z-Image) 
|
| 15 |
+
[](https://huggingface.co/Tongyi-MAI/Z-Image) 
|
| 16 |
+
[](https://huggingface.co/spaces/Tongyi-MAI/Z-Image) 
|
| 17 |
+
[](https://www.modelscope.cn/models/Tongyi-MAI/Z-Image) 
|
| 18 |
+
[](https://www.modelscope.cn/aigc/imageGeneration?tab=advanced&versionId=569345&modelType=Checkpoint&sdVersion=Z_IMAGE&modelUrl=modelscope%3A%2F%2FTongyi-MAI%2FZ-Image%3Frevision%3Dmaster) 
|
| 19 |
+
<a href="https://arxiv.org/abs/2511.22699" target="_blank"><img src="https://img.shields.io/badge/Report-b5212f.svg?logo=arxiv" height="21px"></a>
|
| 20 |
+
|
| 21 |
+
Welcome to the official repository for the Z-Image（造相）project!
|
| 22 |
+
|
| 23 |
+
</div>
|
| 24 |
+
|
| 25 |
+
## 🎨 Z-Image
|
| 26 |
+
|
| 27 |
+
|
| 28 |
+
|
| 29 |
+
|
| 30 |
+
|
| 31 |
+
|
| 32 |
+
**Z-Image** is the foundation model of the ⚡️- Image family, engineered for good quality, robust generative diversity, broad stylistic coverage, and precise prompt adherence.
|
| 33 |
+
While Z-Image-Turbo is built for speed,
|
| 34 |
+
Z-Image is a full-capacity, undistilled transformer designed to be the backbone for creators, researchers, and developers who require the highest level of creative freedom.
|
| 35 |
+
|
| 36 |
+
|
| 37 |
+
|
| 38 |
+
### 🌟 Key Features
|
| 39 |
+
|
| 40 |
+
- **Undistilled Foundation**: As a non-distilled base model, Z-Image preserves the complete training signal. It supports full Classifier-Free Guidance (CFG), providing the precision required for complex prompt engineering and professional workflows.
|
| 41 |
+
- **Aesthetic Versatility**: Z-Image masters a vast spectrum of visual languages—from hyper-realistic photography and cinematic digital art to intricate anime and stylized illustrations. It is the ideal engine for scenarios requiring rich, multi-dimensional expression.
|
| 42 |
+
- **Enhanced Output Diversity**: Built for exploration, Z-Image delivers significantly higher variability in composition, facial identity, and lighting across different seeds, ensuring that multi-person scenes remain distinct and dynamic.
|
| 43 |
+
- **Built for Development**: The ideal starting point for the community. Its non-distilled nature makes it a good base for LoRA training, structural conditioning (ControlNet) and semantic conditioning.
|
| 44 |
+
- **Robust Negative Control**: Responds with high fidelity to negative prompting, allowing users to reliably suppress artifacts and adjust compositions.
|
| 45 |
+
|
| 46 |
+
### 🆚 Z-Image vs Z-Image-Turbo
|
| 47 |
+
|
| 48 |
+
| Aspect | Z-Image | Z-Image-Turbo |
|
| 49 |
+
|------|------|------|
|
| 50 |
+
| CFG | ✅ | ❌ |
|
| 51 |
+
| Steps | 28~50 | 8 |
|
| 52 |
+
| Fintunablity | ✅ | ❌ |
|
| 53 |
+
| Negative Prompting | ✅ | ❌ |
|
| 54 |
+
| Diversity | High | Low |
|
| 55 |
+
| Visual Quality | High | Very High |
|
| 56 |
+
| RL | ❌ | ✅ |
|
| 57 |
+
|
| 58 |
+
## 🚀 Quick Start
|
| 59 |
+
|
| 60 |
+
### Installation & Download
|
| 61 |
+
|
| 62 |
+
Install the latest version of diffusers:
|
| 63 |
+
```bash
|
| 64 |
+
pip install git+https://github.com/huggingface/diffusers
|
| 65 |
+
```
|
| 66 |
+
|
| 67 |
+
Download the model:
|
| 68 |
+
```bash
|
| 69 |
+
pip install -U huggingface_hub
|
| 70 |
+
HF_XET_HIGH_PERFORMANCE=1 hf download Tongyi-MAI/Z-Image
|
| 71 |
+
```
|
| 72 |
+
|
| 73 |
+
### Recommended Parameters
|
| 74 |
+
|
| 75 |
+
- **Resolution:** 512×512 to 2048×2048 (total pixel area, any aspect ratio)
|
| 76 |
+
- **Guidance scale:** 3.0 – 5.0
|
| 77 |
+
- **Inference steps:** 28 – 50
|
| 78 |
+
|
| 79 |
+
### Usage Example
|
| 80 |
+
|
| 81 |
+
```python
|
| 82 |
+
import torch
|
| 83 |
+
from diffusers import ZImagePipeline
|
| 84 |
+
|
| 85 |
+
# Load the pipeline
|
| 86 |
+
pipe = ZImagePipeline.from_pretrained(
|
| 87 |
+
"Tongyi-MAI/Z-Image",
|
| 88 |
+
torch_dtype=torch.bfloat16,
|
| 89 |
+
low_cpu_mem_usage=False,
|
| 90 |
+
)
|
| 91 |
+
pipe.to("cuda")
|
| 92 |
+
|
| 93 |
+
# Generate image
|
| 94 |
+
prompt = "两名年轻亚裔女性紧密站在一起，背景为朴素的灰色纹理墙面，可能是室内地毯地面。左侧女性留着长卷发，身穿藏青色毛衣，左袖有奶油色褶皱装饰，内搭白色立领衬衫，下身白色裤子；佩戴小巧金色耳钉，双臂交叉于背后。右侧女性留直肩长发，身穿奶油色卫衣，胸前印有“Tun the tables”字样，下方为“New ideas”，搭配白色裤子；佩戴银色小环耳环，双臂交叉于胸前。两人均面带微笑直视镜头。照片，自然光照明，柔和阴影，以藏青、奶油白为主的中性色调，休闲时尚摄影，中等景深，面部和上半身对焦清晰，姿态放松，表情友好，室内环境，地毯地面，纯色背景。"
|
| 95 |
+
negative_prompt = "" # Optional, but would be powerful when you want to remove some unwanted content
|
| 96 |
+
|
| 97 |
+
image = pipe(
|
| 98 |
+
prompt=prompt,
|
| 99 |
+
negative_prompt=negative_prompt,
|
| 100 |
+
height=1280,
|
| 101 |
+
width=720,
|
| 102 |
+
cfg_normalization=False,
|
| 103 |
+
num_inference_steps=50,
|
| 104 |
+
guidance_scale=4,
|
| 105 |
+
generator=torch.Generator("cuda").manual_seed(42),
|
| 106 |
+
).images[0]
|
| 107 |
+
|
| 108 |
+
image.save("example.png")
|
| 109 |
+
```
|
| 110 |
+
|
| 111 |
+
|
| 112 |
+
### Troubleshooting
|
| 113 |
+
|
| 114 |
+
- Flash-Attention (optional): native inference defaults to PyTorch SDPA. If you see an error like "Requires Flash-attention version ...", either install a compatible flash-attn version or force native SDPA with `ZIMAGE_ATTENTION=_native_flash`.
|
| 115 |
+
- ComfyUI: This repo does not ship ComfyUI nodes. If you use ComfyUI, keep plugins updated; outdated comfyui-dev-utils has been reported to break after ComfyUI core updates. Please report ComfyUI-specific crashes in the ComfyUI repo with logs.
|
| 116 |
|
| 117 |
## 📜 Citation
|
| 118 |
|
|
|
|
| 125 |
journal={arXiv preprint arXiv:2511.22699},
|
| 126 |
year={2025}
|
| 127 |
}
|
| 128 |
+
```
|