|
Download README.md from cp-cp/Act: direct link, hf CLI and curl.
- Browser
- Download file 7.75 kB
-
https://huggingface.co/cp-cp/Act/resolve/main/README.md
- Command line
-
hf download hf://cp-cp/Act/README.md
-
curl -L -H "Authorization: Bearer $HF_TOKEN" -o README.md https://huggingface.co/cp-cp/Act/resolve/main/README.md
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`。 | |