Ascend-SACT/MiniMax-H3-FastH3-NPU
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

MiniMax-H3-FastH3 on Ascend NPU — 部署指导

1. 背景说明

1.1 功能

在 Ascend NPU 上运行 MiniMax H3 系列视频生成模型,使用 vLLM-Omni 的 OpenAI 兼容 Video API。 本版本覆盖 Dense、VSA V1、VSA V2 和 Omni Ref2VA;所有模型均支持通过启动参数启用的在线 int8:

  • T2VA:文本 → 视频 + 音频
  • FL2VA:首帧图 → 视频 + 音频
  • Ref2VA:参考视频/音频/图片 → 视频 + 音频(仅 Omni)

GPU 原始 VSA 使用 Triton + Tensor Core 的 per-head/per-query 64-block 稀疏注意力。NPU 上无 fastvideo_kernel,本交付改用 MindIE-SD 的块稀疏注意力核,并以 zero-pad + BSA + index_select 方案消除伪影并提速。

1.2 模型配置与任务支持

config权重目录(相对 models/)上游权重支持的 task步数注意力后端sparsity说明
denseFastH3-Dense-Fused/FL2VAbase H3 FL2VA + Dense adaptert2va, fl2va4FLASH_ATTN-Dense 融合权重
v1FastH3-VSA-Fused/FL2VAbase H3 FL2VA + VSA adaptert2va, fl2va4FASTVIDEO_VSA0.9VSA 4-step
v2FastH3-8-StepV2-Fused/FL2VAFastVideo FastH3 8-Step-V2 full checkpointt2va, fl2va8FASTVIDEO_VSA0.8V2 8-step
omniFastH3-Omni-8-Step-Fused/Ref2VAFastVideo/FastVideo-FastH3-Omni-8-Step-V1ref2va8FASTVIDEO_VSA0.9Omni 仅 Ref2VA

在线 int8(所有模型可选):不是独立模型配置;任意模型启动时追加 --dlo-no-use-allgather --quantization int8 即可,task、步数、后端、sparsity 保持该模型原值。

任务约定:dense / v1 / v2 启动时写 --task-type fl2va,请求体通过 extra_params.task 选择 t2va 或 fl2va;omni 启动时写 --task-type ref2va,请求体只允许 extra_params.task=ref2va。

稀疏率:--fastvideo-vsa-sparsity 使用 rate(keep = ceil((1-sparsity) × num_video_blocks)), V1 原生 0.9,V2 训练值 0.8,Omni 0.9。

1.3 服务形态

项目值
服务框架vLLM-Omni (vllm serve --omni),OpenAI 兼容 Video API
模型形态预融合/转换后的 HF 目录(DLO 必需,制备见第 4 节)
并行策略--num-gpus N --usp N --ring 1 --text-encoder-tp-size N(N = 卡数)
VAE--vae-parallel-mode tile --vae-use-tiling --vae-patch-parallel-size N
默认端口9098

2. 环境准备

建议执行顺序:2.1–2.4 准备交付件 → 第 3 节创建容器 → 2.5 应用补丁 → 2.6 安装 BSA 算子 → 第 4 节下载/融合权重 → 第 5 节启动服务 → 第 6 节调用。

2.1 硬件

平台平台/芯片典型设备说明
A3Ascend910CAtlas 800I A38 卡默认;4 卡部署见 5.6
A2Ascend910BAscend 910B 系列卡数按实际设备调整;并行参数须与卡数一致

A3 单卡 64 GiB HBM(8 卡配置);A2 以实际设备为准。显存不足时优先降低分辨率、帧数或卡数。

2.2 镜像

平台镜像
A3quay.io/ascend/vllm-omni:v0.32.0-a3
A2quay.io/ascend/vllm-omni:v0.32.0

镜像自带 CANN、torch/torch_npu、transformers、diffusers、numpy 与 MindIE-SD。vLLM-Omni 源码树位于 镜像内 /vllm-workspace/vllm-omni,不要用宿主机目录覆盖。

2.3 软件

镜像内已包含 CANN 9.1.0、torch/torch_npu 2.10、MindIE-SD。仅需:

  1. 在容器内对 /vllm-workspace/vllm-omni 应用补丁(见 2.5);
  2. 按目标平台安装 BSA 自定义算子(见 2.6);
  3. 在容器内完成权重下载/融合/转换(见第 4 节)。

2.4 交付包目录与挂载约定

本地准备一个单一目录,容器只挂载这个目录;不要挂载 /vllm-workspace,也不要挂载其他宿主目录:

fasth3-bundle/                  # 宿主机目录,整体挂载进容器
├── models/                     # 所有 HF 下载权重与融合产物
│   ├── MiniMax-H3/
│   │   ├── FL2VA/              # dense/v1/v2 的 base
│   │   └── Ref2VA/             # Omni 的 base
│   ├── fasth3-lora/            # VSA/Dense 4-step adapter
│   ├── FastVideo-FastH3-8-Step-V2/
│   ├── FastVideo-FastH3-Omni-8-Step-V1/
│   ├── light-vae/              # MINIMAX_H3_LIGHT_VAE 指向含 config.json 的目录
│   └── FastH3-*-Fused/         # 第 4 节生成的融合产物
├── assets/                     # 调用素材
│   ├── fl2va/keyframe.png
│   └── ref2va/reference_video.mp4
│       ref2va/reference_audio.mp3
│       ref2va/prompt.txt
└── fasth3-delivery/            # 本交付包(即本 README 所在目录)
    ├── README.md
    ├── patches/
    ├── tools/
    └── operators/

容器内统一使用固定挂载路径:

export FASTH3_ROOT=/workspace/fasth3
export MODELS=${FASTH3_ROOT}/models
export ASSETS=${FASTH3_ROOT}/assets
export DELIVER=${FASTH3_ROOT}/fasth3-delivery

2.5 补丁文件准备与应用

本节命令均在容器内执行(先完成第 3 节创建容器)。

补丁直接应用到镜像自带的 vLLM-Omni v0.32.0 源码树,不切换 commit、不 fetch/reset:

项目值
patch 压缩包patches/vllm-omni-final-vs-v0.32.0.patch.tar.gz
容器内路径${DELIVER}/patches/vllm-omni-final-vs-v0.32.0.patch.tar.gz
解压目录/tmp/fasth3-patch
解压后文件/tmp/fasth3-patch/vllm-omni-final-vs-v0.32.0.patch
目标源码树/vllm-workspace/vllm-omni
压缩包 sha2561c91a5106e6103e4345f3aac15cd00815e131fa424808956eb674f06a0f7d0be
解压后 patch sha2562abddedeee7099379570951ebd49ed72af1961f5e5bab5dc4d5bf20439ac484f
cd /vllm-workspace/vllm-omni
export PATCH_TAR="${DELIVER}/patches/vllm-omni-final-vs-v0.32.0.patch.tar.gz"
export PATCH_DIR="/tmp/fasth3-patch"
export PATCH="${PATCH_DIR}/vllm-omni-final-vs-v0.32.0.patch"

sha256sum "${PATCH_TAR}"
tar -tzf "${PATCH_TAR}"
rm -rf "${PATCH_DIR}" && mkdir -p "${PATCH_DIR}"
tar -xzf "${PATCH_TAR}" -C "${PATCH_DIR}"
sha256sum "${PATCH}"
git apply --check "${PATCH}"
git apply "${PATCH}"

# 可选:记录应用结果
git config user.name "fasth3" 2>/dev/null || true
git config user.email "fasth3@example.com" 2>/dev/null || true
git add -A && git commit -m "Apply v0.32.0 -> final patch"
git log --format="%H %s" -1

patch 使用 tar.gz 压缩以绕过上传大小限制,解压后的内容与原 patch 完全一致。

该 patch 以镜像自带 v0.32.0 为基线。若 git apply --check 失败,先确认没有额外改过源码树; 不要执行 git reset --hard 到其他 commit,否则可能与补丁上下文不匹配。

2.6 BSA 算子安装(A2 / A3)

本节命令均在容器内执行。

BSA 自定义算子只影响 FASTVIDEO_VSA(v1 / v2 / omni)。dense 使用 FLASH_ATTN,不依赖自定义 BSA,但仍依赖镜像内 MindIE-SD 的 dense fused attention。

预编包按 SOC 编译:A3=ascend910_93,A2=ascend910b,不可混用。 安装脚本会把自定义 vendor 写入 MindIE-SD 的 customize_transformer 槽,并自动备份原厂核为 .bak_bsa_e2e。安装后不要设置 ASCEND_CUSTOM_OPP_PATH。

cd "${DELIVER}/operators"

A3:head128(推荐,输出与 baseline 位级一致)

mkdir -p /tmp/bsa_headmajor
tar xzf prebuilt_A3_head128/bsa_headmajor_128.tar.gz -C /tmp/bsa_headmajor
bash prebuilt_A3_head128/install_custom_bsa_e2e.sh \
  /tmp/bsa_headmajor/packages/vendors/bsa_headmajor_transformer_transformer
export FASTVIDEO_BSA_BLOCK_SIZE=128

A3:head64(更快,非等价,需要画质验收)

mkdir -p /tmp/bsa64head
tar xzf prebuilt_A3_head64/bsa64head_64.tar.gz -C /tmp/bsa64head
bash prebuilt_A3_head64/install_custom_bsa_e2e.sh \
  /tmp/bsa64head/packages/vendors/bsa64head_transformer_transformer
export FASTVIDEO_BSA_BLOCK_SIZE=64

A2:head64(A2 / ascend910b)

mkdir -p /tmp/bsa64head_a2
tar xzf prebuilt_A2_head64/bsa64head_64_a2.tar.gz -C /tmp/bsa64head_a2
bash prebuilt_A2_head64/install_custom_bsa_e2e.sh \
  /tmp/bsa64head_a2/packages/vendors/bsa64head_transformer
export FASTVIDEO_BSA_BLOCK_SIZE=64

校验与卸载

# 校验 kernel 架构目录:A3 应为 ascend910_93,A2 应为 ascend910b
find /usr/local/python3.12.13/lib/python3.12/site-packages/mindiesd/ops/vendors/customize_transformer/op_impl/ai_core/tbe/kernel \
  -maxdepth 1 -type d -printf '%f\n' | sort -u

# 服务日志中应出现 bsa_block_size=64 或 bsa_block_size=128
grep -a "FASTVIDEO_VSA H3 NPU routing" output.log | tail -1

# 卸载(恢复原厂核;换包前先卸载)
bash prebuilt_A3_head64/uninstall_custom_bsa_e2e.sh
# 或 bash prebuilt_A3_head128/uninstall_custom_bsa_e2e.sh
# 或 bash prebuilt_A2_head64/uninstall_custom_bsa_e2e.sh

FASTVIDEO_BSA_BLOCK_SIZE 必须与已安装包一致。本文 V1/V2 示例使用 64;Omni 示例使用 128 (若 Omni 使用 head64 包,请改为 64 并做画质验收)。

源码重建方式见 operators/source/BUILD.md,补丁为 mindiesd_head_major_task_order.patch 与 mindiesd_bsa64_gather_fix.patch。


3. 创建容器

数据目录只挂载 fasth3-bundle 这一个目录。不要挂载 /vllm-workspace,也不要用宿主机目录覆盖 镜像内的 vLLM-Omni 源码树。下面的 dcmi/driver/npu-smi 挂载是 NPU 运行所必需的设备挂载,不属于工作区。

# 在 fasth3-bundle 的父目录执行
export FASTH3_BUNDLE=$PWD/fasth3-bundle
export IMAGE=quay.io/ascend/vllm-omni:v0.32.0-a3   # A2 改为 quay.io/ascend/vllm-omni:v0.32.0

docker run -itd --name fasth3 \
  --ipc=host --shm-size=64g --privileged \
  --device=/dev/davinci0 --device=/dev/davinci1 \
  --device=/dev/davinci2 --device=/dev/davinci3 \
  --device=/dev/davinci4 --device=/dev/davinci5 \
  --device=/dev/davinci6 --device=/dev/davinci7 \
  --device=/dev/davinci_manager --device=/dev/devmm_svm --device=/dev/hisi_hdc \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v "${FASTH3_BUNDLE}:/workspace/fasth3" \
  -v /dev/shm:/dev/shm \
  -p 9098:9098 \
  "${IMAGE}" bash

docker exec -it fasth3 bash

进入容器后设置路径:

export FASTH3_ROOT=/workspace/fasth3
export MODELS=${FASTH3_ROOT}/models
export ASSETS=${FASTH3_ROOT}/assets
export DELIVER=${FASTH3_ROOT}/fasth3-delivery

4. 权重准备与融合

4.1 下载权重

建议在宿主机 fasth3-bundle/ 目录内执行;下载结果直接写入挂载目录 models/。 若改在容器内执行,把 cd fasth3-bundle 换成 cd /workspace/fasth3,并把 MODELS 设为 /workspace/fasth3/models。

cd fasth3-bundle
export MODELS=./models
mkdir -p "${MODELS}"

# 1) base H3:同时下载 FL2VA 和 Ref2VA
export BASE_DIR="${MODELS}/MiniMax-H3"
hf download MiniMaxAI/MiniMax-H3 \
  --include "FL2VA/*" "Ref2VA/*" \
  --local-dir "${BASE_DIR}"

# 2) FastH3 4-step adapter(受限仓库,先 hf auth login)
export FASTH3_DIR="${MODELS}/fasth3-lora"
hf download FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA \
  --local-dir "${FASTH3_DIR}"

# 3) 8-Step-V2 full checkpoint
hf download FastVideo/FastVideo-FastH3-8-Step-V2 \
  --local-dir "${MODELS}/FastVideo-FastH3-8-Step-V2"

# 4) Omni 8-Step-V1 full checkpoint
hf download FastVideo/FastVideo-FastH3-Omni-8-Step-V1 \
  --local-dir "${MODELS}/FastVideo-FastH3-Omni-8-Step-V1"

# 5) Light VAE(推荐)
hf download stdstu123/LynnReal-Onmi-light-vae \
  --local-dir "${MODELS}/light-vae"

export MINIMAX_H3_LIGHT_VAE=$(dirname "$(find "${MODELS}/light-vae" -name config.json -print -quit)")
echo "MINIMAX_H3_LIGHT_VAE=${MINIMAX_H3_LIGHT_VAE}"

FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA 是受限仓库,需 hf auth login 且账号有权限。

4.2 为什么需要离线融合/转换

  • A3/A2 大模型部署必须开 DLO(Distributed Layerwise Offload)。DLO 直接 mmap 预分片 safetensors, 绕过 load_weights(),因此 GPU 上靠 --lora-path 运行时融合 adapter 的方式不可用,必须离线融合。
  • 官方完整 FastH3 checkpoint 为 diffusers 命名空间,DLO 按精确参数名 mmap,不能直接服务; 4-step Dense/VSA 需要从 base H3 FL2VA 原生布局 + adapter 融合。
  • 8-Step-V2 是 FastVideo 原生 full checkpoint,需要命名/布局转换(数值不变)。
  • Omni 8-Step-V1 是 Ref2VA full checkpoint,需要转换 + 组装 Ref2VA 目录 + 写入 model_index.json 契约。
  • 所有产物都需要在 model_index.json 注入 _minimax_h3.base_schedule;VSA/Omni 还需要 "vsa": true。

4.3 VSA V1(config=v1,4-step,sparsity 0.9)

以下命令在容器内、2.5 补丁应用后执行:

cd "${DELIVER}"

python3 tools/prepare_fasth3_vsa.py \
  --base-model "${MODELS}/MiniMax-H3/FL2VA" \
  --adapter "${MODELS}/fasth3-lora/vsa-datafree/adapter_model.safetensors" \
  --output "${MODELS}/FastH3-VSA-Fused/FL2VA"

python3 tools/prepare_fasth3_vsa.py \
  --output "${MODELS}/FastH3-VSA-Fused/FL2VA" --verify-only

4.4 Dense(config=dense,4-step)

cd "${DELIVER}"

python3 tools/prepare_fasth3_dense.py \
  --base-model "${MODELS}/MiniMax-H3/FL2VA" \
  --adapter "${MODELS}/fasth3-lora/dense-datafree/adapter_model.safetensors" \
  --output "${MODELS}/FastH3-Dense-Fused/FL2VA"

python3 tools/prepare_fasth3_dense.py \
  --output "${MODELS}/FastH3-Dense-Fused/FL2VA" --verify-only

4.5 8-Step-V2(config=v2,8-step,sparsity 0.8)

cd "${DELIVER}"

python3 tools/convert_fasth3_8step_v2.py \
  --source "${MODELS}/FastVideo-FastH3-8-Step-V2/transformer" \
  --reference "${MODELS}/MiniMax-H3/FL2VA/transformer" \
  --output "${MODELS}/FastH3-8-StepV2-Fused/FL2VA/transformer"

python3 tools/convert_fasth3_8step_v2.py --verify \
  --source "${MODELS}/FastVideo-FastH3-8-Step-V2/transformer" \
  --reference "${MODELS}/MiniMax-H3/FL2VA/transformer" \
  --output "${MODELS}/FastH3-8-StepV2-Fused/FL2VA/transformer"

转换后补齐 model_index.json 与外部组件。model_index.json 至少满足:

{
  "_minimax_h3": {
    "partition": "fl2va",
    "tasks": ["t2va", "fl2va"],
    "sigma_shift_scales": {"video": 10.0, "audio": 3.0},
    "base_schedule": [0.999, 0.874, 0.749, 0.624, 0.5, 0.375, 0.25, 0.125, 0.0],
    "vsa": true
  }
}

组件 text_encoder/tokenizer/processor/video_vae/audio_vae 可符号链接到 ${MODELS}/MiniMax-H3/FL2VA 的同名目录。

若发布包 model_index.json 的 tasks 只有 ["t2va"],该 checkpoint 会拒绝 fl2va 请求; 部署前确认 tasks 包含本次要用的 task,或按发布说明更新 metadata。

4.6 Omni 8-Step-V1(config=omni,8-step,仅 Ref2VA)

Omni 使用 base H3 Ref2VA,不是 FL2VA。脚本自动完成:布局转换、数值校验、配置合并、 model_index.json 写入、组件符号链接、scheduler/audio_scheduler 复制。

cd "${DELIVER}"

python3 tools/prepare_fasth3_omni_8step.py \
  --models "${MODELS}" \
  --source "${MODELS}/FastVideo-FastH3-Omni-8-Step-V1" \
  --base-model "${MODELS}/MiniMax-H3" \
  --output "${MODELS}/FastH3-Omni-8-Step-Fused/Ref2VA"

python3 tools/prepare_fasth3_omni_8step.py \
  --models "${MODELS}" \
  --source "${MODELS}/FastVideo-FastH3-Omni-8-Step-V1" \
  --base-model "${MODELS}/MiniMax-H3" \
  --output "${MODELS}/FastH3-Omni-8-Step-Fused/Ref2VA" \
  --verify-only

Omni 产物 model_index.json 契约:

{
  "_minimax_h3": {
    "partition": "ref2va",
    "tasks": ["ref2va"],
    "sigma_shift_scales": {"video": 12.0, "audio": 3.0},
    "base_schedule": [0.999, 0.874, 0.749, 0.624, 0.5, 0.375, 0.25, 0.125, 0.0],
    "vsa": true
  }
}

4.7 产物目录布局与校验

FL2VA 产物:

${MODELS}/FastH3-{Dense|VSA|8-StepV2}-Fused/FL2VA/
├── model_index.json      # _minimax_h3.base_schedule;VSA 还要 vsa:true
├── transformer/          # 原生布局;VSA 额外含 model-gates.safetensors
├── text_encoder/         # 通常为指向 base H3 FL2VA 的符号链接
├── tokenizer/
├── processor/
├── video_vae/
└── audio_vae/

Ref2VA(Omni)产物额外可能有:

${MODELS}/FastH3-Omni-8-Step-Fused/Ref2VA/
├── model_index.json
├── transformer/
├── scheduler/
├── audio_scheduler/
├── text_encoder/ tokenizer/ processor/ video_vae/ audio_vae/

统一校验:

for m in \
  "${MODELS}/FastH3-Dense-Fused/FL2VA" \
  "${MODELS}/FastH3-VSA-Fused/FL2VA" \
  "${MODELS}/FastH3-8-StepV2-Fused/FL2VA" \
  "${MODELS}/FastH3-Omni-8-Step-Fused/Ref2VA"; do
  echo "=== ${m} ==="
  python3 -c "
import json, sys
h = json.load(open(sys.argv[1] + '/model_index.json')).get('_minimax_h3', {})
print('partition =', h.get('partition'))
print('tasks     =', h.get('tasks'))
print('vsa       =', h.get('vsa'))
print('schedule  =', h.get('base_schedule'))
" "${m}"
done

许可证:按 MiniMax H3 原始许可与 FastH3 权重许可执行,使用前请确认授权范围。


5. 服务部署

以下命令在容器内执行。

5.1 公共环境变量

source /usr/local/Ascend/ascend-toolkit/set_env.sh

export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7   # 8 卡;4 卡见 5.6
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export VLLM_OMNI_VIDEO_SYNC_TIMEOUT=7200
export PYTHONDONTWRITEBYTECODE=1
export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export HCCL_OP_EXPANSION_MODE=AIV
export HCCL_NPU_SOCKET_PORT_RANGE=22000-22999
export HCCL_EXEC_TIMEOUT=3600
export HCCL_CONNECT_TIMEOUT=600
if [ -z "${MINIMAX_H3_LIGHT_VAE:-}" ]; then
  export MINIMAX_H3_LIGHT_VAE=$(dirname "$(find "${MODELS}/light-vae" -name config.json -print -quit)")
fi

FASTVIDEO_BSA_BLOCK_SIZE 在启动 VSA 模型前设置,必须与 2.6 安装的包一致:

# V1 / V2 示例使用 head64
export FASTVIDEO_BSA_BLOCK_SIZE=64
# Omni 示例使用 head128;若 Omni 使用 head64 包,改为 64 并做画质验收
# export FASTVIDEO_BSA_BLOCK_SIZE=128

所有模型可选在线 int8:在对应启动命令末尾追加 --dlo-no-use-allgather --quantization int8;task、步数、注意力后端、sparsity 不变。

5.2 Dense(4-step,FLASH_ATTN)

vllm serve "${MODELS}/FastH3-Dense-Fused/FL2VA" \
  --omni --host 0.0.0.0 --port 9098 \
  --trust-remote-code --task-type fl2va \
  --init-timeout 7200 --stage-init-timeout 7200 \
  --num-gpus 8 --usp 8 --ring 1 --text-encoder-tp-size 8 \
  --enable-distributed-layerwise-offload \
  --vae-parallel-mode tile --vae-use-tiling --vae-patch-parallel-size 8 \
  --diffusion-attention-backend FLASH_ATTN \
  --vae-encode-parallel-size 8 \
  --enable-diffusion-pipeline-profiler

5.3 VSA V1(4-step,sparsity 0.9)

export FASTVIDEO_BSA_BLOCK_SIZE=64

vllm serve "${MODELS}/FastH3-VSA-Fused/FL2VA" \
  --omni --host 0.0.0.0 --port 9098 \
  --trust-remote-code --task-type fl2va \
  --init-timeout 7200 --stage-init-timeout 7200 \
  --num-gpus 8 --usp 8 --ring 1 --text-encoder-tp-size 8 \
  --enable-distributed-layerwise-offload \
  --vae-parallel-mode tile --vae-use-tiling --vae-patch-parallel-size 8 \
  --diffusion-attention-backend FASTVIDEO_VSA \
  --fastvideo-vsa-sparsity 0.9 \
  --vae-encode-parallel-size 8 \
  --enable-diffusion-pipeline-profiler

5.4 VSA V2(8-step,sparsity 0.8)

export FASTVIDEO_BSA_BLOCK_SIZE=64

vllm serve "${MODELS}/FastH3-8-StepV2-Fused/FL2VA" \
  --omni --host 0.0.0.0 --port 9098 \
  --trust-remote-code --task-type fl2va \
  --init-timeout 7200 --stage-init-timeout 7200 \
  --num-gpus 8 --usp 8 --ring 1 --text-encoder-tp-size 8 \
  --enable-distributed-layerwise-offload \
  --vae-parallel-mode tile --vae-use-tiling --vae-patch-parallel-size 8 \
  --diffusion-attention-backend FASTVIDEO_VSA \
  --fastvideo-vsa-sparsity 0.8 \
  --vae-encode-parallel-size 8 \
  --enable-diffusion-pipeline-profiler

5.5 Omni(8-step,仅 Ref2VA)

export FASTVIDEO_BSA_BLOCK_SIZE=128

vllm serve "${MODELS}/FastH3-Omni-8-Step-Fused/Ref2VA" \
  --omni --host 0.0.0.0 --port 9098 \
  --trust-remote-code --task-type ref2va \
  --init-timeout 7200 --stage-init-timeout 7200 \
  --num-gpus 8 --usp 8 --ring 1 --text-encoder-tp-size 8 \
  --enable-distributed-layerwise-offload \
  --vae-parallel-mode tile --vae-use-tiling --vae-patch-parallel-size 8 \
  --diffusion-attention-backend FASTVIDEO_VSA \
  --fastvideo-vsa-sparsity 0.9 \
  --vae-encode-parallel-size 8 \
  --enable-diffusion-pipeline-profiler

5.6 4 卡部署

把启动命令中以下并行参数全部改为 4,并让设备数与并行度一致:

修改项8 卡4 卡
ASCEND_RT_VISIBLE_DEVICES0,1,2,3,4,5,6,70,1,2,3(或后 4 卡)
--num-gpus84
--usp84
--text-encoder-tp-size84
--vae-patch-parallel-size84
--vae-encode-parallel-size84

5.7 就绪检查、预热与停止

模型加载(含 DLO 初始化/在线量化)可能需要十几到几十分钟,以 /health 返回 200 为准:

until curl -sf http://localhost:9098/health >/dev/null; do sleep 10; done; echo READY
curl -s http://localhost:9098/v1/models

/health 就绪后,首次推理仍包含算子编译/图构建开销,建议先发一个短请求预热,再对外服务。 本版 Qwen3-VL/attention 图构建在首次请求时完成;性能表只统计 warmup 之后的稳态。

停止:

ps -eo pid,ppid,cmd | grep -E "vllm serve|DiffusionWorker" | grep -v grep
kill -TERM <MAIN_PID>
pkill -f "vLLM-Omni::DiffusionWorker_S[P]"

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9098/health   # 期望非 200
npu-smi info | head -20

优先 SIGTERM 优雅退出;kill -9 可能污染 NPU,后续算子可能报 507057。 服务启动时建议 </dev/null 重定向 stdin,避免 ffmpeg 预处理访问控制终端导致进程组被 job-control 停住。


6. 服务调用

以下 curl 均为 multipart/form-data。先设置:

export BASE_URL=http://localhost:9098
export ASPECT_RATIO=16:9
export WIDTH=1344
export HEIGHT=768
export FPS=24
export NUM_FRAMES=124
export PROMPT="YOUR_PROMPT_HERE"

6.1 T2VA(dense / v1 / v2;任意模型可选在线 int8)

--task-type fl2va 启动的服务也可以接收 t2va 请求;通过 extra_params.task 选择任务。 aspect_ratio 对 T2VA 必须显式给出。

export MODEL_DIR="${MODELS}/FastH3-VSA-Fused/FL2VA"
export STEPS=4

curl -X POST "${BASE_URL}/v1/videos" \
  -F "model=${MODEL_DIR}" \
  -F "prompt=${PROMPT}" \
  -F "width=${WIDTH}" \
  -F "height=${HEIGHT}" \
  -F "aspect_ratio=${ASPECT_RATIO}" \
  -F "num_frames=${NUM_FRAMES}" \
  -F "fps=${FPS}" \
  -F "num_inference_steps=${STEPS}" \
  -F "guidance_scale=1.0" \
  -F "true_cfg_scale=1.0" \
  -F "seed=48" \
  -F "flow_shift=12.0" \
  -F 'extra_params={"task":"t2va","audio_flow_shift":3.0}'

V2 将 MODEL_DIR 改为 ${MODELS}/FastH3-8-StepV2-Fused/FL2VA,STEPS=8。

6.2 FL2VA(dense / v1 / v2;任意模型可选在线 int8)

首帧图放在 ${ASSETS}/fl2va/keyframe.png,通过 input_references 上传:

export MODEL_DIR="${MODELS}/FastH3-VSA-Fused/FL2VA"
export STEPS=4
export KEYFRAME="${ASSETS}/fl2va/keyframe.png"

curl -X POST "${BASE_URL}/v1/videos" \
  -F "model=${MODEL_DIR}" \
  -F "prompt=${PROMPT}" \
  -F "width=${WIDTH}" \
  -F "height=${HEIGHT}" \
  -F "aspect_ratio=${ASPECT_RATIO}" \
  -F "num_frames=${NUM_FRAMES}" \
  -F "fps=${FPS}" \
  -F "num_inference_steps=${STEPS}" \
  -F "guidance_scale=1.0" \
  -F "true_cfg_scale=1.0" \
  -F "seed=48" \
  -F "flow_shift=12.0" \
  -F "input_references=@${KEYFRAME};type=image/png" \
  -F 'extra_params={"task":"fl2va","audio_flow_shift":3.0}'

V2 将 MODEL_DIR 改为 V2 路径,STEPS=8。

6.3 Ref2VA(仅 Omni)

参考视频和音频放在 ${ASSETS}/ref2va/。reference_video.mp4 内的音轨作为 Audio 1, reference_audio.mp3 作为 Audio 2(与 prompt 的 <Audio 1>/<Audio 2> 对应):

export MODEL_DIR="${MODELS}/FastH3-Omni-8-Step-Fused/Ref2VA"
export STEPS=8
export REF_VIDEO="${ASSETS}/ref2va/reference_video.mp4"
export REF_AUDIO="${ASSETS}/ref2va/reference_audio.mp3"
export PROMPT="$(cat "${ASSETS}/ref2va/prompt.txt")"

curl -X POST "${BASE_URL}/v1/videos" \
  -F "model=${MODEL_DIR}" \
  -F "prompt=${PROMPT}" \
  -F "width=${WIDTH}" \
  -F "height=${HEIGHT}" \
  -F "num_frames=${NUM_FRAMES}" \
  -F "fps=${FPS}" \
  -F "num_inference_steps=${STEPS}" \
  -F "guidance_scale=1.0" \
  -F "true_cfg_scale=1.0" \
  -F "seed=48" \
  -F "flow_shift=12.0" \
  -F "input_references=@${REF_VIDEO};type=video/mp4" \
  -F "input_references=@${REF_AUDIO};type=audio/mpeg" \
  -F 'extra_params={"task":"ref2va","audio_flow_shift":3.0}'

6.4 统一参数说明

参数类型适用 task必填约束 / 说明
modelstringall是必须是完整模型目录,且与服务 /v1/models 一致
promptstringall是文本提示;Ref2VA 使用带 <Video 1>/<Audio 1>/<Audio 2> 标签的 prompt
widthintall建议推荐 1344;与 height 一起决定画布
heightintall建议推荐 768
aspect_ratiostringt2va / fl2vat2va 必填T2VA 必须显式给,如 16:9;FL2VA 由关键帧比例决定
num_framesintall二选一推荐。H3 会按 17n+5 向上对齐:124→124,241→243,360→362
secondsfloatall二选一用秒数控制时长;不要与 num_frames 同时作为时长依据
fpsfloatall否H3 固定 24
num_inference_stepsintall是dense/v1=4;v2/omni=8(在线 int8 不改变步数)
guidance_scalefloatall否默认 1.0
true_cfg_scalefloatall否默认 1.0
seedintall否默认 48
flow_shiftfloatall否视频 sigma shift,默认 12.0
extra_paramsJSON stringall是`{"task":"t2va
input_referencesfilefl2va / ref2vafl2va/ref2va 必填可重复。FL2VA 传 keyframe.png(image/png);Ref2VA 传 reference_video.mp4(video/mp4)+ reference_audio.mp3(audio/mpeg)

常用取值:

参数取值
num_frames124(≈5.17s)、241(实际 243 帧,≈10.13s)、360(实际 362 帧,≈15.08s)
width / height1344 / 768
num_inference_stepsdense/v1: 4;v2/omni: 8(在线 int8 不改变步数)
extra_params{"task":"t2va","audio_flow_shift":3.0}、{"task":"fl2va","audio_flow_shift":3.0}、{"task":"ref2va","audio_flow_shift":3.0}

6.5 状态轮询与下载

# POST 返回 JSON 中的 id 即 VIDEO_ID
curl "${BASE_URL}/v1/videos/<VIDEO_ID}"
# 完成态为 "completed"(不是 "succeeded")

curl -o output.mp4 "${BASE_URL}/v1/videos/<VIDEO_ID>/content"

6.6 输出校验

项目期望
分辨率1344×768
帧率24 fps
帧数请求 124 / 241 / 360 时,实际为 124 / 243 / 362(H3 17n+5 对齐)
音频Ref2VA 应包含参考音轨/生成语音;T2VA/FL2VA 应包含生成音频
内容无明显闪点/flicker 伪影

附录 A:性能参考表

测试平台:A3 8 卡(NPU 0-7);分辨率 1344×768;权重 BF16。 表中仅列 E2E 总耗时,单位为秒(s),保留两位小数;int8 数据不在本文展示。 5s / 10s / 15s 分别对应请求 124 / 241 / 360 帧,实际输出 124 / 243 / 362 帧。 数据源:Minimax-H3性能基线.xlsx。

A.1 T2VA

模型5s / 124 帧10s / 241 帧15s / 360 帧
Dense(4-step)15.7940.8678.10
VSA V1(4-step,sparsity 0.9)12.3123.1837.01
VSA V2(8-step,sparsity 0.8)21.8444.6476.29

A.2 FL2VA

模型5s / 124 帧10s / 241 帧15s / 360 帧
Dense(4-step)22.0046.1783.72
VSA V1(4-step,sparsity 0.9)18.8529.7143.86
VSA V2(8-step,sparsity 0.8)29.8654.3187.18

A.3 Ref2VA(仅 Omni)

模型5s / 124 帧10s / 241 帧15s / 360 帧
Omni 8-Step-V1(8-step)97.80161.00217.64

附录 B:工具脚本

脚本用途用法
tools/prepare_fasth3_vsa.pyVSA 4-step 离线融合(base H3 FL2VA + VSA adapter)python3 tools/prepare_fasth3_vsa.py --base-model ... --adapter ... --output ...(--verify-only 校验)
tools/prepare_fasth3_dense.pyDense 4-step 离线融合(base H3 FL2VA + Dense adapter)python3 tools/prepare_fasth3_dense.py --base-model ... --adapter ... --output ...(--verify-only 校验)
tools/convert_fasth3_8step_v2.py8-Step-V2 full checkpoint 命名/布局转换python3 tools/convert_fasth3_8step_v2.py --source ... --reference ... --output ...(--verify 校验)
tools/prepare_fasth3_omni_8step.pyOmni 8-Step-V1 转换 + Ref2VA 目录组装 + 契约校验python3 tools/prepare_fasth3_omni_8step.py --models ...(--verify-only 校验)
tools/download_weights.sh权重批量下载脚本(当前版本默认只含 FL2VA;完整下载以第 4.1 节命令为准)DEST=./models bash tools/download_weights.sh
tools/bench_t2va.pyT2VA 稳态测速(warmup 后 5/10/15s)python3 tools/bench_t2va.py <tag> [port] [steps] [prompt]
operators/source/BUILD.mdBSA vendor 源码重建按文档打补丁并使用 build.sh --soc=...

融合/转换脚本详见第 4 节;bench_*.py 结果写入 /tmp/bench_<tag>.json,10s 官方 case 视频写入 $OUTPUT_DIR(默认 ./outputs)。