目标模型: SeeSee21/Z-Anime（基于 Tongyi-MAI/Z-Image 的动漫风格 Stable Diffusion Transformer） 目标硬件: Atlas 800 A2 (Ascend 910B4) 软件栈: CANN 8.5.1, torch_npu 2.9.0.post1, diffusers >= 0.37.0.dev0, transformers >= 4.51.0
z-anime-npu/
|-- npu_compat.py # NPU 适配层：算子兼容性修复 + torch_npu 亲和算子替换
|-- infer_npu.py # 昇腾 NPU text-to-image 推理脚本
|-- README.md # 部署与使用文档（本文件）
|-- REPORT.md # 完整适配报告（架构分析、性能数据、精度评估）
|-- models/ # 模型权重缓存目录（运行后自动生成）
| |-- Tongyi-MAI/Z-Image # 基座模型（已验证）
| `-- SeeSee21/Z-Anime # 动漫微调模型（需自行下载）
`-- *.png # 推理输出样例# 1. 确认 CANN 和 torch_npu 已正确安装
python -c "import torch; import torch_npu; print(torch.npu.get_device_name(0))"
# 期望输出: Ascend910B4
# 2. 安装依赖
pip install git+https://github.com/huggingface/diffusers
pip install transformers accelerate modelscope基座模型 Tongyi-MAI/Z-Image（国内可直接从 ModelScope 下载）：
python -c "
from modelscope import snapshot_download
snapshot_download('Tongyi-MAI/Z-Image', cache_dir='./models')
"动漫风格模型 SeeSee21/Z-Anime（需 HuggingFace 访问或镜像）：
# 方式 1: 直接下载（需能访问 huggingface.co）
HF_HOME=./models huggingface-cli download SeeSee21/Z-Anime
# 方式 2: 使用镜像
HF_ENDPOINT=https://hf-mirror.com HF_HOME=./models huggingface-cli download SeeSee21/Z-AnimeZ-Anime 是 Z-Image 的动漫风格微调版本，适配层
npu_compat.py完全兼容，无需额外修改。
# Baseline（仅兼容性修复，原生 PyTorch 算子）
python infer_npu.py \
--model ./models/Tongyi-MAI/Z-Image \
--prompt "1girl, anime style, best quality" \
--height 512 --width 512 \
--steps 28 --baseline \
--output output_baseline.png
# Optimized（启用 torch_npu 融合算子）
python infer_npu.py \
--model ./models/Tongyi-MAI/Z-Image \
--prompt "1girl, anime style, best quality" \
--height 512 --width 512 \
--steps 28 --optimized \
--output output_optimized.png
# Optimized + 运行时流水优化（推荐生产环境）
TASK_QUEUE_ENABLE=2 python infer_npu.py \
--model ./models/Tongyi-MAI/Z-Image \
--prompt "1girl, anime style, best quality" \
--height 512 --width 512 \
--steps 28 --optimized \
--output output_prod.png| 参数 | 说明 | 推荐值 |
|---|---|---|
--height, --width | 生成图像分辨率 | 512~2048（任意宽高比） |
--steps | 推理步数 | 28 |
--guidance_scale | CFG 强度 | 3.0~5.0 |
--dtype | 计算精度 | bf16（默认，推荐） |
--optimized | 启用融合算子 | 生产环境建议开启 |
--no_attention_fusion | 禁用 Attention 融合 | 如需像素级可复现性时开启 |
--warmup | 预热轮数 | >=1（首次推理需编译算子） |
--benchmark | Benchmark 轮数 | >=3（用于性能统计） |
npu_compat.py)无论是否启用 --optimized，NPU 运行时都会自动应用以下修复：
| 修复项 | 问题描述 | 解决方案 |
|---|---|---|
RopeEmbedder complex64 索引 | Ascend NPU 不支持 DT_COMPLEX64 类型的 index/aclnnIndex | 预计算保持在 CPU，索引后转移至 NPU |
--optimized）| 原算子 | 替换为 | 适用场景 | 精度差异 |
|---|---|---|---|
手写 RMSNorm (pow->mean->rsqrt) | npu_rms_norm | Qwen3 TextEncoder + Z-Image DiT | ~0.008 (bf16) |
SwiGLU (SiLU(x1)*x3) | npu_swiglu | Qwen3 MLP + Z-Image FeedForward | ~0.06 (bf16) |
| SDPA Attention | npu_fusion_attention | Z-Image DiT joint attention | ~2.0 (bf16) |
注意:
npu_rotary_mul对 Qwen3 的 BNSD layout 存在 shape broadcast 限制，当前版本未启用 Qwen3 RoPE 替换。Qwen3 TextEncoder 已通过 transformers SDPA 后端获得加速。
Atlas 800 A2 (910B4), CANN 8.5.1, bf16, 512x512:
| 配置 | 4 steps | 28 steps |
|---|---|---|
| Baseline (compat only) | 1.027s | 5.624s |
| Optimized (算子融合) | 1.005s | 5.624s |
Optimized + TASK_QUEUE_ENABLE=2 | 0.945s | 5.492s |
首次推理说明: 首次 NPU 推理包含 CANN 算子编译开销（约 60s），预热后消失。生产环境务必先执行 warmup。
融合算子与原生算子在 bf16 精度下存在微小差异：
对于扩散模型，这些差异会在多步迭代中被放大，导致像素级不一致。但两次 Baseline 运行（同 seed）可完全复现（MSE=0）。
如需与 CUDA/CPU 基线保持像素级一致，可使用：
python infer_npu.py --optimized --no_attention_fusion ...此时保留 RMSNorm + SwiGLU 融合（性能收益较小），但禁用 Attention 融合（主要精度差异来源）。
Q1: 首次推理为什么特别慢？ A: Ascend NPU 首次运行需要 JIT 编译算子并生成缓存，约 60s。第二次起恢复正常。
Q2: 能否使用 Z-Anime 替代 Z-Image？ A: 可以。Z-Anime 是 Z-Image 基座 + 动漫风格微调，架构完全相同，直接替换模型路径即可。
Q3: 显存不足 (OOM) 怎么办？ A: 10B 参数 bf16 模型在 512x512 下约需 19~21GB。若 OOM，尝试：
--dtype fp16（部分算子可能回退）PYTORCH_NPU_ALLOC_CONF=max_split_size_mb:512Q4: 如何确认融合算子已生效？
A: 运行时会打印 [npu_compat] Patched xxx。也可通过 CANN Profiling 查看实际算子名称。