如何15分钟读懂DreamDojo机器人世界模型代码库:目录架构全解析

原创2026-10-14 13:20:271,662 阅读

如何15分钟读懂DreamDojo机器人世界模型代码库:目录架构全解析

DreamDojo 是一个基于 4.4 万小时人类视频预训练的通用机器人世界模型(Robot World Model)开源项目,支持预训练、后训练、蒸馏与推理全流程。本文带你逐层拆解它的目录架构——从核心的 cosmos_predict2 到独立的 external 子模块,15 分钟建立完整心智地图 🗺️。

DreamDojo机器人世界模型代码库架构概览

一、DreamDojo 是做什么的?

在理解目录之前,先记住它的三个关键能力(见 README.md):

  • 大规模视频数据集:44k 小时人类第一视角视频,世界模型预训练迄今最大规模
  • 基础世界模型:首个在此类上展现强泛化能力的机器人世界模型,提供 2B / 14B 两个规格
  • 蒸馏管线:蒸馏后可实现长时程自回归生成,稳定 10 FPS 实时交互超过 1 分钟

这个"预训练 → 后训练 → 蒸馏 → 评测"的四段式流程,正是整个目录设计的骨架。

二、顶层目录鸟瞰:一眼看懂职责分工

打开仓库根目录,每个文件夹都有明确分工:

目录 职责 一句话理解
cosmos_predict2/ 核心世界模型 训练、蒸馏、推理的主战场
external/ 潜动作模型(LAM) 独立子项目,负责动作代理提取
groot_dreams/ 机器人数据集层 数据转换与 dataloader
configs/ 训练配置 2B/14B × 多种机器人的 YAML
examples/ 推理示例 快速跑通世界模型生成
packages/ 独立工具包 Gradio 界面、CUDA 算子等
docs/ 官方文档 从环境安装到评测的全流程
scripts/ 训练脚本入口 分布式训练统一入口

根目录还有一组"一键启动"脚本,是理解项目工作流的捷径:

三、核心目录 cosmos_predict2:世界模型主战场

这是整个仓库最大、最重要的目录,内部采用"框架 + 业务"的分层设计:

3.1 _src/imaginaire:通用训练框架

位于 cosmos_predict2/_src/imaginaire/,是被复用的基础设施层:

  • attention/:多后端注意力统一封装(CUDNN、Flash2/Flash3、NATTEN),按硬件自动切换
  • datasets/:WebDataset、视频解码器、多长宽比分发器(distributors)
  • checkpointer/:DDP / 张量并行两种 checkpoint 存取实现
  • modules/:T5-XXL 文本编码器、相机模型、EDM 采样器等
  • utils/:FSDP、EMA、分布式、WandB 等几十个工程化工具

💡 理解要点:这一层与机器人无关,它是通用的视频扩散模型训练框架,DreamDojo 的所有模型都构建在它之上。

3.2 _src/predict2:模型与数据集业务层

位于 cosmos_predict2/_src/predict2/,直接对应"世界模型"本体:

  • models/:Text2World、Video2World 及 Rectified Flow 变体模型
  • networks/:DiT 网络主干(minimal_v4_dit.py)与稀疏注意力实现
  • datasets/:WebDataset 数据源、数据增强器(augmentors)、缓存重放 dataloader
  • inference/:T5/UMT5 文本编码缓存、文本生成图像/视频推理工具
  • tokenizers/:WAN2.1/2.2 与 Cosmos VAE 接口
  • distill/:DMD2 蒸馏管线,含判别器网络与专用训练器

3.3 机器人特有能力:action 与 interactive

世界模型之所以"懂机器人",靠的是这两个子目录:

  • action/:动作条件化世界模型(action_conditioned_minimal_v1_lvg_dit.py),让视频生成响应机器人动作输入,并内置 GR00T 推理管线
  • interactive/:交互式生成训练,包含自回归因果 DiT(dit_causal.py)、Ulysses 序列并行和 KV Cache 支持——这就是 10 FPS 实时交互的实现基础

3.4 reason1:多模态理解组件

cosmos_predict2/_src/reason1/ 封装了基于 Qwen 的 VLM(视觉语言模型),支持 FSDP 并行与 DCP 检查点,用于推理/理解侧能力。

四、external 目录:潜动作模型 LAM 的独立子项目

external/lam/ 与 external/lam_project/ 是一个可独立运行的训练项目,负责训练潜动作模型(Latent Action Model)——它从未标注的人类视频中反推出隐含动作,作为世界模型的动作代理条件。

其目录结构麻雀虽小五脏俱全:

按官方文档 docs/LAM.md,进入该目录执行 bash train.sh 即可开始 LAM 训练。

五、groot_dreams:机器人数据处理的"翻译层"

groot_dreams/ 承担把机器人数据集(如 GR-1)转成世界模型可消费格式的工作:

配套的 datasets/README.md 说明数据放置位置,shared_meta/ 则存放各机器人(AgiBot、G1、GR1、YAM)的模态定义与统计信息 JSON。

六、configs 与启动脚本:配置的"最后一公里"

configs/ 下的 10 个 YAML 遵循统一命名规则:{参数量}_{分辨率}_{机器人}.yaml,例如:

启动逻辑非常统一:以 launch.sh 为例,它通过 torchrun 拉起 scripts.train,指定配置入口 cosmos_predict2/_src/predict2/action/configs/action_conditioned/config.py,再用实验名选择具体 YAML——一条命令即可在 8 卡节点上启动训练。

七、packages 目录:开箱即用的独立工具包

packages/ 下是三个可独立安装的 Python 包:

  • cosmos-oss:OSS 发布包,含 scripts/train.py 训练入口与 VQA 评测工具
  • cosmos-gradio:Gradio 应用,提供模型服务(model_ipc)与 Web 界面,适合快速可视化体验
  • cosmos-cuda:CUDA 加速算子

八、新手推荐阅读路线(15 分钟版)⏱️

按以下顺序浏览,可以最短路径建立全局认知:

  1. README.md + docs/SETUP.md(2 分钟):项目亮点与环境安装
  2. docs/PRETRAIN.md → POSTTRAIN.md → DISTILL.md(4 分钟):理解四段式流程
  3. launch.sh(3 分钟):只看前 40 行,抓住"配置入口 + 实验名"这一核心机制
  4. _src/predict2/models/(4 分钟):扫一眼模型类名,确认"框架层 vs 业务层"边界
  5. external/lam_project/train.sh(2 分钟):感受独立子项目的自包含设计

总结

DreamDojo 的目录设计可以概括为一句话:cosmos_predict2 承载世界模型本体(框架层 imaginaire + 业务层 predict2),external 独立托管潜动作模型,groot_dreams 负责数据翻译,根目录脚本与 configs 提供一键式训练体验。清晰的"框架-业务-数据-工具"四层划分,让它既是可复现的科研代码库,也是可直接扩展的训练平台——读懂这套结构,你就掌握了在大规模世界模型项目中快速定位代码的通用方法论 🚀

登录后查看全文
DreamDojo