Qwen-Image-2.1-mflux-q4 是一个面向 Apple 芯片的文生图（text-to-image）模型仓库，它是 Qwen-Image-2.1 的原生 MLX/mflux 4-bit 量化转换版。整个仓库由四个核心目录组成：text_encoder、transformer、vae 和 processor，分别负责"读懂文字"、"扩散去噪"、"像素还原"和"分词预处理"。下面带你逐个拆解这份约 8.9 GB 的模型包，搞懂每个目录到底装了什么、为什么这样分工。

📦 仓库全景：四个目录各管一摊

先看整体结构，一眼就能看懂各部分定位：

Qwen-Image-2.1-mflux-q4/ ├── text_encoder/ # 文本编码器（Qwen3-VL），把提示词变成向量 ├── transformer/ # 扩散 Transformer（MMDiT），真正的"绘图引擎" ├── vae/ # VAE 变分自编码器，负责潜空间与像素图互转 ├── processor/ # 分词器 + 对话模板，文本预处理 ├── README.md # 项目说明与实测数据 └── LICENSE # Apache-2.0 许可证

四个目录的分工可以用一句话概括：

这种"文本编码器 + 扩散 Transformer + VAE"的三段式架构，是现代扩散类文生图模型（如 Qwen-Image 系列）的标准配置。

✍️ text_encoder：提示词的"翻译官"

text_encoder/ 存放的是 Qwen3-VL 文本编码器的权重，它的工作是把你输入的提示词（如"一只在雪地里打滚的柴犬"）转换成一串高维语义向量，供 transformer 参考"该画什么"。

从分片索引 text_encoder/model.safetensors.index.json 可以看到三个关键信息：

• 36 层 Transformer 结构：从layers.0到layers.35，每层包含 self_attn 注意力（q/k/v/o 投影）与 mlp 前馈网络；
• 4-bit 量化痕迹：几乎每个线性层都带有weight、scales、biases三件套，其中scales就是 4-bit 反量化所需的缩放因子，这是体积大幅压缩的关键；
• 分片存储：权重拆成0.safetensors（约 1.99 GB）和1.safetensors（约 1.97 GB）两个文件，方便按需加载。

🎨 transformer：真正落笔的"扩散引擎"

transformer/ 是整个模型的核心，也是体积最大的部件之一。这里存放 MMDiT（多模态 Diffusion Transformer）的权重，它拿"text_encoder 给的语义向量 + 噪声潜张量"作为输入，经过多步迭代去噪，输出干净的图像潜表示。

查看分片索引 transformer/model.safetensors.index.json，可以看到典型的扩散 Transformer 组件：

• 32 个 transformer_blocks：每个块都有attn.to_q / to_k / to_v（Query/Key/Value 注意力投影）和img_mlp、txt_mlp两条前馈通路，让图像 token 与文本 token 双向交流；
• 时序与位置编码：time_text_embed、pos_embed.cos_tables等参数负责注入扩散步数信息；
• 同样 4-bit 量化：每个权重旁都有对应的.scales/.biases条目，两个分片合计约 3.73 GB。

🖼️ vae：潜空间与像素图的"转换器"

vae/ 存放 Qwen Image 2.1 布局的 VAE（变分自编码器），采用 mflux 的 Qwen Image 2.1 layout。它承担两个方向的任务：

• 编码：image-to-image 场景下，把输入图压成潜空间张量；
• 解码：生成结束后，把 transformer 输出的潜张量"翻译"回可见的像素图像。

从 vae/model.safetensors.index.json 的结构可以看出经典的编解码器设计：encoder.down_blocks（逐级下采样压缩）与decoder.up_blocks（逐级上采样还原），内部由大量 resnet 残差块堆叠而成。

一个有意思的细节：vae/目录只有 1 个分片（约 1.23 GB），且权重名中没有.scales字段——说明 VAE 保留了全精度存储，因为解码质量对像素级细节非常敏感，不宜激进量化。

🧩 processor：小而关键的"前台接待"

processor/ 目录文件最小，却不可或缺，包含 3 个文件：

它相当于模型流水线的"预处理车间"：用户输入的原始文字先在这里被切分、格式化，再交给 text_encoder 编码。

⚡ 实测表现与快速上手

README.md 给出了 Mac Studio 上的实测数据，这也是选择 q4 版本的最大卖点：

• 512×512、40 步：峰值 MLX 内存4.68 GiB
• 1024×1024、4 步：峰值 MLX 内存5.14 GiB
• 打包体积：约8.9 GB

⚠️ 需要注意：该 checkpoint 使用 mflux 0.20.0 + MLX 0.32.2 从上游 revision790c92633540aa0cb11d9abf19eb46d861714758转换而来。README 特别提示，原版 mflux 0.20.0 会跳过 text-encoder 的量化加载，需要搭配Rapid-MLX 的 reviewed low-memory loader才能完整加载这个模型包（使用了提示词物化、编码器驱逐与分块 VAE 解码等省内存策略）。

🤔 常见问题（FAQ）

Q1：为什么权重要拆成 0.safetensors / 1.safetensors 多个文件？

单个超大文件不便加载与校验。分片后加载器可以顺序读取，.safetensors.index.json索引文件记录了每个权重名属于哪个分片，加载器据此精确定位。

Q2：q4 是指什么？会明显损失画质吗？

q4 即 4-bit 量化——每个权重从 16-bit 压缩到 4-bit，体积缩到约 1/4，让 8 GB 内存的 Mac 也能跑起大模型。代价是轻微的精度损失，对大多数文生图场景影响有限。

Q3：这个仓库能直接跑吗？

需要 Apple 芯片（MLX 运行时）+ Rapid-MLX 的省内存加载器，详见 README.md 说明。原模型与转换版均采用Apache-2.0许可（见 LICENSE），可自由使用。

📌 总结

Qwen-Image-2.1-mflux-q4 的目录结构正是标准扩散文生图流水线的缩影：processor分词备料 →text_encoder读懂提示词 →transformer逐步去噪绘图 →vae还原成像素图。理解这四个目录的职责边界，不仅有助于你正确使用这个模型，也为你阅读其他 Hugging Face 风格的文生图仓库打下了通用基础。