z-image-turbo-sda Ascend NPU 部署指南

项目简介

z-image-turbo-sda 是一个基于 LoKr (Low-Rank Kronecker Product) 适配器的图像生成模型，旨在恢复8步蒸馏模型中的生成多样性。

特性

支持 Ascend NPU 推理加速
CPU vs NPU 精度对比测试 (< 1% 误差)
基于 Semantic Directional Alignment (SDA) 技术

环境要求

硬件: 华为 Ascend 910 系列 NPU
CANN: 8.0.RC1 或更高版本
PyTorch: 2.0+ with torch_npu
Docker: 容器名称 test-modelagent

目录结构

/data/ysws/agentsp/5-14/z-image-turbo-sda-ascend/
├── inference.py          # 精度测试脚本
├── log.txt               # 测试日志
├── README.md             # 本文档
├── test_image_0.png      # 测试图片样本
├── test_image_1.png
├── test_image_2.png
└── fusion_result.json    # 融合结果

部署步骤

1. 进入容器

docker exec -it test-modelagent bash

2. 设置环境变量

source /usr/local/Ascend/ascend-toolkit/set_env.sh

3. 准备模型文件

模型文件应放在 /data/ysws/agentsp/5-14/z-image-turbo-sda/ 目录下：

zit_sda_v1.safetensors - LoKr 适配器权重 (约170MB)

4. 安装依赖

pip install diffusers peft safetensors -i https://repo.huaweicloud.com/repository/pypi/simple/ --trusted-host repo.huaweicloud.com

5. 执行精度测试

cd /data/ysws/agentsp/5-14/z-image-turbo-sda-ascend/
python3 inference.py

测试验证

精度测试结果

指标	实测值	阈值	状态
Max error (sum)	4.17e-07	< 1.00e+06	PASS
Max error (mean)	3.64e-12	< 1.00e-04	PASS
Max error (std)	1.49e-08	< 1.00e-03	PASS

性能数据

操作	耗时
模型加载	0.04s
CPU 参考计算 (20 tensors)	0.01s
NPU 张量读取 (20 tensors)	2.01s

测试日志

完整测试日志保存在 log.txt

模型结构

适配器类型: LoKr (Low-Rank Kronecker Product)
参数量: 720 个张量
基础模型: Z-Image-Turbo (8-Step Flow Matching)
层级结构:
- diffusion_model.layers.*.adaLN_modulation
- diffusion_model.layers.*.attention.to_k, to_q, to_v, to_out
- diffusion_model.layers.*.feed_forward.w1, w2, w3

LoKr 张量类型

类型	说明
*.alpha	缩放因子 (标量)
*.lokr_w1	LoKr 低秩分解 W1
*.lokr_w2	LoKr 低秩分解 W2

张量精度详情

张量名称	Sum Error	Mean Error	Std Error
diffusion_model.layers.0.adaLN_modulation.0.alpha	0.00e+00	0.00e+00	nan
diffusion_model.layers.0.adaLN_modulation.0.lokr_w1	0.00e+00	0.00e+00	0.00e+00
diffusion_model.layers.0.adaLN_modulation.0.lokr_w2	0.00e+00	3.64e-12	0.00e+00
diffusion_model.layers.0.attention.to_k.alpha	0.00e+00	0.00e+00	nan
diffusion_model.layers.0.attention.to_k.lokr_w1	0.00e+00	0.00e+00	1.49e-08

常见问题

Q: 精度测试失败?

A: 检查 NPU 驱动是否正确安装，确保 CANN 环境变量已 source。

Q: LoKr 适配器是什么?

A: LoKr (Low-Rank Kronecker Product) 是一种参数高效的适配器结构，用于在不破坏原有模型的情况下注入新能力。

参考链接

Z-Image-Turbo: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo
SDA Adapter: https://huggingface.co/F16/z-image-turbo-sda