Add files using upload-large-folder tool

.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
+evaluation/bf16/composition-s42.png filter=lfs diff=lfs merge=lfs -text

CHANGES.md

@@ -0,0 +1,5 @@
+# Modifications
+
+Modified by ixim / iximbox for Image21-MLX: converted from the pinned BF16 source to MLX layout; eligible linear weights use groupwise affine quantization. See conversion.json for precision and exceptions. Built with Qwen.
+
+VAE convolution layout is transposed without reducing FP32 precision. The entire vision tower, token embeddings, language head, norms, transformer input/output projections, timestep embedding and modulation remain floating point.

LICENSE

@@ -0,0 +1,55 @@
+Qwen RESEARCH LICENSE AGREEMENT
+
+Qwen RESEARCH LICENSE AGREEMENT Release Date: September 20, 2026
+
+By clicking to agree or by using or distributing any portion or element of the Qwen Materials, you will be deemed to have recognized and accepted the content of this Agreement, which is effective immediately.
+
+1. Definitions
+    a. This Qwen RESEARCH LICENSE AGREEMENT (this "Agreement") shall mean the terms and conditions for use, reproduction, distribution and modification of the Materials as defined by this Agreement.
+    b. "We" (or "Us") shall mean Hangzhou Tongyi Laboratory Technology Co., Ltd.
+    c. "You" (or "Your") shall mean a natural person or legal entity exercising the rights granted by this Agreement and/or using the Materials for any purpose and in any field of use.
+    d. "Third Parties" shall mean individuals or legal entities that are not under common control with us or you.
+    e. "Qwen" shall mean the large language models, diffusion models, and software and algorithms, consisting of trained model weights, parameters (including optimizer states), machine-learning model code, inference-enabling code, training-enabling code, fine-tuning enabling code and other elements of the foregoing distributed by us.
+    f. "Materials" shall mean, collectively, our proprietary Qwen and Documentation (and any portion thereof) made available under this Agreement.
+    g. "Source" form shall mean the preferred form for making modifications, including but not limited to model source code, documentation source, and configuration files.
+    h. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+    i. "Non-Commercial" shall mean for research or evaluation purposes only.
+
+2. Grant of Rights
+    a. You are granted a non-exclusive, worldwide, non-transferable and royalty-free limited license under our intellectual property or other rights owned by us embodied in the Materials to use, reproduce, distribute, copy, create derivative works of, and make modifications to the Materials FOR NON-COMMERCIAL PURPOSES ONLY. 
+    b. You shall not use the Materials for any commercial purpose without obtaining a separate commercial license from us. If you wish to use the Materials commercially, you shall request a license from us at model-business@notice.qwencloud.com.
+
+3. Redistribution
+Subject to Section 2 (Grant of Rights), you may distribute copies or make the Materials, or derivative works thereof, available as part of a product or service that contains any of them, with or without modifications, and in Source or Object form, provided that you meet the following conditions:
+    a. You shall give any other recipients of the Materials or derivative works a copy of this Agreement;
+    b. You shall cause any modified files to carry prominent notices stating that you changed the files;
+    c. You shall retain in all copies of the Materials that you distribute the following attribution notices within a "Notice" text file distributed as a part of such copies: "Qwen is licensed under the Qwen RESEARCH LICENSE AGREEMENT, Copyright (c) 2026 Hangzhou Tongyi Laboratory Technology Co., Ltd. All Rights Reserved."; and
+    d. You may add your own copyright statement to your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of your modifications, or for any such derivative works as a whole, provided your use, reproduction, and distribution of the work otherwise complies with the terms and conditions of this Agreement.
+
+4. Rules of use
+    a. The Materials may be subject to export controls or restrictions in China, the United States or other countries or regions. You shall comply with applicable laws and regulations in your use of the Materials.
+    b. If you use the Materials or any outputs or results therefrom to create, train, fine-tune, or improve an AI model that is distributed or made available, you shall prominently display “Built with Qwen” or “Improved using Qwen” in the related product documentation.
+    c. You shall not use "Qwen" as the primary name or identifier of any derivative works or products; reasonable descriptive use (e.g., "fine-tuned from Qwen Image") is permitted.
+
+5. Intellectual Property
+    a. We retain ownership of all intellectual property rights in and to the Materials and derivatives made by or for us. Conditioned upon compliance with the terms and conditions of this Agreement, with respect to any derivative works and modifications of the Materials that are made by you, you are and will be the owner of such derivative works and modifications.
+    b. No trademark license is granted to use the trade names, trademarks, service marks, or product names of us, except as required to fulfill notice requirements under this Agreement or as required for reasonable and customary use in describing and redistributing the Materials.
+    c. If you commence a lawsuit or other proceedings (including a cross-claim or counterclaim in a lawsuit) against us or any entity alleging that the Materials or any output therefrom, or any part of the foregoing, infringe any intellectual property or other right owned or licensable by you, then all licenses granted to you under this Agreement shall terminate as of the date such lawsuit or other proceeding is commenced or brought.
+
+6. Disclaimer of Warranty and Limitation of Liability
+    a. We are not obligated to support, update, provide training for, or develop any further version of the Qwen Materials or to grant any license thereto.
+    b. THE MATERIALS ARE PROVIDED "AS IS" WITHOUT ANY EXPRESS OR IMPLIED WARRANTY OF ANY KIND INCLUDING WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT, OR FITNESS FOR A PARTICULAR PURPOSE. WE MAKE NO WARRANTY AND ASSUME NO RESPONSIBILITY FOR THE SAFETY OR STABILITY OF THE MATERIALS AND ANY OUTPUT THEREFROM.
+    c. IN NO EVENT SHALL WE BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE MATERIALS OR ANY OUTPUT OF IT, NO MATTER HOW IT’S CAUSED.
+    d. You will defend, indemnify and hold harmless us from and against any claim by any third party arising out of or related to your use or distribution of the Materials.
+
+7. Survival and Termination.
+    a. The term of this Agreement shall commence upon your acceptance of this Agreement or access to the Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein.
+    b. We may terminate this Agreement if you breach any of the terms or conditions of this Agreement. Upon termination of this Agreement, you must delete and cease use of the Materials. Sections 6 and 8 shall survive the termination of this Agreement.
+
+8. Governing Law and Jurisdiction.
+    a. This Agreement and any dispute arising out of or relating to it will be governed by the laws of China, without regard to conflict of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement.
+    b. The People's Courts in Hangzhou City shall have exclusive jurisdiction over any dispute arising out of this Agreement.
+
+9. Other Terms and Conditions.
+    a. Any arrangements, understandings, or agreements regarding the Material not stated herein are separate from and independent of the terms and conditions of this Agreement. You shall request a separate license from us, if you use the Materials in ways not expressly agreed to in this Agreement. 
+    b. We shall not be bound by any additional or different terms or conditions communicated by you unless expressly agreed.

MANIFEST.json

@@ -0,0 +1,417 @@
+[
+  {
+    "path": "CHANGES.md",
+    "size": 471,
+    "sha256": "01c72c43bec801321010cccff2049a39940a7fa2ddc21e0a448793bb288dc35c"
+  },
+  {
+    "path": "LICENSE",
+    "size": 7831,
+    "sha256": "8dc973f024ff95966bea25866efa443fd16776dcb1001e681e3d467ea572b28d"
+  },
+  {
+    "path": "Notice",
+    "size": 388,
+    "sha256": "6e5545e72d7e21a0b1b5e1e4254bcf444fbf69c8639409b14248bcff94e63f7d"
+  },
+  {
+    "path": "README.md",
+    "size": 6850,
+    "sha256": "90ea8c96bc0c3b842fed9d78467d7adb6b60bf115875d205ec4c38e49dc8addf"
+  },
+  {
+    "path": "benchmarks/cases.json",
+    "size": 1919,
+    "sha256": "2663ee3d489e1eb136e02b083963b8622146fc65ac301d6acc5a6aab21e63356"
+  },
+  {
+    "path": "conversion.json",
+    "size": 25509,
+    "sha256": "5a0185391cd88f5eec7101c52b7fa4e0c876f542903ba1ba66ff208327f185dd"
+  },
+  {
+    "path": "evaluation/8bit/COMPLETE.json",
+    "size": 73,
+    "sha256": "cd40aa24c15f7458da2a63b571fb0afee8c0c1a2eee9d8339872e0aface2ba8d"
+  },
+  {
+    "path": "evaluation/8bit/chinese_text-s42.png",
+    "size": 1098691,
+    "sha256": "a004a65048217fc709f110d5d00bd4aeb284ef76d42d0df4fc8a5d0df4779e1b"
+  },
+  {
+    "path": "evaluation/8bit/composition-s42.png",
+    "size": 1121051,
+    "sha256": "0add44cd7e9f92f7b4b9fe2d2a1c831a4ab43f8109e0eee2f9191f61b937aee2"
+  },
+  {
+    "path": "evaluation/8bit/edit-s1000042.png",
+    "size": 1726278,
+    "sha256": "152b1dcfd216713dd9d7e79b1de22dc1618692e6e5f1aa35459b3a3ce88d21cb"
+  },
+  {
+    "path": "evaluation/8bit/english_text-s42.png",
+    "size": 968820,
+    "sha256": "283a5b4147a9552701ffc16da7a8763fec928499d8678e205e74afae6f475a52"
+  },
+  {
+    "path": "evaluation/8bit/environment.json",
+    "size": 27251,
+    "sha256": "b84d6aec6456999d088c55578a720add96a90dcb424de6bfba46e9f9381bfd71"
+  },
+  {
+    "path": "evaluation/8bit/portrait-s42.png",
+    "size": 1828666,
+    "sha256": "aaa56d1bd3329428332b527279999472c00ed4bbdd1e6bb13a84d365a13db00e"
+  },
+  {
+    "path": "evaluation/8bit/results.jsonl",
+    "size": 6597,
+    "sha256": "742a088a5e0d30a04a5f8b2ce6eb5ae9fa3613167fed0072227eb1bb991437ff"
+  },
+  {
+    "path": "evaluation/8bit/rgba-s42.png",
+    "size": 689083,
+    "sha256": "722a3d2015ceb8cbfa994ac0b38a3b4d6fbb4c68a80a8198d24ac01de6af121e"
+  },
+  {
+    "path": "evaluation/8bit/texture-s42.png",
+    "size": 1764465,
+    "sha256": "23435675875678ebe9550d697d6b798fcbac9c461e0d2b9c686535182cb42795"
+  },
+  {
+    "path": "evaluation/bf16/COMPLETE.json",
+    "size": 73,
+    "sha256": "cd40aa24c15f7458da2a63b571fb0afee8c0c1a2eee9d8339872e0aface2ba8d"
+  },
+  {
+    "path": "evaluation/bf16/chinese_text-s42.png",
+    "size": 1100420,
+    "sha256": "d2e903aa478d0ea500372b800e5276669f07340ea27227544fe560a900d766ac"
+  },
+  {
+    "path": "evaluation/bf16/composition-s42.png",
+    "size": 1114487,
+    "sha256": "b361dd45e536a8d4d2baa45d412966c1820eb21e0d096829387cd0afa736aaef"
+  },
+  {
+    "path": "evaluation/bf16/edit-s1000042.png",
+    "size": 1726291,
+    "sha256": "51d46aaf58fa9488f5094a553daac0d5ef921b045c619014d75a5256331170d0"
+  },
+  {
+    "path": "evaluation/bf16/english_text-s42.png",
+    "size": 959474,
+    "sha256": "2ce4e2a35c0023832bcea130d1955ded09c390f3571ad43c6aaa44581362e55c"
+  },
+  {
+    "path": "evaluation/bf16/environment.json",
+    "size": 1747,
+    "sha256": "3ac177a51fd089875326d4c7fdb3f78fe7c77cb77fd8870e7da5f18ee6fa5c0e"
+  },
+  {
+    "path": "evaluation/bf16/portrait-s42.png",
+    "size": 1829384,
+    "sha256": "72493104ac6662f1de9e7857e8ec03f4f3971c31c4ea77207d33ae029a3a0c41"
+  },
+  {
+    "path": "evaluation/bf16/results.jsonl",
+    "size": 6601,
+    "sha256": "2c9856ece4b83473cf884aa37c7a55be9cec3a52df31920e6a41b6e07418657d"
+  },
+  {
+    "path": "evaluation/bf16/rgba-s42.png",
+    "size": 687815,
+    "sha256": "c7adbb4da64425795a221e780cf872ee642dc6d8d47c7efdefadc75fdcc0396b"
+  },
+  {
+    "path": "evaluation/bf16/texture-s42.png",
+    "size": 1757770,
+    "sha256": "6399da2b528016420f934dd33613ace33d30cfed338f7815a14645e15b01b1f2"
+  },
+  {
+    "path": "evaluation/cache-parity-8bit.json",
+    "size": 550,
+    "sha256": "125b9eb038bc4a7aa74281e0d819f216dab0e50edbc7b24f82f097d1b257edba"
+  },
+  {
+    "path": "evaluation/cache-parity-bf16.json",
+    "size": 548,
+    "sha256": "47d3ca6081acfa67a1aa0d5575fef11b42caab4ac55b010cf6f0d6d13b558ab2"
+  },
+  {
+    "path": "evaluation/comparison.png",
+    "size": 4156154,
+    "sha256": "19083714350e5b2cdd596df81794ab62b724898b0f63f1245df5a191f1506d8e"
+  },
+  {
+    "path": "evaluation/offload-parity.json",
+    "size": 1340,
+    "sha256": "36343d5931725290cedb150d98f97da3ec9f98d8d4ef43ab2ca7b87fefb94344"
+  },
+  {
+    "path": "evaluation/precision-probe.json",
+    "size": 13644,
+    "sha256": "950a98b43817f51642d59a794712962129133bbc04715831e7aebcba095d70f3"
+  },
+  {
+    "path": "evaluation/report.md",
+    "size": 4544,
+    "sha256": "982d457ebc32c455c58afebf78c0e2dba8d6c0b7ee0858adc87209514603fafc"
+  },
+  {
+    "path": "evaluation/runtime-manifest.json",
+    "size": 509,
+    "sha256": "ee348c543f136b162f3c285f15a66cd59fa51f8d889aad07e6e26e8e02bf39bb"
+  },
+  {
+    "path": "evaluation/source-files.json",
+    "size": 5163,
+    "sha256": "0c0ddea15b77f9a8093144d083ac887b5f8977fc92db52f1a168008deba8b4bc"
+  },
+  {
+    "path": "evaluation/summary.json",
+    "size": 3280,
+    "sha256": "e2c1820cea379a4ac66bd2f1779c56645666ffaafa757855fe3cf0f2943613cc"
+  },
+  {
+    "path": "evaluation/system-context.json",
+    "size": 1188,
+    "sha256": "82fd648e290d6b5f10ee583a827ab08761edc00b9bca448c7793d65c48225a05"
+  },
+  {
+    "path": "evaluation/visual-review.json",
+    "size": 6277,
+    "sha256": "8b41b30803ae40972945ea5777f592c1681fad02de7368a20d4e9e3c68e3696d"
+  },
+  {
+    "path": "model_index.json",
+    "size": 447,
+    "sha256": "cf1ecd104ea090855d60d8cec0895c1e9d6ee41b2f87e231b678beecd1cf7809"
+  },
+  {
+    "path": "processor/added_tokens.json",
+    "size": 707,
+    "sha256": "c0284b582e14987fbd3d5a2cb2bd139084371ed9acbae488829a1c900833c680"
+  },
+  {
+    "path": "processor/chat_template.jinja",
+    "size": 5292,
+    "sha256": "3636d0f0bd6bef02654cdffdc447b79cb2cef8ab02cc75267345946291a489e4"
+  },
+  {
+    "path": "processor/merges.txt",
+    "size": 1671853,
+    "sha256": "8831e4f1a044471340f7c0a83d7bd71306a5b867e95fd870f74d0c5308a904d5"
+  },
+  {
+    "path": "processor/preprocessor_config.json",
+    "size": 782,
+    "sha256": "93585062a80db5e8ca038efc7726a3e6411d9db948472d81d63c6303993be8c5"
+  },
+  {
+    "path": "processor/special_tokens_map.json",
+    "size": 613,
+    "sha256": "76862e765266b85aa9459767e33cbaf13970f327a0e88d1c65846c2ddd3a1ecd"
+  },
+  {
+    "path": "processor/tokenizer.json",
+    "size": 11422654,
+    "sha256": "aeb13307a71acd8fe81861d94ad54ab689df773318809eed3cbe794b4492dae4"
+  },
+  {
+    "path": "processor/tokenizer_config.json",
+    "size": 5445,
+    "sha256": "81ec7bb9530159b326c0bef1d0b6c33d392090524014ea3f0123a3c1eb9c2af5"
+  },
+  {
+    "path": "processor/video_preprocessor_config.json",
+    "size": 817,
+    "sha256": "59c5c9eb52182eb14c06ffb10ca9effd29adce5f238a95de23ca14a38dbd2cb1"
+  },
+  {
+    "path": "processor/vocab.json",
+    "size": 2776833,
+    "sha256": "ca10d7e9fb3ed18575dd1e277a2579c16d108e32f27439684afa0e10b1440910"
+  },
+  {
+    "path": "requirements.lock.txt",
+    "size": 1110,
+    "sha256": "ec2e0402146f97b80165946f96e39374bd68aa7d54c32163e7ade178a06511c5"
+  },
+  {
+    "path": "requirements.txt",
+    "size": 125,
+    "sha256": "4501caf47b8d383e90c5e5ee8e649c7e0dd71de29c508bf2edb34b02e0494f90"
+  },
+  {
+    "path": "scheduler/scheduler_config.json",
+    "size": 485,
+    "sha256": "5895f3a167c14a967fe9ac70c64924ae5acc79799e0679fd12907e594a713cd1"
+  },
+  {
+    "path": "scripts/MLX_VLM_LICENSE.txt",
+    "size": 1069,
+    "sha256": "f74c448746be3376e27dee43e2be9ec9d55f4820cd7466c603a6c7d1fd2d25b8"
+  },
+  {
+    "path": "scripts/__init__.py",
+    "size": 0,
+    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+  },
+  {
+    "path": "scripts/audit.py",
+    "size": 2255,
+    "sha256": "7e6183ffbd1861fc701f247603fc6be44b889a379ecada04e2e1d15529b2fbed"
+  },
+  {
+    "path": "scripts/benchmark.py",
+    "size": 5088,
+    "sha256": "318e2bde9fc68fdd547c8fd32a0fb9fbe69f3cf99e62b5049240ee00754b1566"
+  },
+  {
+    "path": "scripts/cards.py",
+    "size": 9369,
+    "sha256": "740ab304501946e7b8ecce32afd10c2879715a979c2e3b7afdecd42d9560f56a"
+  },
+  {
+    "path": "scripts/common.py",
+    "size": 2712,
+    "sha256": "77ad9a6a8875ed0a1ef5d920058d3406b75cf0b8d038d3f8e9eed39c2a1d6914"
+  },
+  {
+    "path": "scripts/convert.py",
+    "size": 5970,
+    "sha256": "f177576669880b7501924fab5cec8119fcbb7e4c8007665f40ae5c486fdf0b36"
+  },
+  {
+    "path": "scripts/infer.py",
+    "size": 2175,
+    "sha256": "708a48f9dd6ca8a332875799637904bc63656f2bc8b158b81e9e46c5aba7e7e3"
+  },
+  {
+    "path": "scripts/login.py",
+    "size": 898,
+    "sha256": "b39d663babb2b685993433b662b42125ed357332d1d4271e35455c2fc62d259e"
+  },
+  {
+    "path": "scripts/mlx_pipeline.py",
+    "size": 13583,
+    "sha256": "ac001b3cf8b79304fc02efd3127576a67d7b03551a6295a6fc1c2a13d032614b"
+  },
+  {
+    "path": "scripts/probe.py",
+    "size": 2888,
+    "sha256": "3e450e1b077f153ed0c6762e3f3c0b5d0c455c0f11ee8e5578bc05226589a154"
+  },
+  {
+    "path": "scripts/release.py",
+    "size": 5206,
+    "sha256": "d1abeb50b719aa0aa943b6abc0a7596898ea97484ab3b6ba8930e2166eca06be"
+  },
+  {
+    "path": "scripts/report.py",
+    "size": 5600,
+    "sha256": "87634473beb077f9b2617160510d52c1b181bcafdd77de7d458dc27477696563"
+  },
+  {
+    "path": "scripts/runtime.py",
+    "size": 2490,
+    "sha256": "ad32ba856fddf5168d50e930204603fd2caeb016bc70fe9972d769aade6a79f4"
+  },
+  {
+    "path": "scripts/upload.py",
+    "size": 4004,
+    "sha256": "fe50fdf1d2c4eb8e88539324797ca878667a3f7ce03b2a2572b6bbb597b6c54c"
+  },
+  {
+    "path": "scripts/verify_cache.py",
+    "size": 2297,
+    "sha256": "97a2ff08dd26d9f1e085843cbaa9d1a40196f5239c5e521d3f3b6c144db0d612"
+  },
+  {
+    "path": "text_encoder/config.json",
+    "size": 1874,
+    "sha256": "ce16d11ac7f4f9383bce66fcae7932665992ed29b48d5d8ffc83e1585044e2b5"
+  },
+  {
+    "path": "text_encoder/model-00001-of-00006.safetensors",
+    "size": 1152816452,
+    "sha256": "c990998d46948fe255332cfe5f75b0d3d55aabc88717e173f18aa38604d1d797"
+  },
+  {
+    "path": "text_encoder/model-00002-of-00006.safetensors",
+    "size": 1957771354,
+    "sha256": "06c8e0698ce37b7ab750a33a56332b23b2147620482f36ec28c98b3f61094e9a"
+  },
+  {
+    "path": "text_encoder/model-00003-of-00006.safetensors",
+    "size": 1996689654,
+    "sha256": "781e557722909cf1b5db5e13582a4b35be3d49615ba8920a4f7541ac0d54d564"
+  },
+  {
+    "path": "text_encoder/model-00004-of-00006.safetensors",
+    "size": 1952106414,
+    "sha256": "51cff2fe048456449a8131cc0642e091cce43d0116414599fd3ebae04b4fa6fa"
+  },
+  {
+    "path": "text_encoder/model-00005-of-00006.safetensors",
+    "size": 1996689818,
+    "sha256": "023b173e9208a5f406acd516382817c7983b58ef0f57154c55627ba96589f0d6"
+  },
+  {
+    "path": "text_encoder/model-00006-of-00006.safetensors",
+    "size": 1966674243,
+    "sha256": "cb57f09b7e78a82fbede723c680b9d0231357dfec772856f6db4fe8322890898"
+  },
+  {
+    "path": "text_encoder/model.safetensors.index.json",
+    "size": 116487,
+    "sha256": "2caeee17a1f27f641e70bfd07e7f7b7527814d1f1dbab3e1875ea8c8a6f3f59e"
+  },
+  {
+    "path": "transformer/config.json",
+    "size": 727,
+    "sha256": "ae72e14e73a31cb130f1a5a7b5e712c574d3a314c4ed5d8d4f73321b19ec3ced"
+  },
+  {
+    "path": "transformer/model-00001-of-00004.safetensors",
+    "size": 1984463956,
+    "sha256": "2aa12f9c914fe8d152d2a932d485b475a2c30398d8ee70ee15278383e98586c0"
+  },
+  {
+    "path": "transformer/model-00002-of-00004.safetensors",
+    "size": 1996515918,
+    "sha256": "74fae4addedd82000aa70b84c98a7bed253c8ba4d006198841725fae3a3d2ac3"
+  },
+  {
+    "path": "transformer/model-00003-of-00004.safetensors",
+    "size": 1996516732,
+    "sha256": "fafec3d438a2c8d0e6766ff9e8c6d91eccdc7474af13a1a59b78bb3574fcffaa"
+  },
+  {
+    "path": "transformer/model-00004-of-00004.safetensors",
+    "size": 1709726423,
+    "sha256": "a612b703a280a936dc9e10828832e1c030113b0cdeaf628eb0ac5da88c339e80"
+  },
+  {
+    "path": "transformer/model.safetensors.index.json",
+    "size": 62901,
+    "sha256": "83dceafc8c4c4808997e4551f96d160d492e784ac11fc2d2f373768adc7578f8"
+  },
+  {
+    "path": "vae/config.json",
+    "size": 2353,
+    "sha256": "e672be7b41be0d4016dd78e4104fb6f2c246f9f63acb91e4e44e0862a16cbbf8"
+  },
+  {
+    "path": "vae/model-00001-of-00001.safetensors",
+    "size": 1350989238,
+    "sha256": "44e83fe1529df6753a00a0d8981cb3da0332826518f040937777cae4123225b9"
+  },
+  {
+    "path": "vae/model.safetensors.index.json",
+    "size": 20646,
+    "sha256": "86eee223fbf1df185b791785fc5b3775abfb59104a3ed91f19ec819eafe11b37"
+  }
+]

Notice

@@ -0,0 +1,4 @@
+Qwen is licensed under the Qwen RESEARCH LICENSE AGREEMENT, Copyright (c) 2026 Hangzhou Tongyi Laboratory Technology Co., Ltd. All Rights Reserved.
+
+Built with Qwen
+Modified by ixim / iximbox for Image21-MLX: converted from the pinned BF16 source to MLX layout; eligible linear weights use groupwise affine quantization. See conversion.json for precision and exceptions. Built with Qwen.

README.md

@@ -0,0 +1,132 @@
+---
+license: other
+license_name: qwen-research
+license_link: LICENSE
+base_model: Qwen/Qwen-Image-2.1
+library_name: mlx
+pipeline_tag: text-to-image
+tags:
+- mlx
+- mlx-vlm
+- apple-silicon
+- quantized
+- image-to-image
+- rgba
+---
+# Image21-MLX-8bit
+
+**Built with Qwen.** An independent native MLX quantization of Qwen-Image-2.1 for
+Apple Silicon, by ixim / iximbox. **Non-commercial research and evaluation only**
+under the original Qwen Research License. This is not an official Qwen release.
+
+The complete checkpoint is approximately **18.68 GiB**. DiT attention/MLP and
+language-encoder attention/MLP linears use **8-bit affine weights, group size 64**,
+with BF16 activations. The full vision tower, token embeddings, language head,
+norms and DiT input/output/timestep/modulation layers retain floating-point precision.
+The VAE retains its original **FP32** weights. See the exact 476 quantized modules in conversion.json.
+
+Supports text-to-image, native reference-image editing and RGBA transparency through
+the included scripts. The wrapper preserves the sampler's alpha channel, which the
+pinned upstream text-to-image convenience method otherwise slices away.
+The runtime also enables the upstream fixed-prefix KV cache for text-to-image.
+Components are loaded and released by phase to reduce unified-memory use.
+See scripts/mlx_pipeline.py and its retained MIT attribution.
+
+With the included phase-loading runtime, plan for **32GB unified memory as a starting
+budget; 48GB or more gives more room for other applications** at 1024px with one reference.
+These are capacity estimates, not verified minimums: only the 128GB M4 Max was tested.
+The measured Q8 MLX allocation peak is about **16.20 GiB**, excluding OS/driver overhead.
+16/24GB Macs are not the target for this default 1024px configuration. 2048px and
+10-reference editing have not been benchmarked. Allow roughly **50GB free disk space**
+for ordinary inference; rebuilding also needs the original source and baseline checkpoints.
+
+## Visual findings / 视觉检查
+
+Assistant inspection of all seven paired cases found no obvious severe quality regression in this small sample. English and Chinese text are correct in both precisions; cup count/order and sweater recoloring succeed; real RGBA transparency is retained. The English poster changes visibly in typeface and lamp structure, and the dragon changes expression/details. Other pairs are closer. Both portraits are cropped more tightly than requested, and both transparency samples contain slight near-zero background alpha. This is an unblinded, single-seed visual check, not evidence of lossless quantization or statistical equivalence.
+
+## Download / 下载
+
+On an Apple Silicon Mac with [uv](https://docs.astral.sh/uv/) installed:
+
+```bash
+uvx --from huggingface-hub==1.33.0 hf download ixim/Image21-MLX-8bit --local-dir Image21-MLX-8bit
+cd Image21-MLX-8bit
+```
+
+## Reproducible inference
+
+```bash
+uv venv --python 3.13 .venv
+uv pip install --python .venv/bin/python -r requirements.lock.txt
+.venv/bin/python -m scripts.infer --model . \
+  --prompt 'A natural portrait in soft window light' --output outputs/portrait.png
+```
+
+```bash
+.venv/bin/python -m scripts.infer --model . --input input.png \
+  --prompt 'Change only the blue sweater to a red sweater. Preserve the person and background.' \
+  --source-seed 42 --seed 1000042 --output outputs/edit.png
+```
+
+Transparent generation prompt:
+`This is an RGBA image with transparency. A cute cartoon dragon sticker. The image has alpha channel and the background is transparent.`
+
+## Measurements / 实测
+
+Apple M4 Max, 40 GPU cores, 128 GiB unified memory, macOS 26.6.2, MLX 0.32.2.
+Both models use the same pinned MLX runtime and internal SSD; 1024×1024, 40 steps,
+CFG=1, no VAE tiling, one full warm-up per process, seven cases, one seed per case.
+Sequential component loading is enabled in both models. Per-image time includes
+component loading, prompt encoding, denoising and VAE decoding; PNG writing is excluded.
+This is a desktop session with other applications open. BF16 ran before Q8;
+there were no repeated or interleaved trials to control order and thermal effects.
+
+| Case | BF16 seconds | 8-bit seconds | BF16 peak GiB | 8-bit peak GiB |
+|---|---:|---:|---:|---:|
+| portrait | 440.91 | 568.86 | 16.41 | 16.19 |
+| english_text | 464.32 | 566.88 | 16.43 | 16.20 |
+| chinese_text | 474.14 | 567.43 | 16.44 | 16.20 |
+| composition | 480.91 | 562.52 | 16.44 | 16.20 |
+| texture | 487.64 | 445.07 | 16.43 | 16.20 |
+| rgba | 485.45 | 557.30 | 16.42 | 16.20 |
+| edit | 606.29 | 665.00 | 18.68 | 16.20 |
+
+Six-case text-to-image mean / 六类文生图平均：BF16 **7.87 min**, Q8 **9.08 min**. Q8 generation time relative to BF16 / Q8 相对耗时：**+15.3%** in this run.
+
+Peak figures measure MLX allocations, not minimum physical RAM. Full raw records,
+original RGBA samples and the visual review are in [evaluation](evaluation/report.md).
+These are informal measurements, not an official benchmark. The BF16 baseline is
+the same MLX implementation; cross-runtime CUDA equivalence is not claimed.
+One seed per case is insufficient to establish statistical quality equivalence.
+There is no claim of lossless quantization or a guaranteed speedup.
+
+![All seven paired samples](evaluation/comparison.png)
+
+## Provenance
+
+- Source: `Qwen/Qwen-Image-2.1@b3179ad355be050328e483a9dfdd9e60cd62adfa`.
+- Runtime: `Blaizzy/mlx-vlm@95b01ccad2d9f65a9e87f6a87bd1c5df69626261`.
+- Native MLX affine packed weights; not CUDA bitsandbytes INT8, FP8, GGUF or an MFLUX checkpoint.
+- All three components passed exact tensor round-trip verification.
+- [conversion.json](conversion.json), [modifications](CHANGES.md), [Notice](Notice), [license](LICENSE), [file hashes](MANIFEST.json).
+
+To rebuild, first download the original source snapshot at the revision above to
+`source-bf16` (requires additional disk space), then run from this repository:
+
+```bash
+.venv/bin/python -m scripts.audit --source source-bf16 --manifest evaluation/source-files.json
+.venv/bin/python -m scripts.convert --source source-bf16 --bits 8 --output rebuilt-8bit
+```
+The audit verifies the original source file hashes before conversion. Rebuilding
+uses the original floating-point weights, never a dequantized CUDA INT8 checkpoint.
+
+To repeat the paired evaluation after the source audit, create a native baseline
+and run each precision in its own process. This is a lengthy research workflow
+and needs extra memory and disk space beyond ordinary inference:
+
+```bash
+.venv/bin/python -m scripts.convert --source source-bf16 --bits 16 --output rebuilt-bf16
+.venv/bin/python -m scripts.benchmark --model rebuilt-bf16 --output artifacts/eval/bf16
+.venv/bin/python -m scripts.benchmark --model . --output artifacts/eval/8bit --edit-input artifacts/eval/bf16/portrait-s42.png
+.venv/bin/python -m scripts.report
+```

benchmarks/cases.json

@@ -0,0 +1,9 @@
+[
+  {"id":"portrait","category":"portrait","prompt":"A natural documentary portrait of an elderly woman with silver hair and freckles, wearing a blue wool sweater, standing beside a window in soft morning light. Realistic skin texture, gentle expression, waist-up composition."},
+  {"id":"english_text","category":"typography_en","prompt":"A clean editorial poster with a deep blue background. Large exact headline at the top: \"CREATE WITH LIGHT\". Smaller exact subtitle: \"September 2026\". A realistic orange desk lamp occupies the lower half. Elegant balanced typography, no additional text."},
+  {"id":"chinese_text","category":"typography_zh","prompt":"设计一张现代咖啡馆海报，米白背景，中央一杯拉花拿铁。顶部准确写上中文大标题“慢下来，喝杯咖啡”，下方准确写上“小店今日营业”。文字清晰，留白充分，暖色摄影，不添加其他文字。"},
+  {"id":"composition","category":"spatial_counting","prompt":"A studio photograph on a light gray tabletop: exactly three ceramic cups in a row, a red cup on the left, a blue cup in the middle, and a yellow cup on the right. A single green apple sits in front of the blue cup. Soft shadows, no text."},
+  {"id":"texture","category":"texture","prompt":"Macro photography of a small kingfisher perched on a mossy branch beside clear water, detailed blue feathers, droplets, natural sunlight, softly blurred forest background, realistic textures."},
+  {"id":"rgba","category":"transparency","prompt":"This is an RGBA image with transparency. A cute cartoon dragon sticker, full body, green scales and small orange wings. The image has alpha channel and the background is transparent."},
+  {"id":"edit","category":"image_editing","prompt":"Change only the blue sweater to a red sweater. Preserve the same person, face, pose, lighting and background.","input":"artifacts/eval/bf16/portrait-s42.png"}
+]

conversion.json

@@ -0,0 +1,512 @@
+{
+  "name": "Image21-MLX",
+  "source_model": "Qwen/Qwen-Image-2.1",
+  "source_revision": "b3179ad355be050328e483a9dfdd9e60cd62adfa",
+  "runtime_revision": "95b01ccad2d9f65a9e87f6a87bd1c5df69626261",
+  "method": "MLX affine weight-only",
+  "bits": 8,
+  "group_size": 64,
+  "activation_dtype": "bfloat16",
+  "vae_dtype": "float32",
+  "components": {
+    "transformer": {
+      "quantized_modules": [
+        "transformer_blocks.0.attn.to_q",
+        "transformer_blocks.0.attn.to_k",
+        "transformer_blocks.0.attn.to_v",
+        "transformer_blocks.0.attn.to_out.0",
+        "transformer_blocks.0.img_mlp.proj",
+        "transformer_blocks.0.img_mlp.out",
+        "transformer_blocks.0.img_mlp.gate_layer",
+        "transformer_blocks.1.attn.to_q",
+        "transformer_blocks.1.attn.to_k",
+        "transformer_blocks.1.attn.to_v",
+        "transformer_blocks.1.attn.to_out.0",
+        "transformer_blocks.1.img_mlp.proj",
+        "transformer_blocks.1.img_mlp.out",
+        "transformer_blocks.1.img_mlp.gate_layer",
+        "transformer_blocks.2.attn.to_q",
+        "transformer_blocks.2.attn.to_k",
+        "transformer_blocks.2.attn.to_v",
+        "transformer_blocks.2.attn.to_out.0",
+        "transformer_blocks.2.img_mlp.proj",
+        "transformer_blocks.2.img_mlp.out",
+        "transformer_blocks.2.img_mlp.gate_layer",
+        "transformer_blocks.3.attn.to_q",
+        "transformer_blocks.3.attn.to_k",
+        "transformer_blocks.3.attn.to_v",
+        "transformer_blocks.3.attn.to_out.0",
+        "transformer_blocks.3.img_mlp.proj",
+        "transformer_blocks.3.img_mlp.out",
+        "transformer_blocks.3.img_mlp.gate_layer",
+        "transformer_blocks.4.attn.to_q",
+        "transformer_blocks.4.attn.to_k",
+        "transformer_blocks.4.attn.to_v",
+        "transformer_blocks.4.attn.to_out.0",
+        "transformer_blocks.4.img_mlp.proj",
+        "transformer_blocks.4.img_mlp.out",
+        "transformer_blocks.4.img_mlp.gate_layer",
+        "transformer_blocks.5.attn.to_q",
+        "transformer_blocks.5.attn.to_k",
+        "transformer_blocks.5.attn.to_v",
+        "transformer_blocks.5.attn.to_out.0",
+        "transformer_blocks.5.img_mlp.proj",
+        "transformer_blocks.5.img_mlp.out",
+        "transformer_blocks.5.img_mlp.gate_layer",
+        "transformer_blocks.6.attn.to_q",
+        "transformer_blocks.6.attn.to_k",
+        "transformer_blocks.6.attn.to_v",
+        "transformer_blocks.6.attn.to_out.0",
+        "transformer_blocks.6.img_mlp.proj",
+        "transformer_blocks.6.img_mlp.out",
+        "transformer_blocks.6.img_mlp.gate_layer",
+        "transformer_blocks.7.attn.to_q",
+        "transformer_blocks.7.attn.to_k",
+        "transformer_blocks.7.attn.to_v",
+        "transformer_blocks.7.attn.to_out.0",
+        "transformer_blocks.7.img_mlp.proj",
+        "transformer_blocks.7.img_mlp.out",
+        "transformer_blocks.7.img_mlp.gate_layer",
+        "transformer_blocks.8.attn.to_q",
+        "transformer_blocks.8.attn.to_k",
+        "transformer_blocks.8.attn.to_v",
+        "transformer_blocks.8.attn.to_out.0",
+        "transformer_blocks.8.img_mlp.proj",
+        "transformer_blocks.8.img_mlp.out",
+        "transformer_blocks.8.img_mlp.gate_layer",
+        "transformer_blocks.9.attn.to_q",
+        "transformer_blocks.9.attn.to_k",
+        "transformer_blocks.9.attn.to_v",
+        "transformer_blocks.9.attn.to_out.0",
+        "transformer_blocks.9.img_mlp.proj",
+        "transformer_blocks.9.img_mlp.out",
+        "transformer_blocks.9.img_mlp.gate_layer",
+        "transformer_blocks.10.attn.to_q",
+        "transformer_blocks.10.attn.to_k",
+        "transformer_blocks.10.attn.to_v",
+        "transformer_blocks.10.attn.to_out.0",
+        "transformer_blocks.10.img_mlp.proj",
+        "transformer_blocks.10.img_mlp.out",
+        "transformer_blocks.10.img_mlp.gate_layer",
+        "transformer_blocks.11.attn.to_q",
+        "transformer_blocks.11.attn.to_k",
+        "transformer_blocks.11.attn.to_v",
+        "transformer_blocks.11.attn.to_out.0",
+        "transformer_blocks.11.img_mlp.proj",
+        "transformer_blocks.11.img_mlp.out",
+        "transformer_blocks.11.img_mlp.gate_layer",
+        "transformer_blocks.12.attn.to_q",
+        "transformer_blocks.12.attn.to_k",
+        "transformer_blocks.12.attn.to_v",
+        "transformer_blocks.12.attn.to_out.0",
+        "transformer_blocks.12.img_mlp.proj",
+        "transformer_blocks.12.img_mlp.out",
+        "transformer_blocks.12.img_mlp.gate_layer",
+        "transformer_blocks.13.attn.to_q",
+        "transformer_blocks.13.attn.to_k",
+        "transformer_blocks.13.attn.to_v",
+        "transformer_blocks.13.attn.to_out.0",
+        "transformer_blocks.13.img_mlp.proj",
+        "transformer_blocks.13.img_mlp.out",
+        "transformer_blocks.13.img_mlp.gate_layer",
+        "transformer_blocks.14.attn.to_q",
+        "transformer_blocks.14.attn.to_k",
+        "transformer_blocks.14.attn.to_v",
+        "transformer_blocks.14.attn.to_out.0",
+        "transformer_blocks.14.img_mlp.proj",
+        "transformer_blocks.14.img_mlp.out",
+        "transformer_blocks.14.img_mlp.gate_layer",
+        "transformer_blocks.15.attn.to_q",
+        "transformer_blocks.15.attn.to_k",
+        "transformer_blocks.15.attn.to_v",
+        "transformer_blocks.15.attn.to_out.0",
+        "transformer_blocks.15.img_mlp.proj",
+        "transformer_blocks.15.img_mlp.out",
+        "transformer_blocks.15.img_mlp.gate_layer",
+        "transformer_blocks.16.attn.to_q",
+        "transformer_blocks.16.attn.to_k",
+        "transformer_blocks.16.attn.to_v",
+        "transformer_blocks.16.attn.to_out.0",
+        "transformer_blocks.16.img_mlp.proj",
+        "transformer_blocks.16.img_mlp.out",
+        "transformer_blocks.16.img_mlp.gate_layer",
+        "transformer_blocks.17.attn.to_q",
+        "transformer_blocks.17.attn.to_k",
+        "transformer_blocks.17.attn.to_v",
+        "transformer_blocks.17.attn.to_out.0",
+        "transformer_blocks.17.img_mlp.proj",
+        "transformer_blocks.17.img_mlp.out",
+        "transformer_blocks.17.img_mlp.gate_layer",
+        "transformer_blocks.18.attn.to_q",
+        "transformer_blocks.18.attn.to_k",
+        "transformer_blocks.18.attn.to_v",
+        "transformer_blocks.18.attn.to_out.0",
+        "transformer_blocks.18.img_mlp.proj",
+        "transformer_blocks.18.img_mlp.out",
+        "transformer_blocks.18.img_mlp.gate_layer",
+        "transformer_blocks.19.attn.to_q",
+        "transformer_blocks.19.attn.to_k",
+        "transformer_blocks.19.attn.to_v",
+        "transformer_blocks.19.attn.to_out.0",
+        "transformer_blocks.19.img_mlp.proj",
+        "transformer_blocks.19.img_mlp.out",
+        "transformer_blocks.19.img_mlp.gate_layer",
+        "transformer_blocks.20.attn.to_q",
+        "transformer_blocks.20.attn.to_k",
+        "transformer_blocks.20.attn.to_v",
+        "transformer_blocks.20.attn.to_out.0",
+        "transformer_blocks.20.img_mlp.proj",
+        "transformer_blocks.20.img_mlp.out",
+        "transformer_blocks.20.img_mlp.gate_layer",
+        "transformer_blocks.21.attn.to_q",
+        "transformer_blocks.21.attn.to_k",
+        "transformer_blocks.21.attn.to_v",
+        "transformer_blocks.21.attn.to_out.0",
+        "transformer_blocks.21.img_mlp.proj",
+        "transformer_blocks.21.img_mlp.out",
+        "transformer_blocks.21.img_mlp.gate_layer",
+        "transformer_blocks.22.attn.to_q",
+        "transformer_blocks.22.attn.to_k",
+        "transformer_blocks.22.attn.to_v",
+        "transformer_blocks.22.attn.to_out.0",
+        "transformer_blocks.22.img_mlp.proj",
+        "transformer_blocks.22.img_mlp.out",
+        "transformer_blocks.22.img_mlp.gate_layer",
+        "transformer_blocks.23.attn.to_q",
+        "transformer_blocks.23.attn.to_k",
+        "transformer_blocks.23.attn.to_v",
+        "transformer_blocks.23.attn.to_out.0",
+        "transformer_blocks.23.img_mlp.proj",
+        "transformer_blocks.23.img_mlp.out",
+        "transformer_blocks.23.img_mlp.gate_layer",
+        "transformer_blocks.24.attn.to_q",
+        "transformer_blocks.24.attn.to_k",
+        "transformer_blocks.24.attn.to_v",
+        "transformer_blocks.24.attn.to_out.0",
+        "transformer_blocks.24.img_mlp.proj",
+        "transformer_blocks.24.img_mlp.out",
+        "transformer_blocks.24.img_mlp.gate_layer",
+        "transformer_blocks.25.attn.to_q",
+        "transformer_blocks.25.attn.to_k",
+        "transformer_blocks.25.attn.to_v",
+        "transformer_blocks.25.attn.to_out.0",
+        "transformer_blocks.25.img_mlp.proj",
+        "transformer_blocks.25.img_mlp.out",
+        "transformer_blocks.25.img_mlp.gate_layer",
+        "transformer_blocks.26.attn.to_q",
+        "transformer_blocks.26.attn.to_k",
+        "transformer_blocks.26.attn.to_v",
+        "transformer_blocks.26.attn.to_out.0",
+        "transformer_blocks.26.img_mlp.proj",
+        "transformer_blocks.26.img_mlp.out",
+        "transformer_blocks.26.img_mlp.gate_layer",
+        "transformer_blocks.27.attn.to_q",
+        "transformer_blocks.27.attn.to_k",
+        "transformer_blocks.27.attn.to_v",
+        "transformer_blocks.27.attn.to_out.0",
+        "transformer_blocks.27.img_mlp.proj",
+        "transformer_blocks.27.img_mlp.out",
+        "transformer_blocks.27.img_mlp.gate_layer",
+        "transformer_blocks.28.attn.to_q",
+        "transformer_blocks.28.attn.to_k",
+        "transformer_blocks.28.attn.to_v",
+        "transformer_blocks.28.attn.to_out.0",
+        "transformer_blocks.28.img_mlp.proj",
+        "transformer_blocks.28.img_mlp.out",
+        "transformer_blocks.28.img_mlp.gate_layer",
+        "transformer_blocks.29.attn.to_q",
+        "transformer_blocks.29.attn.to_k",
+        "transformer_blocks.29.attn.to_v",
+        "transformer_blocks.29.attn.to_out.0",
+        "transformer_blocks.29.img_mlp.proj",
+        "transformer_blocks.29.img_mlp.out",
+        "transformer_blocks.29.img_mlp.gate_layer",
+        "transformer_blocks.30.attn.to_q",
+        "transformer_blocks.30.attn.to_k",
+        "transformer_blocks.30.attn.to_v",
+        "transformer_blocks.30.attn.to_out.0",
+        "transformer_blocks.30.img_mlp.proj",
+        "transformer_blocks.30.img_mlp.out",
+        "transformer_blocks.30.img_mlp.gate_layer",
+        "transformer_blocks.31.attn.to_q",
+        "transformer_blocks.31.attn.to_k",
+        "transformer_blocks.31.attn.to_v",
+        "transformer_blocks.31.attn.to_out.0",
+        "transformer_blocks.31.img_mlp.proj",
+        "transformer_blocks.31.img_mlp.out",
+        "transformer_blocks.31.img_mlp.gate_layer"
+      ],
+      "tensor_bytes": 7687135232,
+      "tensors": 745,
+      "exact_roundtrip": true
+    },
+    "text_encoder": {
+      "quantized_modules": [
+        "language_model.model.layers.0.self_attn.q_proj",
+        "language_model.model.layers.0.self_attn.k_proj",
+        "language_model.model.layers.0.self_attn.v_proj",
+        "language_model.model.layers.0.self_attn.o_proj",
+        "language_model.model.layers.0.mlp.gate_proj",
+        "language_model.model.layers.0.mlp.up_proj",
+        "language_model.model.layers.0.mlp.down_proj",
+        "language_model.model.layers.1.self_attn.q_proj",
+        "language_model.model.layers.1.self_attn.k_proj",
+        "language_model.model.layers.1.self_attn.v_proj",
+        "language_model.model.layers.1.self_attn.o_proj",
+        "language_model.model.layers.1.mlp.gate_proj",
+        "language_model.model.layers.1.mlp.up_proj",
+        "language_model.model.layers.1.mlp.down_proj",
+        "language_model.model.layers.2.self_attn.q_proj",
+        "language_model.model.layers.2.self_attn.k_proj",
+        "language_model.model.layers.2.self_attn.v_proj",
+        "language_model.model.layers.2.self_attn.o_proj",
+        "language_model.model.layers.2.mlp.gate_proj",
+        "language_model.model.layers.2.mlp.up_proj",
+        "language_model.model.layers.2.mlp.down_proj",
+        "language_model.model.layers.3.self_attn.q_proj",
+        "language_model.model.layers.3.self_attn.k_proj",
+        "language_model.model.layers.3.self_attn.v_proj",
+        "language_model.model.layers.3.self_attn.o_proj",
+        "language_model.model.layers.3.mlp.gate_proj",
+        "language_model.model.layers.3.mlp.up_proj",
+        "language_model.model.layers.3.mlp.down_proj",
+        "language_model.model.layers.4.self_attn.q_proj",
+        "language_model.model.layers.4.self_attn.k_proj",
+        "language_model.model.layers.4.self_attn.v_proj",
+        "language_model.model.layers.4.self_attn.o_proj",
+        "language_model.model.layers.4.mlp.gate_proj",
+        "language_model.model.layers.4.mlp.up_proj",
+        "language_model.model.layers.4.mlp.down_proj",
+        "language_model.model.layers.5.self_attn.q_proj",
+        "language_model.model.layers.5.self_attn.k_proj",
+        "language_model.model.layers.5.self_attn.v_proj",
+        "language_model.model.layers.5.self_attn.o_proj",
+        "language_model.model.layers.5.mlp.gate_proj",
+        "language_model.model.layers.5.mlp.up_proj",
+        "language_model.model.layers.5.mlp.down_proj",
+        "language_model.model.layers.6.self_attn.q_proj",
+        "language_model.model.layers.6.self_attn.k_proj",
+        "language_model.model.layers.6.self_attn.v_proj",
+        "language_model.model.layers.6.self_attn.o_proj",
+        "language_model.model.layers.6.mlp.gate_proj",
+        "language_model.model.layers.6.mlp.up_proj",
+        "language_model.model.layers.6.mlp.down_proj",
+        "language_model.model.layers.7.self_attn.q_proj",
+        "language_model.model.layers.7.self_attn.k_proj",
+        "language_model.model.layers.7.self_attn.v_proj",
+        "language_model.model.layers.7.self_attn.o_proj",
+        "language_model.model.layers.7.mlp.gate_proj",
+        "language_model.model.layers.7.mlp.up_proj",
+        "language_model.model.layers.7.mlp.down_proj",
+        "language_model.model.layers.8.self_attn.q_proj",
+        "language_model.model.layers.8.self_attn.k_proj",
+        "language_model.model.layers.8.self_attn.v_proj",
+        "language_model.model.layers.8.self_attn.o_proj",
+        "language_model.model.layers.8.mlp.gate_proj",
+        "language_model.model.layers.8.mlp.up_proj",
+        "language_model.model.layers.8.mlp.down_proj",
+        "language_model.model.layers.9.self_attn.q_proj",
+        "language_model.model.layers.9.self_attn.k_proj",
+        "language_model.model.layers.9.self_attn.v_proj",
+        "language_model.model.layers.9.self_attn.o_proj",
+        "language_model.model.layers.9.mlp.gate_proj",
+        "language_model.model.layers.9.mlp.up_proj",
+        "language_model.model.layers.9.mlp.down_proj",
+        "language_model.model.layers.10.self_attn.q_proj",
+        "language_model.model.layers.10.self_attn.k_proj",
+        "language_model.model.layers.10.self_attn.v_proj",
+        "language_model.model.layers.10.self_attn.o_proj",
+        "language_model.model.layers.10.mlp.gate_proj",
+        "language_model.model.layers.10.mlp.up_proj",
+        "language_model.model.layers.10.mlp.down_proj",
+        "language_model.model.layers.11.self_attn.q_proj",
+        "language_model.model.layers.11.self_attn.k_proj",
+        "language_model.model.layers.11.self_attn.v_proj",
+        "language_model.model.layers.11.self_attn.o_proj",
+        "language_model.model.layers.11.mlp.gate_proj",
+        "language_model.model.layers.11.mlp.up_proj",
+        "language_model.model.layers.11.mlp.down_proj",
+        "language_model.model.layers.12.self_attn.q_proj",
+        "language_model.model.layers.12.self_attn.k_proj",
+        "language_model.model.layers.12.self_attn.v_proj",
+        "language_model.model.layers.12.self_attn.o_proj",
+        "language_model.model.layers.12.mlp.gate_proj",
+        "language_model.model.layers.12.mlp.up_proj",
+        "language_model.model.layers.12.mlp.down_proj",
+        "language_model.model.layers.13.self_attn.q_proj",
+        "language_model.model.layers.13.self_attn.k_proj",
+        "language_model.model.layers.13.self_attn.v_proj",
+        "language_model.model.layers.13.self_attn.o_proj",
+        "language_model.model.layers.13.mlp.gate_proj",
+        "language_model.model.layers.13.mlp.up_proj",
+        "language_model.model.layers.13.mlp.down_proj",
+        "language_model.model.layers.14.self_attn.q_proj",
+        "language_model.model.layers.14.self_attn.k_proj",
+        "language_model.model.layers.14.self_attn.v_proj",
+        "language_model.model.layers.14.self_attn.o_proj",
+        "language_model.model.layers.14.mlp.gate_proj",
+        "language_model.model.layers.14.mlp.up_proj",
+        "language_model.model.layers.14.mlp.down_proj",
+        "language_model.model.layers.15.self_attn.q_proj",
+        "language_model.model.layers.15.self_attn.k_proj",
+        "language_model.model.layers.15.self_attn.v_proj",
+        "language_model.model.layers.15.self_attn.o_proj",
+        "language_model.model.layers.15.mlp.gate_proj",
+        "language_model.model.layers.15.mlp.up_proj",
+        "language_model.model.layers.15.mlp.down_proj",
+        "language_model.model.layers.16.self_attn.q_proj",
+        "language_model.model.layers.16.self_attn.k_proj",
+        "language_model.model.layers.16.self_attn.v_proj",
+        "language_model.model.layers.16.self_attn.o_proj",
+        "language_model.model.layers.16.mlp.gate_proj",
+        "language_model.model.layers.16.mlp.up_proj",
+        "language_model.model.layers.16.mlp.down_proj",
+        "language_model.model.layers.17.self_attn.q_proj",
+        "language_model.model.layers.17.self_attn.k_proj",
+        "language_model.model.layers.17.self_attn.v_proj",
+        "language_model.model.layers.17.self_attn.o_proj",
+        "language_model.model.layers.17.mlp.gate_proj",
+        "language_model.model.layers.17.mlp.up_proj",
+        "language_model.model.layers.17.mlp.down_proj",
+        "language_model.model.layers.18.self_attn.q_proj",
+        "language_model.model.layers.18.self_attn.k_proj",
+        "language_model.model.layers.18.self_attn.v_proj",
+        "language_model.model.layers.18.self_attn.o_proj",
+        "language_model.model.layers.18.mlp.gate_proj",
+        "language_model.model.layers.18.mlp.up_proj",
+        "language_model.model.layers.18.mlp.down_proj",
+        "language_model.model.layers.19.self_attn.q_proj",
+        "language_model.model.layers.19.self_attn.k_proj",
+        "language_model.model.layers.19.self_attn.v_proj",
+        "language_model.model.layers.19.self_attn.o_proj",
+        "language_model.model.layers.19.mlp.gate_proj",
+        "language_model.model.layers.19.mlp.up_proj",
+        "language_model.model.layers.19.mlp.down_proj",
+        "language_model.model.layers.20.self_attn.q_proj",
+        "language_model.model.layers.20.self_attn.k_proj",
+        "language_model.model.layers.20.self_attn.v_proj",
+        "language_model.model.layers.20.self_attn.o_proj",
+        "language_model.model.layers.20.mlp.gate_proj",
+        "language_model.model.layers.20.mlp.up_proj",
+        "language_model.model.layers.20.mlp.down_proj",
+        "language_model.model.layers.21.self_attn.q_proj",
+        "language_model.model.layers.21.self_attn.k_proj",
+        "language_model.model.layers.21.self_attn.v_proj",
+        "language_model.model.layers.21.self_attn.o_proj",
+        "language_model.model.layers.21.mlp.gate_proj",
+        "language_model.model.layers.21.mlp.up_proj",
+        "language_model.model.layers.21.mlp.down_proj",
+        "language_model.model.layers.22.self_attn.q_proj",
+        "language_model.model.layers.22.self_attn.k_proj",
+        "language_model.model.layers.22.self_attn.v_proj",
+        "language_model.model.layers.22.self_attn.o_proj",
+        "language_model.model.layers.22.mlp.gate_proj",
+        "language_model.model.layers.22.mlp.up_proj",
+        "language_model.model.layers.22.mlp.down_proj",
+        "language_model.model.layers.23.self_attn.q_proj",
+        "language_model.model.layers.23.self_attn.k_proj",
+        "language_model.model.layers.23.self_attn.v_proj",
+        "language_model.model.layers.23.self_attn.o_proj",
+        "language_model.model.layers.23.mlp.gate_proj",
+        "language_model.model.layers.23.mlp.up_proj",
+        "language_model.model.layers.23.mlp.down_proj",
+        "language_model.model.layers.24.self_attn.q_proj",
+        "language_model.model.layers.24.self_attn.k_proj",
+        "language_model.model.layers.24.self_attn.v_proj",
+        "language_model.model.layers.24.self_attn.o_proj",
+        "language_model.model.layers.24.mlp.gate_proj",
+        "language_model.model.layers.24.mlp.up_proj",
+        "language_model.model.layers.24.mlp.down_proj",
+        "language_model.model.layers.25.self_attn.q_proj",
+        "language_model.model.layers.25.self_attn.k_proj",
+        "language_model.model.layers.25.self_attn.v_proj",
+        "language_model.model.layers.25.self_attn.o_proj",
+        "language_model.model.layers.25.mlp.gate_proj",
+        "language_model.model.layers.25.mlp.up_proj",
+        "language_model.model.layers.25.mlp.down_proj",
+        "language_model.model.layers.26.self_attn.q_proj",
+        "language_model.model.layers.26.self_attn.k_proj",
+        "language_model.model.layers.26.self_attn.v_proj",
+        "language_model.model.layers.26.self_attn.o_proj",
+        "language_model.model.layers.26.mlp.gate_proj",
+        "language_model.model.layers.26.mlp.up_proj",
+        "language_model.model.layers.26.mlp.down_proj",
+        "language_model.model.layers.27.self_attn.q_proj",
+        "language_model.model.layers.27.self_attn.k_proj",
+        "language_model.model.layers.27.self_attn.v_proj",
+        "language_model.model.layers.27.self_attn.o_proj",
+        "language_model.model.layers.27.mlp.gate_proj",
+        "language_model.model.layers.27.mlp.up_proj",
+        "language_model.model.layers.27.mlp.down_proj",
+        "language_model.model.layers.28.self_attn.q_proj",
+        "language_model.model.layers.28.self_attn.k_proj",
+        "language_model.model.layers.28.self_attn.v_proj",
+        "language_model.model.layers.28.self_attn.o_proj",
+        "language_model.model.layers.28.mlp.gate_proj",
+        "language_model.model.layers.28.mlp.up_proj",
+        "language_model.model.layers.28.mlp.down_proj",
+        "language_model.model.layers.29.self_attn.q_proj",
+        "language_model.model.layers.29.self_attn.k_proj",
+        "language_model.model.layers.29.self_attn.v_proj",
+        "language_model.model.layers.29.self_attn.o_proj",
+        "language_model.model.layers.29.mlp.gate_proj",
+        "language_model.model.layers.29.mlp.up_proj",
+        "language_model.model.layers.29.mlp.down_proj",
+        "language_model.model.layers.30.self_attn.q_proj",
+        "language_model.model.layers.30.self_attn.k_proj",
+        "language_model.model.layers.30.self_attn.v_proj",
+        "language_model.model.layers.30.self_attn.o_proj",
+        "language_model.model.layers.30.mlp.gate_proj",
+        "language_model.model.layers.30.mlp.up_proj",
+        "language_model.model.layers.30.mlp.down_proj",
+        "language_model.model.layers.31.self_attn.q_proj",
+        "language_model.model.layers.31.self_attn.k_proj",
+        "language_model.model.layers.31.self_attn.v_proj",
+        "language_model.model.layers.31.self_attn.o_proj",
+        "language_model.model.layers.31.mlp.gate_proj",
+        "language_model.model.layers.31.mlp.up_proj",
+        "language_model.model.layers.31.mlp.down_proj",
+        "language_model.model.layers.32.self_attn.q_proj",
+        "language_model.model.layers.32.self_attn.k_proj",
+        "language_model.model.layers.32.self_attn.v_proj",
+        "language_model.model.layers.32.self_attn.o_proj",
+        "language_model.model.layers.32.mlp.gate_proj",
+        "language_model.model.layers.32.mlp.up_proj",
+        "language_model.model.layers.32.mlp.down_proj",
+        "language_model.model.layers.33.self_attn.q_proj",
+        "language_model.model.layers.33.self_attn.k_proj",
+        "language_model.model.layers.33.self_attn.v_proj",
+        "language_model.model.layers.33.self_attn.o_proj",
+        "language_model.model.layers.33.mlp.gate_proj",
+        "language_model.model.layers.33.mlp.up_proj",
+        "language_model.model.layers.33.mlp.down_proj",
+        "language_model.model.layers.34.self_attn.q_proj",
+        "language_model.model.layers.34.self_attn.k_proj",
+        "language_model.model.layers.34.self_attn.v_proj",
+        "language_model.model.layers.34.self_attn.o_proj",
+        "language_model.model.layers.34.mlp.gate_proj",
+        "language_model.model.layers.34.mlp.up_proj",
+        "language_model.model.layers.34.mlp.down_proj",
+        "language_model.model.layers.35.self_attn.q_proj",
+        "language_model.model.layers.35.self_attn.k_proj",
+        "language_model.model.layers.35.self_attn.v_proj",
+        "language_model.model.layers.35.self_attn.o_proj",
+        "language_model.model.layers.35.mlp.gate_proj",
+        "language_model.model.layers.35.mlp.up_proj",
+        "language_model.model.layers.35.mlp.down_proj"
+      ],
+      "tensor_bytes": 11022590432,
+      "tensors": 1254,
+      "exact_roundtrip": true
+    },
+    "vae": {
+      "quantized_modules": [],
+      "tensor_bytes": 1350961616,
+      "tensors": 238,
+      "exact_roundtrip": true
+    }
+  },
+  "source_audit_sha256": "149b336e13a8dc556e1b8992fc333e0e844eb3dbe58fb7346c6f58aea95023f3",
+  "status": "converted_and_roundtrip_verified",
+  "seconds": 28.819035249995068
+}

evaluation/cache-parity-8bit.json

@@ -0,0 +1,21 @@
+{
+  "model": "models/Image21-MLX-8bit",
+  "passed": true,
+  "rows": [
+    {
+      "timestep": 0.7,
+      "max_abs_error": 0.0,
+      "relative_rmse": 0.0,
+      "uncached_seconds": 2.1813871250487864,
+      "cached_seconds": 2.0793312090681866
+    },
+    {
+      "timestep": 0.3,
+      "max_abs_error": 0.0,
+      "relative_rmse": 0.0,
+      "uncached_seconds": 2.1828467500163242,
+      "cached_seconds": 1.9954760000109673
+    }
+  ],
+  "note": "Real transformer with synthetic conditioning/latents; BF16 numerical tolerance, not pixel equality."
+}

evaluation/cache-parity-bf16.json

@@ -0,0 +1,21 @@
+{
+  "model": "models/Image21-MLX-bf16",
+  "passed": true,
+  "rows": [
+    {
+      "timestep": 0.7,
+      "max_abs_error": 0.0,
+      "relative_rmse": 0.0,
+      "uncached_seconds": 2.253576749935746,
+      "cached_seconds": 1.9403239579405636
+    },
+    {
+      "timestep": 0.3,
+      "max_abs_error": 0.0,
+      "relative_rmse": 0.0,
+      "uncached_seconds": 2.003779707942158,
+      "cached_seconds": 1.9097302500158548
+    }
+  ],
+  "note": "Real transformer with synthetic conditioning/latents; BF16 numerical tolerance, not pixel equality."
+}

evaluation/offload-parity.json

@@ -0,0 +1,47 @@
+{
+  "passed": true,
+  "size": 512,
+  "steps": 2,
+  "rows": [
+    {
+      "case": "portrait",
+      "identical_png": true,
+      "resident_peak_gib": 23.64565789140761,
+      "phased_peak_gib": 10.36156104132533,
+      "precision": "8bit"
+    },
+    {
+      "case": "rgba",
+      "identical_png": true,
+      "resident_peak_gib": 23.64657341875136,
+      "phased_peak_gib": 10.389103142544627,
+      "precision": "8bit"
+    },
+    {
+      "case": "edit",
+      "identical_png": true,
+      "resident_peak_gib": 23.646100413054228,
+      "phased_peak_gib": 11.152842032723129,
+      "precision": "8bit"
+    },
+    {
+      "case": "portrait",
+      "precision": "bf16",
+      "identical_png": true,
+      "resident_peak_gib": 35.80386101640761,
+      "phased_peak_gib": 16.414859991520643
+    }
+  ],
+  "note": "PNG SHA256 identical in all four resident-versus-phase checks. Short smoke checks are not quality benchmarks.",
+  "full_resolution_check": {
+    "case": "portrait",
+    "precision": "bf16",
+    "size": 1024,
+    "steps": 40,
+    "identical_png": true,
+    "png_sha256": "72493104ac6662f1de9e7857e8ec03f4f3971c31c4ea77207d33ae029a3a0c41",
+    "resident_peak_gib": 45.77874500118196,
+    "phased_peak_gib": 16.41486000828445,
+    "note": "Resident timing excluded because it belonged to the earlier memory-pressure diagnostic."
+  }
+}

evaluation/precision-probe.json

@@ -0,0 +1,483 @@
+{
+  "group_size": 64,
+  "mode": "affine",
+  "device": {
+    "device_name": "Apple M4 Max",
+    "max_recommended_working_set_size": 115448725504,
+    "memory_size": 137438953472,
+    "architecture": "applegpu_g16s",
+    "max_buffer_length": 86586540032,
+    "resource_limit": 499000
+  },
+  "results": [
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.0.attn.to_q.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.09608591347932816,
+      "synthetic_matmul_relative_rmse": 0.09557931870222092,
+      "matmul_ms": 0.5911250016652048
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.0.attn.to_q.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.02344648726284504,
+      "synthetic_matmul_relative_rmse": 0.023693682625889778,
+      "matmul_ms": 0.4109000088647008
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.0.attn.to_q.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.007525453343987465,
+      "synthetic_matmul_relative_rmse": 0.008602947928011417,
+      "matmul_ms": 0.4843916976824403
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.0.img_mlp.out.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.09441296756267548,
+      "synthetic_matmul_relative_rmse": 0.09449099004268646,
+      "matmul_ms": 0.4845582996495068
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.0.img_mlp.out.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.02303435653448105,
+      "synthetic_matmul_relative_rmse": 0.02340426668524742,
+      "matmul_ms": 0.46681660460308194
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.0.img_mlp.out.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.007468077354133129,
+      "synthetic_matmul_relative_rmse": 0.008637943305075169,
+      "matmul_ms": 0.36163330078125
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.15.attn.to_q.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.09535665810108185,
+      "synthetic_matmul_relative_rmse": 0.09527087211608887,
+      "matmul_ms": 0.57477499358356
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.15.attn.to_q.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.02322564087808132,
+      "synthetic_matmul_relative_rmse": 0.023668956011533737,
+      "matmul_ms": 0.4584625014103949
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.15.attn.to_q.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.0074961441569030285,
+      "synthetic_matmul_relative_rmse": 0.008681540377438068,
+      "matmul_ms": 0.533016596455127
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.15.img_mlp.out.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.09448622912168503,
+      "synthetic_matmul_relative_rmse": 0.09489456564188004,
+      "matmul_ms": 0.9572708979249
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.15.img_mlp.out.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.02305353432893753,
+      "synthetic_matmul_relative_rmse": 0.02346830628812313,
+      "matmul_ms": 0.645641703158617
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.15.img_mlp.out.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.007503869011998177,
+      "synthetic_matmul_relative_rmse": 0.00874588917940855,
+      "matmul_ms": 0.6554292049258947
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.31.attn.to_q.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.09847480803728104,
+      "synthetic_matmul_relative_rmse": 0.0985177680850029,
+      "matmul_ms": 0.5378333968110383
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.31.attn.to_q.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.0240206029266119,
+      "synthetic_matmul_relative_rmse": 0.024259869009256363,
+      "matmul_ms": 0.5431666970252991
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.31.attn.to_q.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.007802714128047228,
+      "synthetic_matmul_relative_rmse": 0.008978405967354774,
+      "matmul_ms": 0.5484999972395599
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.31.img_mlp.out.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.09683173894882202,
+      "synthetic_matmul_relative_rmse": 0.09696819633245468,
+      "matmul_ms": 0.9709125035442412
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.31.img_mlp.out.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.023639416322112083,
+      "synthetic_matmul_relative_rmse": 0.0238750372081995,
+      "matmul_ms": 0.3942042007111013
+    },
+    {
+      "component": "transformer",
+      "tensor": "transformer_blocks.31.img_mlp.out.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.007727540098130703,
+      "synthetic_matmul_relative_rmse": 0.008899149484932423,
+      "matmul_ms": 0.4157708026468754
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.0.mlp.down_proj.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.09275667369365692,
+      "synthetic_matmul_relative_rmse": 0.09330281615257263,
+      "matmul_ms": 0.4116749973036349
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.0.mlp.down_proj.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.022620145231485367,
+      "synthetic_matmul_relative_rmse": 0.022967973724007607,
+      "matmul_ms": 0.3953375038690865
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.0.mlp.down_proj.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.0073314751498401165,
+      "synthetic_matmul_relative_rmse": 0.008502925746142864,
+      "matmul_ms": 0.40935829747468233
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.0.self_attn.q_proj.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.09217474609613419,
+      "synthetic_matmul_relative_rmse": 0.09356217831373215,
+      "matmul_ms": 0.28917910531163216
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.0.self_attn.q_proj.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.022505931556224823,
+      "synthetic_matmul_relative_rmse": 0.02307399921119213,
+      "matmul_ms": 0.2340042032301426
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.0.self_attn.q_proj.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.007364622782915831,
+      "synthetic_matmul_relative_rmse": 0.008642347529530525,
+      "matmul_ms": 0.23023750400170684
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.17.mlp.down_proj.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.0940268263220787,
+      "synthetic_matmul_relative_rmse": 0.09416663646697998,
+      "matmul_ms": 0.7600749959237874
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.17.mlp.down_proj.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.02295832335948944,
+      "synthetic_matmul_relative_rmse": 0.02339865453541279,
+      "matmul_ms": 0.3463750006631017
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.17.mlp.down_proj.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.007490983698517084,
+      "synthetic_matmul_relative_rmse": 0.00866878591477871,
+      "matmul_ms": 0.40897090220823884
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.17.self_attn.q_proj.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.09371878206729889,
+      "synthetic_matmul_relative_rmse": 0.09475100785493851,
+      "matmul_ms": 0.22580409422516823
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.17.self_attn.q_proj.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.022860271856188774,
+      "synthetic_matmul_relative_rmse": 0.02319853939116001,
+      "matmul_ms": 0.2775333006866276
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.17.self_attn.q_proj.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.007405295968055725,
+      "synthetic_matmul_relative_rmse": 0.008685958571732044,
+      "matmul_ms": 0.21041249856352806
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.35.mlp.down_proj.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.09651479870080948,
+      "synthetic_matmul_relative_rmse": 0.09677258133888245,
+      "matmul_ms": 0.8071957970969379
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.35.mlp.down_proj.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.02353922463953495,
+      "synthetic_matmul_relative_rmse": 0.02398456446826458,
+      "matmul_ms": 0.5642374977469444
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.35.mlp.down_proj.weight",
+      "source_shape": [
+        4096,
+        12288
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.0075887893326580524,
+      "synthetic_matmul_relative_rmse": 0.008758915588259697,
+      "matmul_ms": 0.5837332922965288
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.35.self_attn.q_proj.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 4,
+      "weight_relative_rmse": 0.0928456261754036,
+      "synthetic_matmul_relative_rmse": 0.09324980527162552,
+      "matmul_ms": 0.344270805362612
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.35.self_attn.q_proj.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 6,
+      "weight_relative_rmse": 0.022607337683439255,
+      "synthetic_matmul_relative_rmse": 0.02301245927810669,
+      "matmul_ms": 0.24173329584300518
+    },
+    {
+      "component": "text_encoder",
+      "tensor": "model.language_model.layers.35.self_attn.q_proj.weight",
+      "source_shape": [
+        4096,
+        4096
+      ],
+      "sample_rows": 256,
+      "bits": 8,
+      "weight_relative_rmse": 0.007241594605147839,
+      "synthetic_matmul_relative_rmse": 0.008508691564202309,
+      "matmul_ms": 0.20297080045565963
+    }
+  ],
+  "limitations": "Sampled rows and synthetic inputs; not calibrated activations, image quality or end-to-end speed."
+}

evaluation/report.md

@@ -0,0 +1,37 @@
+# Image21-MLX informal evaluation
+
+One seed per case, one machine, same pinned MLX runtime. Sequential BF16-then-Q8 desktop run without repeated or interleaved trials; order, thermal state and other applications may affect timing. Pixel similarity is not a perceptual quality score; no cross-runtime parity claim.
+
+| Case | BF16 s | Q8 s | BF16 peak GiB | Q8 peak GiB | RGB PSNR dB |
+|---|---:|---:|---:|---:|---:|
+| portrait | 440.91 | 568.86 | 16.41 | 16.19 | 42.03 |
+| english_text | 464.32 | 566.88 | 16.43 | 16.20 | 19.89 |
+| chinese_text | 474.14 | 567.43 | 16.44 | 16.20 | 36.97 |
+| composition | 480.91 | 562.52 | 16.44 | 16.20 | 37.17 |
+| texture | 487.64 | 445.07 | 16.43 | 16.20 | 38.41 |
+| rgba | 485.45 | 557.30 | 16.42 | 16.20 | 29.81 |
+| edit | 606.29 | 665.00 | 18.68 | 16.20 | 51.09 |
+
+MLX peak allocated memory excludes the OS, other applications and some process allocations. It is not minimum machine RAM.
+
+Timing includes prompt encoding, phase-by-phase component loading, denoising and VAE decoding; PNG writing is excluded. The after-image RSS field is a snapshot after component release, not a peak.
+
+Existing system swap is recorded separately from per-image swap change. This desktop-session run leaves other applications open. See system-context.json and the per-model environment.json files.
+
+All editing pairs use the same BF16 portrait input. Visual findings and release limitations are in visual-review.json.
+
+![All evaluated pairs](comparison.png)
+
+## Visual review / 视觉检查
+
+逐对检查七类样本，未发现明显严重的量化退化：中英文文字均正确，杯子数量与顺序、毛衣改色及真实透明通道均保留。英文海报的字体和台灯结构有可见变化，龙贴纸的表情与细节也有变化，其余样本更接近。两种精度的人物图都比提示词要求裁得更紧，透明图均有少量接近零的背景 alpha 残留。这是助手进行的非盲法、每类单种子视觉检查，不代表无损或统计等价。
+
+Assistant inspection of all seven paired cases found no obvious severe quality regression in this small sample. English and Chinese text are correct in both precisions; cup count/order and sweater recoloring succeed; real RGBA transparency is retained. The English poster changes visibly in typeface and lamp structure, and the dragon changes expression/details. Other pairs are closer. Both portraits are cropped more tightly than requested, and both transparency samples contain slight near-zero background alpha. This is an unblinded, single-seed visual check, not evidence of lossless quantization or statistical equivalence.
+
+- **portrait**: Very close to BF16 in facial features, framing, silver hair, blue knit sweater and window light. Small local skin/hair/knit texture changes are visible, without an obvious severe degradation. Same chest-up rather than waist-up crop limitation.
+- **english_text**: Exact, legible CREATE WITH LIGHT and September 2026; no extra text. Compared with BF16 the serif typeface/underline and lamp stem/base change visibly, but both remain coherent and satisfy the prompt. This demonstrates non-identical generation, not an obvious readability regression.
+- **chinese_text**: Both Chinese lines and comma are correct and legible, matching BF16. Layout, cream backdrop and cup placement remain very close; small latte/foam texture variations are visible. No obvious text accuracy regression in this sample.
+- **composition**: Exactly three cups in the requested red/blue/yellow order and one green apple in front of the blue cup. Overall layout is very close to BF16. Minor handle/shadow geometry changes are visible; no counting or spatial-order regression.
+- **texture**: Very close to BF16: coherent bird anatomy, fine blue/orange feather detail, wet moss and droplets. Minor local texture/brightness changes without obvious smoothing or broken detail.
+- **rgba**: Full-body green dragon with orange wings and white sticker outline. Expression and surface details change visibly from BF16 while silhouette and requested content remain coherent. 60.69% of pixels have alpha exactly zero (BF16 60.47%); both have canvas-edge alpha at most 4/255. No loss of actual transparency; neither output is a perfectly binary matte.
+- **edit**: Successful red sweater recoloring with facial features, hair, pose and window background very close to the BF16 edit. Minor local texture changes; no obvious edit-consistency regression. Neither output guarantees pixel-identical preservation outside the garment.

evaluation/runtime-manifest.json

@@ -0,0 +1,18 @@
+[
+  {
+    "path": "scripts/runtime.py",
+    "sha256": "ad32ba856fddf5168d50e930204603fd2caeb016bc70fe9972d769aade6a79f4"
+  },
+  {
+    "path": "scripts/mlx_pipeline.py",
+    "sha256": "ac001b3cf8b79304fc02efd3127576a67d7b03551a6295a6fc1c2a13d032614b"
+  },
+  {
+    "path": "scripts/benchmark.py",
+    "sha256": "318e2bde9fc68fdd547c8fd32a0fb9fbe69f3cf99e62b5049240ee00754b1566"
+  },
+  {
+    "path": "requirements.lock.txt",
+    "sha256": "ec2e0402146f97b80165946f96e39374bd68aa7d54c32163e7ade178a06511c5"
+  }
+]

evaluation/source-files.json

@@ -0,0 +1,164 @@
+{
+  "revision": "b3179ad355be050328e483a9dfdd9e60cd62adfa",
+  "files": [
+    {
+      "path": "text_encoder/model-00001-of-00004.safetensors",
+      "size": 4998056552,
+      "sha256": "dde00291b5f7fb92013895310a3da0ddba78674df9f10d505d375243dc01fc6f"
+    },
+    {
+      "path": "text_encoder/model-00002-of-00004.safetensors",
+      "size": 4915962464,
+      "sha256": "9047faccc0a6d98496a52d55f27be1c94a9c259d1e283fbea0128d054a948d42"
+    },
+    {
+      "path": "text_encoder/model-00003-of-00004.safetensors",
+      "size": 4915962496,
+      "sha256": "8c54187654c0176b73ae73785bf791dc9a14c9df7fb4310083a09d42048cb57e"
+    },
+    {
+      "path": "text_encoder/model-00004-of-00004.safetensors",
+      "size": 2704357976,
+      "sha256": "5311532aaaeae3259eb6a7b2c600636be1159adf7ded35f53579f7d0e7d43cdd"
+    },
+    {
+      "path": "transformer/diffusion_pytorch_model-00001-of-00002.safetensors",
+      "size": 9968332504,
+      "sha256": "9e6bc2d641e67bf277895ea8777141044a38f3edb7101bc469b2961dd7c36b4b"
+    },
+    {
+      "path": "transformer/diffusion_pytorch_model-00002-of-00002.safetensors",
+      "size": 4261951904,
+      "sha256": "3aaf234dcbe128530479735854a346b5e3e66283b7c11db56f836bbd1c13ebaa"
+    },
+    {
+      "path": "vae/diffusion_pytorch_model.safetensors",
+      "size": 1350989512,
+      "sha256": "a07a1b7c4ee2966a1b3bdc37de9b4f983d56937e46619f709a80b6e490675417"
+    },
+    {
+      "path": "LICENSE",
+      "sha256": "8dc973f024ff95966bea25866efa443fd16776dcb1001e681e3d467ea572b28d",
+      "size": 7831
+    },
+    {
+      "path": "model_index.json",
+      "sha256": "cf1ecd104ea090855d60d8cec0895c1e9d6ee41b2f87e231b678beecd1cf7809",
+      "size": 447
+    },
+    {
+      "path": "processor/added_tokens.json",
+      "sha256": "c0284b582e14987fbd3d5a2cb2bd139084371ed9acbae488829a1c900833c680",
+      "size": 707
+    },
+    {
+      "path": "processor/chat_template.jinja",
+      "sha256": "3636d0f0bd6bef02654cdffdc447b79cb2cef8ab02cc75267345946291a489e4",
+      "size": 5292
+    },
+    {
+      "path": "processor/merges.txt",
+      "sha256": "8831e4f1a044471340f7c0a83d7bd71306a5b867e95fd870f74d0c5308a904d5",
+      "size": 1671853
+    },
+    {
+      "path": "processor/preprocessor_config.json",
+      "sha256": "93585062a80db5e8ca038efc7726a3e6411d9db948472d81d63c6303993be8c5",
+      "size": 782
+    },
+    {
+      "path": "processor/special_tokens_map.json",
+      "sha256": "76862e765266b85aa9459767e33cbaf13970f327a0e88d1c65846c2ddd3a1ecd",
+      "size": 613
+    },
+    {
+      "path": "processor/tokenizer.json",
+      "sha256": "aeb13307a71acd8fe81861d94ad54ab689df773318809eed3cbe794b4492dae4",
+      "size": 11422654
+    },
+    {
+      "path": "processor/tokenizer_config.json",
+      "sha256": "81ec7bb9530159b326c0bef1d0b6c33d392090524014ea3f0123a3c1eb9c2af5",
+      "size": 5445
+    },
+    {
+      "path": "processor/video_preprocessor_config.json",
+      "sha256": "59c5c9eb52182eb14c06ffb10ca9effd29adce5f238a95de23ca14a38dbd2cb1",
+      "size": 817
+    },
+    {
+      "path": "processor/vocab.json",
+      "sha256": "ca10d7e9fb3ed18575dd1e277a2579c16d108e32f27439684afa0e10b1440910",
+      "size": 2776833
+    },
+    {
+      "path": "scheduler/scheduler_config.json",
+      "sha256": "5895f3a167c14a967fe9ac70c64924ae5acc79799e0679fd12907e594a713cd1",
+      "size": 485
+    },
+    {
+      "path": "text_encoder/config.json",
+      "sha256": "6001331949f7f86ab6d791a80b12246d4f8da5159fa08c3e62368a39f36d63a9",
+      "size": 1517
+    },
+    {
+      "path": "text_encoder/generation_config.json",
+      "sha256": "4d9818c3d27895c0058828a5f68bc7a4de80c3ae1bcdac90936ce24178063f59",
+      "size": 213
+    },
+    {
+      "path": "text_encoder/model.safetensors.index.json",
+      "sha256": "859146bff8db1d617fca8b457a5223edff963bb70076b3645f2189fe0540a147",
+      "size": 67795
+    },
+    {
+      "path": "transformer/config.json",
+      "sha256": "56ae3281c4e6c2d1aa3658252d187488071815fd79bef15808bb0205fc1a2241",
+      "size": 370
+    },
+    {
+      "path": "transformer/diffusion_pytorch_model.safetensors.index.json",
+      "sha256": "17987f6623b1c814d0ef55a137d99142b7b3b040eb1bf241b5575dd35af803a2",
+      "size": 30283
+    },
+    {
+      "path": "vae/config.json",
+      "sha256": "9785d527b278cb8b210e9f48a8028d92a4190968ce7e24c8fc85d9d1b82f6ba2",
+      "size": 2079
+    }
+  ],
+  "inventory": {
+    "transformer": {
+      "parameters": 7115124736,
+      "quantizable_parameters": 6979321856,
+      "tensor_bytes": 14230249472,
+      "dtypes": [
+        "BF16"
+      ]
+    },
+    "text_encoder": {
+      "parameters": 8767123696,
+      "quantizable_parameters": 6945767424,
+      "tensor_bytes": 17534247392,
+      "dtypes": [
+        "BF16"
+      ]
+    },
+    "vae": {
+      "parameters": 337740404,
+      "quantizable_parameters": 0,
+      "tensor_bytes": 1350961616,
+      "dtypes": [
+        "F32"
+      ]
+    }
+  },
+  "estimated_weight_bytes": {
+    "4": 13098142640.0,
+    "6": 16579414960.0,
+    "8": 20060687280.0
+  },
+  "platform": "macOS-26.6.2-arm64-arm-64bit-Mach-O",
+  "source_model": "Qwen/Qwen-Image-2.1",
+  "note": "Public source-file hashes and precision inventory; local source directory omitted."
+}

evaluation/summary.json

@@ -0,0 +1,101 @@
+{
+  "pairs": 7,
+  "cases": 7,
+  "size": 1024,
+  "steps": 40,
+  "warmup": true,
+  "phase_offload": true,
+  "bf16_mean_seconds": 491.3783866848597,
+  "q8_mean_seconds": 561.8662204464033,
+  "bf16_t2i_mean_seconds": 472.2269847920009,
+  "q8_t2i_mean_seconds": 544.6779421319758,
+  "bf16_max_peak_gib": 18.68414589576423,
+  "q8_max_peak_gib": 16.196932649239898,
+  "rows": [
+    {
+      "case_id": "portrait",
+      "seed": 42,
+      "bf16_seconds": 440.9093492079992,
+      "q8_seconds": 568.857087665936,
+      "bf16_peak_gib": 16.41486000828445,
+      "q8_peak_gib": 16.19291958771646,
+      "bf16_swap_delta_gib": 0.0,
+      "q8_swap_delta_gib": 0.0,
+      "rgb_psnr_db": 42.02969487919134,
+      "alpha_mae": 0.011185646057128906
+    },
+    {
+      "case_id": "english_text",
+      "seed": 42,
+      "bf16_seconds": 464.31536945910193,
+      "q8_seconds": 566.884881041944,
+      "bf16_peak_gib": 16.431492125615478,
+      "q8_peak_gib": 16.196902131661773,
+      "bf16_swap_delta_gib": -0.0078125,
+      "q8_swap_delta_gib": 0.0,
+      "rgb_psnr_db": 19.89081080658791,
+      "alpha_mae": 0.055230140686035156
+    },
+    {
+      "case_id": "chinese_text",
+      "seed": 42,
+      "bf16_seconds": 474.137312249979,
+      "q8_seconds": 567.4320387080079,
+      "bf16_peak_gib": 16.43712263740599,
+      "q8_peak_gib": 16.196932649239898,
+      "bf16_swap_delta_gib": 0.0,
+      "q8_swap_delta_gib": -0.0078125,
+      "rgb_psnr_db": 36.96905851474672,
+      "alpha_mae": 0.007161140441894531
+    },
+    {
+      "case_id": "composition",
+      "seed": 42,
+      "bf16_seconds": 480.91022845893167,
+      "q8_seconds": 562.5225267919013,
+      "bf16_peak_gib": 16.43643598817289,
+      "q8_peak_gib": 16.196932649239898,
+      "bf16_swap_delta_gib": 0.0,
+      "q8_swap_delta_gib": 0.0,
+      "rgb_psnr_db": 37.16673614061903,
+      "alpha_mae": 0.023729324340820312
+    },
+    {
+      "case_id": "texture",
+      "seed": 42,
+      "bf16_seconds": 487.6394271670142,
+      "q8_seconds": 445.06702766695525,
+      "bf16_peak_gib": 16.425296997651458,
+      "q8_peak_gib": 16.196780061349273,
+      "bf16_swap_delta_gib": 0.0,
+      "q8_swap_delta_gib": 0.0,
+      "rgb_psnr_db": 38.407761046077326,
+      "alpha_mae": 0.021371841430664062
+    },
+    {
+      "case_id": "rgba",
+      "seed": 42,
+      "bf16_seconds": 485.45022220897954,
+      "q8_seconds": 557.3040909171104,
+      "bf16_peak_gib": 16.422336785122752,
+      "q8_peak_gib": 16.19676480256021,
+      "bf16_swap_delta_gib": 0.0,
+      "q8_swap_delta_gib": 0.0,
+      "rgb_psnr_db": 29.813264394212403,
+      "alpha_mae": 1.0648202896118164
+    },
+    {
+      "case_id": "edit",
+      "seed": 1000042,
+      "bf16_seconds": 606.2867980420124,
+      "q8_seconds": 664.995890332968,
+      "bf16_peak_gib": 18.68414589576423,
+      "q8_peak_gib": 16.196322314441204,
+      "bf16_swap_delta_gib": 0.0,
+      "q8_swap_delta_gib": 0.0,
+      "rgb_psnr_db": 51.09023795494214,
+      "alpha_mae": 0.006680488586425781
+    }
+  ],
+  "limitations": "One seed per case, one machine, same pinned MLX runtime. Sequential BF16-then-Q8 desktop run without repeated or interleaved trials; order, thermal state and other applications may affect timing. Pixel similarity is not a perceptual quality score; no cross-runtime parity claim."
+}

evaluation/system-context.json

@@ -0,0 +1,14 @@
+{
+  "power": "AC",
+  "low_power_mode": false,
+  "thermal_warning_reported": false,
+  "other_model_service": "llama-server present, observed 0.1% CPU, approximately 15.6 GiB physical footprint",
+  "caveat": "Desktop-session benchmark; other applications remain open. Not an isolated laboratory run.",
+  "idle_sleep": "Temporarily inhibited for benchmark process only",
+  "phase_offload": true,
+  "swap_before_formal_run_gib": 19.60015869140625,
+  "swap_note": "Swap allocated during earlier resident diagnostics; per-image swap deltas are recorded separately.",
+  "other_model_services": "Other pre-existing Python and llama-server services left running; earlier physical footprints approximately 25.5 and 15.6 GiB.",
+  "mid_run_observation": "At approximately 23:35 PDT both pre-existing model services were still present and around 0.1% CPU; pmset reported no thermal or performance warning. GPU contention and thermal state were not continuously instrumented.",
+  "timing_variability": "Q8 texture was substantially faster than its preceding Q8 cases despite unchanged runtime; do not interpret the aggregate latency difference as a controlled causal estimate of quantization speed."
+}

evaluation/visual-review.json

@@ -0,0 +1,68 @@
+{
+  "approved_for_research_release": true,
+  "review_method": "Assistant visual inspection of original PNGs, followed by paired comparison; not a blinded human study.",
+  "review_date": "2026-09-26",
+  "summary_en": "Assistant inspection of all seven paired cases found no obvious severe quality regression in this small sample. English and Chinese text are correct in both precisions; cup count/order and sweater recoloring succeed; real RGBA transparency is retained. The English poster changes visibly in typeface and lamp structure, and the dragon changes expression/details. Other pairs are closer. Both portraits are cropped more tightly than requested, and both transparency samples contain slight near-zero background alpha. This is an unblinded, single-seed visual check, not evidence of lossless quantization or statistical equivalence.",
+  "summary_zh": "逐对检查七类样本，未发现明显严重的量化退化：中英文文字均正确，杯子数量与顺序、毛衣改色及真实透明通道均保留。英文海报的字体和台灯结构有可见变化，龙贴纸的表情与细节也有变化，其余样本更接近。两种精度的人物图都比提示词要求裁得更紧，透明图均有少量接近零的背景 alpha 残留。这是助手进行的非盲法、每类单种子视觉检查，不代表无损或统计等价。",
+  "results_sha256": {
+    "bf16": "2c9856ece4b83473cf884aa37c7a55be9cec3a52df31920e6a41b6e07418657d",
+    "8bit": "742a088a5e0d30a04a5f8b2ce6eb5ae9fa3613167fed0072227eb1bb991437ff"
+  },
+  "runtime_manifest_sha256": "ee348c543f136b162f3c285f15a66cd59fa51f8d889aad07e6e26e8e02bf39bb",
+  "cases": {
+    "portrait": {
+      "bf16": "Natural elderly face, detailed silver hair/skin and blue knit sweater, coherent window light. Crop is chest-up rather than the requested waist-up. No obvious broken facial features.",
+      "q8": "Very close to BF16 in facial features, framing, silver hair, blue knit sweater and window light. Small local skin/hair/knit texture changes are visible, without an obvious severe degradation. Same chest-up rather than waist-up crop limitation.",
+      "obvious_severe_quantization_regression": false
+    },
+    "english_text": {
+      "bf16": "Headline CREATE WITH LIGHT and subtitle September 2026 are exact and legible; no extra text. Orange desk lamp, dark blue backdrop and balanced layout match the prompt.",
+      "q8": "Exact, legible CREATE WITH LIGHT and September 2026; no extra text. Compared with BF16 the serif typeface/underline and lamp stem/base change visibly, but both remain coherent and satisfy the prompt. This demonstrates non-identical generation, not an obvious readability regression.",
+      "obvious_severe_quantization_regression": false
+    },
+    "chinese_text": {
+      "bf16": "Both requested lines 慢下来，喝杯咖啡 and 小店今日营业 are correctly rendered and legible, with the comma present. Cream background and central latte art match the prompt; no extra text.",
+      "q8": "Both Chinese lines and comma are correct and legible, matching BF16. Layout, cream backdrop and cup placement remain very close; small latte/foam texture variations are visible. No obvious text accuracy regression in this sample.",
+      "obvious_severe_quantization_regression": false
+    },
+    "composition": {
+      "bf16": "Exactly three cups, red left / blue center / yellow right, and one green apple in front of the blue cup. Soft studio shadows and gray tabletop are coherent; no text.",
+      "q8": "Exactly three cups in the requested red/blue/yellow order and one green apple in front of the blue cup. Overall layout is very close to BF16. Minor handle/shadow geometry changes are visible; no counting or spatial-order regression.",
+      "obvious_severe_quantization_regression": false
+    },
+    "texture": {
+      "bf16": "Coherent kingfisher with detailed blue feathers, orange breast, moist mossy branch and water below. Fine textures and droplets are visible, with a blurred natural background; no obvious structural failure.",
+      "q8": "Very close to BF16: coherent bird anatomy, fine blue/orange feather detail, wet moss and droplets. Minor local texture/brightness changes without obvious smoothing or broken detail.",
+      "obvious_severe_quantization_regression": false
+    },
+    "rgba": {
+      "bf16": "Full-body green cartoon dragon with small orange wings and a white sticker outline. Real transparency: 60.47% of pixels have alpha exactly zero; canvas edge alpha is at most 4/255. Minor residual near-zero background alpha is present.",
+      "q8": "Full-body green dragon with orange wings and white sticker outline. Expression and surface details change visibly from BF16 while silhouette and requested content remain coherent. 60.69% of pixels have alpha exactly zero (BF16 60.47%); both have canvas-edge alpha at most 4/255. No loss of actual transparency; neither output is a perfectly binary matte.",
+      "obvious_severe_quantization_regression": false
+    },
+    "edit": {
+      "bf16": "Sweater recolored red. Facial features, silver hair, pose, lighting and window background remain visually consistent with the input. Small local texture variations exist beyond the garment; this is not a pixel-locked masked edit.",
+      "q8": "Successful red sweater recoloring with facial features, hair, pose and window background very close to the BF16 edit. Minor local texture changes; no obvious edit-consistency regression. Neither output guarantees pixel-identical preservation outside the garment.",
+      "obvious_severe_quantization_regression": false
+    }
+  },
+  "alpha_checks": {
+    "bf16": {
+      "zero_fraction": 0.6047077178955078,
+      "near_zero_fraction": 0.6159038543701172,
+      "opaque_fraction": 0.3482656478881836,
+      "edge_max": 4
+    },
+    "8bit": {
+      "zero_fraction": 0.6069240570068359,
+      "near_zero_fraction": 0.6179990768432617,
+      "opaque_fraction": 0.3452177047729492,
+      "edge_max": 4
+    }
+  },
+  "limitations": [
+    "One seed per case and one machine; no blinded human panel or statistical quality benchmark.",
+    "No CUDA/MLX cross-runtime equivalence claim.",
+    "Long prompts, 2048px, multiple-reference stress tests and smaller-memory Macs were not evaluated."
+  ]
+}

model_index.json

@@ -0,0 +1,24 @@
+{
+  "_class_name": "QwenImage21Pipeline",
+  "_diffusers_version": "0.37.0.dev0",
+  "processor": [
+    "transformers",
+    "Qwen3VLProcessor"
+  ],
+  "scheduler": [
+    "diffusers",
+    "FlowMatchEulerDiscreteScheduler"
+  ],
+  "text_encoder": [
+    "transformers",
+    "Qwen3VLForConditionalGeneration"
+  ],
+  "transformer": [
+    "diffusers",
+    "QwenImage21Transformer2DModel"
+  ],
+  "vae": [
+    "diffusers",
+    "AutoencoderKLQwenImage21"
+  ]
+}

processor/added_tokens.json

@@ -0,0 +1,28 @@
+{
+  "</think>": 151668,
+  "</tool_call>": 151658,
+  "</tool_response>": 151666,
+  "<think>": 151667,
+  "<tool_call>": 151657,
+  "<tool_response>": 151665,
+  "<|box_end|>": 151649,
+  "<|box_start|>": 151648,
+  "<|endoftext|>": 151643,
+  "<|file_sep|>": 151664,
+  "<|fim_middle|>": 151660,
+  "<|fim_pad|>": 151662,
+  "<|fim_prefix|>": 151659,
+  "<|fim_suffix|>": 151661,
+  "<|im_end|>": 151645,
+  "<|im_start|>": 151644,
+  "<|image_pad|>": 151655,
+  "<|object_ref_end|>": 151647,
+  "<|object_ref_start|>": 151646,
+  "<|quad_end|>": 151651,
+  "<|quad_start|>": 151650,
+  "<|repo_name|>": 151663,
+  "<|video_pad|>": 151656,
+  "<|vision_end|>": 151653,
+  "<|vision_pad|>": 151654,
+  "<|vision_start|>": 151652
+}

processor/chat_template.jinja

@@ -0,0 +1,120 @@
+{%- if tools %}
+    {{- '<|im_start|>system\n' }}
+    {%- if messages[0].role == 'system' %}
+        {%- if messages[0].content is string %}
+            {{- messages[0].content }}
+        {%- else %}
+            {%- for content in messages[0].content %}
+                {%- if 'text' in content %}
+                    {{- content.text }}
+                {%- endif %}
+            {%- endfor %}
+        {%- endif %}
+        {{- '\n\n' }}
+    {%- endif %}
+    {{- "# 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>" }}
+    {%- for tool in tools %}
+        {{- "\n" }}
+        {{- tool | tojson }}
+    {%- endfor %}
+    {{- "\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" }}
+{%- else %}
+    {%- if messages[0].role == 'system' %}
+        {{- '<|im_start|>system\n' }}
+        {%- if messages[0].content is string %}
+            {{- messages[0].content }}
+        {%- else %}
+            {%- for content in messages[0].content %}
+                {%- if 'text' in content %}
+                    {{- content.text }}
+                {%- endif %}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- endif %}
+{%- endif %}
+{%- set image_count = namespace(value=0) %}
+{%- set video_count = namespace(value=0) %}
+{%- for message in messages %}
+    {%- if message.role == "user" %}
+        {{- '<|im_start|>' + message.role + '\n' }}
+        {%- if message.content is string %}
+            {{- message.content }}
+        {%- else %}
+            {%- for content in message.content %}
+                {%- if content.type == 'image' or 'image' in content or 'image_url' in content %}
+                    {%- set image_count.value = image_count.value + 1 %}
+                    {%- if add_vision_id %}Picture {{ image_count.value }}: {% endif -%}
+                    <|vision_start|><|image_pad|><|vision_end|>
+                {%- elif content.type == 'video' or 'video' in content %}
+                    {%- set video_count.value = video_count.value + 1 %}
+                    {%- if add_vision_id %}Video {{ video_count.value }}: {% endif -%}
+                    <|vision_start|><|video_pad|><|vision_end|>
+                {%- elif 'text' in content %}
+                    {{- content.text }}
+                {%- endif %}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- elif message.role == "assistant" %}
+        {{- '<|im_start|>' + message.role + '\n' }}
+        {%- if message.content is string %}
+            {{- message.content }}
+        {%- else %}
+            {%- for content_item in message.content %}
+                {%- if 'text' in content_item %}
+                    {{- content_item.text }}
+                {%- endif %}
+            {%- endfor %}
+        {%- endif %}
+        {%- if message.tool_calls %}
+            {%- for tool_call in message.tool_calls %}
+                {%- if (loop.first and message.content) or (not loop.first) %}
+                    {{- '\n' }}
+                {%- endif %}
+                {%- if tool_call.function %}
+                    {%- set tool_call = tool_call.function %}
+                {%- endif %}
+                {{- '<tool_call>\n{"name": "' }}
+                {{- tool_call.name }}
+                {{- '", "arguments": ' }}
+                {%- if tool_call.arguments is string %}
+                    {{- tool_call.arguments }}
+                {%- else %}
+                    {{- tool_call.arguments | tojson }}
+                {%- endif %}
+                {{- '}\n</tool_call>' }}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- elif message.role == "tool" %}
+        {%- if loop.first or (messages[loop.index0 - 1].role != "tool") %}
+            {{- '<|im_start|>user' }}
+        {%- endif %}
+        {{- '\n<tool_response>\n' }}
+        {%- if message.content is string %}
+            {{- message.content }}
+        {%- else %}
+            {%- for content in message.content %}
+                {%- if content.type == 'image' or 'image' in content or 'image_url' in content %}
+                    {%- set image_count.value = image_count.value + 1 %}
+                    {%- if add_vision_id %}Picture {{ image_count.value }}: {% endif -%}
+                    <|vision_start|><|image_pad|><|vision_end|>
+                {%- elif content.type == 'video' or 'video' in content %}
+                    {%- set video_count.value = video_count.value + 1 %}
+                    {%- if add_vision_id %}Video {{ video_count.value }}: {% endif -%}
+                    <|vision_start|><|video_pad|><|vision_end|>
+                {%- elif 'text' in content %}
+                    {{- content.text }}
+                {%- endif %}
+            {%- endfor %}
+        {%- endif %}
+        {{- '\n</tool_response>' }}
+        {%- if loop.last or (messages[loop.index0 + 1].role != "tool") %}
+            {{- '<|im_end|>\n' }}
+        {%- endif %}
+    {%- endif %}
+{%- endfor %}
+{%- if add_generation_prompt %}
+    {{- '<|im_start|>assistant\n' }}
+{%- endif %}

processor/preprocessor_config.json

@@ -0,0 +1,39 @@
+{
+  "crop_size": null,
+  "data_format": "channels_first",
+  "default_to_square": true,
+  "device": null,
+  "disable_grouping": null,
+  "do_center_crop": null,
+  "do_convert_rgb": true,
+  "do_normalize": true,
+  "do_pad": null,
+  "do_rescale": true,
+  "do_resize": true,
+  "image_mean": [
+    0.5,
+    0.5,
+    0.5
+  ],
+  "image_processor_type": "Qwen2VLImageProcessorFast",
+  "image_std": [
+    0.5,
+    0.5,
+    0.5
+  ],
+  "input_data_format": null,
+  "max_pixels": null,
+  "merge_size": 2,
+  "min_pixels": null,
+  "pad_size": null,
+  "patch_size": 16,
+  "processor_class": "Qwen3VLProcessor",
+  "resample": 3,
+  "rescale_factor": 0.00392156862745098,
+  "return_tensors": null,
+  "size": {
+    "longest_edge": 16777216,
+    "shortest_edge": 65536
+  },
+  "temporal_patch_size": 2
+}

processor/special_tokens_map.json

@@ -0,0 +1,31 @@
+{
+  "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|>"
+  ],
+  "eos_token": {
+    "content": "<|im_end|>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "pad_token": {
+    "content": "<|endoftext|>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  }
+}

processor/tokenizer_config.json

@@ -0,0 +1,240 @@
+{
+  "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,
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "errors": "replace",
+  "extra_special_tokens": {},
+  "model_max_length": 262144,
+  "pad_token": "<|endoftext|>",
+  "processor_class": "Qwen3VLProcessor",
+  "split_special_tokens": false,
+  "tokenizer_class": "Qwen2Tokenizer",
+  "unk_token": null
+}

processor/video_preprocessor_config.json

@@ -0,0 +1,41 @@
+{
+  "crop_size": null,
+  "data_format": "channels_first",
+  "default_to_square": true,
+  "device": null,
+  "do_center_crop": null,
+  "do_convert_rgb": true,
+  "do_normalize": true,
+  "do_rescale": true,
+  "do_resize": true,
+  "do_sample_frames": true,
+  "fps": 2,
+  "image_mean": [
+    0.5,
+    0.5,
+    0.5
+  ],
+  "image_std": [
+    0.5,
+    0.5,
+    0.5
+  ],
+  "input_data_format": null,
+  "max_frames": 768,
+  "merge_size": 2,
+  "min_frames": 4,
+  "num_frames": null,
+  "pad_size": null,
+  "patch_size": 16,
+  "processor_class": "Qwen3VLProcessor",
+  "resample": 3,
+  "rescale_factor": 0.00392156862745098,
+  "return_metadata": false,
+  "size": {
+    "longest_edge": 25165824,
+    "shortest_edge": 4096
+  },
+  "temporal_patch_size": 2,
+  "video_metadata": null,
+  "video_processor_type": "Qwen3VLVideoProcessor"
+}

requirements.lock.txt

@@ -0,0 +1,59 @@
+annotated-doc==0.0.5
+annotated-types==0.8.0
+anyio==4.15.1
+certifi==2026.7.22
+cffi==2.1.1
+charset-normalizer==3.5.1
+click==8.5.0
+cryptography==50.0.1
+fastapi==0.141.1
+filelock==4.0.3
+fsspec==2026.9.0
+h11==0.16.0
+hf-xet==1.6.0
+httpcore==1.0.9
+httpx==0.28.1
+huggingface-hub==1.33.0
+idna==3.20
+jinja2==3.1.6
+llguidance==1.8.0
+markdown-it-py==4.2.0
+markupsafe==3.0.3
+mdurl==0.1.2
+miniaudio==1.71
+mlx==0.32.2
+mlx-audio==0.5.6
+mlx-metal==0.32.2
+mlx-vlm @ https://github.com/Blaizzy/mlx-vlm/archive/95b01ccad2d9f65a9e87f6a87bd1c5df69626261.zip
+modelscope==1.40.1
+modelscope-hub==0.4.5
+numpy==2.5.3
+opencv-python==5.0.0.93
+packaging==26.3
+pillow==12.3.0
+psutil==7.2.2
+pycparser==3.0
+pydantic==2.13.5
+pydantic-core==2.46.5
+pygments==2.21.0
+python-multipart==0.0.32
+pyyaml==6.0.3
+regex==2026.9.10
+requests==2.34.2
+rich==15.0.0
+safetensors==0.8.0
+scipy==1.18.1
+sentencepiece==0.2.2
+setuptools==84.0.0
+shellingham==1.5.4
+sounddevice==0.5.6
+starlette==1.7.0
+tokenizers==0.23.2
+tqdm==4.70.1
+transformers==5.17.0
+typer==0.27.2
+typing-extensions==4.16.0
+typing-inspection==0.4.4
+urllib3==2.8.0
+uvicorn==0.54.0
+websockets==17.1

requirements.txt

@@ -0,0 +1,3 @@
+mlx-vlm @ https://github.com/Blaizzy/mlx-vlm/archive/95b01ccad2d9f65a9e87f6a87bd1c5df69626261.zip
+psutil>=7
+modelscope>=1.30

scheduler/scheduler_config.json

@@ -0,0 +1,18 @@
+{
+  "_class_name": "FlowMatchEulerDiscreteScheduler",
+  "_diffusers_version": "0.37.0.dev0",
+  "base_image_seq_len": 256,
+  "base_shift": 0.5,
+  "invert_sigmas": false,
+  "max_image_seq_len": 8192,
+  "max_shift": 0.9,
+  "num_train_timesteps": 1000,
+  "shift": 1.0,
+  "shift_terminal": 0.02,
+  "stochastic_sampling": false,
+  "time_shift_type": "exponential",
+  "use_beta_sigmas": false,
+  "use_dynamic_shifting": true,
+  "use_exponential_sigmas": false,
+  "use_karras_sigmas": false
+}

scripts/MLX_VLM_LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2025 Prince Canuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scripts/audit.py

@@ -0,0 +1,44 @@
+"""Verify the complete BF16 source against the saved official revision."""
+import argparse
+import json
+import platform
+import subprocess
+from pathlib import Path
+from scripts.common import SOURCE, REVISION, inventory, sha256, write_json
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--source', type=Path, default=SOURCE)
+    ap.add_argument('--output', type=Path, default=Path('artifacts/source-audit.json'))
+    ap.add_argument('--manifest', type=Path, help='Published evaluation/source-files.json for a portable rebuild')
+    args = ap.parse_args()
+    if args.manifest:
+        info=json.loads(args.manifest.read_text())
+        if info['revision']!=REVISION: raise ValueError('Unexpected source revision')
+        rows=info['files']
+    else:
+        info = json.loads(Path('artifacts/upstream/source-model-info.json').read_text())
+        if info['sha'] != REVISION:
+            raise ValueError('Unexpected source revision')
+        rows = [{'path': x['rfilename'], 'size': x['size'], 'sha256': x['lfs']['sha256']}
+                for x in info['siblings'] if x['rfilename'].endswith('.safetensors')]
+        rows += [r for r in json.loads(Path('artifacts/upstream/source-config-manifest.json').read_text())
+                 if r['path'] not in ('.gitattributes', 'README.md')]
+    for row in rows:
+        file = args.source / row['path']
+        if file.stat().st_size != row['size'] or sha256(file) != row['sha256']:
+            raise ValueError(f'Source mismatch: {file}')
+        print('Verified', row['path'], flush=True)
+    inv = inventory(args.source)
+    estimates = {}
+    for bits in (4, 6, 8):
+        estimates[str(bits)] = sum(v['tensor_bytes'] - v['quantizable_parameters'] * 2 +
+                                   v['quantizable_parameters'] * (bits / 8 + 4 / 64)
+                                   for v in inv.values())
+    write_json(args.output, dict(source=str(args.source), revision=REVISION, files=rows,
+                                inventory=inv, estimated_weight_bytes=estimates,
+                                platform=platform.platform()))
+    print(json.dumps(dict(inventory=inv, estimated_weight_GiB={k:v/2**30 for k,v in estimates.items()}),indent=2))
+
+if __name__ == '__main__':
+    main()

scripts/benchmark.py

@@ -0,0 +1,85 @@
+"""Paired 1024px evaluation, separate processes per precision, unchanged RGBA samples."""
+import argparse
+import gc
+import importlib.metadata
+import json
+import platform
+import time
+from pathlib import Path
+import mlx.core as mx
+import numpy as np
+import psutil
+from scripts.common import sha256, write_json
+from scripts.runtime import load, generate, enable_progress
+
+def main():
+    ap=argparse.ArgumentParser()
+    ap.add_argument('--model',type=Path,required=True)
+    ap.add_argument('--output',type=Path,required=True)
+    ap.add_argument('--cases',type=Path,default=Path('benchmarks/cases.json'))
+    ap.add_argument('--only',nargs='+')
+    ap.add_argument('--seeds',nargs='+',type=int,default=[42])
+    ap.add_argument('--steps',type=int,default=40)
+    ap.add_argument('--size',type=int,default=1024)
+    ap.add_argument('--edit-input',type=Path)
+    ap.add_argument('--no-warmup',action='store_true')
+    ap.add_argument('--resident',action='store_true',help='Diagnostic mode: keep all components resident')
+    args=ap.parse_args()
+    if args.output.exists(): raise FileExistsError(args.output)
+    cases=json.loads(args.cases.read_text())
+    if args.only: cases=[x for x in cases if x['id'] in args.only]
+    if not cases: raise ValueError('No cases selected')
+    args.output.mkdir(parents=True)
+    env=dict(model=str(args.model.resolve()),device=mx.device_info(),platform=platform.platform(),
+             total_memory_gib=psutil.virtual_memory().total/2**30,
+             packages={p:importlib.metadata.version(p) for p in ('mlx','mlx-vlm','numpy','transformers')},
+             cases_sha256=sha256(args.cases),warmup=not args.no_warmup,
+             phase_offload=not args.resident,
+             note='MLX allocated peak is not whole-system memory or a proven minimum RAM requirement.')
+    if (args.model/'conversion.json').exists(): env['conversion']=json.loads((args.model/'conversion.json').read_text())
+    write_json(args.output/'environment.json',env)
+    enable_progress()
+    start=time.perf_counter(); pipe=load(args.model,phase_offload=not args.resident)
+    if args.resident:
+        mx.eval(pipe.transformer.parameters(),pipe.text_encoder.model.parameters(),pipe.vae.parameters())
+    load_seconds=time.perf_counter()-start
+    print(f'Pipeline ready in {load_seconds:.2f}s; phase loads are included in image timings',flush=True)
+    if not args.no_warmup:
+        print('Full untimed warm-up',flush=True)
+        generate(pipe,cases[0]['prompt'],seed=20260926,steps=args.steps,width=args.size,height=args.size)
+        mx.synchronize(); gc.collect(); mx.clear_cache()
+    for case in cases:
+        for generation_seed in args.seeds:
+            is_edit=case['id']=='edit'
+            seed=1_000_000+generation_seed if is_edit else generation_seed
+            inputs=None
+            if is_edit:
+                ref=args.edit_input or args.output/f'portrait-s{generation_seed}.png'
+                if not ref.exists(): raise FileNotFoundError(f'Provide the shared BF16 portrait: {ref}')
+                inputs=[str(ref)]
+            gc.collect(); mx.clear_cache(); mx.reset_peak_memory()
+            swap_before=psutil.swap_memory().used/2**30
+            start=time.perf_counter()
+            print(f'Running {case["id"]} seed={seed}',flush=True)
+            img=generate(pipe,case['prompt'],seed=seed,steps=args.steps,width=args.size,height=args.size,
+                         inputs=inputs,source_seed=generation_seed if is_edit else None,resolution=args.size)
+            mx.synchronize(); seconds=time.perf_counter()-start
+            name=f'{case["id"]}-s{seed}.png'; img.save(args.output/name)
+            pixels=np.asarray(img); alpha=pixels[:,:,3]
+            row=dict(case_id=case['id'],prompt=case['prompt'],seed=seed,width=args.size,height=args.size,
+                     steps=args.steps,cfg=1.0,vae_tiling=False,kv_cache=True,phase_offload=not args.resident,
+                     input_sha256=sha256(inputs[0]) if inputs else None,pipeline_init_seconds=load_seconds,
+                     seconds=seconds,mlx_peak_gib=mx.get_peak_memory()/2**30,
+                     rss_gib=psutil.Process().memory_info().rss/2**30,
+                     system_available_gib=psutil.virtual_memory().available/2**30,
+                     swap_used_gib=psutil.swap_memory().used/2**30,
+                     swap_before_gib=swap_before,swap_delta_gib=psutil.swap_memory().used/2**30-swap_before,
+                     output=name,output_sha256=sha256(args.output/name),mode=img.mode,
+                     alpha_min=int(alpha.min()),alpha_max=int(alpha.max()),
+                     alpha_fraction_below_250=float(np.mean(alpha<250)),
+                     rgb_std=float(pixels[:,:,:3].astype(np.float32).std()),warmup=not args.no_warmup)
+            with (args.output/'results.jsonl').open('a') as f: f.write(json.dumps(row,ensure_ascii=False)+'\n')
+            print(json.dumps(row,ensure_ascii=False),flush=True)
+    write_json(args.output/'COMPLETE.json',dict(cases=len(cases),seeds=args.seeds,steps=args.steps,size=args.size))
+
+if __name__=='__main__': main()

scripts/cards.py

@@ -0,0 +1,166 @@
+"""Render bilingual model cards from actual evaluation records."""
+import json
+from pathlib import Path
+
+def main():
+    summary=json.loads(Path('artifacts/eval/summary.json').read_text())
+    review=json.loads(Path('artifacts/eval/visual-review.json').read_text())
+    if review.get('approved_for_research_release') is not True:
+        raise ValueError('Complete the paired visual review before rendering release cards')
+    conversion=json.loads(Path('models/Image21-MLX-8bit/conversion.json').read_text())
+    gib=sum(x['tensor_bytes'] for x in conversion['components'].values())/2**30
+    header='''---
+license: other
+license_name: qwen-research
+license_link: LICENSE
+base_model: Qwen/Qwen-Image-2.1
+library_name: mlx
+pipeline_tag: text-to-image
+tags:
+- mlx
+- mlx-vlm
+- apple-silicon
+- quantized
+- image-to-image
+- rgba
+---
+'''
+    common=f'''
+## Reproducible inference
+
+```bash
+uv venv --python 3.13 .venv
+uv pip install --python .venv/bin/python -r requirements.lock.txt
+.venv/bin/python -m scripts.infer --model . \\
+  --prompt 'A natural portrait in soft window light' --output outputs/portrait.png
+```
+
+```bash
+.venv/bin/python -m scripts.infer --model . --input input.png \\
+  --prompt 'Change only the blue sweater to a red sweater. Preserve the person and background.' \\
+  --source-seed 42 --seed 1000042 --output outputs/edit.png
+```
+
+Transparent generation prompt:
+`This is an RGBA image with transparency. A cute cartoon dragon sticker. The image has alpha channel and the background is transparent.`
+
+## Measurements / 实测
+
+Apple M4 Max, 40 GPU cores, 128 GiB unified memory, macOS 26.6.2, MLX 0.32.2.
+Both models use the same pinned MLX runtime and internal SSD; 1024×1024, 40 steps,
+CFG=1, no VAE tiling, one full warm-up per process, seven cases, one seed per case.
+Sequential component loading is enabled in both models. Per-image time includes
+component loading, prompt encoding, denoising and VAE decoding; PNG writing is excluded.
+This is a desktop session with other applications open. BF16 ran before Q8;
+there were no repeated or interleaved trials to control order and thermal effects.
+
+| Case | BF16 seconds | 8-bit seconds | BF16 peak GiB | 8-bit peak GiB |
+|---|---:|---:|---:|---:|
+'''
+    for r in summary['rows']:
+        common+=f'| {r["case_id"]} | {r["bf16_seconds"]:.2f} | {r["q8_seconds"]:.2f} | {r["bf16_peak_gib"]:.2f} | {r["q8_peak_gib"]:.2f} |\n'
+    relative=100*(summary['q8_t2i_mean_seconds']/summary['bf16_t2i_mean_seconds']-1)
+    common+=f'\nSix-case text-to-image mean / 六类文生图平均：BF16 **{summary["bf16_t2i_mean_seconds"]/60:.2f} min**, Q8 **{summary["q8_t2i_mean_seconds"]/60:.2f} min**. Q8 generation time relative to BF16 / Q8 相对耗时：**{relative:+.1f}%** in this run.\n'
+    common+='''
+Peak figures measure MLX allocations, not minimum physical RAM. Full raw records,
+original RGBA samples and the visual review are in [evaluation](evaluation/report.md).
+These are informal measurements, not an official benchmark. The BF16 baseline is
+the same MLX implementation; cross-runtime CUDA equivalence is not claimed.
+One seed per case is insufficient to establish statistical quality equivalence.
+There is no claim of lossless quantization or a guaranteed speedup.
+
+![All seven paired samples](evaluation/comparison.png)
+
+## Provenance
+
+- Source: `Qwen/Qwen-Image-2.1@b3179ad355be050328e483a9dfdd9e60cd62adfa`.
+- Runtime: `Blaizzy/mlx-vlm@95b01ccad2d9f65a9e87f6a87bd1c5df69626261`.
+- Native MLX affine packed weights; not CUDA bitsandbytes INT8, FP8, GGUF or an MFLUX checkpoint.
+- All three components passed exact tensor round-trip verification.
+- [conversion.json](conversion.json), [modifications](CHANGES.md), [Notice](Notice), [license](LICENSE), [file hashes](MANIFEST.json).
+
+To rebuild, first download the original source snapshot at the revision above to
+`source-bf16` (requires additional disk space), then run from this repository:
+
+```bash
+.venv/bin/python -m scripts.audit --source source-bf16 --manifest evaluation/source-files.json
+.venv/bin/python -m scripts.convert --source source-bf16 --bits 8 --output rebuilt-8bit
+```
+The audit verifies the original source file hashes before conversion. Rebuilding
+uses the original floating-point weights, never a dequantized CUDA INT8 checkpoint.
+
+To repeat the paired evaluation after the source audit, create a native baseline
+and run each precision in its own process. This is a lengthy research workflow
+and needs extra memory and disk space beyond ordinary inference:
+
+```bash
+.venv/bin/python -m scripts.convert --source source-bf16 --bits 16 --output rebuilt-bf16
+.venv/bin/python -m scripts.benchmark --model rebuilt-bf16 --output artifacts/eval/bf16
+.venv/bin/python -m scripts.benchmark --model . --output artifacts/eval/8bit --edit-input artifacts/eval/bf16/portrait-s42.png
+.venv/bin/python -m scripts.report
+```
+'''
+    en=f'''# Image21-MLX-8bit
+
+**Built with Qwen.** An independent native MLX quantization of Qwen-Image-2.1 for
+Apple Silicon, by ixim / iximbox. **Non-commercial research and evaluation only**
+under the original Qwen Research License. This is not an official Qwen release.
+
+The complete checkpoint is approximately **{gib:.2f} GiB**. DiT attention/MLP and
+language-encoder attention/MLP linears use **8-bit affine weights, group size 64**,
+with BF16 activations. The full vision tower, token embeddings, language head,
+norms and DiT input/output/timestep/modulation layers retain floating-point precision.
+The VAE retains its original **FP32** weights. See the exact 476 quantized modules in conversion.json.
+
+Supports text-to-image, native reference-image editing and RGBA transparency through
+the included scripts. The wrapper preserves the sampler's alpha channel, which the
+pinned upstream text-to-image convenience method otherwise slices away.
+The runtime also enables the upstream fixed-prefix KV cache for text-to-image.
+Components are loaded and released by phase to reduce unified-memory use.
+See scripts/mlx_pipeline.py and its retained MIT attribution.
+
+With the included phase-loading runtime, plan for **32GB unified memory as a starting
+budget; 48GB or more gives more room for other applications** at 1024px with one reference.
+These are capacity estimates, not verified minimums: only the 128GB M4 Max was tested.
+The measured Q8 MLX allocation peak is about **16.20 GiB**, excluding OS/driver overhead.
+16/24GB Macs are not the target for this default 1024px configuration. 2048px and
+10-reference editing have not been benchmarked. Allow roughly **50GB free disk space**
+for ordinary inference; rebuilding also needs the original source and baseline checkpoints.
+'''
+    zh=f'''# Image21-MLX-8bit
+
+**Built with Qwen。** ixim / iximbox 基于 Qwen-Image-2.1 原始 BF16 权重制作的
+Apple Silicon 原生 MLX 量化版。**仅限非商业研究与评估**，沿用 Qwen Research License；
+本项目为独立衍生模型，不是官方发布。
+
+完整权重约 **{gib:.2f} GiB**。DiT 和文本编码器中的注意力/MLP 线性层采用
+**8-bit affine、group size 64、BF16 激活**。整个视觉编码器、词嵌入、语言输出头、
+归一化及 DiT 输入/输出、时间嵌入和 modulation 保留浮点精度；VAE 保留原始 **FP32**。
+全部 476 个量化模块详见 conversion.json。本模型从原始权重直接转换，没有从 CUDA INT8 二次量化。
+
+通过配套脚本支持文生图、参考图指令编辑和 RGBA 透明图；适配器保留原生 sampler 的 alpha，
+避免固定版本上游文生图便捷方法丢弃透明通道。
+运行时还将上游固定前缀 KV 缓存启用于文生图；完整改动与 MIT 归属保留在 scripts 中。
+配套脚本默认按阶段加载与释放组件，组件加载开销计入下表时间。
+
+使用配套分阶段加载运行时，1024px、单参考图建议按 **32GB 起、48GB 以上更有余量**规划。
+这是容量估算，未验证最低内存边界；本次只实测了 128GB M4 Max。量化版 MLX 分配峰值约
+**16.20 GiB**，还需为操作系统、驱动和其他软件留空间。16/24GB 不是默认 1024px 配置的目标。
+2048px 与十张参考图的编辑尚未测评。普通推理建议预留约 **50GB 可用磁盘**；
+重建量化与 BF16 基线还需额外存放原始及基线权重。
+
+下表为非正式、同后端、单种子对照，不能证明无损，也不能与 CUDA 时间直接横向比较。
+MLX 分配峰值不等于整机内存需求。参考图编辑共用同一张 BF16 原图，编辑种子与原图生成种子不同。
+'''
+    Path('cards').mkdir(exist_ok=True)
+    for platform,body in [('huggingface',en),('modelscope',zh)]:
+        command=(
+            'uvx --from huggingface-hub==1.33.0 hf download ixim/Image21-MLX-8bit --local-dir Image21-MLX-8bit'
+            if platform=='huggingface' else
+            'uvx --from modelscope-hub==0.4.5 modelscope download iximbox/Image21-MLX-8bit --local-dir Image21-MLX-8bit'
+        )
+        download=f'\n## Download / 下载\n\nOn an Apple Silicon Mac with [uv](https://docs.astral.sh/uv/) installed:\n\n```bash\n{command}\ncd Image21-MLX-8bit\n```\n'
+        quality='\n## Visual findings / 视觉检查\n\n'+review['summary_en' if platform=='huggingface' else 'summary_zh']+'\n'
+        Path(f'cards/{platform}.md').write_text(header+body+quality+download+common)
+
+if __name__=='__main__': main()

scripts/common.py

@@ -0,0 +1,60 @@
+"""Local, reproducible model identities and safetensors inspection."""
+import hashlib
+import json
+import math
+import struct
+from pathlib import Path
+
+SOURCE = Path('/Volumes/ZX6 1TB/Qwen-Image-2.1/models/bf16')
+REVISION = 'b3179ad355be050328e483a9dfdd9e60cd62adfa'
+RUNTIME_REVISION = '95b01ccad2d9f65a9e87f6a87bd1c5df69626261'
+NOTICE = ('Qwen is licensed under the Qwen RESEARCH LICENSE AGREEMENT, Copyright (c) 2026 '
+          'Hangzhou Tongyi Laboratory Technology Co., Ltd. All Rights Reserved.')
+MODIFICATION = ('Modified by ixim / iximbox for Image21-MLX: converted from the pinned '
+                'BF16 source to MLX layout; eligible linear weights use groupwise affine '
+                'quantization. See conversion.json for precision and exceptions. Built with Qwen.')
+
+def write_json(path, value):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(value, ensure_ascii=False, indent=2) + '\n')
+
+def sha256(path):
+    with Path(path).open('rb') as f:
+        return hashlib.file_digest(f, 'sha256').hexdigest()
+
+def header(path):
+    with Path(path).open('rb') as f:
+        length = struct.unpack('<Q', f.read(8))[0]
+        if length > 100_000_000:
+            raise ValueError('Invalid safetensors header')
+        return json.loads(f.read(length))
+
+def tensors(root):
+    for path in sorted(Path(root).glob('*.safetensors')):
+        if path.name.startswith('._'):
+            continue
+        for name, info in header(path).items():
+            if name != '__metadata__':
+                yield path, name, info
+
+def eligible(component, name, shape):
+    # Preserve all visual encoder, embeddings, norms, modulation and boundary layers.
+    if len(shape) != 2 or shape[-1] % 64 or not name.endswith('.weight'):
+        return False
+    if component == 'transformer':
+        return name.startswith('transformer_blocks.') and ('.attn.to_' in name or '.img_mlp.' in name)
+    if component == 'text_encoder':
+        return 'language_model' in name and '.layers.' in name and ('.self_attn.' in name or '.mlp.' in name)
+    return False
+
+def inventory(root):
+    result = {}
+    for component in ('transformer', 'text_encoder', 'vae'):
+        rows = list(tensors(Path(root) / component))
+        params = sum(math.prod(v['shape']) for _, _, v in rows)
+        qparams = sum(math.prod(v['shape']) for _, n, v in rows if eligible(component, n, v['shape']))
+        nbytes = sum(v['data_offsets'][1] - v['data_offsets'][0] for _, _, v in rows)
+        result[component] = dict(parameters=params, quantizable_parameters=qparams, tensor_bytes=nbytes,
+                                 dtypes=sorted({v['dtype'] for _, _, v in rows}))
+    return result

scripts/convert.py

@@ -0,0 +1,106 @@
+"""Convert verified BF16 components to a native MLX checkpoint, with round-trip checks."""
+import argparse
+import gc
+import json
+import shutil
+import time
+from pathlib import Path
+import mlx.core as mx
+import mlx.nn as nn
+from mlx.utils import tree_flatten
+from mlx_vlm.models.qwen_image.weights import load_transformer, load_text_encoder, load_vae
+from scripts.common import (SOURCE, REVISION, RUNTIME_REVISION, MODIFICATION, NOTICE,
+                            eligible, sha256, write_json)
+
+LOADERS = dict(transformer=load_transformer, text_encoder=load_text_encoder, vae=load_vae)
+
+def save_component(model, folder, config, limit=2_000_000_000):
+    folder.mkdir(parents=True)
+    weights = dict(tree_flatten(model.parameters()))
+    chunks, current, size = [], {}, 0
+    for name, value in weights.items():
+        if current and size + value.nbytes > limit:
+            chunks.append(current); current, size = {}, 0
+        current[name] = value; size += value.nbytes
+    if current: chunks.append(current)
+    index = {'metadata': {'total_size': sum(v.nbytes for v in weights.values()),
+                          'modification_notice': MODIFICATION}, 'weight_map': {}}
+    for i, chunk in enumerate(chunks,1):
+        name = f'model-{i:05d}-of-{len(chunks):05d}.safetensors'
+        mx.save_safetensors(str(folder/name), chunk,
+                           metadata={'format':'mlx', 'modification_notice':MODIFICATION,
+                                     'source_revision':REVISION})
+        index['weight_map'].update({key:name for key in chunk})
+    config['mlx_format'] = True
+    config['_modification_notice'] = MODIFICATION
+    write_json(folder/'config.json', config)
+    write_json(folder/'model.safetensors.index.json', index)
+    return weights
+
+def main():
+    ap=argparse.ArgumentParser()
+    ap.add_argument('--source',type=Path,default=SOURCE)
+    ap.add_argument('--output',type=Path,required=True)
+    ap.add_argument('--bits',type=int,choices=(4,6,8,16),default=8)
+    ap.add_argument('--audit',type=Path,default=Path('artifacts/source-audit.json'))
+    args=ap.parse_args()
+    if args.output.exists(): raise FileExistsError(f'Refusing to overwrite {args.output}')
+    audit=json.loads(args.audit.read_text())
+    if audit['revision'] != REVISION or Path(audit['source']).resolve()!=args.source.resolve():
+        raise ValueError('Source audit does not match')
+    # Audit SHA256 was computed in this workspace; reject changes since then.
+    for row in audit['files']:
+        p=args.source/row['path']
+        if p.stat().st_size != row['size'] or p.stat().st_mtime > args.audit.stat().st_mtime:
+            raise ValueError(f'Source changed since audit: {p}')
+    args.output.mkdir(parents=True)
+    report=dict(name='Image21-MLX',source_model='Qwen/Qwen-Image-2.1',source_revision=REVISION,
+                runtime_revision=RUNTIME_REVISION,method='MLX affine weight-only' if args.bits<16 else 'MLX BF16 layout conversion',bits=args.bits,
+                group_size=64,activation_dtype='bfloat16',vae_dtype='float32',components={},
+                source_audit_sha256=sha256(args.audit),status='in_progress')
+    write_json(args.output/'conversion.json',report)
+    started=time.perf_counter()
+    for component, loader in LOADERS.items():
+        print(f'Loading {component}',flush=True)
+        model=loader(args.source)
+        quantized=[]
+        if component!='vae' and args.bits<16:
+            def predicate(path, module):
+                yes=isinstance(module,nn.Linear) and eligible(component,path+'.weight',module.weight.shape)
+                if yes: quantized.append(path)
+                return yes
+            nn.quantize(model,bits=args.bits,group_size=64,mode='affine',class_predicate=predicate)
+            if not quantized: raise RuntimeError(f'No quantized modules: {component}')
+        mx.eval(model.parameters())
+        config=json.loads((args.source/component/'config.json').read_text())
+        if quantized: config['quantization']=dict(bits=args.bits,group_size=64,mode='affine')
+        expected=save_component(model,args.output/component,config)
+        print(f'Saved {component}; verifying fresh loader',flush=True)
+        restored=loader(args.output)
+        actual=dict(tree_flatten(restored.parameters()))
+        if set(expected)!=set(actual): raise ValueError(f'Reload keys differ: {component}')
+        for key,value in expected.items():
+            other=actual[key]
+            if value.dtype!=other.dtype or value.shape!=other.shape or not mx.array_equal(value,other).item():
+                raise ValueError(f'Reload mismatch: {component}/{key}')
+        report['components'][component]=dict(quantized_modules=quantized,
+                                            tensor_bytes=sum(v.nbytes for v in expected.values()),
+                                            tensors=len(expected),exact_roundtrip=True)
+        write_json(args.output/'conversion.json',report)
+        del model,restored,actual,expected
+        gc.collect(); mx.clear_cache()
+    for sub in ('processor','scheduler'):
+        shutil.copytree(args.source/sub,args.output/sub,
+                        ignore=shutil.ignore_patterns('._*','.cache','*.lock'))
+    for name in ('model_index.json','LICENSE'):
+        shutil.copy2(args.source/name,args.output/name)
+    (args.output/'Notice').write_text(NOTICE+'\n\nBuilt with Qwen\n'+MODIFICATION+'\n')
+    (args.output/'CHANGES.md').write_text('# Modifications\n\n'+MODIFICATION+'\n\n'
+        'VAE convolution layout is transposed without reducing FP32 precision. '
+        'The entire vision tower, token embeddings, language head, norms, '
+        'transformer input/output projections, timestep embedding and modulation remain floating point.\n')
+    report.update(status='converted_and_roundtrip_verified',seconds=time.perf_counter()-started)
+    write_json(args.output/'conversion.json',report)
+    print(json.dumps(report,indent=2),flush=True)
+
+if __name__=='__main__': main()

scripts/infer.py

@@ -0,0 +1,42 @@
+"""Generate an RGBA image from a local Image21-MLX or original BF16 model."""
+import argparse
+import time
+from pathlib import Path
+import mlx.core as mx
+from scripts.runtime import load,generate
+from scripts.common import write_json
+
+def main():
+    ap=argparse.ArgumentParser()
+    ap.add_argument('--model',type=Path,required=True)
+    ap.add_argument('--prompt',required=True)
+    ap.add_argument('--output',type=Path,required=True)
+    ap.add_argument('--input',nargs='+')
+    ap.add_argument('--seed',type=int)
+    ap.add_argument('--source-seed',type=int)
+    ap.add_argument('--steps',type=int,default=40)
+    ap.add_argument('--width',type=int)
+    ap.add_argument('--height',type=int)
+    ap.add_argument('--resolution',type=int,default=1024)
+    args=ap.parse_args()
+    if args.output.exists(): raise FileExistsError(args.output)
+    if (args.width is None)!=(args.height is None): ap.error('Set width and height together')
+    if args.width is None:
+        if args.input:
+            from PIL import Image
+            from mlx_vlm.models.qwen_image.pipeline import _image_dimensions
+            with Image.open(args.input[-1]) as source:
+                args.width,args.height=_image_dimensions(args.resolution,source.width/source.height)
+        else: args.width=args.height=args.resolution
+    seed=args.seed if args.seed is not None else (1000042 if args.input else 42)
+    start=time.perf_counter(); pipe=load(args.model)
+    load_s=time.perf_counter()-start; mx.reset_peak_memory(); start=time.perf_counter()
+    img=generate(pipe,args.prompt,seed=seed,steps=args.steps,width=args.width,height=args.height,
+                 inputs=args.input,source_seed=args.source_seed,resolution=args.resolution)
+    seconds=time.perf_counter()-start
+    args.output.parent.mkdir(parents=True,exist_ok=True); img.save(args.output)
+    row=dict(model=str(args.model),prompt=args.prompt,seed=seed,steps=args.steps,width=args.width,height=args.height,
+             mode=img.mode,pipeline_init_seconds=load_s,seconds=seconds,mlx_peak_gib=mx.get_peak_memory()/2**30)
+    write_json(args.output.with_suffix('.json'),row); print(row,flush=True)
+
+if __name__=='__main__': main()

scripts/login.py

@@ -0,0 +1,23 @@
+"""Run interactively in your own terminal; never pass tokens on the command line."""
+import argparse
+from getpass import getpass
+
+def main():
+    ap=argparse.ArgumentParser()
+    ap.add_argument('platform',choices=('huggingface','modelscope'))
+    args=ap.parse_args()
+    if args.platform=='huggingface':
+        from huggingface_hub import login,HfApi
+        login(token=getpass('Hugging Face write token (hidden): '),add_to_git_credential=False)
+        owner=HfApi().whoami()['name']
+        expected='ixim'
+    else:
+        from modelscope_hub import HubApi
+        api=HubApi()
+        user=api.login(getpass('ModelScope SDK write token (hidden): '))
+        owner=user.username
+        expected='iximbox'
+    if owner!=expected: raise ValueError(f'Expected {expected}; logged in as {owner}')
+    print(f'Authenticated {owner}. No token has been printed.')
+
+if __name__=='__main__': main()

scripts/mlx_pipeline.py

@@ -0,0 +1,351 @@
+# Adapted from MLX-VLM 95b01ccad2d9f65a9e87f6a87bd1c5df69626261.
+# Copyright (c) 2025 Prince Canuma. MIT: see MLX_VLM_LICENSE.txt.
+# Modifications: text-to-image prefix KV cache and sequential component loading.
+"""Generation and reference-image editing for Qwen-Image-2.1."""
+
+from __future__ import annotations
+
+import json
+import math
+import gc
+from collections.abc import Sequence
+from pathlib import Path
+
+import mlx.core as mx
+import numpy as np
+from PIL import Image
+
+from mlx_vlm.models.qwen_image.config import QwenImageVariant, get_variant
+from mlx_vlm.models.qwen_image.download import download_model, validate_model_layout
+from mlx_vlm.models.qwen_image.kv_cache import QwenImageKVCache
+from mlx_vlm.models.qwen_image.scheduler import FlowMatchEulerDiscreteScheduler
+from mlx_vlm.models.qwen_image.text_encoder import QwenImageTextEncoder
+from mlx_vlm.models.qwen_image.weights import _read_quant, load_text_encoder, load_transformer, load_vae
+
+
+def _image_dimensions(resolution: int, ratio: float) -> tuple[int, int]:
+    width = math.sqrt(resolution * resolution * ratio)
+    return max(32, round(width / 32) * 32), max(32, round(width / ratio / 32) * 32)
+
+
+class QwenImagePipeline:
+    def __init__(
+        self,
+        *,
+        variant: QwenImageVariant,
+        model_path: str | Path,
+        text_encoder,
+        transformer,
+        vae,
+        phase_offload: bool = True,
+    ) -> None:
+        self.variant = variant
+        self.model_path = Path(model_path)
+        self.text_encoder = QwenImageTextEncoder(
+            model=text_encoder, model_path=self.model_path
+        )
+        self.transformer = transformer
+        self.vae = vae
+        self.phase_offload = phase_offload
+        cfg = json.loads((self.model_path / "vae" / "config.json").read_text())
+        self.z_dim = cfg["z_dim"]
+        self.latents_mean = mx.array(cfg["latents_mean"]).reshape(
+            1, self.z_dim, 1, 1, 1
+        )
+        self.latents_std = mx.array(cfg["latents_std"]).reshape(1, self.z_dim, 1, 1, 1)
+        self.quantization_config = _read_quant(self.model_path / "transformer")
+        scheduler_path = self.model_path / "scheduler" / "scheduler_config.json"
+        scheduler_config = (
+            json.loads(scheduler_path.read_text()) if scheduler_path.exists() else {}
+        )
+        self.scheduler_config = {
+            key: scheduler_config[key]
+            for key in (
+                "base_shift",
+                "max_shift",
+                "base_image_seq_len",
+                "max_image_seq_len",
+                "num_train_timesteps",
+                "shift_terminal",
+            )
+            if key in scheduler_config
+        }
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        variant: str | QwenImageVariant = "qwen-image-2.1",
+        *,
+        model_path: str | Path | None = None,
+        download: bool = True,
+        token: str | None = None,
+        revision: str | None = None,
+        force_download: bool = False,
+        phase_offload: bool = True,
+    ) -> "QwenImagePipeline":
+        variant = get_variant(variant)
+        if model_path is None:
+            if not download:
+                raise ValueError("model_path is required when download=False")
+            model_path = download_model(
+                variant, token=token, revision=revision, force_download=force_download
+            )
+        model_path = validate_model_layout(model_path)
+        return cls(
+            variant=variant,
+            model_path=model_path,
+            text_encoder=None if phase_offload else load_text_encoder(model_path),
+            transformer=None if phase_offload else load_transformer(model_path, variant),
+            vae=None if phase_offload else load_vae(model_path),
+            phase_offload=phase_offload,
+        )
+
+    def activate(self, component: str) -> None:
+        """Keep only the currently needed component resident in unified memory.
+
+        Callers materialize activations before switching, so no lazy graph keeps
+        the preceding model alive. Loading happens before resetting sample RNG.
+        """
+        if self.phase_offload:
+            if component != 'text_encoder': self.text_encoder.model = None
+            if component != 'transformer': self.transformer = None
+            if component != 'vae': self.vae = None
+            gc.collect()
+            mx.clear_cache()
+        if component == 'text_encoder':
+            if self.text_encoder.model is None:
+                self.text_encoder.model = load_text_encoder(self.model_path)
+            model = self.text_encoder.model
+        elif component == 'transformer':
+            if self.transformer is None:
+                self.transformer = load_transformer(self.model_path, self.variant)
+            model = self.transformer
+        elif component == 'vae':
+            if self.vae is None: self.vae = load_vae(self.model_path)
+            model = self.vae
+        else: raise ValueError(component)
+        mx.eval(model.parameters())
+
+    def release(self) -> None:
+        if self.phase_offload:
+            self.text_encoder.model = self.transformer = self.vae = None
+            gc.collect()
+            mx.clear_cache()
+
+    def count_prompt_tokens(self, prompt: str) -> int:
+        return len(self.text_encoder.tokenizer(prompt)["input_ids"])
+
+    def generate_array(
+        self,
+        prompt: str,
+        *,
+        seed: int = 0,
+        steps: int = 30,
+        width: int = 512,
+        height: int = 512,
+        guidance: float = 1.0,
+        negative_prompt: str = " ",
+        num_images: int = 1,
+    ) -> mx.array:
+        """Generate one ``[H, W, 3]`` image, or ``[N, H, W, 3]`` when num_images > 1."""
+        self.activate('text_encoder')
+        emb = self.text_encoder.encode(prompt).astype(mx.bfloat16)
+        do_cfg = guidance is not None and guidance > 1.0
+        neg = (
+            self.text_encoder.encode(negative_prompt).astype(mx.bfloat16)
+            if do_cfg
+            else None
+        )
+
+        return self._sample(
+            emb,
+            neg,
+            seed=seed,
+            steps=steps,
+            width=width,
+            height=height,
+            guidance=guidance,
+            num_images=num_images,
+        )[..., :3]
+
+    def edit_array(
+        self,
+        prompt: str,
+        image_paths: Sequence[str | Path],
+        *,
+        seed: int = 0,
+        steps: int = 40,
+        width: int | None = None,
+        height: int | None = None,
+        guidance: float = 1.0,
+        negative_prompt: str = " ",
+        output_resolution: int = 1024,
+        use_kv_cache: bool = True,
+    ) -> mx.array:
+        """Edit one or more references; return an [H, W, 4] uint8 RGBA image."""
+        if not image_paths:
+            raise ValueError("At least one reference image is required")
+        if output_resolution < 256:
+            raise ValueError("output_resolution must be at least 256")
+        self.activate('vae')
+        references, reference_latents, reference_shapes = [], [], []
+        for path in image_paths:
+            with Image.open(Path(path).expanduser()) as source:
+                image = source.convert("RGBA")
+            size = _image_dimensions(output_resolution, image.width / image.height)
+            image = image.resize(size, Image.Resampling.LANCZOS)
+            references.append(image)
+            pixels = mx.array(np.asarray(image).astype(np.float32) / 127.5 - 1.0)
+            pixels = pixels.transpose(2, 0, 1)[None, :, None].astype(mx.bfloat16)
+            mean, variance = self.vae.encode(pixels)
+            mx.eval(mean, variance)
+            normalized = (
+                mean - self.latents_mean.astype(mean.dtype)
+            ) / self.latents_std.astype(mean.dtype)
+            h, w = normalized.shape[-2:]
+            reference_shapes.append((1, h, w))
+            reference_latents.append(
+                normalized.reshape(1, self.z_dim, h * w).transpose(0, 2, 1)
+            )
+            mx.eval(reference_latents[-1])
+        default_width, default_height = references[-1].size
+        width = (default_width if width is None else width) // 32 * 32
+        height = (default_height if height is None else height) // 32 * 32
+        if width < 32 or height < 32:
+            raise ValueError("Output width and height must be at least 32")
+        self.activate('text_encoder')
+        emb, image_pad_mask = self.text_encoder.encode_edit(prompt, references)
+        neg = negative_image_pad_mask = None
+        if guidance is not None and guidance > 1.0:
+            neg, negative_image_pad_mask = self.text_encoder.encode_edit(
+                negative_prompt, references
+            )
+            neg = neg.astype(mx.bfloat16)
+        return self._sample(
+            emb.astype(mx.bfloat16),
+            neg,
+            seed=seed,
+            steps=steps,
+            width=width,
+            height=height,
+            guidance=guidance,
+            reference_latents=mx.concatenate(reference_latents, axis=1).astype(
+                mx.bfloat16
+            ),
+            reference_image_shapes=reference_shapes,
+            image_pad_mask=image_pad_mask,
+            negative_image_pad_mask=negative_image_pad_mask,
+            use_kv_cache=use_kv_cache,
+        )
+
+    def _sample(
+        self,
+        emb,
+        neg,
+        *,
+        seed,
+        steps,
+        width,
+        height,
+        guidance,
+        num_images=1,
+        reference_latents=None,
+        reference_image_shapes=None,
+        image_pad_mask=None,
+        negative_image_pad_mask=None,
+        use_kv_cache=False,
+    ) -> mx.array:
+        mx.eval(emb, [] if neg is None else neg,
+                [] if reference_latents is None else reference_latents)
+        self.activate('transformer')
+        z = self.z_dim
+        h_lat, w_lat = height // 16, width // 16
+        tokens = h_lat * w_lat
+        mx.random.seed(seed)
+        latents = mx.random.normal((num_images, 1, z, h_lat, w_lat)).astype(mx.bfloat16)
+        latents = latents.reshape(num_images, z, tokens).transpose(0, 2, 1)
+        if num_images > 1:
+            emb = mx.broadcast_to(emb, (num_images, *emb.shape[1:]))
+            if neg is not None:
+                neg = mx.broadcast_to(neg, (num_images, *neg.shape[1:]))
+        scheduler = FlowMatchEulerDiscreteScheduler(
+            image_seq_len=tokens, num_inference_steps=steps, **self.scheduler_config
+        )
+        cache = negative_cache = None
+        if (
+            use_kv_cache
+            and steps > 1
+            and self.transformer.causal_condition
+        ):
+            num_layers = len(self.transformer.transformer_blocks)
+            cache = QwenImageKVCache(num_layers)
+            if neg is not None:
+                negative_cache = QwenImageKVCache(num_layers)
+        for i in range(steps):
+            t = scheduler.timesteps[i : i + 1].astype(latents.dtype) / 1000
+            model_input = latents
+            edit_kwargs = {}
+            if reference_latents is not None:
+                if cache is None or i == 0:
+                    model_input = mx.concatenate([reference_latents, latents], axis=1)
+                edit_kwargs = dict(
+                    reference_image_shapes=reference_image_shapes,
+                    image_pad_mask=image_pad_mask,
+                )
+            if cache is not None:
+                edit_kwargs.update(
+                    kv_cache=cache, kv_cache_mode="extract" if i == 0 else "cached"
+                )
+            pred = self.transformer(
+                hidden_states=model_input,
+                encoder_hidden_states=emb,
+                timestep=t,
+                img_shape=(1, h_lat, w_lat),
+                **edit_kwargs,
+            )
+            if neg is not None:
+                if reference_latents is not None:
+                    edit_kwargs["image_pad_mask"] = negative_image_pad_mask
+                if negative_cache is not None:
+                    edit_kwargs["kv_cache"] = negative_cache
+                neg_pred = self.transformer(
+                    hidden_states=model_input,
+                    encoder_hidden_states=neg,
+                    timestep=t,
+                    img_shape=(1, h_lat, w_lat),
+                    **edit_kwargs,
+                )
+                pred = neg_pred + guidance * (pred - neg_pred)
+            latents = scheduler.step(noise=pred, step_index=i, latents=latents)
+            if cache is not None and i == 0:
+                # Materialize compact prefix storage at the existing step boundary,
+                # releasing the extraction graph before the next denoising step.
+                mx.eval(
+                    latents,
+                    cache.arrays(),
+                    [] if negative_cache is None else negative_cache.arrays(),
+                )
+            else:
+                mx.eval(latents)
+
+        # The VAE decoder does not need the per-layer prefix buffers.
+        if cache is not None:
+            cache.clear()
+        if negative_cache is not None:
+            negative_cache.clear()
+
+        z_lat = (
+            latents.transpose(0, 2, 1)
+            .reshape(num_images, z, 1, h_lat, w_lat)
+            .astype(mx.float32)
+        )
+        z_lat = z_lat * self.latents_std + self.latents_mean
+        mx.eval(z_lat)
+        self.activate('vae')
+        image = self.vae.decode(z_lat)[:, :, 0]
+        image = ((mx.clip(image, -1.0, 1.0) + 1.0) / 2.0 * 255).astype(mx.uint8)
+        images = image.transpose(0, 2, 3, 1)
+        return images[0] if num_images == 1 else images
+
+
+__all__ = ["QwenImagePipeline"]

scripts/probe.py

@@ -0,0 +1,55 @@
+"""Stratified weight reconstruction and GPU matmul probe, not an image-quality score."""
+import argparse
+import gc
+import json
+import time
+from pathlib import Path
+import mlx.core as mx
+from scripts.common import SOURCE, eligible, tensors, write_json
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--source', type=Path, default=SOURCE)
+    ap.add_argument('--output', default='artifacts/precision-probe.json')
+    args = ap.parse_args()
+    results = []
+    for component, layers in [('transformer', ('0', '15', '31')), ('text_encoder', ('0','17','35'))]:
+        for path, name, info in tensors(args.source / component):
+            if not eligible(component, name, info['shape']):
+                continue
+            if not any(f'.{i}.' in name for i in layers):
+                continue
+            if not any(x in name for x in ('to_q.weight', 'img_mlp.out.weight', 'q_proj.weight', 'down_proj.weight')):
+                continue
+            all_weights = mx.load(str(path))
+            # 256 evenly spaced rows, all columns/groups: bounded memory and reproducible.
+            full = all_weights[name]
+            weight = full[mx.linspace(0, full.shape[0]-1, 256).astype(mx.int32)]
+            mx.eval(weight)
+            del full, all_weights
+            wf = weight.astype(mx.float32)
+            mx.random.seed(2026)
+            x = mx.random.normal((1,256,weight.shape[-1])).astype(mx.bfloat16)
+            expected = x @ weight.T
+            mx.eval(expected)
+            for bits in (4,6,8):
+                q,s,b = mx.quantize(weight, bits=bits, group_size=64)
+                rec = mx.dequantize(q,s,b,bits=bits,group_size=64).astype(mx.float32)
+                err = float(mx.sqrt(mx.mean((rec-wf)**2) / mx.mean(wf**2)).item())
+                fn = lambda: mx.quantized_matmul(x,q,s,b,bits=bits,group_size=64,transpose=True)
+                for _ in range(3): mx.eval(fn())
+                start=time.perf_counter()
+                for _ in range(10): mx.eval(fn())
+                ms=(time.perf_counter()-start)*100
+                y=fn().astype(mx.float32); e=expected.astype(mx.float32)
+                out_err=float(mx.sqrt(mx.mean((y-e)**2)/mx.mean(e**2)).item())
+                row=dict(component=component,tensor=name,source_shape=info['shape'],sample_rows=256,
+                         bits=bits,weight_relative_rmse=err,synthetic_matmul_relative_rmse=out_err,matmul_ms=ms)
+                results.append(row)
+                print(json.dumps(row),flush=True)
+            del weight,wf,x,expected,q,s,b,rec,y,e
+            gc.collect(); mx.clear_cache()
+    write_json(args.output,dict(group_size=64,mode='affine',device=mx.metal.device_info(),results=results,
+                               limitations='Sampled rows and synthetic inputs; not calibrated activations, image quality or end-to-end speed.'))
+
+if __name__ == '__main__': main()

scripts/release.py

@@ -0,0 +1,91 @@
+"""Stage only verified weights, reproducible tools and paired evaluation evidence."""
+import argparse
+import json
+import shutil
+from pathlib import Path
+from scripts.common import REVISION,RUNTIME_REVISION,sha256,header,write_json
+from scripts.report import REQUIRED_CASES,pair_records,records
+
+def manifest(root):
+    root=Path(root)
+    return [dict(path=p.relative_to(root).as_posix(),size=p.stat().st_size,sha256=sha256(p))
+            for p in sorted(root.rglob('*')) if p.is_file() and p.name!='MANIFEST.json'
+            and not any(x.startswith('.') or x=='__pycache__' for x in p.relative_to(root).parts)]
+
+def validate_manifest(root):
+    root=Path(root).resolve()
+    rows=json.loads((root/'MANIFEST.json').read_text())
+    names=set()
+    for row in rows:
+        name=row['path']; original=root/name; path=original.resolve()
+        if original.is_symlink() or not path.is_relative_to(root) or name in names:
+            raise ValueError(f'Invalid manifest path: {name}')
+        names.add(name)
+        if path.stat().st_size!=row['size'] or sha256(path)!=row['sha256']:
+            raise ValueError(f'Manifest mismatch: {name}')
+    actual={p.relative_to(root).as_posix() for p in root.rglob('*') if p.is_file()
+            and not any(x.startswith('.') or x=='__pycache__' for x in p.relative_to(root).parts)}
+    if actual!=names|{'MANIFEST.json'}: raise ValueError('Unexpected/missing release files')
+    return rows
+
+def validate_evaluation(root):
+    root=Path(root)
+    pairs=list(pair_records(records(root/'bf16'),records(root/'8bit')))
+    if {a['case_id'] for a,b in pairs}!=REQUIRED_CASES: raise ValueError('Incomplete seven-case suite')
+    for a,b in pairs:
+        if a['steps']!=40 or a['width']!=1024 or a['height']!=1024 or not a['warmup']:
+            raise ValueError('Release requires the full 1024px/40-step warmed protocol')
+        if b['mode']!='RGBA' or b['rgb_std']<1: raise ValueError('Broken output')
+    review=json.loads((root/'visual-review.json').read_text())
+    if review.get('approved_for_research_release') is not True:
+        raise ValueError('Visual review incomplete or failed')
+    if set(review.get('cases',{}))!=REQUIRED_CASES: raise ValueError('Missing visual case reviews')
+    for name in ('bf16','8bit'):
+        if review['results_sha256'][name]!=sha256(root/name/'results.jsonl'):
+            raise ValueError('Visual review does not match current results')
+
+def main():
+    ap=argparse.ArgumentParser()
+    ap.add_argument('--model',type=Path,default=Path('models/Image21-MLX-8bit'))
+    ap.add_argument('--evaluation',type=Path,default=Path('artifacts/eval'))
+    ap.add_argument('--platform',choices=('huggingface','modelscope'),required=True)
+    ap.add_argument('--output',type=Path)
+    args=ap.parse_args(); out=args.output or Path('release')/args.platform
+    if out.exists(): raise FileExistsError(out)
+    validate_evaluation(args.evaluation)
+    conversion=json.loads((args.model/'conversion.json').read_text())
+    if conversion['status']!='converted_and_roundtrip_verified' or conversion['source_revision']!=REVISION or conversion['runtime_revision']!=RUNTIME_REVISION:
+        raise ValueError('Unverified conversion')
+    for comp in conversion['components'].values():
+        if not comp['exact_roundtrip']: raise ValueError('Roundtrip not verified')
+    for p in args.model.glob('*/*.safetensors'):
+        if 'modification_notice' not in header(p).get('__metadata__',{}): raise ValueError('Missing modification notice')
+    shutil.copytree(args.model,out,copy_function=shutil.copy2)
+    shutil.copytree(args.evaluation,out/'evaluation',ignore=shutil.ignore_patterns('._*','*.tmp'))
+    # Publish useful machine measurements without the workstation's absolute paths.
+    for precision in ('bf16','8bit'):
+        path=out/'evaluation'/precision/'environment.json'
+        env=json.loads(path.read_text())
+        env['model']=f'Image21-MLX-{precision}'
+        write_json(path,env)
+    audit=json.loads(Path('artifacts/source-audit.json').read_text())
+    audit.pop('source')
+    audit['source_model']='Qwen/Qwen-Image-2.1'
+    audit['note']='Public source-file hashes and precision inventory; local source directory omitted.'
+    write_json(out/'evaluation'/'source-files.json',audit)
+    shutil.copytree('scripts',out/'scripts',ignore=shutil.ignore_patterns('__pycache__'))
+    shutil.copytree('benchmarks',out/'benchmarks')
+    for name in ('requirements.txt','requirements.lock.txt'):
+        shutil.copy2(name,out/name)
+    shutil.copy2(f'cards/{args.platform}.md',out/'README.md')
+    shutil.copy2('artifacts/precision-probe.json',out/'evaluation'/'precision-probe.json')
+    for name in ('cache-parity-bf16.json','cache-parity-8bit.json','offload-parity.json'):
+        shutil.copy2(Path('artifacts')/name,out/'evaluation'/name)
+    for row in json.loads((args.evaluation/'runtime-manifest.json').read_text()):
+        if sha256(out/row['path'])!=row['sha256']:
+            raise ValueError(f'Runtime changed after evaluation: {row["path"]}')
+    write_json(out/'MANIFEST.json',manifest(out))
+    rows=validate_manifest(out)
+    print(f'Staged and verified {len(rows)} files in {out}')
+
+if __name__=='__main__': main()

scripts/report.py

@@ -0,0 +1,82 @@
+"""Pair raw records and generate inspectable image comparisons (no invented quality score)."""
+import argparse
+import json
+import math
+import statistics
+from pathlib import Path
+import numpy as np
+from PIL import Image,ImageDraw
+from scripts.common import sha256,write_json
+
+PAIR_KEYS=('case_id','prompt','seed','width','height','steps','cfg','vae_tiling','kv_cache','phase_offload','input_sha256','warmup')
+REQUIRED_CASES={'portrait','english_text','chinese_text','composition','texture','rgba','edit'}
+
+def records(root):
+    root=Path(root)
+    if not (root/'COMPLETE.json').exists(): raise ValueError(f'Incomplete evaluation: {root}')
+    data=[json.loads(s) for s in (root/'results.jsonl').read_text().splitlines()]
+    out={}
+    for row in data:
+        key=(row['case_id'],row['seed'])
+        if key in out: raise ValueError('Duplicate case/seed')
+        if sha256(root/row['output'])!=row['output_sha256']: raise ValueError('Image hash mismatch')
+        out[key]=row
+    return out
+
+def pair_records(baseline,candidate):
+    if set(baseline)!=set(candidate): raise ValueError('Different evaluation cases')
+    for key,a in baseline.items():
+        b=candidate[key]
+        for k in PAIR_KEYS:
+            if a.get(k)!=b.get(k): raise ValueError(f'Incomparable pair: {key}/{k}')
+        yield a,b
+
+def main():
+    ap=argparse.ArgumentParser()
+    ap.add_argument('--baseline',type=Path,default=Path('artifacts/eval/bf16'))
+    ap.add_argument('--candidate',type=Path,default=Path('artifacts/eval/8bit'))
+    ap.add_argument('--output',type=Path,default=Path('artifacts/eval'))
+    args=ap.parse_args(); args.output.mkdir(parents=True,exist_ok=True)
+    pairs=list(pair_records(records(args.baseline),records(args.candidate)))
+    rows=[]; sheet=Image.new('RGB',(1024,len(pairs)*550),'#eeeeee'); draw=ImageDraw.Draw(sheet)
+    for i,(a,b) in enumerate(pairs):
+        images=[Image.open(root/row['output']).convert('RGBA') for root,row in [(args.baseline,a),(args.candidate,b)]]
+        av,bv=[np.asarray(img).astype(np.float32) for img in images]
+        mse=float(np.mean((av[:,:,:3]-bv[:,:,:3])**2))
+        row=dict(case_id=a['case_id'],seed=a['seed'],bf16_seconds=a['seconds'],q8_seconds=b['seconds'],
+                 bf16_peak_gib=a['mlx_peak_gib'],q8_peak_gib=b['mlx_peak_gib'],
+                 bf16_swap_delta_gib=a.get('swap_delta_gib'),q8_swap_delta_gib=b.get('swap_delta_gib'),
+                 rgb_psnr_db=10*math.log10(255**2/max(mse,1e-12)),
+                 alpha_mae=float(np.mean(np.abs(av[:,:,3]-bv[:,:,3]))))
+        rows.append(row)
+        for j,(img,label) in enumerate(zip(images,('BF16','Q8'))):
+            checker=Image.new('RGBA',img.size,'white'); cd=ImageDraw.Draw(checker)
+            for y in range(0,img.height,32):
+                for x in range(0,img.width,32):
+                    if (x//32+y//32)%2: cd.rectangle((x,y,x+31,y+31),fill='#d7d7d7')
+            thumb=Image.alpha_composite(checker,img).convert('RGB').resize((512,512),Image.Resampling.LANCZOS)
+            sheet.paste(thumb,(j*512,i*550+30)); draw.text((j*512+10,i*550+8),f'{a["case_id"]} / {label} / seed {a["seed"]}',fill='black')
+    sheet.save(args.output/'comparison.png')
+    summary=dict(pairs=len(pairs),cases=len({x['case_id'] for x in rows}),size=pairs[0][0]['width'],steps=pairs[0][0]['steps'],
+                 warmup=pairs[0][0]['warmup'],phase_offload=pairs[0][0].get('phase_offload',False),
+                 bf16_mean_seconds=statistics.mean(x['bf16_seconds'] for x in rows),
+                 q8_mean_seconds=statistics.mean(x['q8_seconds'] for x in rows),
+                 bf16_t2i_mean_seconds=statistics.mean(x['bf16_seconds'] for x in rows if x['case_id']!='edit'),
+                 q8_t2i_mean_seconds=statistics.mean(x['q8_seconds'] for x in rows if x['case_id']!='edit'),
+                 bf16_max_peak_gib=max(x['bf16_peak_gib'] for x in rows),
+                 q8_max_peak_gib=max(x['q8_peak_gib'] for x in rows),
+                 rows=rows,limitations='One seed per case, one machine, same pinned MLX runtime. Sequential BF16-then-Q8 desktop run without repeated or interleaved trials; order, thermal state and other applications may affect timing. Pixel similarity is not a perceptual quality score; no cross-runtime parity claim.')
+    write_json(args.output/'summary.json',summary)
+    text=['# Image21-MLX informal evaluation','',summary['limitations'],'',
+          '| Case | BF16 s | Q8 s | BF16 peak GiB | Q8 peak GiB | RGB PSNR dB |',
+          '|---|---:|---:|---:|---:|---:|']
+    for r in rows: text.append(f'| {r["case_id"]} | {r["bf16_seconds"]:.2f} | {r["q8_seconds"]:.2f} | {r["bf16_peak_gib"]:.2f} | {r["q8_peak_gib"]:.2f} | {r["rgb_psnr_db"]:.2f} |')
+    text+=['','MLX peak allocated memory excludes the OS, other applications and some process allocations. It is not minimum machine RAM.',
+           '', 'Timing includes prompt encoding, phase-by-phase component loading, denoising and VAE decoding; PNG writing is excluded. The after-image RSS field is a snapshot after component release, not a peak.',
+           '', 'Existing system swap is recorded separately from per-image swap change. This desktop-session run leaves other applications open. See system-context.json and the per-model environment.json files.',
+           '', 'All editing pairs use the same BF16 portrait input. Visual findings and release limitations are in visual-review.json.',
+           '', '![All evaluated pairs](comparison.png)','']
+    (args.output/'report.md').write_text('\n'.join(text))
+    print(json.dumps(summary,indent=2))
+
+if __name__=='__main__': main()

scripts/runtime.py

@@ -0,0 +1,48 @@
+"""Pinned MLX runtime adapter preserving the source model's RGBA output."""
+from pathlib import Path
+import mlx.core as mx
+import numpy as np
+from PIL import Image
+from scripts.mlx_pipeline import QwenImagePipeline
+
+def enable_progress():
+    """Materialize at the existing Euler boundary and show progress every ten steps."""
+    from scripts import mlx_pipeline as module
+    from mlx_vlm.models.qwen_image.scheduler import FlowMatchEulerDiscreteScheduler
+    import time
+    class ProgressScheduler(FlowMatchEulerDiscreteScheduler):
+        def step(self,*,noise,step_index,latents):
+            value=super().step(noise=noise,step_index=step_index,latents=latents)
+            mx.eval(value)
+            if step_index==0 or (step_index+1)%10==0:
+                print(f'  denoise step {step_index+1} at {time.strftime("%H:%M:%S")}',flush=True)
+            return value
+    module.FlowMatchEulerDiscreteScheduler=ProgressScheduler
+
+def load(model,phase_offload=True):
+    return QwenImagePipeline.from_pretrained(model_path=Path(model),download=False,phase_offload=phase_offload)
+
+def generate(pipe,prompt,*,seed=42,steps=40,width=1024,height=1024,inputs=None,
+             source_seed=None,resolution=1024):
+    if steps<1 or width<256 or height<256 or width%32 or height%32:
+        raise ValueError('Use positive steps and dimensions >=256 divisible by 32')
+    if inputs:
+        if source_seed is not None and seed==source_seed:
+            raise ValueError('Editing must use a different seed from the source image')
+        if len(inputs)>10: raise ValueError('At most ten references are supported')
+        result=pipe.edit_array(prompt,inputs,seed=seed,steps=steps,width=width,height=height,
+                               guidance=1.0,output_resolution=resolution,use_kv_cache=True)
+    else:
+        # The pinned upstream generate_array slices RGB. Call its unchanged RGBA
+        # sampler so transparent generation keeps all four native output channels.
+        print('Encoding prompt',flush=True)
+        pipe.activate('text_encoder')
+        emb=pipe.text_encoder.encode(prompt).astype(mx.bfloat16)
+        mx.eval(emb)
+        print('Denoising',flush=True)
+        result=pipe._sample(emb,None,seed=seed,steps=steps,width=width,height=height,guidance=1.0,use_kv_cache=True)
+    mx.eval(result)
+    pixels=np.asarray(result)
+    pipe.release()
+    if pixels.shape!=(height,width,4): raise ValueError(f'Unexpected output: {pixels.shape}')
+    return Image.fromarray(pixels)

scripts/upload.py

@@ -0,0 +1,67 @@
+"""Publish the explicit release inventory; never upload workspace caches or credentials."""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+from scripts.common import write_json,sha256
+from scripts.release import validate_manifest,validate_evaluation
+
+def main():
+    ap=argparse.ArgumentParser()
+    ap.add_argument('platform',choices=('huggingface','modelscope'))
+    ap.add_argument('--folder',type=Path)
+    ap.add_argument('--dry-run',action='store_true')
+    args=ap.parse_args(); folder=args.folder or Path('release')/args.platform
+    owner='ixim' if args.platform=='huggingface' else 'iximbox'
+    repo=f'{owner}/Image21-MLX-8bit'
+    validate_evaluation(folder/'evaluation')
+    rows=validate_manifest(folder); names=[x['path'] for x in rows]+['MANIFEST.json']
+    remote_rows=rows+[dict(path='MANIFEST.json',size=(folder/'MANIFEST.json').stat().st_size,
+                           sha256=sha256(folder/'MANIFEST.json'))]
+    print(f'Validated {len(rows)} files: {repo}',flush=True)
+    if args.dry_run: return
+    if args.platform=='huggingface':
+        from huggingface_hub import HfApi,get_token
+        if not get_token(): raise RuntimeError('Run python -m scripts.login huggingface locally')
+        api=HfApi()
+        if api.whoami()['name']!=owner: raise ValueError('Wrong HF account')
+        api.create_repo(repo_id=repo,repo_type='model',private=False,exist_ok=True)
+        result=api.upload_folder(repo_id=repo,repo_type='model',folder_path=folder,allow_patterns=names,
+                                 commit_message='Release Image21-MLX 8-bit with reproducible evaluation')
+        info=api.model_info(repo,files_metadata=True)
+        remote={x.rfilename:x for x in info.siblings}
+        for row in remote_rows:
+            if row['path'] not in remote or remote[row['path']].size!=row['size']:
+                raise ValueError(f'Remote size mismatch: {row["path"]}')
+            lfs=remote[row['path']].lfs
+            if lfs is not None and lfs.sha256!=row['sha256']: raise ValueError('Remote LFS hash mismatch')
+            if lfs is None:
+                data=(folder/row['path']).read_bytes()
+                blob=hashlib.sha1(f'blob {len(data)}\0'.encode()+data).hexdigest()
+                if remote[row['path']].blob_id!=blob: raise ValueError('Remote Git blob hash mismatch')
+        record=dict(repo_id=repo,url=f'https://huggingface.co/{repo}',revision=info.sha,
+                    commit_url=str(result.commit_url),verified_files=len(remote_rows))
+    else:
+        from modelscope_hub import HubApi
+        from modelscope_hub.errors import NotExistError
+        api=HubApi()
+        if api.whoami().username!=owner: raise ValueError('Wrong ModelScope account')
+        # create only on an explicit not-found response; never hide authentication failures.
+        try: api.get_repo(repo,repo_type='model')
+        except NotExistError:
+            api.create_repo(repo,repo_type='model',visibility='public',license='other',
+                            description='Image21-MLX 8-bit. Built with Qwen. Research/evaluation only.')
+        result=api.upload_folder(repo_id=repo,repo_type='model',folder_path=folder,allow_patterns=names,
+                                 max_workers=4,commit_message='Release verified Image21-MLX 8-bit')
+        remote={x.path:x for x in api.list_repo_files(repo,repo_type='model')}
+        for row in remote_rows:
+            item=remote.get(row['path'])
+            if item is None or item.size!=row['size']: raise ValueError(f'Remote size mismatch: {row["path"]}')
+            if item.sha256 and item.sha256!=row['sha256']: raise ValueError('Remote SHA256 mismatch')
+        record=dict(repo_id=repo,url=f'https://modelscope.cn/models/{repo}',
+                    verified_files=len(remote_rows),remote_verification='file sizes and available SHA256')
+    write_json(Path('artifacts')/f'publication-{args.platform}.json',record)
+    print(json.dumps(record,indent=2))
+
+if __name__=='__main__': main()

scripts/verify_cache.py

@@ -0,0 +1,42 @@
+"""Validate native text-prefix caching against the exact uncached transformer."""
+import argparse
+import json
+import time
+from pathlib import Path
+import mlx.core as mx
+from mlx_vlm.models.qwen_image.weights import load_transformer
+from mlx_vlm.models.qwen_image.kv_cache import QwenImageKVCache
+from scripts.common import write_json
+
+def main():
+    ap=argparse.ArgumentParser()
+    ap.add_argument('--model',type=Path,required=True)
+    ap.add_argument('--output',type=Path,required=True)
+    args=ap.parse_args()
+    model=load_transformer(args.model); mx.eval(model.parameters())
+    mx.random.seed(20260926)
+    emb=mx.random.normal((1,48,4096)).astype(mx.bfloat16)
+    latent=mx.random.normal((1,1024,64)).astype(mx.bfloat16)
+    cache=QwenImageKVCache(len(model.transformer_blocks))
+    kw=dict(encoder_hidden_states=emb,img_shape=(1,32,32))
+    init=model(hidden_states=latent,timestep=mx.array([0.9],dtype=mx.bfloat16),kv_cache=cache,kv_cache_mode='extract',**kw)
+    mx.eval(init,cache.arrays())
+    rows=[]
+    for t in (0.7,0.3):
+        latent=mx.random.normal((1,1024,64)).astype(mx.bfloat16)
+        timestep=mx.array([t],dtype=mx.bfloat16)
+        start=time.perf_counter(); expected=model(hidden_states=latent,timestep=timestep,**kw); mx.eval(expected)
+        uncached=time.perf_counter()-start
+        start=time.perf_counter(); actual=model(hidden_states=latent,timestep=timestep,kv_cache=cache,kv_cache_mode='cached',**kw); mx.eval(actual)
+        cached=time.perf_counter()-start
+        delta=actual.astype(mx.float32)-expected.astype(mx.float32)
+        rel=float(mx.sqrt(mx.mean(delta**2)/mx.mean(expected.astype(mx.float32)**2)).item())
+        row=dict(timestep=t,max_abs_error=float(mx.max(mx.abs(delta)).item()),relative_rmse=rel,
+                 uncached_seconds=uncached,cached_seconds=cached)
+        rows.append(row); print(row,flush=True)
+        # Kernel splitting can change BF16 rounding; guard against material drift.
+        if rel>0.01: raise ValueError(f'KV cache changes predictions materially: {rel}')
+    write_json(args.output,dict(model=str(args.model),passed=True,rows=rows,
+                                note='Real transformer with synthetic conditioning/latents; BF16 numerical tolerance, not pixel equality.'))
+
+if __name__=='__main__': main()

text_encoder/config.json

@@ -0,0 +1,71 @@
+{
+  "architectures": [
+    "Qwen3VLForConditionalGeneration"
+  ],
+  "dtype": "bfloat16",
+  "image_token_id": 151655,
+  "model_type": "qwen3_vl",
+  "text_config": {
+    "attention_bias": false,
+    "attention_dropout": 0.0,
+    "bos_token_id": 151643,
+    "dtype": "bfloat16",
+    "eos_token_id": 151645,
+    "head_dim": 128,
+    "hidden_act": "silu",
+    "hidden_size": 4096,
+    "initializer_range": 0.02,
+    "intermediate_size": 12288,
+    "max_position_embeddings": 262144,
+    "model_type": "qwen3_vl_text",
+    "num_attention_heads": 32,
+    "num_hidden_layers": 36,
+    "num_key_value_heads": 8,
+    "rms_norm_eps": 1e-06,
+    "rope_scaling": {
+      "mrope_interleaved": true,
+      "mrope_section": [
+        24,
+        20,
+        20
+      ],
+      "rope_type": "default"
+    },
+    "rope_theta": 5000000,
+    "use_cache": true,
+    "vocab_size": 151936
+  },
+  "tie_word_embeddings": false,
+  "transformers_version": "4.57.1",
+  "video_token_id": 151656,
+  "vision_config": {
+    "deepstack_visual_indexes": [
+      8,
+      16,
+      24
+    ],
+    "depth": 27,
+    "dtype": "bfloat16",
+    "hidden_act": "gelu_pytorch_tanh",
+    "hidden_size": 1152,
+    "in_channels": 3,
+    "initializer_range": 0.02,
+    "intermediate_size": 4304,
+    "model_type": "qwen3_vl",
+    "num_heads": 16,
+    "num_position_embeddings": 2304,
+    "out_hidden_size": 4096,
+    "patch_size": 16,
+    "spatial_merge_size": 2,
+    "temporal_patch_size": 2
+  },
+  "vision_end_token_id": 151653,
+  "vision_start_token_id": 151652,
+  "quantization": {
+    "bits": 8,
+    "group_size": 64,
+    "mode": "affine"
+  },
+  "mlx_format": true,
+  "_modification_notice": "Modified by ixim / iximbox for Image21-MLX: converted from the pinned BF16 source to MLX layout; eligible linear weights use groupwise affine quantization. See conversion.json for precision and exceptions. Built with Qwen."
+}

transformer/config.json

@@ -0,0 +1,26 @@
+{
+  "_class_name": "QwenImage21Transformer2DModel",
+  "_diffusers_version": "0.37.0.dev0",
+  "attention_head_dim": 128,
+  "axes_dims_rope": [
+    16,
+    56,
+    56
+  ],
+  "context_in_dim": 4096,
+  "in_channels": 64,
+  "num_attention_heads": 32,
+  "num_layers": 32,
+  "out_channels": 64,
+  "patch_size": 1,
+  "mlp_ratio": 3,
+  "eps": 1e-06,
+  "causal_condition": true,
+  "quantization": {
+    "bits": 8,
+    "group_size": 64,
+    "mode": "affine"
+  },
+  "mlx_format": true,
+  "_modification_notice": "Modified by ixim / iximbox for Image21-MLX: converted from the pinned BF16 source to MLX layout; eligible linear weights use groupwise affine quantization. See conversion.json for precision and exceptions. Built with Qwen."
+}