maliang / docs /HANDOFF.md
teawhite's picture
docs: HANDOFF points to maliang-teaser backup
fc66c32 verified
|
Raw History Blame Contribute Delete
16.3 kB

maliang / WorldMind / ActionRoPE 项目交接

工作区根目录:/opt/dlami/nvme/zhiyangdeng/。三个项目都以 Wan2.2-TI2V-5B 为基座,先微调出双向教师模型,再用 Causal Forcing++ 三阶段蒸馏(TF → CD → DMD)得到实时因果模型。

项目 做什么 根目录 数据 权重
maliang 由语义图和动作生成 2.5D 动作 RPG 视频的世界模型 /opt/dlami/nvme/zhiyangdeng/maliang HF teawhite/GameCrafter-Data-v10 本机 outputs/;代码、关键权重和评测结果备份在 HF teawhite/maliang(私有)
WorldMind 四层解耦的游戏世界模型,让 Boss 根据局势决策出招 /opt/dlami/nvme/zhiyangdeng/WorldMind HF teawhite/worldmind 本机 ckpt/ 加 HF
ActionRoPE 把动作写进 RoPE 坐标的平面相机游戏世界模型 /opt/dlami/nvme/zhiyangdeng/maliang/ref/arope_git/ActionRoPE HF teawhite/EYBX-processed;原始录像 teawhite/EYBXROAM(私有镜像) HF teawhite/ActionRoPE-internal

每个仓库、每个文件放在哪、能否续训、有哪些缺口,见 docs/CLOUD_REPORT.md(云端资产报告)。


一、maliang

下文 $M = /opt/dlami/nvme/zhiyangdeng/maliang。代码包名为 gc25d。

1. 项目介绍

maliang 是一个「代码驱动」的游戏世界模型:输入首帧、逐帧的数值语义图和动作文本,输出 2.5D 俯视角动作 RPG 视频。推理时语义图由代码直接画出,不依赖游戏引擎(UE)。

  • 输入
    • 首帧 RGB。
    • 每帧一张 uint8 语义 id 图,分辨率 832×480。
    • 每 0.25 秒一句动作文本,例如 "the player is moving right, attacking."。
  • 输出:16 fps 视频。
  • 语义 id
    • 0–6 是场景类别:天空、地面、铺地、建筑、岩石、植被、道具。
    • 玩家部件是 10、12–16,Boss 部件是 11、17–21(躯干、双臂、双腿、武器)。
    • 255 表示未知区域。
  • 模型
    • 在 Wan2.2-TI2V-5B 上加一个语义条件分支。语义图以数值形式直接编码后加到 patch embedding 上,不经过 VAE。
    • 蒸馏后的实时模型每 0.25 秒(一个 cell)做 4 步去噪,用滑动 KV cache 生成长视频,用 TAEHV 解码。
  • 文档:设计规格见 $M/docs/SPEC.md,各组件的实现说明见 $M/docs/impl/。

2. 交付权重

权重 路径
实时模型(DMD,部署用) $M/outputs/distill/gc25d_v10/stage3_dmd/ema/ema_step500.safetensors
双向教师模型(480p) $M/outputs/sft_v10/step-8000.safetensors
双向教师模型(704p,1280×704) $M/outputs/sft_v10_704/step-5000.safetensors
蒸馏中间产物 $M/outputs/distill/gc25d_v10/stage1_tf/、stage2_cd/
基座模型 $M/models/Wan2.2-TI2V-5B/(HF Wan-AI/Wan2.2-TI2V-5B)
旧版实时部署包(含 FastStream 推理加速)。也是评测和数据生成的运行时依赖:TAEHV 解码器、文本表默认路径、FastStream $M/ref/gc25d-live-demo/(HF teawhite/gc25d-live-demo,私有)

上表中的交付权重(DMD ema500、两个教师、stage1 dit8000、stage2 ema8000)和各阶段的续训文件都备份在 HF teawhite/maliang,路径与本机相同。蒸馏的其他中间步数权重只在本机。续训文件如下:

  • 双向教师模型:480p 用 outputs/sft_v10/state_B(step 8000),704p 用 outputs/sft_v10_704/state_A(step 5000)。
  • 蒸馏:stage1 用 outputs/distill/gc25d_v10/stage1_tf/state_B(step 8000);stage2 用 dit8000 加 ema8000;stage3 用 dit500、critic500 加 ema500。
  • 用法见该仓库 README 的「续训」一节。

teaser 素材($M/outputs/teaser/,约 20 万个文件)全部备份在 HF 数据集 teawhite/maliang-teaser(私有),说明见它的 README:

  • rollouts/:480p 泛化类单条结果;
  • hd704/:1280×704 高清版;
  • edits/:编辑类,包括换 Boss、无限世界 1–3 轮;
  • _extras/*.tar:其余本地中间文件,带 manifest*.json 清单,解包到 outputs/teaser/ 就能还原本机目录。

生成和打包代码在 teawhite/maliang 的 scripts/teaser/ 和 tools/hf_stage/。

3. 数据集

数据 路径 说明
原始数据 $M/data/GameCrafter-Data-v10/ 来自 HF teawhite/GameCrafter-Data-v10,482 GB,256 个 run,共 12,800 条 81 帧 clip。分写实户外(v10_real)和多画风游戏场景(v9_stylized)两部分。说明见该目录下的 README.md
480p 训练数据 $M/data/gc25d_v10/ 53 GB。480p 的训练和评测都用这份
704p 训练数据 $M/data/gc25d_v10_704/ 114 GB
小样 $M/data/gc25d_v10_mini/、$M/data/gc25d_v10_704_mini/ 4 个 run,用于冒烟测试
文本嵌入表 $M/data/gc25d_v10/text_table_gc25d.pt 动作文本的 UMT5 预计算嵌入

训练数据的目录结构如下:

  • index/clips.jsonl:每行一条 clip,记录场景、run、train/val 划分等信息。
  • latents/:VAE latent 和动作文本。
  • cond/:语义 id 图。
  • cond_ext/、cond_ext_canvas/:stage3 用的后续扩展帧。
  • meta/:相机参数、角色胶囊体等元数据。

train/val 按 run 划分,val 共 10 个 run、500 条 clip。

用原始数据生成训练数据:

cd $M
env $ENV .venv/bin/python code/gc25d/prep_v10.py --src $M/data/GameCrafter-Data-v10/data --out $M/data/gc25d_v10 --gpus 0,1,2,3,4,5,6,7
env $ENV .venv/bin/python code/gc25d/verify_prep.py --root $M/data/gc25d_v10
env $ENV .venv/bin/python code/gc25d/ext_canvas.py --root $M/data/gc25d_v10
# 生成 704p 数据:命令前加 GC_RES=1280x704,--out 改为 data/gc25d_v10_704

4. 训练代码

模型和训练代码在 $M/code/gc25d/,蒸馏代码在 $M/code/gc25d/gcdistill/。

阶段 启动脚本 主程序
双向 SFT(教师) scripts/train_sft.sh code/gc25d/train.py(加上 dataset.py、model.py)
蒸馏 stage1:Teacher Forcing code/gc25d/gcdistill/run_stage1.sh gcdistill/ar_tf_gc.py
蒸馏 stage2:一致性蒸馏 code/gc25d/gcdistill/run_stage2.sh gcdistill/cd_gc.py
蒸馏 stage3:DMD code/gc25d/gcdistill/run_stage3.sh gcdistill/dmd_gc.py
  • scripts/chain_after_sft.sh:依次跑完三阶段蒸馏和评测。中断后重新运行即可,已完成的阶段会自动跳过。
  • gcdistill/config_stage*.json:各阶段的配方。
  • code/gc25d/tests/:单元测试(pytest)。
  • $M/configs/:accelerate 配置。
  • $M/code/arope/:从 ActionRoPE 引用的公共模块。只读,不要修改。
cd $M
OUT=outputs/sft_v10 bash scripts/train_sft.sh                    # 双向 SFT,8 卡
SFT=$M/outputs/sft_v10/step-8000.safetensors setsid nohup bash scripts/chain_after_sft.sh \
    > outputs/distill/gc25d_v10/chain.log 2>&1 &                 # 三阶段蒸馏

5. 评测代码

评测 入口 用途
双向模型评测 code/gc25d/sample.py 在 val clip 上生成视频,对 GT 算 PSNR / SSIM
实时模型评测 code/gc25d/gcdistill/eval_rollout.py 按部署方式自回归生成,支持 60 秒长链,算 PSNR / ZNCC / 亮度漂移
自定义输入推理 code/gc25d/sample_user.py 输入自备的首帧、语义 id 视频和文本,不需要 GT
画风 / 角色外观泛化 scripts/genbench3/ 测试没见过的画风和玩家 / Boss 外观,用 VLM 打分
场景泛化 scripts/genbench4/ 测试没见过的场景类型(城堡、地牢、岩浆等),用 VLM 打分
推理速度 scripts/bench_fast704.py 测 FastStream 每个 cell 的耗时
展示视频 scripts/genbench4/showcase.py 左边是条件,右边是生成结果。成片在 outputs/genbench4/showcase.mp4

评测结果在 $M/outputs/ 下对应的子目录里。genbench3 / genbench4 用到的 FLUX 首帧生成和 Qwen3-VL 打分跑在 /opt/dlami/nvme/zhiyangdeng/PCE/envs/pce_f3 环境。

cd $M
env CUDA_VISIBLE_DEVICES=0 $ENV .venv/bin/python code/gc25d/gcdistill/eval_rollout.py \
    --ckpt outputs/distill/gc25d_v10/stage3_dmd/ema/ema_step500.safetensors \
    --chain_cells 241 --n_clips 10 --vae tae --out outputs/distill/gc25d_v10/eval/stage3_ema500/chain241
env CUDA_VISIBLE_DEVICES=0 $ENV .venv/bin/python code/gc25d/sample.py \
    --ckpt outputs/sft_v10/step-8000.safetensors --val_n 20 --out_dir outputs/sft_v10/eval_step-8000/L1_cond

6. 运行环境

Python 解释器是 $M/.venv/bin/python(torch 2.11,DiffSynth-Studio 安装在 $M/third_party/DiffSynth-Studio)。每条命令都要带上下面的环境变量:

M=/opt/dlami/nvme/zhiyangdeng/maliang
ENV="DIFFSYNTH_SKIP_DOWNLOAD=True PYTHONPATH=$M/code/gc25d:$M/code/arope \
HF_HOME=/opt/dlami/nvme/zhiyangdeng/.cache/huggingface TMPDIR=$M/.tmp \
TORCHINDUCTOR_CACHE_DIR=$M/.tmp/inductor TRITON_CACHE_DIR=$M/.tmp/triton"
# 分辨率由 GC_RES 指定:832x480(默认)或 1280x704

二、WorldMind

下文 $WM = /opt/dlami/nvme/zhiyangdeng/WorldMind。HF 备份在 teawhite/worldmind。

1. 项目介绍

WorldMind 把「Boss 下一步出什么招」从视频生成里拆出来,变成一个显式的、读取局势的决策步骤。论文题目是《WorldMind: Decoupled Game World Model for State-Aware NPC Behavior》(AAAI-27 投稿)。

系统分四层:

  • L1 理解:ResNet18 + GRU,从画面读出局势。
  • L2 决策:Gemma-4-E2B,通过 prompt 决定 Boss 出招。
  • L3 控制:把决策翻译成逐段的文本条件。
  • L4 生成:Wan2.2-TI2V-5B 微调后再蒸馏成实时模型。

覆盖三个游戏(V Rising、Hollow Knight、Isaac),共 14 个 Boss。

权重谱系见 /opt/dlami/nvme/zhiyangdeng/LINEAGE.md,代号对照见 /opt/dlami/nvme/zhiyangdeng/GLOSSARY.md。

2. 数据集

数据 路径 说明
原始采集 $WM/data/raw/ 三个游戏共 5,733 场对局。完整版在 HF(165 GB),本机只有一部分
服务端日志 $WM/data/serverlogs/ 20 Hz 的游戏状态日志
标注 $WM/data/labels/v4/ 逐段的动作和出招标注,以及 prompt
文本嵌入表 $WM/data/text_tables/ HF 上有 4 张:v4_ortho_2365(v4.1 主线)、v35_fine_6011(闭环渲染器)、player_only_22、v35_move_sidecar。文档里列的 v3_coarse_486、vrising_only_137 在任何地方都没有
训练 latent — 用 $WM/train/code/scripts/precompute_latents.py 从原始数据重新计算

3. 训练代码

模块 位置
L4 双向模型训练 $WM/train/code/scripts/train.py,启动脚本也在 train/code/scripts/
L4 三阶段蒸馏 启动脚本在 $WM/distill/launch/,代码在 $WM/distill/code/
L1 理解模型 $WM/eval/authoritative/l1_unified/

4. 权重

L4 的最新主线是 v4.1。下表路径相对于 $WM;HF 上的路径是 WorldMind/ 加同一路径。

权重 路径 位置
L4 主线双向模型(v4.1) ckpt/l4_bidir/v4_ortho/dits/dit_step120000.safetensors 仅 HF
L4 主线蒸馏 stage1 ckpt/l4_distill/stage1_ar/v4/dits/dit_step20000.safetensors 仅 HF
L4 主线蒸馏 stage2(CD) ckpt/l4_distill/stage2_cd/v4_LIVE/ema/ema_step12000.safetensors 仅 HF
L4 主线实时模型(DMD,训练停在 430/500 步,最新存档为 400 步;续训用的 dit400 和 critic400 也在) ckpt/l4_distill/stage3_dmd/v4/ema/ema_step400.safetensors 仅 HF
论文闭环实验用的 L4 渲染器(v3) ckpt/l4_bidir/v3_boss_v35/dits/dit_step70000.safetensors 本机和 HF
v3 实时模型(DMD,吞吐和长时 rollout 评测用) ckpt/l4_distill/stage3_dmd/v3_cd15k/ema/ema_step400.safetensors 本机和 HF
L1 理解模型(三个游戏各一个) ckpt/l1/canon_3f/ 本机和 HF
出招识别器(Qwen3-VL-4B LoRA) ckpt/l2/aca_qwen3vl_lora/checkpoint-2340 本机和 HF
其余权重 HF teawhite/worldmind 的 WorldMind/ckpt/ 目录 HF

5. 评测代码

评测 位置
闭环对局(L1 → L2 → L3 → L4) $WM/eval/closedloop/harness/,配置在 harness/configs/l2_strict.json
VLM 判官评测 $WM/eval/judge/
L1 / L2 静态评测 $WM/eval/static/current/
出招识别(ACA) $WM/eval/aca/
论文主表数据来源 $WM/eval/authoritative/AUTHORITATIVE.md
论文源码 $WM/paper/tex/

6. 运行环境

  • 先运行 source /opt/dlami/nvme/zhiyangdeng/env.sh,再用 WM_ENV 选择 conda 环境。
    • pactbench:L1 和静态评测。
    • wmloop:闭环对局。
    • gemma4:L2 决策。
    • aca:出招识别。
  • L4 训练和蒸馏需要 gamemaster 环境。本机还没有这个环境,可以参考 $WM/_archive/srcmachine_env/conda_gamemaster.yml 重建。
  • GPU 7 上常驻 gemma_server.py(端口 8018),这是 L2 的推理服务,不要停掉。

三、ActionRoPE

下文 $A = /opt/dlami/nvme/zhiyangdeng/maliang/ref/arope_git/ActionRoPE(git 仓库,分支 world-canvas)。本机只有代码,数据和权重都在 HF 上。

1. 项目介绍

ActionRoPE 面向平面相机游戏的世界模型:动作不通过文本输入,而是作为 RoPE 位置坐标的偏移(玩家累计屏幕位移)写进视频 token。这样画面内容和相机运动在空间上保持一致。

  • 数据是《恶意不息》(No Rest for the Wicked)的 2.5D 俯视角漫游录像。
  • 论文题目是《ActionRoPE: Action as Coordinates for Spatially Consistent Control in Planar-Camera Game World Models》(ICLR 2027 投稿)。
  • maliang 的训练和蒸馏代码由本项目 fork 而来。

2. 数据集与权重

数据

  • HF dataset teawhite/EYBX-processed,解包后约 189 GB。内容包括 latent、mp4、元数据和 20 Hz 日志,规格为 832×480、81 帧、16 fps。
  • 配套文件 arope_sidecar.pt 和 text_table_actionrope.pt 在 HF teawhite/ActionRoPE-internal 的 data/ 下。
  • 下载命令:hf download teawhite/EYBX-processed --repo-type dataset --local-dir data
  • 原始录像:HF dataset teawhite/EYBXROAM(私有,161.9 GB),是公开数据集 yuzhewu207/EYBXROAM 的逐字节镜像。从原始录像重新处理的流水线在 teawhite/EYBX-processed 的 code/run_all.sh。

权重(都在 HF teawhite/ActionRoPE-internal)

  • 双向教师模型:checkpoints/arope_10k_ga2/step-10000。
  • 论文主模型:backup_2026-09-17/checkpoints/wan_arope_cns_shift2_5k__step-5000。
  • 蒸馏学生模型和完整的权重清单见 checkpoints/README.md。本机有一份部分下载的副本:/opt/dlami/nvme/zhiyangdeng/maliang/ref/ActionRoPE-internal/。

3. 代码位置

模块 位置(相对 $A)
说明 README.md
核心实现(ActionRoPE 位置编码) actionrope/arope.py
双向模型训练 scripts/train_arope.sh → actionrope/train.py,数据集在 actionrope/dataset.py
推理 actionrope/infer.py,示例 scripts/infer_demo.sh
双向模型评测 actionrope/eval_bg50.py、actionrope/eval_val_replay.py
三阶段蒸馏 distill/stage1_ar/、distill/stage2_cd/、distill/stage3_dmd/,操作手册是 distill/RUNBOOK.md
蒸馏模型评测 distill/eval/
实时 Demo demo/run.sh
对比基线 baseline/、skyreels/、ltx/、h3/

脚本里写死了 ROOT=/opt/dlami/nvme/zhiyangdeng/ActionRoPE,本机没有这个目录。运行前需要先改 ROOT,或者把仓库放到这个位置。


四、机器与注意事项

  • 硬件:8 × H200、192 核 CPU、2 TB 内存。
  • 磁盘:根分区 / 只有 100 GB。数据、权重、日志和缓存一律放到 /opt/dlami/nvme/(28 TB)。
  • AWS 鉴权:不要读取或修改本机的 AWS 鉴权信息(~/.aws/、AWS_* 环境变量、实例元数据凭证),否则机器会报废。
  • 系统操作:不使用 sudo / apt,不要停掉别人启动的进程。
  • HuggingFace:token 已配置在 HF_HOME/token,不要写进代码或日志。