WavyFusion on Ascend NPU

1. 简介

本文档记录 wavymulder/wavyfusion（Stable Diffusion 1.5 Fine-tune）在 Ascend 910B4 NPU 环境下的适配部署与验证结果。

WavyFusion 是一个基于 Stable Diffusion 1.5 的微调模型，能生成波浪/迷幻风格的艺术图像。

2. 验证环境

组件	版本
`torch`	`2.9.0`
`torch-npu`	`2.9.0.post1+gitee7ba04`
`diffusers`	`0.38.0`
`transformers`	`4.57.6`
`accelerate`	`1.13.0`

NPU：Ascend 910B4 × 1 卡（32GB HBM）
模型路径：/opt/atomgit/models/wavyfusion
CANN 版本：8.5.1

3. 环境准备

安装依赖

pip install torch torch_npu diffusers transformers accelerate

模型权重下载

从 HuggingFace 镜像下载（国内推荐）：

import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
from huggingface_hub import snapshot_download
snapshot_download('wavymulder/wavyfusion', local_dir='./model')

或使用 HuggingFace 直连：

git lfs clone https://huggingface.co/wavymulder/wavyfusion

4. 推理脚本

单张图片生成：

python3 inference.py \
  --prompt "a beautiful landscape in wavy art style, surreal waves of color" \
  --steps 25 \
  --seed 42 \
  --output output.png

参数说明：

参数	默认值	说明
`--prompt`	`"a beautiful landscape..."`	文本提示词
`--seed`	`42`	随机种子
`--steps`	`25`	推理步数
`--guidance`	`7.5`	CFG 引导尺度
`--output`	`output.png`	输出图片路径
`--benchmark`	`False`	是否运行性能基准

5. 性能参考

测试条件：单卡 Ascend 910B4，torch.float16，512×512 输出分辨率。

推理步数	平均延迟	吞吐量 (steps/s)
20	`1.45s`	`13.8`
25	`1.80s`	`13.9`
30	`2.20s`	`13.6`

注：首次推理包含 NPU 图编译开销（约 80-90s），以上为 warm cache 后的稳态性能。

多 Prompt 基准测试

Prompt	Steps	延迟	Steps/s
a cat in a wavy dreamlike style	25	1.81s	13.8
a beautiful landscape with wavy mountains	25	1.80s	13.9
portrait of a woman, wavy abstract style	25	1.80s	13.9
a cosmic galaxy with swirling waves	25	1.78s	14.0
an underwater scene with wavy coral	25	1.78s	14.0

6. 精度评测

6.1 NPU 内部精度（fp16 vs fp32）

对比 NPU float16 和 NPU float32 在相同种子下的输出差异：

指标	数值
MAE (0-255)	`0.4738`
RMSE	`0.9333`
Max Pixel Diff	`31.0`
相对误差	`0.51%`
PSNR	`48.73 dB`
结论	PASS (< 1%)

6.2 CPU vs NPU 精度对比（相同初始噪声）

使用完全相同的初始噪声张量（CPU 生成）输入 CPU(fp32) 和 NPU 管道，排除 PRNG 差异后的真实计算精度对比：

对比项	相对误差	PSNR	直方图相关性	结论
CPU(fp32) vs NPU(fp16)	0.36%	47.82 dB	0.9972	PASS ✅
CPU(fp32) vs NPU(fp32)	0.23%	51.59 dB	0.9965	PASS ✅
NPU(fp16) vs NPU(fp32)	0.26%	49.77 dB	0.9986	PASS ✅

6.3 精度说明

NPU 计算精度合格：在控制初始噪声一致的前提下，NPU fp16 与 CPU fp32 的像素误差仅 0.36%，远低于 1% 阈值
PRNG 差异说明：torch.Generator(device='cpu') 与 torch.Generator(device='npu') 在同一种子下产生不同的随机噪声序列。这是不同后端 PRNG 实现差异，非计算精度问题。NPU 自身可复现（同 seed → 同输出）
fp16 推荐：NPU fp16 与 fp32 输出差异仅 0.26%，视觉上无差异，推荐使用 fp16 推理以充分利用 NPU 带宽

7. 适配说明

关键点

无需代码修改：StableDiffusionPipeline 通过 pipe.to("npu") 即可切换到 NPU 设备，无需模型代码改动。
GEGLU 算子：diffusers 0.38.0 在 torch_npu 环境下自动调用 torch_npu.npu_geglu() 融合算子优化推理速度。
设备切换：diffusers 基于 torch_npu 的 PrivateUse1 后端自动完成算子分发。

注意事项

首次推理包含 ACL Graph 编译开销，建议先 warmup 一次再测性能
CPU 上运行需要 patch is_torch_npu_available() 防止调用 npu_geglu（NPU 推理无需此操作）
推荐使用 torch.float16 推理以充分利用 NPU 带宽和减少显存占用

8. 参考文档