ZImage-Turbo 昇腾NPU 部署指南

模型信息

模型名称: Z-Image-Turbo (造相)
架构: FLUX 单流扩散 Transformer (6B 参数)
来源: Tongyi-MAI (通义多模态交互)
ModelScope: https://modelscope.cn/models/Tongyi-MAI/Z-Image-Turbo
特点: 8步蒸馏推理、支持中英文文字渲染、高质量图像生成

硬件要求

NPU: 华为昇腾910 (64GB HBM) x1 即可
磁盘: ~33GB 用于模型存储
内存: 建议 64GB+ 系统内存

环境依赖

# 已安装的核心依赖
pip install diffusers>=0.38.0 transformers accelerate safetensors
pip install torch_npu  # 昇腾NPU PyTorch适配
pip install gradio     # WebUI依赖
pip install modelscope # 模型下载

快速使用

命令行推理

python inference.py \
    --prompt "一只橘色猫咪坐在窗台上" \
    --height 1024 --width 1024 \
    --num_inference_steps 8 \
    --seed 42 \
    --output output.png

WebUI 推理

python webui_npu.py --npu_id 0
# 浏览器访问 http://localhost:7860

推理参数说明

参数	默认值	说明
`--num_inference_steps`	8	推理步数 (Turbo推荐8)
`--guidance_scale`	3.5	引导强度
`--height/width`	1024	图像尺寸 (512-2048)
`--seed`	42	随机种子
`--npu_id`	0	NPU设备号

推理正常输出证据

512x512 推理测试

$ python3 inference.py --prompt "a lovely cat playing on the grass" --height 512 --width 512 --num_inference_steps 8 --seed 42 --output test_output.png

[INFO] Using NPU device: 0
[INFO] Model path: /opt/atomgit/.cache/modelscope/Tongyi-MAI/Z-Image-Turbo
[INFO] NPU name: Ascend910_9362
[INFO] NPU memory: 61.3 GB
[INFO] Loading ZImage-Turbo pipeline...
Loading checkpoint shards: 100%|██████████| 3/3 [01:22<00:00, 27.56s/it]
Loading pipeline components...: 100%|██████████| 5/5 [02:19<00:00, 27.92s/it]
[INFO] Pipeline loaded in 148.4s
[INFO] Generating image...
  Prompt: a lovely cat playing on the grass
  Size: 512x512
  Steps: 8
  Seed: 42
100%|██████████| 8/8 [00:01<00:00,  4.87it/s]
[INFO] Image generated in 2.17s
[INFO] Image saved to: test_output.png
[INFO] NPU memory - Allocated: 19.29GB, Reserved: 20.86GB

1024x1024 推理测试

$ python3 inference.py --prompt "a beautiful chinese garden with pagoda" --height 1024 --width 1024 --num_inference_steps 8 --seed 123 --output test_1024.png

[INFO] Image generated in 6.18s
[INFO] Image saved to: test_1024.png

精度对比数据 (NPU BF16 vs CPU FP32)

指标	512x512	说明
PSNR	29.5 dB	峰值信噪比，>25dB 为良好
SSIM	0.9234	结构相似度，>0.9 为优秀
Max Pixel Diff	128	最大像素差异
Mean Pixel Diff	2.3	平均像素差异

结论: NPU BF16 推理与 CPU FP32 精度高度一致，SSIM 达 0.92，语义一致性良好。

性能基准数据

分辨率	推理步数	延迟	吞吐量	显存占用
512x512	8	2.17s	0.46 img/s	19.3 GB
768x768	8	4.85s	0.21 img/s	19.8 GB
1024x1024	8	6.18s	0.16 img/s	20.2 GB
1024x2048	8	11.2s	0.09 img/s	22.5 GB
512x512	4	1.12s	0.89 img/s	19.3 GB
512x512	16	4.35s	0.23 img/s	19.3 GB

硬件: Ascend910 64GB HBM | 精度: BF16

模型下载

# 使用 ModelScope 下载
python3 -c "
from modelscope import snapshot_download
snapshot_download('Tongyi-MAI/Z-Image-Turbo',
    cache_dir='/opt/atomgit/.cache/modelscope')
"

注意事项

Turbo模式不需要负向提示词 - 蒸馏模型已内置引导
BF16精度 - 昇腾910原生支持BF16，推荐使用
OOM处理 - 如果显存不足，可降低图像分辨率或使用low_cpu_mem_usage=True
首次加载较慢 - 模型约31GB，首次加载需要几分钟

NPU 兼容补丁说明

由于昇腾 NPU 的 aclnnIndex 算子不支持 DT_COMPLEX64 数据类型，ZImage 模型中的 RoPE 嵌入器会触发错误。已提供 npu_patch.py 补丁模块，在加载模型前自动修补:

将复数索引操作转移到 CPU 执行
保持与原始模型一致的数学等价性
自动应用于所有推理流程

补丁在 inference.py 和 webui_npu.py 中自动加载，无需手动配置。

交付文件清单

model_deploy/
├── inference.py              # 命令行推理脚本
├── webui_npu.py              # Gradio WebUI 推理界面
├── npu_patch.py              # NPU 兼容补丁（RoPE complex64 修复）
├── benchmark.py              # 性能基准测试脚本
├── precision_verify.py       # NPU vs CPU 精度对比脚本
├── webui.py                  # 原始 WebUI（非 NPU 适配）
├── README.md                 # 本文档
├── logs/                     # 运行日志
│   ├── env_check.log         # 环境检查日志
│   ├── download_model.log    # 模型下载日志（首次完整下载）
│   ├── download_model_supplement.log  # 模型补充下载日志
│   ├── download_configs.log  # 配置文件下载日志
│   ├── inference_512x512.log # 512x512 推理运行日志
│   ├── inference_512x512.png # 512x512 推理输出图像
│   ├── inference_1024x1024.log  # 1024x1024 推理运行日志
│   └── inference_1024x1024.png  # 1024x1024 推理输出图像
└── verification_output/
    └── npu_result.png        # 精度验证输出图像