atlasleong/ltx-video-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

LTX-Video 昇腾 NPU 迁移适配

原模型仓库

  • 原仓库地址:https://ai.gitcode.com/hf_mirrors/Lightricks/LTX-Video
  • 固定版本:8984fa25007f376c1a299016d0957a37a2f797bb

一、模型简介

LTX-Video 是由 Lightricks 提出的基于 DiT(Diffusion Transformer)的视频生成模型, 能够以 30 FPS、最高 1216×704 分辨率生成高质量视频,支持 文本生成视频(text-to-video) 与 图像生成视频(image-to-video) 两种任务。

本交付物以 Hugging Face diffusers 的 LTXPipeline 形式封装模型,包含以下组件:

组件类型说明
text_encoderT5EncoderModel(google/t5-v1_1-xxl)文本编码器,4.7B 参数
tokenizerT5TokenizerT5 词表(vocab 32128)
transformerLTXVideoTransformer3DModel3D DiT 去噪网络,28 层
vaeAutoencoderKLLTXVideo视频自编码器,时空 8×/32× 压缩
schedulerFlowMatchEulerDiscreteScheduler流匹配欧拉调度器

说明:本仓库 model_index.json 声明的默认管线为 LTXPipeline(文本/图像 → 视频)。 权重已本地化到任务目录 model/,运行时不依赖任何外部网络下载。

二、环境依赖

2.1 硬件与系统

项目要求
硬件Ascend 910 系列(至少 1 卡)
OSopenEuler / Ubuntu(aarch64)
CANN≥ 8.0(推荐 8.2+,本环境 8.5.1)
Python3.10 – 3.11
PyTorch2.9.0(与 torch_npu 配套)
torch_npu2.9.0

2.2 依赖安装

# 华为/国内镜像源
export PIP_INDEX_URL=https://repo.huaweicloud.com/repository/pypi/simple/

# 安装非平台依赖(torch/torch_npu 由昇腾镜像预置,不在此列)
pip install --ignore-installed --no-deps -r requirements.txt

关键依赖版本:

  • diffusers==0.39.0
  • transformers==5.15.0
  • safetensors==0.8.0
  • huggingface-hub==1.27.0
  • numpy==1.26.4
  • protobuf==5.29.6(T5Tokenizer 加载 spiece.model 必需)
  • tiktoken==0.13.0(TikToken 词表回退解析,保证 tokenizer 加载稳健)
  • sentencepiece==0.2.2

三、分步推理

3.1 环境初始化

source /usr/local/Ascend/ascend-toolkit/set_env.sh
export ASCEND_RT_VISIBLE_DEVICES=0

3.2 运行推理

# 进入任务根目录
cd /srv/model-pipeline/jobs/LTX-Video

python3 delivery/inference.py \
    --prompt "A tiny robotic dog wags its tail on a sunny beach, cinematic lighting, high detail." \
    --height 128 --width 128 --num_frames 9 --num_inference_steps 1 --seed 42

程序在逻辑 npu:0 上加载 LTXPipeline 并完成一次前向生成,输出到 delivery/assets/:

  • latent_tensors.npy:去噪后的潜变量张量
  • generated_media.npy:解码后的视频帧(uint8,[B, F, C, H, W])
  • output.mp4:合成视频文件
  • input_ids.npy:提示词 token 化结果

标准输出包含设备标记:

INPUT_DEVICE=npu:0
MODEL_DEVICE=npu:0
OUTPUT_DEVICE=npu:0
CPU_FALLBACK=false

四、测试用例

4.1 CPU 基线(多样本回归基准)

python3 runners/run_cpu.py

输出 cpu_baseline/stage_outputs.json 及 latent_tensors、generated_media 等工件。

4.2 NPU 未打补丁前向

python3 runners/run_npu.py

输出 npu_unpatched/stage_outputs.json,并打印 INPUT_DEVICE/MODEL_DEVICE/OUTPUT_DEVICE=npu:0、CPU_FALLBACK=false。

4.3 多样本回归

python3 runners/run_multi_sample.py

对 ≥10 个不同样本(每个样本一个独立子进程,运行于 npu:0)生成 multi_sample_regression/sample_results.jsonl 与 multi_sample_regression/tamper_test.json, 每个样本包含一组连续 CPU/NPU 对(latent_tensors_*)与一组离散 CPU/NPU 对 (generated_media_*)。

4.4 性能基准

python3 runners/run_performance.py

输出 performance/performance_results.json,含 warmup_iterations、 repeat_iterations、synchronized、raw_timings_ms、snapshot_count。

五、输出结果

产物路径说明
模型说明architecture_profile.json / model_metadata.json架构画像与元数据
执行计划execution_plan.json各阶段运行命令
CPU 基线cpu_baseline/stage_outputs.jsonCPU 前向工件
NPU 基线npu_unpatched/stage_outputs.jsonNPU 未打补丁前向工件
多样本回归multi_sample_regression/样本结果与防篡改测试
性能数据performance/performance_results.jsonNPU 时延数据
交付物delivery/推理脚本、依赖、说明文档

在 128×128、9 帧、1 步去噪的配置下,端到端前向即可输出可用的潜变量与视频帧。 更高分辨率/更多帧数会显著增加计算量。

六、截图

以下截图将由可信截图工具在真实 NPU 验证后生成,本阶段仅占位引用,不创建或伪造图片。

  • 推理输出视频帧:assets/agent_workflow.png
  • 潜变量可视化:assets/npu_device_call.png
  • 运行日志/设备标记:assets/model_result.png

七、许可证

本模型遵循 LTX-Video Open Weights License(LTX-Video-Open-Weights-License-0.X.txt), 2B v0.9.1 版本遵循 RAIL-M License。详见仓库内许可证文本。

精度限制与社区跟进

隔离实验显示,同一 latent 经 CPU 与 NPU VAE 解码的一致率约为 0.975;NPU fp64 解码路径不可用,已验证的 runner 级候选无法达到官方 1.0 离散门槛。仓库按最大适配努力发布,不声明精度 PASSED,欢迎社区继续优化算子和 VAE 路径。

Agent 使用截图

以下图片由真实 Model Agent 对话记录、npu-smi 设备日志和最终 NPU 推理日志 以无头浏览器渲染生成;每张 PNG 均有同名 .provenance.json,记录源证据哈希。

Model Agent 完整适配工作流

Model Agent 完整适配工作流

昇腾 NPU 设备调用

昇腾 NPU 设备调用

模型最终适配验收结果

模型最终适配验收结果