Deng_RH/LTX-2
模型介绍
文件和版本
Pull Requests
讨论
分析

LTX-Video (LTX-2) 昇腾NPU部署文档

1. 模型简介

模型名称： LTX-Video-2B (LTX-2)

模型链接： HuggingFace | HF-Mirror 镜像

模型描述： LTX-Video (LTX-2) 是 Lightricks 发布的开源文生视频（Text-to-Video）扩散模型，基于 DiT（Diffusion Transformer）架构。模型支持从文本描述生成视频序列，具有较高的时序一致性和视觉质量。蒸馏版（distilled）减少了推理步数，显著提升生成速度。

模型架构： T5-FLAN Text Encoder + LTX-Video Transformer (DiT) + VAE 潜在空间编解码

参数规模： 1,923,385,472（约 1.92B，Transformer 部分）

2. 环境依赖

依赖项版本要求说明
Python>= 3.10推荐 3.11
torch / torch_npu2.10.0昇腾 NPU 运行时
diffusers>= 0.32.0LTX-Video Pipeline 支持
transformers>= 4.30.0T5 文本编码器
accelerate>= 0.30.0模型加速加载
safetensors>= 0.4.0权重文件格式
numpy>= 1.26.0数值计算
fastapi>= 0.100.0HTTP 服务框架
uvicorn>= 0.20.0ASGI 服务器
Pillow>= 9.0.0图像帧处理
昇腾驱动CANN 8.5.1推荐最新版

安装命令：

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

pip install -r requirements.txt

3. 推理步骤

3.1 环境准备

# 加载 CANN 环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 检查 NPU 设备
npu-smi info

3.2 下载模型权重

# 从 HF-Mirror 国内镜像下载（约 33GB）
pip install huggingface_hub
export HF_ENDPOINT=https://hf-mirror.com

# 下载核心推理权重
python3 -c "
from huggingface_hub import hf_hub_download
import os
base = '/data2/drh/LTX-Video-model/ms-git'
os.makedirs(base, exist_ok=True)

# Transformer 权重（2个分片）
for f in ['diffusion_pytorch_model-00001-of-00002.safetensors', 'diffusion_pytorch_model-00002-of-00002.safetensors']:
    hf_hub_download('Lightricks/LTX-Video', f'transformer/{f}', local_dir=base)
# VAE 权重
hf_hub_download('Lightricks/LTX-Video', 'vae/diffusion_pytorch_model.safetensors', local_dir=base)
# Text Encoder 权重（4个分片）
for i in range(1,5):
    hf_hub_download('Lightricks/LTX-Video', f'text_encoder/model-{i:05d}-of-00004.safetensors', local_dir=base)
# 配置文件
hf_hub_download('Lightricks/LTX-Video', 'model_index.json', local_dir=base)
hf_hub_download('Lightricks/LTX-Video', 'scheduler/scheduler_config.json', local_dir=base)
hf_hub_download('Lightricks/LTX-Video', 'tokenizer/spiece.model', local_dir=base)
"

# 或直接设置 MODEL_PATH 环境变量指向已下载的权重目录
export MODEL_PATH=/data2/drh/LTX-Video-model/ms-git

3.3 运行推理

# 单次推理（文生视频）
python3 inference.py \
  --prompt "一只可爱的小猫在阳光下的花园里散步，电影级画质" \
  --num-inference-steps 8 \
  --num-frames 9 \
  --width 256 \
  --height 128 \
  --seed 42

# 启动 FastAPI 服务化推理
python3 service.py --port 8082

# 端到端测试
python3 test_case.py --port 8082

3.4 推理参数说明

参数类型默认值说明
--promptstr-正向提示词（必需）
--negative-promptstrNone负向提示词
--num-inference-stepsint8去噪推理步数（蒸馏版推荐4-8步）
--num-framesint9生成帧数
--widthint256视频宽度
--heightint128视频高度
--seedint42随机种子
--guidance-scalefloat3.0分类器引导系数
--devicestrnpu:0推理设备
--model-pathstr自动检测模型权重目录

4. 测试样例及输出结果

样例：文生视频推理

输入：

提示词: "一只可爱的小猫在阳光下的花园里散步，电影级画质，4K高清"
推理步数: 8, 帧数: 9, 分辨率: 256×128, 种子: 42

输出：

模型加载耗时: 32975 ms (约33 秒)
推理耗时: 4604.39 ms (4.60 秒)
生成帧数: 9, 帧尺寸: 256×128 px
每帧平均耗时: 511.60 ms
设备: Ascend910B1 (NPU:0, 60.96 GB 显存)

5. Agent适配截图

5.1 Agent适配全过程截图

Agent 适配流程

5.2 NPU设备调用截图

NPU 设备调用

5.3 模型适配结果截图

模型适配结果

6. 性能数据

指标耗时
Pipeline 加载（首次）32,975 ms
推理（8步，9帧，256×128）4,604 ms (4.60 秒)
每帧平均511.60 ms
NPU 显存占用（推理中）~18 GB / 60.96 GB

7. API 接口说明

接口方法说明
/healthGET健康检查，返回 NPU 状态信息
/generatePOST文生视频生成，请求体 {"prompt": "...", "num_frames": 9, ...}
/infoGET模型和设备信息

8. 目录结构

ltx-video-npu/
├── inference.py               # NPU 推理脚本
├── service.py                 # FastAPI 服务
├── test_case.py               # 端到端测试
├── requirements.txt           # 依赖包列表
├── adaptation_report.md       # 适配报告
├── assets/
│   ├── agent_workflow.png     # Agent适配全过程截图
│   ├── npu_device_call.png    # NPU设备调用截图
│   └── model_result.png       # 模型适配结果截图
├── results/                   # 推理结果
└── README.md                  # 本文档

9. 注意事项

  • 推理脚本通过 torch_npu + transfer_to_npu 自动迁移调用 NPU
  • RMSNorm 兼容修复：transfer_to_npu 会破坏 RMSNorm 初始化，需在模型加载后替换 forward 为纯 PyTorch 实现（共修复 134 个模块）
  • 模型使用 bfloat16 精度，Ascend 910B1 对 bfloat16 有良好支持
  • 模型总权重约 33GB（transformer: 7.2GB, vae: 1.6GB, text_encoder: 17.7GB）
  • 国内推荐使用 hf-mirror.com 镜像下载模型权重
  • 若显存不足，可启用 --cpu-offload 将部分模块放到 CPU