Act / README.md
cp-cp's picture
Clarify long-video KV window
e0e5686 verified
|
Raw History Blame Contribute Delete
7.75 kB

LiveAct

双人动作可控的实时世界模型。输入一张首帧、一句场景描述和两个玩家(或两条机械臂)的逐帧动作,自回归生成 448×512、16 FPS 的视频。基于 Wan2.2-TI2V-5B,经因果 teacher-forcing + DMD 蒸馏,4 步采样,单卡推理。

这个目录只包含推理:代码、权重、打包好的环境和 108 条测试样例,拷到有 GPU 的机器上就能跑。

下载(约 38 GB):

pip install -U huggingface_hub
hf download cp-cp/Act --local-dir LiveAct
cd LiveAct

目录

LiveAct/
├── generate.py              # 生成视频(模型只加载一次,可批量)
├── benchmark_latency.py     # 测速,结果写 JSON
├── run_generate.sh          # generate.py 的 shell 入口
├── run_latency.sh           # benchmark_latency.py 的 shell 入口
├── liveact_core.py          # 加载模型、读输入的公共代码
├── configs/liveact.yaml     # 推理配置(路径相对于 LiveAct/)
├── samples/                 # 108 条测试样例:metadata.jsonl + images/
├── weights/                 # 全部权重,约 31 GB
├── env/liveact-env.tar.gz   # conda-pack 环境(Python 3.11 + torch 2.7.1 cu128),8.6 GB
├── pipeline/ utils/ wan/    # 模型代码
└── tools/export_checkpoint.py

weights/ 内容:

文件 大小 说明
liveact_stage3_step700_ema.safetensors 18.5 GB LiveAct 生成器(含完整 DiT + 动作模块,EMA 权重)
models_t5_umt5-xxl-enc-bf16.safetensors 11.4 GB 文本编码器
Wan2.2_VAE.safetensors 1.4 GB VAE
umt5-xxl/ 21 MB tokenizer
Wan2.2-TI2V-5B/config.json 1 KB DiT 结构配置(不需要原始 Wan 权重)

环境

硬件:单张 ≥ 48 GB 显存的 NVIDIA GPU。81 帧生成的峰值显存约 43 GB。B200 / B300 需要 CUDA ≥ 12.8 的驱动(nvidia-smi 显示的 CUDA Version ≥ 12.8,驱动 ≥ 570)。

方式一:直接用打包好的环境(推荐)

mkdir -p ~/envs/liveact
tar -xzf env/liveact-env.tar.gz -C ~/envs/liveact
source ~/envs/liveact/bin/activate
conda-unpack                         # 修正环境内路径,只需执行一次
python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))"

方式二:自己装

conda create -n liveact python=3.11 -y && conda activate liveact
pip install torch==2.7.1 torchvision==0.22.1 --index-url https://download.pytorch.org/whl/cu128
pip install -r requirements.txt
pip install flash-attn==2.8.3 --no-build-isolation   # 可选

注意力后端: 装了 flash-attn 就用它,没装就自动用 PyTorch SDPA,两者速度差不多。如果 flash-attn 在 B 卡上报 no kernel image is available 之类的错误,加 LIVEACT_ATTN=sdpa 强制走 SDPA,不用卸载:

LIVEACT_ATTN=sdpa bash run_generate.sh

快速开始

所有命令都在 LiveAct/ 下执行。模型加载需要 1–2 分钟(主要是读 30 GB 权重,放在本地 NVMe 上会快很多),之后每条样例单独计时。

# 1. 生成一条(街霸),输出到 outputs/
bash run_generate.sh

# 2. 每种场景各一条:街霸 / 饿狼传说 / 微型赛车 / 机械臂 / 炸弹人
SAMPLES=0,1,2,8,9 bash run_generate.sh

# 3. 跑全部 108 条测试样例
SAMPLES=all bash run_generate.sh

# 4. 长视频:241 帧(15 秒)
SAMPLES=0,9 NUM_FRAMES=241 LONG_VIDEO=1 bash run_generate.sh

# 5. 测速
bash run_latency.sh

其他环境变量:GPU_ID(默认 0)、SEED(默认 0)、OUTPUT_DIR、PYTHON(默认用当前环境的 python)。也可以直接调 Python:python generate.py --help。

每条样例生成完会打印一行 JSON,seconds 是这条样例的端到端生成时间(首帧编码 + 文本编码 + DiT + VAE 解码,不含模型加载和写 mp4):

{"sample": 9, "source": "bomberman_2p_v1", "frames": 81, "seconds": 7.697, "fps": 10.52, "output": "outputs/009_bomberman_2p_v1_seed0_81f.mp4"}

第一条样例包含 CUDA 预热,会慢一些,看速度请看后面几条,或者用 run_latency.sh。

测速

bash run_latency.sh                                   # 81 帧,预热 1 次,测 5 次
REPEATS=10 SAMPLE_INDEX=9 bash run_latency.sh
NUM_FRAMES=241 LONG_VIDEO=1 bash run_latency.sh

结果写到 outputs/latency/*.json,终端会打印汇总,分两种口径:

  • without_vae:文本编码 + 因果 DiT 4 步去噪 + KV cache 更新
  • with_vae:再加上首帧 VAE 编码和整段视频 VAE 解码

参考数据(A800 80GB,81 帧,bf16,单卡):

口径 耗时 输出帧率
without_vae 4.53 s 17.9 FPS
with_vae 6.89 s 11.8 FPS

其中 VAE 解码约 2.34 s。241 帧长视频端到端约 24 s。B200 / B300 上应明显更快,请以实测为准。

样例

samples/metadata.jsonl 共 108 条,按行号索引(SAMPLES=0,3,5 或 SAMPLES=10-20):

场景 条数 行号示例
街霸 2(street_fighter_v6_intense) 26 0, 3, 6
饿狼传说 2(fatalfury2_2p_v1) 22 1, 5, 21
微型赛车(micromachines_2p_v1) 15 2, 4, 12
炸弹人(bomberman_2p_v1) 15 9, 11, 16
双臂机器人放置物体(robotwin_h195_ep20_2p_640x512) 28 8, 10, 17
双机器人叠方块(two_robots_stack_cube_rf_2p_head_global_640x512_v2) 2 57, 91

自定义输入

写一个同样格式的 JSONL,用 --metadata 传进去。每行:

{
  "sample_id": "my_case",
  "input_image": "images/my_first_frame.png",
  "prompt": "场景描述(英文,描述背景和环境)",
  "action_space": { "...": "从同场景的样例里复制" },
  "p1_actions": [[0,0,0,0,0,0,0,1,0,0,0,0], "..."],
  "p2_actions": [[0,0,0,0,0,0,0,0,0,0,0,0], "..."]
}
python generate.py --metadata /path/to/my_inputs.jsonl --samples all
  • input_image:相对路径相对于这个 JSONL 所在目录,会被 resize 到 512×448。
  • p1_actions / p2_actions:每帧一行,每行 12 维。第 i 行对应视频第 i 帧。行数不够 num_frames 时用最后一行补齐,多了截断。
  • action_space:描述两个玩家是谁、12 个通道各是什么动作(如 light_kick、left)。模型通过它理解动作含义,直接从同一场景的样例里复制,只改 agents 里的角色描述即可。
  • 模型只在上面 6 个场景上训练过,其他游戏或画面不保证效果。

长视频

模型训练长度是 81 帧(5 秒)。生成更长的视频时加 --long_video(shell 里 LONG_VIDEO=1),会打开三项推理时的设置,不需要重新训练:

  • 注意力只看首帧 + 16 个历史 latent + 当前 4 个 latent,共 21 个,和训练长度一致(KV 窗口),显存和单块耗时不随长度增长
  • RoPE 位置在窗口内重新编号,不超出训练范围
  • 动作 time embedding 固定在训练区间内

帧数需满足 16k+1(81、161、241、321……)。

常见问题

  • **CUDA error: no kernel image is available**:torch 或 flash-attn 不支持当前 GPU。先确认 torch.version.cuda ≥ 12.8;如果只有 flash-attn 报错,加 LIVEACT_ATTN=sdpa。
  • 显存不足:81 帧峰值约 43 GB,需要 48 GB 以上的卡。
  • 权重放在别处:改 configs/liveact.yaml 里的路径,相对路径以 LiveAct/ 为根,也可以写绝对路径。
  • 复现论文结果:默认只跑条件分支(guidance_scale=1.0 时与论文评测设置等价,更快)。要和论文评测完全同设置,加 --full_cfg。