企业官网建设流程全解析

3步上手 Ball-in-Cup：用 stable-worldmodel 做世界模型控制的完整指南

【免费下载链接】stable-worldmodelA platform for reproducible world model research and evaluation项目地址: https://gitcode.com/GitHub_Trending/st/stable-worldmodel

stable-worldmodel 是一个把「数据采集、模型训练、模型预测控制评估」串成一条流水线的世界模型研究平台。这篇以 Ball-in-Cup 环境为例子，带你复现一个带物理扰动的控制任务，并讲清楚它的环境接口、variation space 机制和 LeWM 训练脚本怎么用。

一个会「换个重力就崩」的世界模型测试场景

你多半遇到过这种情况：世界模型在固定环境里跑得很顺，稍微换一下光照、物体尺寸或动力学参数，策略立刻掉线。问题往往不在算法本身，而是你从头到尾只在一个干净配置上验证过。

Ball-in-Cup 就是一个很适合做这种鲁棒性体检的任务。它由两个力驱动一个 U 形杯，球用一根线吊在杯柄一侧，目标是把球荡进杯里并一直留住：

它动作空间只有两个轴（杯的 x、z 方向力），观测是低维特征向量，规模小但反馈链长。正因为它「小而不简单」，跑通它对 MPC 求解器和世界模型来说是很好的压力测试——这也是 stable-worldmodel 把它做成标准化 DMC 环境的用意。

读懂 Ball-in-Cup 的机制：任务、难点与 variation space

任务到底难在哪

先看物理结构：杯受两维力控制，球被线约束，既要有足够动量荡进杯口，又不能在杯口「弹飞」。这意味着策略必须同时处理「到达」和「保持」两个阶段，而这两个阶段对控制增益的要求不同。

再看它对环境扰动有多敏感。同一个策略，如果把球径、杯体密度或重力方向改掉，动力学就变了；如果只是换个颜色和地面纹理，纯图像输入的世界模型也得重新适应。这正是真实机器人部署里最常见的两类失效：动力学漂移和视觉漂移。

stable-worldmodel 如何处理：显式建模可扰动的因素

这个项目没有把「扰动」藏进黑盒，而是让每个环境暴露一个variation_space，把可以动的量列清楚。以 Ball-in-Cup 为例，可扰因素包括杯和球的color、density，球的size，三轴gravity，地面floor.color，以及target的颜色/形状和light.intensity。

这些扰动的落地写在 stable_worldmodel/envs/dmcontrol/ball_in_cup.py 里：视觉和物理参数通过修改 MuJoCo 的 MJCF 模型写入，重力则用set_gravity直接作用到编译后的物理体上。reset()时按需采样，等于把 domain randomization、OOD 评估和可复现回放统一到了同一套接口下。

上下的对比动画里，球径、杯体颜色、地面与光照都在变化，但接口没变——你只需要在reset的options里指定要随机哪些因素。训练侧则交给仓库内置的基线脚本，scripts/train/lewm.py用 Hydra + Lightning 组织数据加载、SIGReg 正则和断点保存，右图的 GPU 占用曲线就是 LeWM 在长序列数据上训练时的实际负载，可以看到它把算力和数据管线都跑满了。

3步跑通 Ball-in-Cup：克隆、安装与运行

第 1 步，克隆仓库。

git clone https://gitcode.com/GitHub_Trending/st/stable-worldmodel

第 2 步，按 pyproject.toml 安装依赖。依赖定义在 pyproject.toml，源码安装推荐用uv拉齐环境：

cd stable-worldmodel uv venv --python=3.10 && source .venv/bin/activate uv sync --extra all --group dev

如果只想走 PyPI，pip install 'stable-worldmodel[all]'也能装齐训练、环境与数据格式依赖。

第 3 步，先跑通环境。Ball-in-Cup 的注册名是swm/BallInCupDMControl-v0，最省事的冒烟测试是直接用它的入口文件确认环境能 reset、观测形状正确：

python stable_worldmodel/envs/dmcontrol/ball_in_cup.py

跑通之后，采集或评估就切到统一接口：swm.World('swm/BallInCupDMControl-v0', num_envs=4)，挂上策略后调collect()存数据集、evaluate()出成功率，需要扰动时再在reset的variation里指定因素。完整的 API 与variation_values用法见 docs/quick_start.md。

把环境、扰动和训练脚本这三块串起来之后，Ball-in-Cup 就是一个可以反复复用的压力测试台：改一行 variation 配置就能验证你的世界模型在动力学漂移和视觉漂移下到底扛不扛得住，这正是一个可复现研究平台想省掉你的部分。

【免费下载链接】stable-worldmodelA platform for reproducible world model research and evaluation项目地址: https://gitcode.com/GitHub_Trending/st/stable-worldmodel