Diffusers 昇腾 NPU Pipeline 推理

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

使用顺序

按下面顺序使用本 Skill：

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

前置要求

| 依赖 | 说明 | 参考 | |------|------|------| | CANN + torch_npu | NPU 运行环境 | diffusers-ascend-env-setup | | 模型权重 | 真实权重或假权重 | diffusers-ascend-weight-prep | | diffusers | pip install diffusers["torch"] transformers accelerate | |

快速开始

1. 预检

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

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

检查项：

| 检查项 | 说明 | |--------|------| | Python 包 | torch, torch_npu, diffusers, transformers | | CANN 环境 | ASCEND_HOME_PATH 等环境变量 | | NPU 可用性 | 设备数量和名称 | | NPU 内存 | 空闲内存是否满足最低要求 | | 模型权重 | model_index.json 存在，组件完整 |

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 内存不足，可组合使用以下优化技术：

| 技术 | 方法 | NPU 兼容 | 内存节省 | |------|------|---------|---------| | Attention Slicing | pipe.enable_attention_slicing() | ✅ 验证通过 | 中等 | | VAE Slicing | pipe.enable_vae_slicing() | ✅ 验证通过 | 低 | | VAE Tiling | pipe.enable_vae_tiling() | ✅ 验证通过 | 高（高分辨率） | | BF16 推理 | torch_dtype=torch.bfloat16 | ✅ 推荐 | 约 50% | | Sequential CPU Offload | pipe.enable_sequential_model_cpu_offload() | ⚠️ 实验性 | 很高 | | Model CPU Offload | pipe.enable_model_cpu_offload() | ⚠️ 实验性 | 高 |

# 使用内存优化运行
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，先按下面流程检索：

读取用户实际版本（例如 0.35.2、0.36.0）。
枚举对应 Tag 的 API 文件树：docs/source/en/api/**。
根据用户问题定位具体路径（例如 parallel.md、pipelines/flux.md）。
再映射到官网文档 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

关键指标：

| 指标 | 说明 | |------|------| | 首次推理延迟 | 含图编译/缓存构建，通常较慢 | | 平均推理延迟 | 稳态性能（排除预热） | | P50 / P95 延迟 | 延迟分布 | | NPU 内存峰值 | torch.npu.max_memory_allocated() | | 吞吐量 | images/sec 或 frames/sec |

脚本参考

run_pipeline.py

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

| 参数 | 必需 | 默认 | 说明 | |------|------|------|------| | --model | 是 | - | 模型路径（本地目录或 HF 模型 ID） | | --prompt | 是 | - | 生成提示词 | | --device | 否 | npu:0 | 目标设备 | | --dtype | 否 | bfloat16 | 数据类型：float32, float16, bfloat16 | | --steps | 否 | 20 | 推理步数 | | --seed | 否 | 42 | 随机种子 | | --output | 否 | output.png | 输出文件（.png 图像 / .mp4 视频） | | --width | 否 | 模型默认 | 输出宽度 | | --height | 否 | 模型默认 | 输出高度 | | --guidance-scale | 否 | 3.5 | Classifier-free guidance | | --lora | 否 | - | LoRA 权重路径 | | --lora-scale | 否 | 1.0 | LoRA 强度 | | --attention-slicing | 否 | 关闭 | 启用 attention slicing | | --vae-slicing | 否 | 关闭 | 启用 VAE slicing | | --vae-tiling | 否 | 关闭 | 启用 VAE tiling | | --cpu-offload | 否 | 关闭 | 启用 sequential CPU offload | | --benchmark | 否 | 关闭 | 打印详细计时指标 |

validate_pipeline.py

推理前预检脚本：

| 参数 | 必需 | 默认 | 说明 | |------|------|------|------| | --model | 否 | - | 模型路径（提供时检查权重结构） | | --device | 否 | npu:0 | 目标设备 | | --min-memory | 否 | 16 | 最低空闲 NPU 内存（GB） |

benchmark_pipeline.py

详细性能基准测试脚本：

| 参数 | 必需 | 默认 | 说明 | |------|------|------|------| | --model | 是 | - | 模型权重路径 | | --prompt | 是 | - | 生成提示词 | | --device | 否 | npu:0 | 设备 | | --dtype | 否 | bfloat16 | 数据类型 | | --steps | 否 | 20 | 推理步数 | | --warmup-runs | 否 | 1 | 预热次数 | | --num-runs | 否 | 5 | 测试次数 | | --attention-slicing | 否 | 关闭 | 启用 attention slicing | | --vae-slicing | 否 | 关闭 | 启用 VAE slicing | | --vae-tiling | 否 | 关闭 | 启用 VAE tiling | | --output-json | 否 | - | 结果 JSON 输出路径 |

run_context_parallel.py

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

| 参数 | 必需 | 默认 | 说明 | |------|------|------|------| | --model | 是 | - | 本地模型路径 | | --prompt | 是 | - | 生成提示词 | | --parallel-mode | 否 | context | context（Parallel API）或 data（多进程并行） | | --device-type | 否 | npu | npu/cuda/cpu | | --backend | 否 | hccl | 分布式后端 | | --attention-backend | 否 | 按设备自动选择 | NPU 默认 _native_npu，CUDA 默认 _native_cudnn | | --ring-degree | 否 | - | Ring Attention 并行度 | | --ulysses-degree | 否 | 自动（默认=world_size） | Ulysses Attention 并行度 | | --dtype | 否 | bfloat16 | 数据类型 | | --steps | 否 | 20 | 推理步数 | | --output | 否 | cp_output.png | Rank0 输出图像 |

常见模型参考

| 模型 | Pipeline 类型 | 推荐 dtype | 推荐 NPU 内存 | |------|-------------|-----------|-------------| | FLUX.1-dev | FluxPipeline | bfloat16 | ≥24 GB | | SDXL | StableDiffusionXLPipeline | float16 | ≥8 GB | | SD 3.5 | StableDiffusion3Pipeline | bfloat16 | ≥16 GB | | Wan 2.1 | WanPipeline | bfloat16 | ≥24 GB | | CogVideoX | CogVideoXPipeline | bfloat16 | ≥24 GB |

常见问题

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 扩展

diffusers-ascend-pipeline

Diffusers 昇腾 NPU Pipeline 推理

使用顺序

前置要求

快速开始

1. 预检

2. 图像模型推理

3. 视频模型推理

4. 内存优化

5. LoRA 集成

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

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

性能基准测试

脚本参考

run_pipeline.py

validate_pipeline.py

benchmark_pipeline.py

run_context_parallel.py

常见模型参考

常见问题

NPU 内存不足（OOM）

首次推理很慢

Generator 设备错误

CPU Offload 不生效

参考资源