企业官网建设流程全解析

在模型移植和量化场景里，PSNR是衡量两个实现输出差异的核心指标。开源项目HEART-fp16将 16.7M 参数的 HEART 超分辨率网络从 PyTorch 移植到 MLX（fp16），其精度对齐（Parity）验证在 128² 输入上拿到了127.5 dB的 PSNR——这个水平几乎意味着"两次实现的输出在数值噪声层面完全一致"。本文带你搞懂：PSNR 刻度怎么看、HEART-fp16 用了哪套三步验证法、以及哪些张量必须保留 fp32。

一、PSNR 刻度表：127.5 dB 到底算什么水平？

PSNR（Peak Signal-to-Noise Ratio，峰值信噪比）公式为10·log10(MAX²/MSE)，单位 dB。数值越大，两份输出越接近：

💡 直观感受：100 dB 意味着信号与误差的比值达到 10¹⁰ 倍，127.5 dB 则约为 7×10¹² 倍。而 fp32 浮点本身的机器精度（epsilon）只有 ~1e-7——也就是说，127.5 dB 的差异已经比单精度浮点自身的误差底噪还要小，完全可以判定两套实现在数学上等价。

作为对照，ONNX Runtime 与 PyTorch 之间常见的跨引擎一致性通常在 80~95 dB（本仓库实测 90.2 / 84.9 / 95.8 dB）；而 fp16 与 fp32 对比一般只能做到 25~35 dB。

二、HEART-fp16 是什么？

HEART（Hybrid Efficient Attention with Rank-factorized bias Transformer，作者 Philip Hofmann）是一个基于 HAT-iLN 窗口注意力（window_size=32）的超分辨率网络，仅使用 CC0 许可数据集训练，总参数约 16.7M。HEART-fp16 是它的 MLX 移植版，专为 Swift/MLX 生态提供 2×/4× 放大能力。

仓库文件清单（每个 variant 独立成文件，按需加载）：

它采用"双通道"设计：HEART-fp16是发布通道（conv/linear 张量 fp16，其余关键张量 fp32），配套的HEART-fp32通道专门用作Parity 参考基线。

三、Parity 验证三步法：整模型 → 子算子 → 跨引擎

精度对齐（Parity）的目标一句话概括：同一输入喂给两个实现，量化输出差异是否小到可以忽略。HEART-fp16 的验证流程分三层，由粗到细：

第 1 步：固定参考实现 + 固定输入

• 参考实现：上游 PyTorch 版（heart_arch.py+ traiNNer-redux 辅助代码），跑在CPU fp32上；
• 固定输入：128×128 测试块，两个实现使用完全相同的输入张量；
• 权重逐张量精确转换（conv 权重布局从(O,I,kH,kW)重排为(O,kH,kW,I)，其余不动），上游文件锁定在 revision868878ce，并在 config.json 中记录source_sha256/fp32_sha256/fp16_sha256供校验。

第 2 步：整模型 PSNR 对比（每个 variant 单独跑）

fp32 通道 vs PyTorch 参考，128² 输入的实测结果：

第 3 步：子算子（sub-op）相对误差定位

整模型 PSNR 达标只说明"结果对"，子算子检查说明"每一层都对"：对每个子操作单独对比，要求全部落在1e-5 相对误差以内。这样一旦出现回归，能直接定位到具体算子，而不是在整网黑盒里猜。

此外还做了跨引擎对照：与作者提供的 ONNX 导出文件在 ONNX Runtime 下对比，得到 90.2 / 84.9 / 95.8 dB——"和 ONNX 一致到 torch 自身一致的程度"。这个对照还反向暴露了一个参考端问题：heart_4x_pretrain的 ONNX 文件无法复现其 checkpoint（仅 7.8 dB），且 ORT 输出会随图像尺寸漂移。这说明 Parity 检查是双向的：既能抓移植错误，也能抓参考端问题。

四、fp16 精度策略：哪 220 个张量必须留在 fp32？

748 个张量中有220 个保持 fp32，规则记录在 config.json 的fp16_keeps_fp32字段：

"fp16_keeps_fp32": [ "*.norm1.{weight,bias}", "*.norm2.{weight,bias}", "norm.{weight,bias}", "patch_embed.norm.{weight,bias}", "*.to_hidden", "*.hidden_b", "*.to_q", "*.to_k" ]

同时，所有归约（reduction）运算强制 fp32：i-LN 的统计量、RIB 位置表、softmax、全局平均池化及其 squeeze/excite 头。

为什么？这些位置要么参与跨大量元素的累加（fp16 累加误差放大、易溢出），要么是 Query/Key 投影和隐式网络参数（对频率/位置编码敏感）。保留它们 fp32 后，模型文件体积仍从 66.8 MB 压到 33.7 MB，几乎减半。

五、如何复现这套验证？（快速上手）

1. 拉取仓库（参考通道同理换成HEART-fp32）：

   git clone https://gitcode.com/hf_mirrors/mlx-community/HEART-fp16

2. 准备参考实现：上游 PyTorchheart_arch.py（CPU fp32），并加载同一 revision 的原始 checkpoint。

3. 固定输入：生成一个 128×128 的固定测试图（随机种子固定，两边复用同一份字节）。

4. 分别推理：PyTorch 与 MLX 各跑一次，保存输出张量为数组。

5. 计算 PSNR（以 uint8 域为例，MAX=255）：

   mse = np.mean((a.astype(np.float64) - b.astype(np.float64)) ** 2) psnr = 10 * np.log10(255 ** 2 / mse)

6. 按阈值判级：

   • 跨框架 fp32 对比：> 90 dB视为完全对齐，本仓库达到 122.5~127.5 dB；
   • 子算子：相对误差 < 1e-5逐层通过；
   • fp16 通道对 fp32：25~35 dB属正常范围，低于 20 dB 需排查 dtype 处理。

7. sha256 校验：用 config.json 中记录的fp16_sha256确认权重文件未被篡改或二次量化。

六、FAQ 速答

Q：为什么不用 40 dB 之类的低阈值当"及格线"？A：40 dB 只够判断"人眼看不出差别"，无法区分"实现正确"和"恰好接近"。跨框架移植必须做到 > 90 dB（本例 127.5 dB），才能排除逐层累计的系统性偏差。

Q：PSNR 不达标时先查什么？A：按顺序查：① 输入是否完全一致（归一化、通道序）；② 权重布局是否按OHWI/NHWC正确重排（见 config.json 的layout字段）；③ 敏感算子是否漏配 fp32（softmax、归约、i-LN）；④ 用子算子对比定位第一处偏差层。

Q：PSNR 和 SSIM 怎么选？A：验证实现一致性用 PSNR（对逐像素差异敏感、可复现）；评估视觉效果用 SSIM/主观观感。两者互补，不可互相替代。

七、关键资料索引

• 项目说明与 Parity 数据总览：README.md（"Parity" 小节）
• 架构参数 / variant 元数据 / fp16 保留规则 / 校验和：config.json
• 四个模型权重文件：heart_4x_otf_v2_fp16.safetensors、heart_4x_otf_gan_fp16.safetensors、heart_4x_pretrain_fp16.safetensors、heart_2x_fp16.safetensors
• fp16 精度研究与分块（tiling）研究的完整细节，见移植仓库的PORTING-SPEC.md（README 中有指引）

📌一句话总结：HEART-fp16 用"固定输入 + 固定参考 + 三层对比（整网 PSNR / 子算子 1e-5 / 跨引擎 ONNX）+ sha256 溯源"这套组合拳，把 127.5 dB 的精度对齐做成了可复现的工程流程——这正是任何模型移植项目都该抄的作业。