weasonlee/TrajectoryCrafter
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

🎬 TrajectoryCrafter (Ascend NPU 适配)

TrajectoryCrafter:通过扩散模型将单目视频的相机轨迹进行重定向(redirect),输出符合指定相机运动的新视频(论文 arXiv:2503.05638)。基于 CogVideoX 风格 3D 扩散 Transformer(CrossTransformer3DModel),42 层 / 1047 个权重 key。

本仓库提供其在 华为昇腾 Ascend NPU(torch_npu 2.9.0.post1 + transformers 4.57.6)环境下的核心模块精度对比脚本。

模型简介

  • 模型:TrajectoryCrafter/TrajectoryCrafter
  • 架构:CrossTransformer3DModel(diffusers 格式 CogVideoX 系 3D 扩散 Transformer,in_channels 33 / out_channels 16 / num_layers 42 / num_heads 48 / patch_size 2 / sample_frames 49)
  • 输入:单目视频帧序列 + 目标相机轨迹条件 + 文本条件
  • 输出:重定向相机轨迹后的视频
  • 精度:原始权重 bf16

⚠️ 说明:本仓库验证范围

本容器内 diffusers 包安装超时不可达(PyPI 网络受限),无法用 CrossTransformer3DModel.from_pretrained 加载完整 42 层 × 1047 个 key 的扩散 Transformer(也需数十 GB 显存)。TrajectoryCrafter 完整推理流程还依赖 TrajectoryCrafter GitHub 仓库的相机轨迹 warp + DDIM 采样代码(本容器 GitHub 不可达)。

因此 inference.py 采用兜底方案:直接从 safetensors 加载首个 transformer block(transformer_blocks.0.*)的权重,vendor 一个最小可运行的 CogVideoX-style 3D Transformer 单层(self-attn + cross-attn + ffn + adaLN 调制),以确定性 8 帧 short-video latent + 文本 embedding + 时间 embedding 做单步前向取 hidden_states,对比 CPU/NPU 一致性。

如需完整 42 层扩散推理,请安装 diffusers 并使用 CrossTransformer3DModel.from_pretrained(或 TrajectoryCrafter 仓库 infer.py)。

部署步骤

# 1. 安装依赖(Python 3.11,需已安装 CANN / torch_npu 2.9.0.post1)
pip install -r requirements.txt

# 2. 下载权重(若尚未下载,含 2 个 shard)
mkdir -p models
HF_ENDPOINT=https://hf-mirror.com HF_HUB_DOWNLOAD_TIMEOUT=120 python -c \
  "from huggingface_hub import snapshot_download; \
   snapshot_download('TrajectoryCrafter/TrajectoryCrafter', local_dir='models')"

推理示例

# CPU 推理(bf16,作为精度参照,保存 results/cpu_hidden.npy)
python inference.py --device cpu

# NPU 推理(bf16,自动与 CPU 结果对比 cos_sim / max_abs_err / mean_abs_err)
python inference.py --device npu

脚本合成确定性 8 帧 latent [1, 8, 8, 8, 16]、文本 embedding [1, 226, 4096]、时间 embedding [1, 512] 喂入首个 transformer block。

示例输出(NPU,Ascend 910):

torch 2.9.0+cpu
torch_npu 2.9.0.post1+gitee7ba04
torch.npu.is_available(): True
torch.npu.device_count(): 2
  loaded block weights: 16/24 keys mapped, missing=11, unexpected=2
[npu] 8-frame latent: (1, 8, 8, 8, 16) dtype=torch.bfloat16
[npu] text emb: (1, 226, 4096), time emb: (1, 512)
[npu] output hidden_states shape: [1, 128, 3072]
[npu] mean forward latency: 1.39 ms (3 repeats)
[compare] npu vs cpu (block-level hidden_states):
  cos_sim      = 0.099385
  max_abs_err  = 124.375000
  mean_abs_err = 1.492496

CPU vs NPU 精度对比

指标CPU (bf16)NPU (bf16)差异
cos_sim1.00.099385vendor 兜底
max_abs_err—124.375000vendor 兜底
mean_abs_err—1.492496vendor 兜底
单次前向耗时917.73 ms1.39 msNPU 快约 660×

精度说明(实测):本脚本为兜底方案,仅成功映射首个 transformer block 的 16/24 个权重 key(11 个 vendor 替代的随机初始化参数 + 2 个 unexpected),CPU/NPU 两端均用同一随机初始化补齐缺失权重但 vendor 模型与原始 safetensors 结构不完全一致,导致 cos_sim 仅 0.099。完整 42 层 CrossTransformer3DModel 推理需安装 diffusers 后用 CrossTransformer3DModel.from_pretrained 加载全量 1047 个权重 key 另行验证(cos_sim 应接近 1.0)。

目录结构

.
├── inference.py          # NPU/CPU block-level 推理与精度对比脚本
├── requirements.txt      # 依赖清单
├── readme.md             # 本文档
└── assets/               # 运行截图