Upload full MLX-4bit pipeline (Auto-packaged)

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer/tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,163 +1,31 @@
 ---
 library_name: mlx
+tags:
+- mlx
+- diffusion
+- text-to-image
+- 4-bit
+base_model: Tongyi-MAI/Z-Image-Turbo
 license: apache-2.0
-base_model:
-- Tongyi-MAI/Z-Image-Turbo
 ---
 
 # uqer1244/MLX-z-image
 
-This is a 4-bit quantized version of Z-Image-Turbo for MLX.
+This is a **4-bit quantized MLX version** of [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo).
+It is optimized for Apple Silicon (macOS) using the [MLX framework](https://github.com/ml-explore/mlx).
 
-https://github.com/uqer1244/MLX_z-image
+## Model Details
+- **Transformer**: MLX 4-bit quantized
+- **Text Encoder**: MLX 4-bit quantized (Qwen2)
+- **VAE**: Original PyTorch Model (Sourced from original repo)
+- **Tokenizer**: Original Qwen2 Tokenizer (Sourced from original repo)
+- **Scheduler**: FlowMatchEulerDiscreteScheduler (Sourced from original repo)
 
+## Usage
+This model can be used with the custom MLX pipeline script.
+Please refer to the original repository for detailed usage instructions regarding the model architecture.
 
-# MLX z-image 🍎
-
-An efficient **MLX implementation** of [Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) optimized for Apple Silicon (M1/M2/M3/M4).
-
-This repository allows you to run high-quality image generation locally on your Mac using **4-bit quantization**, significantly reducing memory usage while maintaining quality.
-
-
-## 📂 Project Structure
-
-It is recommended to organize your folders as follows:
-
-```text
-MLX_z-image/
-├── Z-Image-Turbo-MLX-4bit/        # MLX Quantized Weights 
-├── Z-Image-Turbo/                 # Original PyTorch Model 
-├── run.py                         # Inference Script
-├── mlx_z_image.py                 # MLX converted transformer
-├── convert.py                     # Script to convert PyTorch weights to MLX
-└── quantize.py                    # Script to quantize FP16 model to 4-bit
-````
-
-
-## 📊 Performance & Gallery
-
-### Benchmarks
-Inference tests were conducted on Apple Silicon devices using **native MLX** with **4-bit quantization**.
-
-- **Resolution**: 1024x1024
-- **Steps**: 5 (Turbo)
-- **Batch Size**: 1
-
-| Device     | RAM  | Total Time | Denoise Time (MLX) | Time per Step |
-|:-----------|:-----|:-----------|:-------------------|:--------------|
-| **M3 Pro** | 18GB | ~ 182.17 s | 95.48 s            | 19.097 s/Step |
-
-
-
-
-
-## Installation
-
-### 1\. Clone the repository
-
-```bash
-git clone https://github.com/uqer1244/MLX_z-image.git
-cd MLX_z-image
-```
-
-### 2\. Install dependencies
-
-Make sure you have Python installed.
-
-```bash
-pip install -r requirements.txt
-```
-
------
-
-## Quick Start
-
-To run the model, you need two things:
-
-1.  **Z-Image-Turbo-MLX-4bit**: The converted transformer model (4bit_quantized).
-2.  **Z-Image-Turbo**: The original VAE, Text Encoder, and Scheduler.
-
-### 1\. Download MLX Weights (Quantized)
-
-Download the 4-bit converted weights from [uqer1244/MLX-z-image](https://huggingface.co/uqer1244/MLX-z-image).
-
-```bash
-# Install CLI if needed
-pip install huggingface_hub
-
-# Download to 'Z-Image-Turbo-MLX-4bit' folder
-huggingface-cli download uqer1244/MLX-z-image --local-dir Z-Image-Turbo-MLX-4bit
-```
-
-### 2\. Download Base Model (Original)
-
-Download the original [Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) to use its VAE and Text Encoder.
-
-```bash
-# Download to 'Z-Image-Turbo' folder
-huggingface-cli download Tongyi-MAI/Z-Image-Turbo --local-dir Z-Image-Turbo
-```
-
-### 3\. Run Inference
-
-Run the `run.py` script. Make sure to point to both model paths.
-
-```bash
-python run.py \
-  --prompt "A futuristic city with flying cars, cinematic lighting, 8k" \
-  --mlx_model_path "Z-Image-Turbo-MLX-4bit" \
-  --pt_model_id "Z-Image-Turbo" \
-  --output "res.png" \
-  --steps 5
-```
-
-### Options
-
-| Argument | Description | Default                  |
-| :--- | :--- |:-------------------------|
-| `--prompt` | Text prompt for generation | *Astronaut...* |
-| `--mlx_model_path` | Path to the MLX weights folder | `Z-Image-Turbo-MLX-4bit` |
-| `--pt_model_id` | Path to the Base Model (or HF ID) | `Z-Image-Turbo`          |
-| `--output` | Output filename | `res.png`                |
-| `--steps` | Number of inference steps | `5`                      |
-| `--height` | Image height | `1024`                   |
-| `--width` | Image width | `1024`                   |
-
------
-
-## Todo & Roadmap
-
-We are actively working on making this implementation pure MLX and bug-free.
-
-  - [ ] **Fix Artifacts**: Investigate and resolve visual artifacts (tiling/color issues) currently visible in some generations.
-  - [ ] **Full MLX Pipeline**: Port the remaining PyTorch components (VAE, Text Encoder, Tokenizer, Scheduler) to native MLX to remove the `torch` and `diffusers` dependencies completely.
-  - [ ] **LoRA Support**: Add support for loading and applying LoRA adapters for style customization.
-
------
-
-## Advanced: Manual Conversion
-
-If you want to convert the original PyTorch weights yourself (instead of downloading the pre-converted ones), follow these steps.
-
-**1. Convert PyTorch to MLX (FP16)**
-
-```bash
-python convert.py \
-  --model_id "Z-Image-Turbo" \
-  --dest_path "Z-Image-Turbo-MLX"
-```
-
-**2. Quantize to 4-bit**
-
-```bash
-python quantize.py \
-  --model_path "Z-Image-Turbo-MLX" \
-  --dest_path "Z-Image-Turbo-MLX-4bit" \
-  --group_size 32
-```
-
-## Acknowledgements
-
-  - Original Model: [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)
-  - MLX Framework: [Apple Machine Learning Research](https://github.com/ml-explore/mlx)
-
+## Attribution & License
+This model is a derivative work of [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo).
+- **Original License**: Apache 2.0
+- **Modifications**: Converted Transformer and Text Encoder weights to MLX format and quantized to 4-bit.

model_index.json

@@ -0,0 +1,24 @@
+{
+    "_class_name": "ZImagePipelineMLX",
+    "_diffusers_version": "0.36.0.dev0",
+    "scheduler": [
+        "diffusers",
+        "FlowMatchEulerDiscreteScheduler"
+    ],
+    "text_encoder": [
+        "transformers",
+        "Qwen3Model"
+    ],
+    "tokenizer": [
+        "transformers",
+        "Qwen2Tokenizer"
+    ],
+    "transformer": [
+        "diffusers",
+        "ZImageTransformer2DModel"
+    ],
+    "vae": [
+        "diffusers",
+        "AutoencoderKL"
+    ]
+}

scheduler/scheduler_config.json

@@ -0,0 +1,7 @@
+{
+  "_class_name": "FlowMatchEulerDiscreteScheduler",
+  "_diffusers_version": "0.36.0.dev0",
+  "num_train_timesteps": 1000,
+  "use_dynamic_shifting": false,
+  "shift": 3.0
+}

text_encoder/config.json

@@ -0,0 +1,30 @@
+{
+    "architectures": [
+        "Qwen3ForCausalLM"
+    ],
+    "attention_bias": false,
+    "attention_dropout": 0.0,
+    "bos_token_id": 151643,
+    "eos_token_id": 151645,
+    "head_dim": 128,
+    "hidden_act": "silu",
+    "hidden_size": 2560,
+    "initializer_range": 0.02,
+    "intermediate_size": 9728,
+    "max_position_embeddings": 40960,
+    "max_window_layers": 36,
+    "model_type": "qwen3",
+    "num_attention_heads": 32,
+    "num_hidden_layers": 36,
+    "num_key_value_heads": 8,
+    "rms_norm_eps": 1e-06,
+    "rope_scaling": null,
+    "rope_theta": 1000000,
+    "sliding_window": null,
+    "tie_word_embeddings": true,
+    "torch_dtype": "bfloat16",
+    "transformers_version": "4.51.0",
+    "use_cache": true,
+    "use_sliding_window": false,
+    "vocab_size": 151936
+}

text_encoder/model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:82a08bd3360bf23b47db61b7b758b46401f04c3f3533d97af9f370df81239fa4
+size 3017590306

tokenizer/tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aeb13307a71acd8fe81861d94ad54ab689df773318809eed3cbe794b4492dae4
+size 11422654

tokenizer/tokenizer_config.json

@@ -0,0 +1,239 @@
+{
+  "add_bos_token": false,
+  "add_prefix_space": false,
+  "added_tokens_decoder": {
+    "151643": {
+      "content": "<|endoftext|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151644": {
+      "content": "<|im_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151645": {
+      "content": "<|im_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151646": {
+      "content": "<|object_ref_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151647": {
+      "content": "<|object_ref_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151648": {
+      "content": "<|box_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151649": {
+      "content": "<|box_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151650": {
+      "content": "<|quad_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151651": {
+      "content": "<|quad_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151652": {
+      "content": "<|vision_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151653": {
+      "content": "<|vision_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151654": {
+      "content": "<|vision_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151655": {
+      "content": "<|image_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151656": {
+      "content": "<|video_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151657": {
+      "content": "<tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151658": {
+      "content": "</tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151659": {
+      "content": "<|fim_prefix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151660": {
+      "content": "<|fim_middle|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151661": {
+      "content": "<|fim_suffix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151662": {
+      "content": "<|fim_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151663": {
+      "content": "<|repo_name|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151664": {
+      "content": "<|file_sep|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151665": {
+      "content": "<tool_response>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151666": {
+      "content": "</tool_response>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151667": {
+      "content": "<think>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151668": {
+      "content": "</think>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    }
+  },
+  "additional_special_tokens": [
+    "<|im_start|>",
+    "<|im_end|>",
+    "<|object_ref_start|>",
+    "<|object_ref_end|>",
+    "<|box_start|>",
+    "<|box_end|>",
+    "<|quad_start|>",
+    "<|quad_end|>",
+    "<|vision_start|>",
+    "<|vision_end|>",
+    "<|vision_pad|>",
+    "<|image_pad|>",
+    "<|video_pad|>"
+  ],
+  "bos_token": null,
+  "chat_template": "{%- if tools %}\n    {{- '<|im_start|>system\\n' }}\n    {%- if messages[0].role == 'system' %}\n        {{- messages[0].content + '\\n\\n' }}\n    {%- endif %}\n    {{- \"# Tools\\n\\nYou may call one or more functions to assist with the user query.\\n\\nYou are provided with function signatures within <tools></tools> XML tags:\\n<tools>\" }}\n    {%- for tool in tools %}\n        {{- \"\\n\" }}\n        {{- tool | tojson }}\n    {%- endfor %}\n    {{- \"\\n</tools>\\n\\nFor each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:\\n<tool_call>\\n{\\\"name\\\": <function-name>, \\\"arguments\\\": <args-json-object>}\\n</tool_call><|im_end|>\\n\" }}\n{%- else %}\n    {%- if messages[0].role == 'system' %}\n        {{- '<|im_start|>system\\n' + messages[0].content + '<|im_end|>\\n' }}\n    {%- endif %}\n{%- endif %}\n{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}\n{%- for message in messages[::-1] %}\n    {%- set index = (messages|length - 1) - loop.index0 %}\n    {%- if ns.multi_step_tool and message.role == \"user\" and message.content is string and not(message.content.startswith('<tool_response>') and message.content.endswith('</tool_response>')) %}\n        {%- set ns.multi_step_tool = false %}\n        {%- set ns.last_query_index = index %}\n    {%- endif %}\n{%- endfor %}\n{%- for message in messages %}\n    {%- if message.content is string %}\n        {%- set content = message.content %}\n    {%- else %}\n        {%- set content = '' %}\n    {%- endif %}\n    {%- if (message.role == \"user\") or (message.role == \"system\" and not loop.first) %}\n        {{- '<|im_start|>' + message.role + '\\n' + content + '<|im_end|>' + '\\n' }}\n    {%- elif message.role == \"assistant\" %}\n        {%- set reasoning_content = '' %}\n        {%- if message.reasoning_content is string %}\n            {%- set reasoning_content = message.reasoning_content %}\n        {%- else %}\n            {%- if '</think>' in content %}\n                {%- set reasoning_content = content.split('</think>')[0].rstrip('\\n').split('<think>')[-1].lstrip('\\n') %}\n                {%- set content = content.split('</think>')[-1].lstrip('\\n') %}\n            {%- endif %}\n        {%- endif %}\n        {%- if loop.index0 > ns.last_query_index %}\n            {%- if loop.last or (not loop.last and reasoning_content) %}\n                {{- '<|im_start|>' + message.role + '\\n<think>\\n' + reasoning_content.strip('\\n') + '\\n</think>\\n\\n' + content.lstrip('\\n') }}\n            {%- else %}\n                {{- '<|im_start|>' + message.role + '\\n' + content }}\n            {%- endif %}\n        {%- else %}\n            {{- '<|im_start|>' + message.role + '\\n' + content }}\n        {%- endif %}\n        {%- if message.tool_calls %}\n            {%- for tool_call in message.tool_calls %}\n                {%- if (loop.first and content) or (not loop.first) %}\n                    {{- '\\n' }}\n                {%- endif %}\n                {%- if tool_call.function %}\n                    {%- set tool_call = tool_call.function %}\n                {%- endif %}\n                {{- '<tool_call>\\n{\"name\": \"' }}\n                {{- tool_call.name }}\n                {{- '\", \"arguments\": ' }}\n                {%- if tool_call.arguments is string %}\n                    {{- tool_call.arguments }}\n                {%- else %}\n                    {{- tool_call.arguments | tojson }}\n                {%- endif %}\n                {{- '}\\n</tool_call>' }}\n            {%- endfor %}\n        {%- endif %}\n        {{- '<|im_end|>\\n' }}\n    {%- elif message.role == \"tool\" %}\n        {%- if loop.first or (messages[loop.index0 - 1].role != \"tool\") %}\n            {{- '<|im_start|>user' }}\n        {%- endif %}\n        {{- '\\n<tool_response>\\n' }}\n        {{- content }}\n        {{- '\\n</tool_response>' }}\n        {%- if loop.last or (messages[loop.index0 + 1].role != \"tool\") %}\n            {{- '<|im_end|>\\n' }}\n        {%- endif %}\n    {%- endif %}\n{%- endfor %}\n{%- if add_generation_prompt %}\n    {{- '<|im_start|>assistant\\n' }}\n    {%- if enable_thinking is defined and enable_thinking is false %}\n        {{- '<think>\\n\\n</think>\\n\\n' }}\n    {%- endif %}\n{%- endif %}",
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "errors": "replace",
+  "model_max_length": 131072,
+  "pad_token": "<|endoftext|>",
+  "split_special_tokens": false,
+  "tokenizer_class": "Qwen2Tokenizer",
+  "unk_token": null
+}

transformer/config.json

@@ -0,0 +1,32 @@
+{
+    "_class_name": "ZImageTransformer2DModel",
+    "_diffusers_version": "0.36.0.dev0",
+    "all_f_patch_size": [
+        1
+    ],
+    "all_patch_size": [
+        2
+    ],
+    "axes_dims": [
+        32,
+        48,
+        48
+    ],
+    "axes_lens": [
+        1536,
+        512,
+        512
+    ],
+    "cap_feat_dim": 2560,
+    "dim": 3840,
+    "in_channels": 16,
+    "n_heads": 30,
+    "n_kv_heads": 30,
+    "n_layers": 30,
+    "n_refiner_layers": 2,
+    "norm_eps": 1e-05,
+    "qk_norm": true,
+    "rope_theta": 256.0,
+    "t_scale": 1000.0,
+    "nheads": 30
+}

transformer/model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c574bbc33780e5a0805469d2825cd8991741fd880199273a4df38e960004c7b4
+size 3848371009

vae/config.json

@@ -0,0 +1,38 @@
+{
+  "_class_name": "AutoencoderKL",
+  "_diffusers_version": "0.36.0.dev0",
+  "_name_or_path": "flux-dev",
+  "act_fn": "silu",
+  "block_out_channels": [
+    128,
+    256,
+    512,
+    512
+  ],
+  "down_block_types": [
+    "DownEncoderBlock2D",
+    "DownEncoderBlock2D",
+    "DownEncoderBlock2D",
+    "DownEncoderBlock2D"
+  ],
+  "force_upcast": true,
+  "in_channels": 3,
+  "latent_channels": 16,
+  "latents_mean": null,
+  "latents_std": null,
+  "layers_per_block": 2,
+  "mid_block_add_attention": true,
+  "norm_num_groups": 32,
+  "out_channels": 3,
+  "sample_size": 1024,
+  "scaling_factor": 0.3611,
+  "shift_factor": 0.1159,
+  "up_block_types": [
+    "UpDecoderBlock2D",
+    "UpDecoderBlock2D",
+    "UpDecoderBlock2D",
+    "UpDecoderBlock2D"
+  ],
+  "use_post_quant_conv": false,
+  "use_quant_conv": false
+}

vae/diffusion_pytorch_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f5b59a26851551b67ae1fe58d32e76486e1e812def4696a4bea97f16604d40a3
+size 167666902