Diffusers Ascend Pipeline

Diffusers 昇腾 NPU Pipeline 推理

本 Skill 指导用户在华为昇腾 NPU 上运行 HuggingFace Diffusers Pipeline 推理，适用于任意 Diffusers 模型。

使用顺序

按下面顺序使用本 Skill：

1. 先做预检，确认环境、NPU 和权重可用。
2. 再执行图像或视频 Pipeline 推理。
3. 需要时再启用内存优化、LoRA 或多卡推理。
4. 查询 API 时，按版本先定位 GitHub API 路径，再打开官网文档。

前置要求

快速开始

1. 预检

运行预检脚本，确认环境、NPU 内存和模型权重就绪：

python scripts/validate_pipeline.py --model ./my_model --device npu:0 --min-memory 16

检查项：

2. 图像模型推理

通用模式（适用于 FLUX、SDXL、SD3 等任何图像 Pipeline）：

import torch
import torch_npu

from diffusers import DiffusionPipeline

# 加载 Pipeline（自动识别 Pipeline 类型）
pipe = DiffusionPipeline.from_pretrained(
    "./my_model",
    torch_dtype=torch.bfloat16,
)
pipe = pipe.to("npu:0")

# 生成图像
generator = torch.Generator("npu").manual_seed(42)
image = pipe(
    prompt="a cat sitting on a windowsill, watercolor style",
    num_inference_steps=20,
    guidance_scale=3.5,
    generator=generator,
).images[0]

image.save("output.png")

使用脚本：

# FLUX.1-dev 推理
python scripts/run_pipeline.py \
    --model ./fake_flux_dev \
    --prompt "a cat sitting on a windowsill" \
    --device npu:0 --dtype bfloat16 \
    --steps 20 --seed 42 \
    --output flux_output.png --benchmark

# SDXL 推理
python scripts/run_pipeline.py \
    --model stabilityai/stable-diffusion-xl-base-1.0 \
    --prompt "a beautiful landscape" \
    --device npu:0 --dtype float16 \
    --steps 30 --guidance-scale 7.5 \
    --output sdxl_output.png --benchmark

3. 视频模型推理

视频 Pipeline（Wan、CogVideoX 等）输出帧序列，脚本自动检测并导出为 MP4：

import torch
import torch_npu

from diffusers import DiffusionPipeline
from diffusers.utils import export_to_video

pipe = DiffusionPipeline.from_pretrained(
    "./wan_model",
    torch_dtype=torch.bfloat16,
)
pipe = pipe.to("npu:0")

generator = torch.Generator("npu").manual_seed(42)
output = pipe(
    prompt="a dog running on the beach",
    num_inference_steps=30,
    generator=generator,
)

# 导出视频
export_to_video(output.frames[0], "output.mp4", fps=16)

使用脚本：

python scripts/run_pipeline.py \
    --model ./wan_model \
    --prompt "a dog running on the beach" \
    --device npu:0 --dtype bfloat16 \
    --steps 30 --seed 42 \
    --output wan_output.mp4 --benchmark

4. 内存优化

大模型推理时可能遇到 NPU 内存不足，可组合使用以下优化技术：

# 使用内存优化运行
python scripts/run_pipeline.py \
    --model ./fake_flux_dev \
    --prompt "a landscape" \
    --device npu:0 --dtype bfloat16 \
    --steps 20 \
    --attention-slicing --vae-tiling \
    --output optimized.png --benchmark

详细指南：references/memory-optimization.md

5. LoRA 集成

加载 LoRA 适配器增强生成效果：

import torch
import torch_npu

from diffusers import DiffusionPipeline

pipe = DiffusionPipeline.from_pretrained("./my_model", torch_dtype=torch.bfloat16)
pipe = pipe.to("npu:0")

# 加载 LoRA
pipe.load_lora_weights("./my_lora", adapter_name="style")

# 生成（控制 LoRA 强度）
image = pipe(
    prompt="a portrait in oil painting style",
    num_inference_steps=20,
    cross_attention_kwargs={"scale": 0.8},
).images[0]

多 LoRA 叠加：

pipe.load_lora_weights("./lora_style", adapter_name="style")
pipe.load_lora_weights("./lora_detail", adapter_name="detail")
pipe.set_adapters(["style", "detail"], adapter_weights=[0.7, 0.3])

使用脚本：

python scripts/run_pipeline.py \
    --model ./my_model \
    --prompt "a portrait" \
    --device npu:0 --dtype bfloat16 \
    --lora ./my_lora --lora-scale 0.8 \
    --output lora_output.png

详细指南：references/lora-guide.md

6. 多卡并行推理（Context Parallel）

从 diffusers>=0.36.0 开始，可参考 Parallel API 在多卡上做上下文并行（Context Parallel），核心入口为：

• ContextParallelConfig
• ParallelConfig
• apply_context_parallel

Ascend NPU 需使用 torch.distributed + hccl 后端启动多进程。

import os

import torch
import torch.distributed as dist
import torch_npu

from diffusers import ContextParallelConfig, DiffusionPipeline


def setup_dist():
    if not dist.is_initialized():
        dist.init_process_group(backend="hccl")
    local_rank = int(os.environ["LOCAL_RANK"])
    world_size = dist.get_world_size()
    torch.npu.set_device(local_rank)
    return local_rank, world_size


local_rank, world_size = setup_dist()
device = f"npu:{local_rank}"

pipe = DiffusionPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    torch_dtype=torch.bfloat16,
).to(device)

# NPU 推荐使用 _native_npu；CUDA 示例通常使用 _native_cudnn
pipe.transformer.set_attention_backend("_native_npu")

cp_config = ContextParallelConfig(ulysses_degree=world_size)
pipe.transformer.enable_parallelism(config=cp_config)

image = pipe(
    prompt="a tiny astronaut hatching from an egg on the moon",
    guidance_scale=3.5,
    num_inference_steps=30,
).images[0]

if dist.get_rank() == 0:
    image.save("flux_cp_output.png")

dist.destroy_process_group()

在单机 2 卡示例中可用：

torchrun --nproc_per_node=2 scripts/run_context_parallel.py \
    --model ./fake_flux_dev \
    --prompt "a tiny astronaut hatching from an egg on the moon" \
    --parallel-mode context \
    --device-type npu --backend hccl \
    --attention-backend _native_npu \
    --steps 20 --output flux_cp_output.png

若当前后端暂不支持 context parallel（例如底层 attention 内核限制），可退化为多进程 data parallel：

torchrun --nproc_per_node=2 scripts/run_context_parallel.py \
    --model ./fake_flux_dev \
    --prompt "a tiny astronaut hatching from an egg on the moon" \
    --parallel-mode data \
    --device-type npu --backend hccl \
    --steps 20 --output flux_dp_output.png

默认推荐直接使用 Ulysses Attention：

cp_config = ContextParallelConfig(ulysses_degree=world_size)
pipe.transformer.enable_parallelism(config=cp_config)

若需要，再按模型/后端特性切换到 Ring Attention：

cp_config = ContextParallelConfig(ring_degree=world_size)
pipe.transformer.enable_parallelism(config=cp_config)

若需要进一步调优，请优先查看官方 attention backend 文档：

• https://huggingface.co/docs/diffusers/v0.36.0/en/optimization/attention_backends
• 镜像：https://hf-mirror.com/docs/diffusers/v0.36.0/en/optimization/attention_backends

版本注意：

• diffusers>=0.36.0：可使用 api/parallel。
• diffusers<=0.35.2：仓库路径中无 docs/source/en/api/parallel.md，应退化为常规多进程并行（按卡拆分请求）或升级版本。

详细流程：references/distributed-inference.md

7. API 文档索引与按版本检索

当用户询问 "某个 API 怎么用" 时，不要先猜 URL，先按下面流程检索：

1. 读取用户实际版本（例如 0.35.2、0.36.0）。
2. 枚举对应 Tag 的 API 文件树：docs/source/en/api/**。
3. 根据用户问题定位具体路径（例如 parallel.md、pipelines/flux.md）。
4. 再映射到官网文档 URL；如果官网不可达，回退 hf-mirror。

路径映射规则：

• GitHub 源文件：
  • https://github.com/huggingface/diffusers/blob/v{version}/docs/source/en/api/{path}.md
• 官方文档：
  • https://huggingface.co/docs/diffusers/v{version}/en/api/{path}
• 镜像文档：
  • https://hf-mirror.com/docs/diffusers/v{version}/en/api/{path}

示例：parallel.md 在 v0.36.0 存在，但在 v0.35.2 的 API 路径中不存在。

详细索引：references/api-navigation.md

性能基准测试

使用 benchmark 脚本测量推理性能：

python scripts/benchmark_pipeline.py \
    --model ./model_weights \
    --prompt "a photo of a cat" \
    --num-runs 5 \
    --warmup-runs 1 \
    --output-json benchmark_results.json

关键指标：

脚本参考

run_pipeline.py

通用 Pipeline 推理脚本，支持任意 Diffusers 模型：

validate_pipeline.py

推理前预检脚本：

benchmark_pipeline.py

详细性能基准测试脚本：

run_context_parallel.py

多卡 context parallel 推理脚本（需配合 torchrun）：

常见模型参考

常见问题

NPU 内存不足（OOM）

RuntimeError: NPU out of memory

解决：启用内存优化（--attention-slicing --vae-tiling），使用 bfloat16，减少分辨率或步数。

首次推理很慢

NPU 首次推理需要编译计算图，后续推理速度正常。脚本的 --benchmark 模式会自动进行预热。

Generator 设备错误

RuntimeError: Expected a 'npu' device type for generator

解决：使用 torch.Generator("npu") 而非 torch.Generator("cpu")。

CPU Offload 不生效

accelerate 的设备钩子可能不完全支持 npu。建议优先使用 attention slicing 和 VAE tiling。

更多问题：references/troubleshooting.md

参考资源

• 环境配置 - Phase #1: CANN + torch_npu 环境搭建
• 权重准备 - Phase #2: 模型下载与假权重生成
• 内存优化详解 - NPU 内存优化完整指南
• LoRA 详解 - LoRA 加载、多 LoRA、权重融合
• 多卡并行推理 - Context Parallel 与 torchrun 多卡执行
• API 检索索引 - 按版本定位 Diffusers API 路径与文档 URL
• 故障排查 - NPU 推理常见问题与修复
• Diffusers 官方文档
• 昇腾 PyTorch 扩展