INTACT 使用指南

INTACT（INtent-To-ACTion）是一款开源的端到端 JEPA 世界模型。它在 LeWM 的基础上增加一个"意图 → 动作"的 Actor，从带动作标注、无奖励的离线轨迹中学习。部署时输入当前画面和目标画面，模型直接输出动作块，不需要 CEM 这类大规模动作搜索。

每个任务只训练 1 个 epoch，不做任何搜索的 Direct 推理在 PushT、Cube、Reacher、TwoRoom 四个仿真任务上的平均成功率为 95.61%，规划侧耗时 3.9–4.8 ms。

资源入口：

本节介绍 INTACT 的工作原理、两套运行时、发布的模型和环境配置。完成本节后，你可以在自己的 GPU 机器上装好环境、准备好数据，并跑通一次单任务 smoke 训练。

仓库发布的训练配置和评测都针对这四个仿真任务。

INTACT 保留 LeWM 的 Encoder 和 Forward Predictor，再加一个 Actor：

1. 编码。 ViT-Tiny/14 Encoder 把 224×224 的 RGB 画面编码成 192 维 latent z_t。Forward Predictor 根据历史 latent 和动作预测下一步 latent，回答"执行这个动作会发生什么"。

2. 构造意图。 意图 m_t 是两个 latent 之差，有两种实例：

   • 局部意图（local intent）m_t = z_{t+1} − z_t：这一步真实发生的变化，梯度正常回传；

   • 目标意图（goal intent）m_t = sg(z_g) − z_t：当前离目标还差多少，目标一端截断梯度。

3. 读出动作。 两种意图用同一个 Actor、同一种四槽输入 [z_t, m_t, z_t ⊙ m_t, A(a_{t−1})]，输出动作的对角高斯分布。A(a_{t−1}) 是上一步动作的编码。

4. 端到端训练。 每个 8 帧窗口有 7 个相邻转移。每个转移都用同一个示范动作，分别计算局部意图和目标意图两项负对数似然，再和 Forward 预测损失、SIGReg 正则一起训练，动作梯度一直回传到 Encoder。两种意图之间不加距离约束。

5. Direct 推理。 编码当前画面和目标画面，取 Actor 输出的均值作为动作，用 Forward Predictor 向前推一步；重复 5 步得到一个动作块。执行后从新的真实画面重新规划。整个过程不评估任何候选动作序列。

两者的 Actor 参数结构不同：论文 checkpoint 使用旧版五槽输入，当前运行时使用四槽输入。不要用 scripts/eval.sh 加载论文 checkpoint，也不要修改 paper_runtime/ 中的文件，它们与论文评测时记录的文件指纹一致。

Hugging Face 仓库 INTACT-JEPA/INTACT 的 main 分支有三组模型。E1、E5 分别表示训练 1 个和 5 个 epoch。

同一批 72 个论文 checkpoint 还以固定版本 paper-e5-goal-v1 发布，第 5 节的下载脚本使用这个版本。各模型的成功率见 5.5 节。

install.sh 在仓库下创建 .venv，先安装 torch==2.6.0 和 torchvision==0.21.0，再安装 requirements-cu124.lock 中锁定的全部依赖，最后运行 pip check 和 scripts/verify_install.py。机器上有 uv 时用 uv 建环境，没有时用 Python 3.10 自带的 venv 和 pip。

没有 NVIDIA GPU 的机器只能做导入和配置检查，不能训练或评测：

注意 安装完成后，不要再单独安装未锁定版本的 PyTorch 或 torchvision。CPU 版和 CUDA 版 wheel 混装，是导入时缺少算子的常见原因。安装脚本不能用时，按 docs/INSTALL.md 的 "Manual equivalent" 一节手动安装。

编辑 .env，填写四个变量：

当前 shell 中已经导出的同名变量优先于 .env。加载并检查实际生效的路径：

fleet_env.sh 会把 stable-worldmodel 的缓存根目录 STABLEWM_HOME 设为 INTACT_OUTPUT_HOME。下文出现的 checkpoint 相对路径，都以 $INTACT_OUTPUT_HOME/checkpoints/ 为起点。

提示 少数命令按 STABLEWM_HOME 而不是 LOCAL_DATASET_DIR 找数据（1.8 节的格式转换、5.2 节的论文评测）。把 LOCAL_DATASET_DIR 和 INTACT_OUTPUT_HOME 设成同一个目录，可以省去这两处的额外参数。

INTACT 使用 LeWM 官方数据集，训练脚本不会自动下载。四个压缩包都在 LeWM 的 Hugging Face 合集中：

下载并解压到 $LOCAL_DATASET_DIR/datasets/。hf 命令随锁定的 huggingface_hub 一起装在 .venv 中：

PushT 训练读取 Lance 格式，需要把 HDF5 转换一次。回到仓库目录运行：

转换命令在 $STABLEWM_HOME/datasets/ 下找源文件并写出结果。命令前的 STABLEWM_HOME="$LOCAL_DATASET_DIR" 让它在数据目录里转换；两个根目录相同时可以省略。

完成后的目录布局：

注意 转换后不要删除 pusht_expert_train.h5。训练读取 .lance，但 Official 评测按 pusht_expert_train.h5 读取起点和目标状态。

注意 Reacher 的评测配置（config/eval/reacher.yaml）读取的数据集是 dmc/reacher_random，即 datasets/dmc/reacher_random.h5，不是上面布局中的 reacher.h5。如果评测 Reacher 时提示找不到这个文件，说明本机缺少它。

在仓库根目录依次运行三项检查，再跑一次 smoke 训练：

smoke 只确认代码路径能跑通，不代表模型精度。有 4 张 GPU 时，再检查四任务训练：

注意 输出目录不会被覆盖。同名日志已存在时，启动脚本直接退出并提示 Log already exists。再次运行时换一个 --run-name。

本节为一个任务训练一个 INTACT 模型，即论文中的单任务 E1 设置。命令都在仓库根目录运行；train.sh 会自行加载 .env。

train.sh 的前两个参数依次是意图坐标和任务。

把 pusht 换成 cube、reacher 或 tworoom 训练其他任务；把 goal 换成 waypoint 训练对照坐标。论文的单任务设置是用全部数据训练 1 个 epoch，即上面的命令。

train.sh 自己识别以下选项，其余参数原样转给 Hydra：

Hydra 覆盖项写在命令末尾，格式为 键=值，例如 loader.num_workers=4。常用参数如下，默认值来自 config/train/intact_goal.yaml：

注意 训练固定使用 Math SDPA（sdpa_backend: math）。要和论文结果对比时，保持以上默认值，只改 seed。换种子时同时换 --run-name，或者不写 --run-name，让脚本按种子自动命名；沿用旧名称会因目录已存在而停止。

脚本启动时打印本次的意图坐标、任务、run 名称、数据目录、输出目录和日志路径。训练在第 1 步、每 100 步和最后一步各输出一行进度：

同样的记录逐行写入 checkpoints/<run>/metrics/train.jsonl。run_metadata.json 中的 status 依次为 configured、running，正常结束时为 complete，出错时为 failed，并记下异常类型。训练成功时，最后一行是：

$INTACT_OUTPUT_HOME/checkpoints/<run>/ 中有：

完整的终端输出在 $INTACT_OUTPUT_HOME/logs/<run>.log。checkpoint 目录已有文件时，训练会报 FileExistsError 并停止，不会覆盖旧结果。

本节训练论文中的四任务共享 Encoder 模型（E5 设置）。4 个进程各负责一个任务、各占一张 GPU，共享同一个 Encoder 和 projector；Forward Predictor、动作编码器和 Actor 按任务分开。

• 四个数据集都已就位，bash scripts/check_fleet.sh 通过。

• 有 4 张可用 GPU。设置了 CUDA_VISIBLE_DEVICES 时必须正好列出 4 张，否则脚本直接退出。

• 进程与任务的对应关系固定：rank 0 为 PushT，rank 1 为 Cube，rank 2 为 Reacher，rank 3 为 TwoRoom。

脚本用 torch.distributed.run 在本机启动 4 个进程，每一步同步一次共享部分的梯度。默认配置为：fused AdamW，学习率 5e-4 全程不变，权重衰减 1e-3，SIGReg 权重 0.03，5 个 epoch，每个任务 batch size 256，Math SDPA，启用确定性算法。

注意 复现论文的共享 Encoder 结果时，不要调小 --batch-size。显存不够而改动了 batch size 的结果，要在报告中写明。

每个进程按同样的节奏输出一行进度，并写入各自的记录文件：

每个 epoch 结束时，脚本先确认 4 个进程的共享参数哈希一致（不一致会报 Shared states diverged 并停止），再为每个任务保存 checkpoint，最后打印 MULTITASK_EPOCH_COMPLETE=。产物布局：

提示 任务目录里每个 epoch 有一个 .pt 文件，评测时要写到具体文件，例如 intact_multitask_goal_s3072_e5_pusht/weights_epoch_5.pt。只写目录会因为目录里有多个 .pt 而报错。

本节在仿真环境中评测 checkpoint。scripts/eval.sh 是唯一的评测入口，按 Official LeWM 协议判分；CLEAR-LeWM v0.8 协议另用 clear_eval.py，见 4.5 节。

Guarded A 的规划长度 H=5、重规划长度 RH=5，初始采样标准差 0.25（原始动作空间），每轮保留前 16 条。最后对均值计划做一次确定性复评，这一次单独记录，不计入 384 条候选。

注意 Guarded A 的参数被评测代码锁定。通过 Hydra 改动其中任何一项（例如 solver.num_samples），评测都会报 Guarded A configuration mismatch 并停止。

第 6 个参数起是 Hydra 覆盖项。每个 episode 从专家数据中随机抽一个起点，以 25 步之后的状态为目标，最多执行 50 步。

论文协议对每个 checkpoint 评测三个种子，每个种子 100 个 episode：

评测四任务模型时，任务参数要和 checkpoint 目录对应：

direct 和 guarded_a 使用同一套因果动作历史：

1. 在抽到的起点 t，Actor 第一次读到的是数据集中 t 之前的 5 个动作 rows[t-5:t]。只有起点前不足 5 步（已到真实 episode 开头）时，才用原始零动作左侧补齐。

2. 之后每一步，把控制器实际执行的动作移入历史。

3. 当前数据行的动作 row[t] 和目标动作都不会提供给 Actor。

cem 模式关闭 Actor，不使用动作历史。Official 和 CLEAR 是两种判分协议，不是两种历史模式。

结果写在 $INTACT_OUTPUT_HOME/<run>/ 下，不在 checkpoints/ 目录里：

.txt.json 记录了推理方式、判分协议、checkpoint 的 SHA-256、评测种子、配置哈希、SDPA 设置、主机与 GPU、评测代码文件的哈希、指标、抽到的 episode 与起点，以及规划耗时和候选数量的汇总（总和与均值）。

CLEAR-LeWM 是单独发布版本的评测器，复位清单和成功判据都与 Official 不同。先按它的说明安装其固定版本的环境，再在 INTACT 仓库根目录运行：

/path/to/CLEAR-LeWM-v0.8 换成本机的 CLEAR-LeWM 目录。--mode 可选 direct、pure_cem、guarded_a。

注意 Official 和 CLEAR 的成功率回答的是不同的问题，要分开报告，不要合并到同一个平均值里。

本节下载论文的四任务共享 Encoder checkpoint，用冻结的论文运行时复现论文主表，并说明 Hugging Face 上单任务模型的使用方式。

论文矩阵有 6 个对照单元，每个单元 3 个训练种子（0、42、3072），每个种子 4 个任务，共 72 个 checkpoint：

脚本从 INTACT-JEPA/INTACT 的 paper-e5-goal-v1 版本匿名下载，先核对 SHA256SUMS 本身和每个存档的哈希，解压到 $STABLEWM_HOME（即 INTACT_OUTPUT_HOME），再逐个核对 checkpoint 的大小、哈希和配套文件。成功时最后一行是 Paper checkpoints installed under …/checkpoints。

• 想放到别的目录，在最后加一个路径参数，例如 bash scripts/download_paper_checkpoints.sh matrix all /path/to/cache。

• 需要换镜像时，设置 INTACT_HF_REPO、INTACT_CHECKPOINT_REVISION 或 INTACT_CHECKPOINT_BASE_URL。

训练种子只能是 0、42、3072；评测种子默认 0，episode 数默认 100。eval_paper_matrix.sh 对 lewm 使用 CEM 300×30，对其余五个单元使用零搜索 Direct。两个脚本都会先核对 checkpoint 哈希，再把 paper_runtime/ 放到 PYTHONPATH 最前面运行评测。

脚本从 $STABLEWM_HOME/checkpoints/ 读取 checkpoint。下载时指定了别的目录，就先把 PAPER_CHECKPOINT_HOME 设为那个目录，即 checkpoints/ 的上一级。结果写在 $STABLEWM_HOME/<checkpoint 目录名>/，文件名为 pusht_results.txt、ogb_cube_results.txt、dmc_results.txt 或 tworoom_results.txt，另有同名 .json。

注意 论文评测脚本按 $STABLEWM_HOME/datasets/ 找数据，不读 LOCAL_DATASET_DIR。两个根目录不同时，在命令末尾加 cache_dir="$LOCAL_DATASET_DIR"，例如 bash scripts/eval_paper_direct.sh pusht 0 0 100 cache_dir="$LOCAL_DATASET_DIR"。eval_paper_matrix.sh 要先写全前 5 个参数，再加这一项。

goal_intact 单元各训练种子的 Official Direct 成功率（%），每格为评测种子 0、1、42 各 100 个 episode 的平均：

六个单元的完整结果见 5.5 节。

目录中有三个存档 intact-goal-e1-single-seed<种子>.tar.gz（每个约 310 MB）。每个存档含四个任务的权重，路径为 checkpoints/intact_goal_<task>_s<种子>_p77_v1/weights_epoch_1.pt，解压到 $INTACT_OUTPUT_HOME 后就位于 checkpoints/ 之下。RESULTS.csv 给出这批存档 36 个评测格（任务 × 训练种子 × 评测种子）各 100 个 episode 的成功数，可以逐格对照自己的评测。

注意 这批存档只包含 weights_epoch_1.pt，没有 config.json；scripts/eval.sh 加载 .pt 时要求同一目录下有 config.json，所以解压后不能直接评测。

提示 INTACT/ 存档自带的 MANIFEST.json 记录的宏平均是 95.75%，对应这三个训练种子。项目公布的 95.61% 来自另一组训练种子（3072、3073、3074），以 AUDITED_RESULTS_20260914.json 为准。

INTACT-unified/ 与 paper-e5-goal-v1 是同一批 72 个论文 checkpoint，用 5.1 节的脚本下载即可。INTACT-no-previous-action/ 的 Actor 只有三槽输入，与当前运行时的四槽 Actor 不同，仓库没有提供它的评测脚本。

以下均为 Official LeWM 协议下的成功率（%），± 为训练种子间的样本标准差。

项目当前结果

单任务 E1 各任务结果（训练种子 3072、3073、3074）

四任务共享 Encoder E5 论文矩阵（训练种子 0、42、3072）

单任务的完整推理方式对照和共享 Encoder 主要单元的方差见仓库的 docs/RESULTS.md；六个单元的样本标准差和每个 checkpoint 的哈希见 checkpoints/PAPER_E5_MATRIX_MANIFEST.json。

本节说明报告 INTACT 结果时要保留哪些信息、怎样汇总成功率，依据是仓库的 docs/REPRODUCIBILITY.md。

每个报告的结果都要能追溯到以下信息。训练和评测脚本会尽量自动记录（见 2.5 节的 run_metadata.json 和 4.4 节的 .txt.json），缺的部分手动补全：

• 源码提交号和解析后的完整配置

• 数据集、判分协议和任务

• 训练种子、评测种子、epoch 数、每个任务的 batch size

• 推理方式和 SDPA 后端

• checkpoint 的 SHA-256 与训练完成状态

• 评测器的机器可读输出

1. 对每个独立训练的 checkpoint，先平均它在评测种子 0、1、42 上的成功率（每个种子 100 个 episode）。

2. 再对训练种子求均值和样本标准差，写成"均值 ± 标准差"。

3. 单任务和共享 Encoder 两组结果分开报告。

4. Official 和 CLEAR-LeWM 的结果分开报告。

5. 没有跑或主动停止的格子写 --，不要写 0。

6. 事后挑选的研究和早期试验单独标注，不混入受控对比。

• 3.9–4.8 ms 是规划侧耗时，不包含环境渲染、观测传输等开销，不能当作端到端的机器人控制延迟。

• 候选数指每次规划评估的动作序列条数，不是环境步数。

• 公开的 LeWM 论文数值使用它自己的 10 epoch + CEM 协议，只作背景参考，不是配对对照；受控对照以 5.5 节的论文矩阵为准。