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):
```bash
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)。
**方式一:直接用打包好的环境(推荐)**
```bash
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))"
```
**方式二:自己装**
```bash
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,不用卸载:
```bash
LIVEACT_ATTN=sdpa bash run_generate.sh
```
## 快速开始
所有命令都在 `LiveAct/` 下执行。模型加载需要 1–2 分钟(主要是读 30 GB 权重,放在本地 NVMe 上会快很多),之后每条样例单独计时。
```bash
# 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
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` 传进去。每行:
```json
{
"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], "..."]
}
```
```bash
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`。