参赛文档 · TRONCamp

01 / 安装

安装(全透明分步)

在选手包根目录按 0 – 8 步依次执行,每步都是一条可复制的命令:建隔离 conda 环境 → 装 RoboTwin / SAPIEN / cuRobo 与 ACT 依赖 → 还原打包占位路径 → 自检。安装逻辑完全透明,可逐步核对;首次安装建议逐段核对输出(RoboTwin 本体较重)。

0. 前提:已装 conda(未装见 Miniconda 官方安装 ↗);NVIDIA 驱动支持 CUDA 12.x(cuRobo、torch 需要)。HF / pip 有墙时按需设代理。

# 1. 建并激活 conda 环境(python 3.10) conda create -y -n troncamp_env python=3.10 && conda activate troncamp_env

环境名用本赛事独立的 troncamp_env,与 RoboTwin 官方教程默认的 RoboTwin 环境天然隔离——不会复用或污染你已有的环境。想换别的名字,把这条命令里两处 troncamp_env 一并替换即可。

# 2. 锁 setuptools<81(新版 setuptools 会让 sapien 装不上,锁旧版) pip install "setuptools<81"

# 3. 装 RoboTwin 本体(跑它自带的安装脚本) ( cd external/robotwin_local && bash script/_install.sh )

# 4. 装 ACT 训练栈 + cuRobo runtime 依赖 pip install -r setup/requirements.txt

离线环境(无外网):先把 wheels 镜像到本地目录,再改用 pip install --no-index --find-links=<wheels 目录> -r setup/requirements.txt。

# 5. 装 cuRobo 0.8.0 SETUPTOOLS_SCM_PRETEND_VERSION=0.8.0 pip install -e external/robotwin_local/envs/curobo --no-build-isolation

# 6.【关键】把打包占位符 __KIT_ROOT__ 还原为你的实际路径 grep -rl --include='*.yml' __KIT_ROOT__ . | xargs -r sed -i "s#__KIT_ROOT__#$(pwd)#g"

这步绝不能漏:打包时把绝对路径换成了占位符 __KIT_ROOT__,不还原成你的实际路径,cuRobo 规划器起不来(采集 / 评测会失败)。须在选手包根目录执行;占位只存在于 cuRobo 的 .yml 配置,故命令用 --include='*.yml' 精确还原,避免误伤代码 / 文档里对占位符名的说明性引用。

# 7. ffmpeg 兜底(无系统 ffmpeg 时用 imageio-ffmpeg 静态二进制;已有系统 ffmpeg 可跳过) ffmpeg -version >/dev/null 2>&1 || { pip install imageio-ffmpeg; ln -sf "$(python -c 'import imageio_ffmpeg,os;print(imageio_ffmpeg.get_ffmpeg_exe())')" "$CONDA_PREFIX/bin/ffmpeg"; }

采集保存视频需要 ffmpeg;缺它会静默保存失败、采集计数卡在 0。

# 8. 环境自检(检查 curobo==0.8.0 / sapien / mplib / ffmpeg 就位) python setup/env_check.py

自检全绿即安装完成,可进入 §02 采集。任一步失败请按 env_check.py 的中文提示定位:缺 curobo 元数据 → 复查第 5 步;import sapien 失败 → 复查第 2 步 setuptools<81;ffmpeg 缺失 → 复查第 7 步。

02 / 采集

数据采集 collect(四题全部自采)

四题都自采 —— 用下发的调好专家在 TRON 2 上跑 RoboTwin 采集,只留成功的轨迹。专家 = external/robotwin_local/envs/<task_name>.py 的 play_once(),可直接改进。采集集数 / 域随机化 / 场景在 task_config 里调。数据经 JPEG 压缩,~12M/集(不炸盘)。

# 在选手包根目录执行;先按 §01 完成安装(含第 6 步 __KIT_ROOT__ 占位还原,curobo 规划器才能起) # bash collect_data.sh <task_name> <task_config> <gpu_id> —— 打 TRON 2 自碰撞 patch 后采集 bash collect_data.sh adjust_bottle adjust_bottle_200ep 0 # 采完用 process_data 转 ACT 16-D(见下节);collect / process_data / train 用同一 config 名(adjust_bottle_200ep)串起来

只有 T1 的采集 config adjust_bottle_200ep.yml 随包下发(直接照跑);评测用的 <task>_clean.yml 也随包下发但勿改。T2–T4 的采集 / 训练 config 不随包下发,自己建:把 external/robotwin_local/task_config/adjust_bottle_200ep.yml 拷贝改名成 <task>_200ep.yml,调 episode_num / 场景后,把三步命令里的 adjust_bottle 换成对应任务名即可。

想采更多 / 更优数据 → 改 task_config 的集数与域随机化,或直接改进 envs/<task>.py 的专家。这类改动只影响你自采的数据(进而影响你训出的 ckpt);官方评测生效的是你提交的 ckpt + policy/ACT 代码与推理配置,不加载 envs/ 专家。

(可选)想直观查看采集:把 task_config/<config>.yml 的 render_freq 从 0 改成 >0(如 20)会弹出 SAPIEN 仿真窗口 —— 仅在种子搜索阶段显示(正式落盘阶段固定关闭),且需带显示器 / 图形环境的机器(无头服务器 / SSH 无 X 会报错)。评测(§05)不支持可视化。纯调试便利,不影响成绩。

03 / 数据处理

数据处理 process_data

把 RoboTwin 采集的轨迹转成 ACT 训练格式,产物落在 processed_data/sim-<task>/<config>-<num>/(RoboTwin 官方两级目录约定)。四题自采(上一步)后都用本步转 16-D 格式再训练(JPEG 压缩存储)。

# bash process_data.sh <task_name> <task_config> <expert_data_num> —— 在 external/robotwin_local/policy/ACT 下执行 ( cd external/robotwin_local/policy/ACT && bash process_data.sh adjust_bottle adjust_bottle_200ep 200 )

参数	含义
`task_name`	任务名,如 `adjust_bottle` / `grab_roller` / `stack_bowls_two` / `stack_bowls_three`
`task_config`	配置名(数据采集设定),如 `adjust_bottle_200ep`
`expert_data_num`	用于训练的专家轨迹数,如 `200`

04 / 训练

训练 train

训练脚本 train.sh 内部已设好 ACT 标准超参(kl_weight 10 / chunk_size 50 / hidden_dim 512 / dim_feedforward 3200 / batch_size 8 / lr 1e-5 / state_dim 16),默认 num_epochs=6000,单卡可训。ckpt 落在 act_ckpt/act-<task_name>/<task_config>-<expert_data_num>/。

# bash train.sh <task_name> <task_config> <expert_data_num> <seed> <gpu_id> —— 在 external/robotwin_local/policy/ACT 下执行 ( cd external/robotwin_local/policy/ACT && bash train.sh adjust_bottle adjust_bottle_200ep 200 0 0 ) # 产出 ckpt → act_ckpt/act-adjust_bottle/adjust_bottle_200ep-200/

题号	训练命令
T1	`bash train.sh adjust_bottle adjust_bottle_200ep 200 0 0`
T2	`bash train.sh grab_roller grab_roller_200ep 200 0 0`
T3	`bash train.sh stack_bowls_two stack_bowls_two_200ep 200 0 0`
T4	`bash train.sh stack_bowls_three stack_bowls_three_200ep 200 0 0`

表中训练命令同上方示例,都在 external/robotwin_local/policy/ACT 下执行(从根目录跑就套页头的 ( cd … && bash … ) 子 shell 写法)。T2–T4 的 <task>_200ep 是你在 §02 自建的 config 名(拷 adjust_bottle_200ep.yml 改名而来),不随包下发;只有 T1 的 adjust_bottle_200ep 是随包下发、可直接照跑的。

参数	含义
`seed`	随机种子,如 `0`
`gpu_id`	GPU 设备号,如 `0`(脚本内 `export CUDA_VISIBLE_DEVICES`)

需改步数 / 超参时直接编辑 train.sh 或底层 imitate_episodes.py 的参数(训练时生效,决定你训出的 ckpt)。官方评测生效的是你提交的 ckpt + policy/ACT 代码与推理配置(deploy_policy.yml);评测时会用你代码包里的 policy/ 替换官方同名代码,envs/ 不参与评测。

参考耗时(单题全流程)

步骤	参考耗时	条件
采集 collect(§02)	~1 h 55 min	单卡 4090;搜 ~500 seed 采够 200 条成功轨迹
数据处理 process_data(§03)	~1.5 min	200 条轨迹转 ACT 16-D 格式
训练 train(§04)	~9 h	单卡 4090;`num_epochs=6000`
单题全套	~11 h	采集 + 处理 + 训练合计(不含评测与调参迭代)

主办方实测参考(单卡 4090),实际因机器 / 配置 / 数据量而异。赛期约 12 天、每日 2 次正式提交(本地自测不限次),单题全套约 11 h——请据此规划机时与迭代轮次。

05 / 评测

评测与部署 eval

评测脚本 eval.sh 加载评测推理配置 deploy_policy.yml,跑一遍仿真,结果(含视频)落在工程根的 eval_result/。ckpt_setting 选 act_ckpt 下的 ckpt 目录,可与评测环境 task_config 不同(跨设定泛化测试)。

# bash eval.sh <task_name> <task_config> <ckpt_setting> <expert_data_num> <seed> <gpu_id> —— 在 external/robotwin_local/policy/ACT 下执行 # 同设定评测(评测环境 = 训练设定) ( cd external/robotwin_local/policy/ACT && bash eval.sh adjust_bottle adjust_bottle_200ep adjust_bottle_200ep 200 0 0 ) # 跨设定评测(用官方评测同款 clean 设定测泛化) ( cd external/robotwin_local/policy/ACT && bash eval.sh adjust_bottle adjust_bottle_clean adjust_bottle_200ep 200 0 0 )

参数	含义
`task_config`	评测环境的配置(测哪种设定)
`ckpt_setting`	ckpt 的来源设定(选 `act_ckpt/act-<task>/<ckpt_setting>-<num>/`)
结果	视频 + 指标 → 工程根 `eval_result/`

本地自评(与官方同一套流程)

比赛自测用选手包的 starter/eval_local.py 包装:和官方评测同一套流程,只换成公开测试场景(官方用私有测试场景);本地分是官方分的估计,不保证逐分相等。

# 在选手包根目录执行;--ckpt-dir 指向训练产出的 act_ckpt 目录 python starter/eval_local.py --track T1 --ckpt-dir external/robotwin_local/policy/ACT/act_ckpt/act-adjust_bottle/adjust_bottle_200ep-200

达标阈值(在同一 easy/clean 官方评测环境下的成功率):T1 成功率 ≥ 0.50 / T2 成功率 ≥ 0.60 / T3 成功率 ≥ 0.50 —— 达标即顺序解锁(T1→T2→T3→T4),T1–T3 本身不计分;T4 是主榜分数(末态分层得分 /100,三个碗各占 1/3)。提交命令与 token 用法见 §07 提交。

单场景数值核查 watch_rollout

想快速核查某个场景的行为是否合理,用 starter/watch_rollout.py 跑单个场景(和官方同一套评测),打印该场景末态的 sr / graded 数值(不渲染视频,纯数值核查)。

# 在选手包根目录执行;--ckpt-dir 指训练产出的 act_ckpt 目录,--seed 选单个场景 python starter/watch_rollout.py --track T1 --ckpt-dir external/robotwin_local/policy/ACT/act_ckpt/act-adjust_bottle/adjust_bottle_200ep-200 --seed 0

06 / 配置

配置文件与任务键

每个数据键的字段定义在 SIM_TASK_CONFIGS.json 里(dataset_dir / num_episodes / episode_len / camera_names),训练 / 评测的 --task_name 就是这里的键;评测推理配置放在 deploy_policy.yml(如 temporal_agg)。

题号	数据键(task_name)	train.sh 三元组
T1	`sim-adjust_bottle-adjust_bottle_200ep-200`	adjust_bottle adjust_bottle_200ep 200
T2	`sim-grab_roller-grab_roller_200ep-200`	grab_roller grab_roller_200ep 200
T3	`sim-stack_bowls_two-stack_bowls_two_200ep-200`	stack_bowls_two stack_bowls_two_200ep 200
T4	`sim-stack_bowls_three-stack_bowls_three_200ep-200`	stack_bowls_three stack_bowls_three_200ep 200

表中 T2–T4 的 <task>_200ep 为你自建的 config 名(见 §02,拷 adjust_bottle_200ep.yml 改名);只有 T1 的 adjust_bottle_200ep 随包下发。

policy/ACT 关键文件

policy/ACT/ ├── process_data.sh / process_data.py # 数据 → ACT 格式 ├── train.sh / imitate_episodes.py # 训练入口 ├── eval.sh / deploy_policy.py # 评测 / 部署 ├── act_policy.py # ACT 模型(detr backbone) ├── SIM_TASK_CONFIGS.json # 任务键定义 └── deploy_policy.yml # 评测推理配置

07 / 提交

提交 submit

submit/submit.py 是唯一提交通道:把 ckpt(T2/T3/T4 另加整库代码包)+ token 上传后端评测队列。T1 只交权重;T2/T3/T4 交权重 + 代码包。顺序解锁 T1→T2→T3→T4,过一档才能交下一档。命令在选手包根目录执行。

# T1:只交权重(直接照跑的题,评测机跑官方 config) python submit/submit.py --server https://submit.troncamp-mani.limxdynamics.com --token=<你的 token> --track T1 --ckpt external/robotwin_local/policy/ACT/act_ckpt/act-adjust_bottle/<config>-<num>/policy_best.ckpt

# T2 / T3 / T4:权重 + 代码包(--code-dir 指含 policy/ 的 RoboTwin 根 = external/robotwin_local) python submit/submit.py --server https://submit.troncamp-mani.limxdynamics.com --token=<你的 token> --track <T2|T3|T4> --code-dir external/robotwin_local --ckpt external/robotwin_local/policy/ACT/act_ckpt/act-<task>/<config>-<num>/policy_best.ckpt

ckpt 路径规律:act_ckpt/act-<task>/<config>-<num>/policy_best.ckpt,其中 <task> 见 §06 配置的任务键表(T2 grab_roller / T3 stack_bowls_two / T4 stack_bowls_three)。

ckpt 与代码包

参数	说明
`--ckpt`	指向单个 checkpoint 文件;CLI 自动附带同目录的 `dataset_stats.pkl`、并作为评测加载名 `policy_last.ckpt` 上传——交哪个就评哪个,无需改名。训练同时存 `policy_best.ckpt`(验证集最优)与 `policy_last.ckpt`(末轮);建议交 `policy_best.ckpt`(早停,实测显著高于末轮)。
`--code-dir`	T2/T3/T4 必填,指 `external/robotwin_local`(含 `policy/`);评测时用你 `policy/ACT` 下的模型 / 推理代码与 `deploy_policy.yml`。重型平台目录(assets/envs/description)自动排除,代码包 ~8.5MB;`envs/` 专家不入包、不参与官方评测。传 `.` 会评测失败(根目录下没有 `policy/ACT`);T1 不需要。

token 三种传法

任选一种(优先级 --token-file > env TRONCAMP_TOKEN > --token);多数队直接贴字符串即可,不必建文件。

方式	用法
直接贴字符串	`--token=<你的 token>` —— 必须带等号。别用空格形式的裸 `--token <串>`:token 若以 `-` 开头会被当成参数报错(url-safe token 常以 `-`/`_` 起头)。
环境变量	`export TRONCAMP_TOKEN=<你的 token>` 后照常跑;好处是不落 shell 历史 / 进程列表。
文件	`--token-file <文件>`,文件里就一行 token(`echo "你的token" > token.txt`,结尾换行会被自动去掉)。

限额与地址

正式提交每日 2 次(本地自评不限次);无报名、无队名,榜上只显示 token 尾 6 位。--server 已内置官方默认地址(https://submit.troncamp-mani.limxdynamics.com),一般可省略;可用 --server 或环境变量 TRONCAMP_SERVER 覆盖。

后端拒绝提示

被后端拒绝时,submit.py 会打印友好中文提示并非零退出(不再抛原始 traceback):

HTTP	含义
`400`	请求不合法:字段 / 参数有误,检查 `--track` / `--ckpt` / `--code-dir` 或更新选手包。
`401`	令牌无效:检查 `--token` / `TRONCAMP_TOKEN` / `--token-file`。
`403`	赛道未解锁:需按 T1→T2→T3→T4 顺序,先过上一档(如交 T2 前须先过 T1)。
`404`	地址不对:检查 `--server` 是否为主办方公布的提交地址。
`409`	赛道已锁定:该赛道已达标锁定,不能重复提交。
`413`	文件过大:ckpt / 代码包超出后端上限。
`429`	过于频繁:提交有频率限制(每日 2 次),请稍后再试。