Qwen-Image-Lightning Ascend Adapter

1. 模型信息

项目	内容
模型名称	Qwen-Image-Lightning
模型来源	ModelScope
基础模型	Qwen/Qwen-Image
模型类型	文生图 (text-to-image)
框架	Diffusers
推荐硬件	华为昇腾 Ascend 910B/B1（HBM >= 32GB）

2. 环境准备

2.1 硬件与驱动

• 华为昇腾 Ascend 910 系列 NPU
• CANN >= 8.0
• Driver >= 24.0

2.2 软件依赖

# 激活 CANN 环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 安装 Python 依赖
pip install torch>=2.5.0 torch_npu>=2.5.0
pip install diffusers>=0.38.0 transformers>=4.45.0
pip install accelerate safetensors packaging Pillow numpy

# 可选：国内模型下载加速
pip install modelscope

2.3 模型下载

# 使用 ModelScope 下载（推荐国内环境）
python3 -c "
from modelscope import snapshot_download
snapshot_download('lightx2v/Qwen-Image-Lightning', local_dir='/tmp/qwen-image-lightning')
snapshot_download('Qwen/Qwen-Image', local_dir='/tmp/qwen-image-base')
"

或从 Hugging Face 下载：

pip install huggingface_hub
huggingface-cli download lightx2v/Qwen-Image-Lightning --local-dir /tmp/qwen-image-lightning
huggingface-cli download Qwen/Qwen-Image --local-dir /tmp/qwen-image-base

3. 快速部署

3.1 环境检查

python3 qwen_image_lightning_env_check.py

3.2 单图推理

python3 inference.py \
  --base-model /tmp/qwen-image-base \
  --lightning-path /tmp/qwen-image-lightning \
  --weight-name Qwen-Image-Lightning-4steps-V1.0-bf16.safetensors \
  --steps 4 --dtype bf16 \
  --prompt "a cat wearing a space suit" \
  --output output.png

3.3 批量推理

创建 prompts.txt：

a cat wearing a space suit
a futuristic city at sunset
an astronaut riding a horse in space

运行：

python3 inference.py \
  --prompt-file prompts.txt \
  --output-dir outputs/ \
  --steps 4 --dtype bf16

3.4 大图像优化

python3 inference.py \
  --width 2048 --height 2048 \
  --vae-slicing \
  --steps 8

4. 关键参数说明

参数	说明	推荐值
--base-model	基础模型路径或 HuggingFace ID	/tmp/qwen-image-base
--lightning-path	Lightning LoRA 权重目录	/tmp/qwen-image-lightning
--weight-name	LoRA 权重文件名	Qwen-Image-Lightning-4steps-V1.0-bf16.safetensors
--dtype	数据类型	bf16（昇腾推荐）
--steps	推理步数	4（快速）/ 8（质量更好）
--device	目标设备	auto（自动检测 NPU）
--vae-slicing	启用 VAE Slicing	大图像时建议开启
--vae-tiling	启用 VAE Tiling	超大图像（>2048）建议开启
--compile	尝试 torch.compile	需确认昇腾支持
--seed	随机种子	固定种子保证可复现性

5. 性能优化

5.1 环境变量优化

# 启用 TaskQueue 流水优化
export TASK_QUEUE_ENABLE=1

# CPU 绑核优化
export CPU_AFFINITY_CONF=1

# 内存分配器调优
export PYTORCH_NPU_ALLOC_CONF=max_split_size_mb:512

# 使用 tcmalloc（如已安装）
export LD_PRELOAD=/usr/lib/libtcmalloc.so.4

5.2 推理参数优化

• 使用 bf16 而非 fp16 或 fp32
• 4步推理适合快速预览，8步推理适合生产环境
• 开启 --vae-slicing 可降低大图像的峰值显存

6. 精度与性能评测

评测脚本位于 evaluation/ 目录：

# 一键运行测试（冒烟测试）
cd evaluation
python3 test_run.py --steps 4 --width 512 --height 512

# 精度评测
python3 precision_eval.py --save-diff

# 性能评测
python3 performance_eval.py --output performance_report.json

详见 evaluation/README.md。

运行测试结果

7. 文件结构

.
├── inference.py              # 标准推理入口
├── readme.md                 # 部署文档
├── requirements.txt          # Python 依赖
├── qwen_image_lightning_env_check.py   # 环境检查脚本
├── qwen_image_lightning_test_load.py   # 模型加载预检
├── evaluation/
│   ├── test_run.py           # 运行测试（一键冒烟测试）
│   ├── precision_eval.py     # 精度评测源代码
│   ├── performance_eval.py   # 性能评测源代码
│   ├── README.md             # 评测说明文档
│   ├── logs/                 # 运行日志
│   │   ├── env_check_*.log
│   │   ├── npu_info_*.log
│   │   └── inference_*.log
│   ├── screenshots/          # 自验证截图/文本
│   │   ├── npu_smi_info.txt
│   │   ├── npu_properties.txt
│   │   ├── package_versions.txt
│   │   └── verification_report.md
│   └── images/               # 评测生成的图像
└── Qwen-Image-Lightning_昇腾适配报告.md   # 详细适配报告

8. 常见问题

Q: NPU 报 torch.compile 失败？
A: 当前昇腾对 diffusers pipeline 的图编译支持有限，失败会自动回退到 eager 模式，不影响推理。

Q: 显存不足？
A: 开启 --vae-slicing 或 --vae-tiling，并确保使用 bf16 而非 fp32。

Q: 模型下载慢？
A: 使用 ModelScope 镜像，或预先下载到本地路径后通过 --base-model / --lightning-path 指定。

9. License

本项目遵循 Apache 2.0 协议。