README.md

---
base_model: Tongyi-MAI/Z-Image
base_model_relation: quantized
license: apache-2.0
pipeline_tag: text-to-image
tags:
  - text-to-image
  - diffusion
  - fp8
  - quantized
  - comfyui
---

# Z-Image · FP8 (transformer)

FP8 (`float8_e4m3fn`) quantization of the **Z-Image DiT (ZImageTransformer2DModel, 6.1B)** transformer from [`Tongyi-MAI/Z-Image`](https://huggingface.co/Tongyi-MAI/Z-Image). Quantized by **axteam**.

| File | Size |
|---|---|
| `Z-Image-transformer-fp8_e4m3fn.safetensors` | 6.2 GB |

## What this is
- **Only the transformer (DiT) is quantized** to `float8_e4m3fn` (2-D weight tensors; norms/biases kept in BF16). ~half the size of the BF16 transformer.
- **VAE and text encoder(s) are NOT included** — use the ones from the original [`Tongyi-MAI/Z-Image`](https://huggingface.co/Tongyi-MAI/Z-Image).

## Requirements

| | |
|---|---|
| **Runtime** | ComfyUI (Load Diffusion Model node, `float8_e4m3fn` single file). Not run here — no ComfyUI on this server. |
| **Also needed** | the Qwen3 text encoder (8.0 GB) and VAE (0.17 GB) from the base repo. |
| **Memory** | this file is **6.2 GB**; add the text encoder(s) and VAE above. |

## Usage (ComfyUI)

1. Download the FP8 file into ComfyUI's diffusion-model folder:

```bash
hf download axteam/Z-Image-FP8 Z-Image-transformer-fp8_e4m3fn.safetensors --local-dir ComfyUI/models/diffusion_models
```

2. Get the **VAE** and **text encoder(s)** from the original [`Tongyi-MAI/Z-Image`](https://huggingface.co/Tongyi-MAI/Z-Image) repo (or the matching ComfyUI repackaged files) and put them in `ComfyUI/models/vae/` and `ComfyUI/models/text_encoders/`.
3. In your workflow, load this file with the **Load Diffusion Model** node (`UNETLoader`) — leave `weight_dtype` at `default` (the file is already `float8_e4m3fn`) — and wire the original VAE / text-encoder loaders as in the base model's reference workflow.
4. Sampler settings (steps, CFG/guidance, resolution) are the same as for the original model.

> The FP8 file is a plain cast of the transformer weights (no scaling), the common ComfyUI `fp8_e4m3fn` convention; norms and biases stay BF16.

## License
Quantized derivative of [`Tongyi-MAI/Z-Image`](https://huggingface.co/Tongyi-MAI/Z-Image). Original weights belong to the upstream authors; the base model's license applies to this derivative.

---
## 한국어 요약

**[`Tongyi-MAI/Z-Image`](https://huggingface.co/Tongyi-MAI/Z-Image)의 transformer(DiT) FP8 양자화 빌드 (ComfyUI용 단일 파일)** · 제작 axteam

### 개요
| 항목 | 내용 |
|---|---|
| 원본 모델 | [`Tongyi-MAI/Z-Image`](https://huggingface.co/Tongyi-MAI/Z-Image) |
| 형식 | `float8_e4m3fn` 단일 safetensors (ComfyUI 표준 방식) |
| 파일 | `Z-Image-transformer-fp8_e4m3fn.safetensors` 6.2 GB |
| 포함 | transformer(DiT) |

### 양자화 상세
- **방식**: transformer의 2D 가중치를 `float8_e4m3fn`으로 그대로 변환 (스케일 없음, ComfyUI 관례)
- **BF16 유지**: 정규화층·bias
- **미포함**: VAE·텍스트 인코더 — 원본 리포에서 받아 사용

### 요구사항
- **실행 환경**: ComfyUI — Load Diffusion Model 노드로 `float8_e4m3fn` 단일 파일 로드 (이 서버에는 ComfyUI가 없어 미실행)
- **추가로 필요한 파일**: 원본 리포의 Qwen3 텍스트 인코더(8.0 GB)와 VAE(0.17 GB)
- **메모리**: 이 파일 6.2 GB + 위 텍스트 인코더·VAE

### 사용법 (ComfyUI)
- **다운로드**: `hf download axteam/Z-Image-FP8 Z-Image-transformer-fp8_e4m3fn.safetensors --local-dir ComfyUI/models/diffusion_models`
- **텍스트 인코더·VAE**: 원본 리포에서 받아 `ComfyUI/models/text_encoders/`·`ComfyUI/models/vae/`에 배치
- **불러오기**: Load Diffusion Model 노드(`UNETLoader`), `weight_dtype`은 default
- **샘플러 설정**: 스텝·CFG(guidance)·해상도는 원본 모델과 동일

### 라이선스
- **라이선스**: Apache-2.0 — 원본 모델의 라이선스를 그대로 따름
- **권리**: 원본 가중치·토크나이저의 권리는 Tongyi-MAI(Alibaba)에 있으며, 이 리포는 양자화 파생물