Z-Image-Fun-Lora-Distill 是阿里云 PAI 团队开发的一组 LoRA 蒸馏权重，用于加速 Z-Image 文本到图像生成模型的推理。该模型通过蒸馏技术同时优化了步数和 CFG（Classifier-Free Guidance），使得推理只需 2-8 步即可完成，大幅提升了生成速度。
主要特点：
模型变体：
| 模型名称 | 步数 | 说明 |
|---|---|---|
| Z-Image-Fun-Lora-Distill-2-Steps-2603.safetensors | 2步 | 最快速度，推荐 sigma 0.5-0.8 |
| Z-Image-Fun-Lora-Distill-4-Steps-2603.safetensors | 4步 | 平衡速度与质量 |
| Z-Image-Fun-Lora-Distill-8-Steps-2603.safetensors | 8步 | 最高质量 |
# 安装基础依赖
pip install diffusers transformers safetensors accelerate
pip install imageio einops ftfy
# 安装 VideoX-Fun（可选，用于完整功能）
pip install git+https://github.com/aigc-apps/VideoX-Fun.git
# 如果 decord 安装失败，可以创建 mock 模块（仅用于 T2I 推理）
mkdir -p /tmp/decord
cat > /tmp/decord/__init__.py << 'EOF'
class VideoReader:
def __init__(self, *args, **kwargs): pass
def __getitem__(self, idx): return None
def __len__(self): return 0
EOF# 下载基础模型
huggingface-cli download Tongyi-MAI/Z-Image --local-dir ./base_model
# 下载 LoRA 权重
huggingface-cli download alibaba-pai/Z-Image-Fun-Lora-Distill --local-dir ./model使用提供的 inference.py 脚本：
# 基础推理
PYTHONPATH=/tmp:$PYTHONPATH python3 inference.py \
--prompt "A beautiful sunset over the ocean" \
--height 1024 --width 1024 \
--num_inference_steps 4 \
--lora_weight 0.8 \
--output_dir output| 参数 | 默认值 | 说明 |
|---|---|---|
--model_path | ./base_model | Z-Image 基础模型路径 |
--lora_path | ./model/...4-Steps-2603.safetensors | LoRA 权重路径 |
--prompt | - | 文本提示词 |
--height | 1024 | 图像高度 |
--width | 1024 | 图像宽度 |
--num_inference_steps | 4 | 推理步数（2/4/8） |
--guidance_scale | 1.0 | CFG 引导强度（蒸馏模型建议 1.0） |
--lora_weight | 0.8 | LoRA 权重 |
--device | npu:0 | 设备 |
--warmup_runs | 1 | 预热次数 |
--benchmark_runs | 3 | 基准测试次数 |
# 512x512 快速验证
PYTHONPATH=/tmp:$PYTHONPATH python3 inference.py \
--prompt "A beautiful sunset" \
--height 512 --width 512 \
--num_inference_steps 4 \
--warmup_runs 1 --benchmark_runs 1 \
--output_dir output/smoke_test验证结果：
推理脚本会在输出目录生成 PNG 格式图像，文件名为 image_XXX.png。
| 配置 | 分辨率 | 步数 | 平均延迟 | 吞吐量 |
|---|---|---|---|---|
| 2-Steps-2603 | 512x512 | 2 | 0.46s | 2.18 img/s |
| 4-Steps-2603 | 512x512 | 4 | 0.76s | 1.31 img/s |
| 4-Steps-2603 | 1024x1024 | 4 | 2.19s | 0.46 img/s |
Q: 出现 "NPU function error: call aclnnIndex failed" A: 这是 NPU 不支持 complex64 导致的，已通过 RoPE 补丁解决。
Q: 如何使用 ControlNet？ A: 参考 VideoX-Fun 项目文档，可加载 Z-Image-Fun-Controlnet-Union-2.1 权重。
Q: 如何获得更高质量？ A: 增加步数（使用 8-step 模型）或使用原始 Z-Image 模型。
NPU vs CPU 精度对比（CPU 为基线，NPU 为验证目标）：
| 指标 | 数值 |
|---|---|
| 测试用例数 | 待运行 |
| 最大 logits 差异 | 待运行 |
| 预测一致性 | 待运行 |
| 精度要求 | NPU vs CPU 最大 logits 误差 < 1% |
| 精度结论 | 待运行 |
精度评测源代码和日志详见 eval/ 目录。