Qwen-Image-2.1 纹理修复 VAE 是什么？一文看懂 Texture-Fix-VAE 的两大核心能力

【免费下载链接】texture-fix-vae-for-qwen-image-2.1项目地址: https://ai.gitcode.com/hf_mirrors/madebyollin/texture-fix-vae-for-qwen-image-2.1

Texture-Fix-VAE-for-Qwen-Image-2.1是一款面向 Qwen-Image-2.1 的纹理修复 VAE 模型，基于官方 Qwen-Image-2.1 VAE 微调而来。它只改了解码器（decoder）部分，专门修复两个让生图用户头疼的老问题：解码后的棋盘格伪影（checkerboard artifacts）和fp16 半精度下输出 NaN 的问题，同时还能兼容--fp16-vae运行。对新手来说，它最大的价值就是：不用改模型、不用换工作流，替换一个 VAE 文件即可显著提升画面质感。

一、什么是 VAE？为什么生图会出"棋盘格"？

在扩散模型（Diffusion Model）生成图像的流程中，VAE（变分自编码器）扮演"翻译官"的角色：扩散模型在低分辨率的潜空间（latent）里"画草稿"，最后由 VAE 解码器把潜变量还原成你看到的像素图。

也就是说，画面最终呈现的纹理细节、锐利程度，很大程度上取决于 VAE 解码器的质量。

而 Qwen-Image-2.1 原版 VAE 解码器有一个常见瑕疵：在照片风格的复杂画面（花卉、毛发、岩石纹理等）上，放大后能看到一层不规则的棋盘格状色块。作者在 README.md 中推测，原因很可能是原版 VAE 训练时没有启用有效的对抗损失（adversarial/GAN loss）——MSE/MAE 损失会把细节"抹糊"，LPIPS 损失则容易诱发棋盘格，只有 GAN 损失能逼出"看起来锐利又合理"的细节。

Texture-Fix-VAE 的解法：借用 TAESD 的对抗式训练配方，只对解码器中分辨率最高的两个阶段 + 输出头（约 7.5M 可训练参数）做约 5000 步的短时微调，即可消除棋盘格伪影。

下面是同一张 latent 分别用两个 VAE 解码后的放大对比（左侧为原版，右侧为纹理修复版）。左图中紫色羽扇豆花簇区域可见明显的棋盘格杂色，右图则干净得多。

原版 Qwen-Image-2.1-VAE	Texture-Fix VAE

💡 对比图使用的 latent 由 Qwen-Image-2.1 根据一张"太平洋西北高山草甸溪流"的照片风格提示词生成，文件见 images/pnw_meadow_stream_2048.latent.pt。

二、能力一：消除棋盘格伪影，照片级细节更干净

核心能力一就是"纹理修复"：在照片风格、细节密集的画面（野花、岩石、植被等）上，解码结果不再有棋盘格杂色，细节更自然。

值得一提的是，修复纹理的代价很小。根据 README.md 中的指标（COCO val2017，5000 张 256² 图）：

可以总结为：感知质量指标 rFID 大幅变好（3.38 → 2.06），重建精度指标（LPIPS/PSNR）只有轻微损失——对绝大多数用户来说，"看起来更好"比"逐像素更准"更有价值。

三、能力二：修复 fp16 下的 NaN，低精度也能稳跑

核心能力二是"fp16 稳定性修复"。很多用户在消费级显卡上会开启 fp16 半精度以省显存、提速，但原版 Qwen-Image-2.1 VAE 的解码器在 fp16 下经常出现NaN（无效像素）：

• 最容易在全透明区域（如带透明通道的贴纸、贴图类 RGBA 图）产生，并且会"渗"到周围正常内容里；
• 原版 VAE 解码器内部最大激活值可达约350 万，而 fp16 的上限只有 65504，必然溢出。

Texture-Fix VAE 用了两步"治本"手段（详见 NOTICE 与 README.md 的 Mechanism 章节）：

1. 微调解码器权重（约 61k 个参数：卷积的 scale/bias 与 RMSNorm gain），在保持输出基本不变的前提下压小激活幅值——思路和 SDXL-VAE-FP16-Fix 类似；
2. 手动缩小部分权重（解码器 /512、编码器 /8，均为 2 的整数次幂），进一步压低残差流的数值规模，输出完全不变。

修复效果：解码器最大激活值从 ~3.5M 降到~1.3k；185 项压力测试（透明/不透明/合成图/随机 latent，256²~2048²）中，输出 NaN 的输入从75 个降到 0 个。

你可以通过仓库自带的 fp16_demo.py 脚本完整复现 README 中的 fp16 对比效果（运行python fp16_demo.py，NaN/inf 像素会被染成紫红色高亮），测试数据就是仓库里的 images/rgba_dragon_sticker_1024.latent.pt（一张 1024×1024 RGBA 透明贴纸的 latent）。

四、如何上手使用？两步替换即可

方式 1：ComfyUI（最简单）

1. 下载权重文件 texture_fix_vae_for_qwen_image_2.1_bf16.safetensors；
2. 放入ComfyUI/models/vae/目录；
3. 在Load VAE节点中选中它，替代原来的qwen_image_2.1_vae_bf16.safetensors；
4. 完成 ✅（支持--fp16-vae参数运行）。

方式 2：Diffusers（代码用户）

只需在加载流水线时把 VAE 换成微调版即可，编码器逻辑不变（权重仅做了 2 的幂次缩放）：

import torch from diffusers import QwenImage21Pipeline, AutoencoderKLQwenImage21 vae = AutoencoderKLQwenImage21.from_pretrained( "madebyollin/texture-fix-vae-for-qwen-image-2.1", torch_dtype=torch.bfloat16 ) pipe = QwenImage21Pipeline.from_pretrained( "Qwen/Qwen-Image-2.1", vae=vae, torch_dtype=torch.bfloat16 ).to("cuda")

模型结构配置（64 通道 latent、16 倍空间下采样等）见 config.json。

五、版本历史与注意事项

• 2026-10-05：更新版本，新增修复 fp16 NaN（微调解码器 + 透明训练数据 ~60k 步，再重跑 8000 步恢复纹理细节，权重按 2 的幂次缩放）；
• 2026-09-24：初始版本，仅微调解码器修复棋盘格（~5000 步，学习率 3e-5，7.5M 可训练参数）。

⚠️许可提醒：本模型基于 Qwen/Qwen-Image-2.1，遵循 Qwen 研究许可协议（见 LICENSE 与 NOTICE），仅限非商业/研究用途，商用前请自行确认版权要求。

总结：一张表看懂 Texture-Fix-VAE

如果你正在用 Qwen-Image-2.1 做照片风格创作或带透明通道的素材，替换这个 VAE 是投入产出比极高的一步小改动。🪄

【免费下载链接】texture-fix-vae-for-qwen-image-2.1项目地址: https://ai.gitcode.com/hf_mirrors/madebyollin/texture-fix-vae-for-qwen-image-2.1