SLAI Diffusers Adapter

SLAI-Diffusers-Adapter 是面向昇腾 910C / NPU 环境的 Diffusers 文生图模型适配资产库。仓库保存可复用的迁移流程、推理脚本、性能测试脚本、优化脚本和质量评测记录，不保存模型权重和生成图片数据集。

适用场景：

• 把 Hugging Face / Diffusers 文生图模型迁移到昇腾 NPU 上运行。
• 复用已经完成适配的模型脚本，快速做 NPU 推理、测速和质量评测。
• 按统一目录和元数据标准沉淀新的模型适配结果，方便后续合并和复查。

目录结构

SLAI-Diffusers-Adapter/
  migration/                  # 新模型迁移工作流、提示词、技能文档和交付模板
    MIGRATION_PLAN.md
    MERGE_READY_TEMPLATE.md
    prompts/
    skills/
  adapted_models/             # 已适配模型的脚本、环境、报告和评测结果
    README.md
    ref_code/                 # IS / FID 等评测工具
    eval_env/                 # 评测环境
    reports/                  # 汇总报告
    {MODEL_NAME}/
      migration/              # 基线 NPU 推理、测速和迁移报告
      optimization/           # 优化推理、优化测速和对比报告
      generation_quality/     # MSCOCO 生成脚本与 IS / FID 结果

已包含模型

当前仓库包含以下模型的适配资产：

• CogView4-6B
• FLUX.1-dev
• FLUX.2-dev
• FLUX.2-klein-9B
• GLM-Image
• LongCat-Image
• Qwen-Image
• Z-Image
• stable-diffusion-3.5-large

快速使用

模型权重需要放在仓库外部，例如：

/mnt/model/image_model/{MODEL_NAME}

运行基线 NPU 推理：

cd adapted_models/{MODEL_NAME}/migration
source /usr/local/Ascend/ascend-toolkit/set_env.sh
uv run python infer_npu.py --model-path /mnt/model/image_model/{MODEL_NAME}

部分模型使用了模型专属脚本名，例如 flux1_npu_inference.py 或 run_*.py。进入对应模型目录后可以先查看：

ls *.py

运行基线测速：

cd adapted_models/{MODEL_NAME}/migration
source /usr/local/Ascend/ascend-toolkit/set_env.sh
uv run python benchmark.py

运行优化后测速：

cd adapted_models/{MODEL_NAME}/optimization
source /usr/local/Ascend/ascend-toolkit/set_env.sh
uv run python benchmark_optimized.py

运行生成质量评测脚本：

cd adapted_models/{MODEL_NAME}/generation_quality
source /usr/local/Ascend/ascend-toolkit/set_env.sh
uv run python run_{MODEL_NAME}_npu_coco_generation.py

生成图片、MSCOCO 数据集、模型权重、缓存目录和运行输出不进入本仓库；它们应保存在外部运行目录中。

适配新模型

新增模型时，建议从 migration/MIGRATION_PLAN.md 开始，按以下流程执行：

1. 准备本地 Hugging Face / Diffusers 模型权重目录。
2. 在 adapted_models/{MODEL_NAME}/migration/ 下创建 uv 环境、NPU 推理脚本和基线测速脚本。
3. 记录硬件、CANN、PyTorch、torch-npu、NPU 型号和推理设置来源。
4. 在 adapted_models/{MODEL_NAME}/optimization/ 下加入可复用优化脚本，并与基线做同条件对比。
5. 在 adapted_models/{MODEL_NAME}/generation_quality/ 下加入 MSCOCO 生成脚本，保存 IS / FID 摘要结果。
6. 按 migration/MERGE_READY_TEMPLATE.md 补齐标准文件后再合并。

新模型完成适配后，推荐目录形态如下：

adapted_models/{MODEL_NAME}/
  migration/
    pyproject.toml
    uv.lock
    infer_npu.py
    benchmark.py
    hardware.json
    benchmark_result.json
    MIGRATION_REPORT.md
  optimization/
    pyproject.toml
    uv.lock
    infer_optimized.py
    benchmark_optimized.py
    npu_optimizations.py
    benchmark_comparison.json
    OPTIMIZATION_REPORT.md
  generation_quality/
    run_{MODEL_NAME}_npu_coco_generation.py
    generation_config.json
    is_score.txt
    fid_score.txt

交付标准

• 推理脚本应优先支持 --model-path、--prompt、--output、--device、--num-inference-steps、--height、--width、--guidance-scale、--seed、--dtype 等通用参数。
• 测速结果必须记录 NPU 型号，优先使用 torch.npu.get_device_properties(device_id).name 获取。
• 速度测试和质量测试应遵循 Hugging Face 模型卡或官方 Diffusers 文档推荐的 scheduler、分辨率、guidance scale 和推理步数。
• 非 step-distilled 模型在官方文档没有特殊说明时，质量评测默认使用约 50 个推理步。
• step-distilled、turbo、lightning、LCM 等少步模型应使用官方推荐的低步数设置，不应强行改成 50 步。
• 基线和优化版本做速度对比时，prompt、seed、dtype、分辨率、scheduler、guidance scale 和推理步数必须保持一致。

不包含的内容

本仓库不保存以下内容：

• Hugging Face 模型权重。
• .safetensors、.bin、.pt、.pth、.ckpt、.onnx 等大文件。
• .venv、__pycache__、kernel_meta、运行缓存和临时目录。
• MSCOCO 生成图片、评测图片集和本地输出图片。

这些内容请放在独立模型目录或运行目录中，通过脚本参数传入。