{"id":49028921,"url":"https://github.com/uqer1244/MLX_z-image","last_synced_at":"2026-05-05T13:01:01.497Z","repository":{"id":328184890,"uuid":"1113214602","full_name":"uqer1244/MLX_z-image","owner":"uqer1244","description":"MLX version of z-image model","archived":false,"fork":false,"pushed_at":"2026-01-21T17:34:56.000Z","size":7187,"stargazers_count":31,"open_issues_count":2,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-01-22T05:18:00.772Z","etag":null,"topics":["apple-silicon","image-generation","mlx"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uqer1244.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-09T17:13:00.000Z","updated_at":"2026-01-21T17:35:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/uqer1244/MLX_z-image","commit_stats":null,"previous_names":["uqer1244/mlx_z-image"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/uqer1244/MLX_z-image","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uqer1244%2FMLX_z-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uqer1244%2FMLX_z-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uqer1244%2FMLX_z-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uqer1244%2FMLX_z-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uqer1244","download_url":"https://codeload.github.com/uqer1244/MLX_z-image/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uqer1244%2FMLX_z-image/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32650449,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-silicon","image-generation","mlx"],"created_at":"2026-04-19T09:00:36.931Z","updated_at":"2026-05-05T13:01:01.488Z","avatar_url":"https://github.com/uqer1244.png","language":"Python","funding_links":[],"categories":["Rising projects"],"sub_categories":[],"readme":"\n# MLX z-image 🍎\n\nAn efficient **MLX implementation** of [Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) optimized for Apple Silicon (M1/M2/M3/M4).\n\nThis repository allows you to run high-quality image generation locally on your Mac using **4-bit quantization**, significantly reducing memory usage while maintaining quality.\n\n[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Model-ffc107?style=flat-square)](https://huggingface.co/uqer1244/MLX-z-image)\n\n## 📂 Project Structure\n\nIt is recommended to organize your folders as follows:\n\n```text\nMLX_z-image/\n├── converting/                    # Scripts to convert PyTorch to MLX (just non functional files)\n├── Z-Image-Turbo-MLX/             # MLX Weights (auto download on first run)\n├── mlx_text_encoder.py            # MLX converted Text Encoder\n├── mlx_z_image.py                 # MLX converted transformer\n├── check_lora.py                  # Checking lora is suitable for mlx-z-image\n├── lora_utils.py                  # Apply lora\n├── run.py                         # Run Script\n├── prompt.txt                     # prompt\n└── mlx_pipeline.py                # mlx Pipeline\n````\n## 📊 Performance \u0026 Gallery\n\n### Benchmarks\nInference tests were conducted on Apple Silicon devices using **native MLX** with **4-bit quantization**.\n\n- **Resolution**: 1024x1024\n- **Steps**: 9 (Turbo)\n\n| Device     | RAM  | Total Time | Denoise Time | Time per Step |\n|:-----------|:-----|:-----------|:-------------|:--------------|\n| **M3 Pro** | 18GB | ~ 150 s    | 140 s        | 15 s/Step     |\n| **M4**     | 16GB | ~ 240 s    | 230 s        | 25 s/Step     |\n\n\n### Gallary\nUncurated samples generated directly on a Mac using the 4-bit quantized model.\n\n*\"anime digital painting  She sat poised on a ledge of polished peach quartz, the very image of a classical statue brought to wild, impish life within the sunlit cave dwellings. Her Korean features were framed by a stunning ginger hime cut, its straight, . A wild assembly of leather straps and sheer, iridescent fabric served as her lingerie, barely covering her slim figure while perfectly accentuating her narrow waist, tight ass, and breasts. The natural sunlight filtering through the cave's opening bathed her in a warm, rosy glow, making her pale skin seem to glow from within. One hand rested flat on the quartz beside her, supporting her lean, while the other was raised to her mouth, a single finger resting thoughtfully on her lower lip as she watched the dust motes dance in the light.\"*\n\n|               **MLX**               |\n|:-----------------------------------:|\n| \u003cimg src=\"img/res.png\" width=\"512\"\u003e | \n\n## Technical Highlights\n\nI implemented a **Single-Stream Z-Image Transformer** fully based on MLX, optimizing specifically for the **Unified Memory Architecture** of Apple Silicon.\n\n### 1. Linear Projection Fusion (QKV Optimization)\nIn standard PyTorch implementations, Q, K, and V projections are often performed sequentially:\n\n```python\nq = x @ W_q, k = x @ W_k, v = x @ W_v  # 3 Memory Accesses\n\n```\n\nI fused these weights into a single tensor to minimize memory reads:\n\n```python\nqkv = x @ W_qkv  # 1 Memory Access\n\n```\n\nThis is crucial for LLMs and Diffusion models on Mac, where **memory bandwidth** often becomes the bottleneck before compute power.\n\n### 2. Hardware-Accelerated Flash Attention\n\nI utilize MLX's native kernel `mx.fast.scaled_dot_product_attention`. This operation runs directly on the GPU using optimized Metal kernels, avoiding the creation of large intermediate attention maps. This allows for higher resolution generation without OOM (Out Of Memory) errors.\n\n### 3. Loop-Invariant RoPE Caching\n\nThe denoising process involves iterative steps, but the **spatial grid (H, W)** of the image latent remains constant. Instead of recalculating rotary embeddings at every step.\n\n* **Pre-compute** Cosine/Sine tables for the maximum sequence length before the loop.\n* **Cache** them in VRAM.\n* **Pass** the cached tensors to the compiled step function.\n\nThis reduces the computational overhead of the `ApplyRoPE` operation to near zero during sampling.\n\n\n## Installation\n\n### 1\\. Clone the repository\n\n```bash\ngit clone https://github.com/uqer1244/MLX_z-image.git\ncd MLX_z-image\n```\n\n### 2\\. Install dependencies\n\nEnsure you have Python installed (Python 3.10+ recommended).\n\n```bash\npip install -r requirements.txt\n```\n\n*(Note: `huggingface_hub` is required for downloading models)*\n\n-----\n\n## Quick Start\n\nWe have packaged everything (Transformer, Text Encoder, VAE, Tokenizer, Scheduler) into a single repository for easy usage.\n\n### Option 1: Automatic Download \u0026 Run (Recommended)\n\nSimply run the script. If the model is not found locally, it will automatically download the full 4-bit quantized package from Hugging Face.\n\n```bash\npython run.py \n```\n\n\n\u003e **Note:** The prompt is always loaded from `prompt.txt` to handle long/complex prompts easily.\n\n\n### Options\n\n| Argument       | Description     | Default  |\n|:---------------|:----------------|:---------|\n| `--width`      | Image Width     | `1024`   |\n| `--height`     | Image Height    | `1024`   |\n| `--steps`      | Inference Steps | `9`      |\n| `--seed`       | Random Seed     | `42`     |\n| `--output`     | Output filename | `res.png` |\n| `--lora_path`  | Lora path       | `None`   |\n| `--lora_scale` | Lora scale      | `1.0`    |\n\nLora only works when insert \"Lora_path\"\n\n\n```bash\npython run.py \\\n  --width 1024 \\ \n  --height 1024 \\\n  --steps 9 \\\n  --seed 42 \\\n  --output \"res.png\" \\\n  --steps 5 \\ \n  --lora_path \"~~.safetensor\" \\\n  --lora_scale 1.0 \\\n  ```\n\n\u003e **Note:** Width and Height resolutions are always able to devide by 8\n\n\n\n### [ComfyUI Custom node setup](custom_nodes/readme.md)\n\n\n-----\n\n## Todo \u0026 Roadmap\n\nWe are actively working on making this implementation pure MLX and bug-free.\n\n  - [x] **Fix Artifacts**: Investigate and resolve visual artifacts (tiling/color issues) currently visible in some generations.\n  - [ ] **Full MLX Pipeline**: Port the remaining PyTorch components (VAE, Text Encoder, Tokenizer, Scheduler) to native MLX to remove the `torch` and `diffusers` dependencies completely.\n    - [x] Text Encoder - 4bit\n    - [ ] Tokenizer - tokenizer is faster enough\n    - [x] Scheduler\n    - [x] Transformer - 4bit\n    - [ ] VAE - I tried MLX converting for VAE, but pytorch version is more stable\n  - [x] **LoRA Support**: Add support for loading and applying LoRA adapters for style customization.\n  - [x] **ComfyUI Node**: Add custom node for ComfyUI GUI.\n  - [ ] **IP over ThunderBolt (or RDMA on TB5) support** : Add support for multiple mac cluster.\n  - [ ] **Z-Image-Edit, Base model support** : now on turbo only.\n\n-----\n\n\n## Acknowledgements\n\n  - Original Model: [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)\n  - MLX Framework: [Apple Machine Learning Research](https://github.com/ml-explore/mlx)\n\n## License\n\nThis project is a modification of [Tongyi-MAI/Z-Image](https://github.com/Tongyi-MAI/Z-Image) and is licensed under the **Apache License 2.0**.\n\n  - **Original Code**: Copyright (c) Tongyi-MAI\n  - **Modifications**: Ported to Apple MLX by uqer1244\n\n\u003c!-- end list --\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuqer1244%2FMLX_z-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuqer1244%2FMLX_z-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuqer1244%2FMLX_z-image/lists"}