poet70/vla-sft-suite

VLA SFT Suite

这是一个面向新服务器/大规模集群复现的入口仓库。目标是让使用者尽可能少操作，即可下载代码、数据、checkpoint，安装环境，完成 smoke test，并启动 full SFT。

当前 active baseline：

• DreamZero
• Motus
• DreamTacVLA

RDP 已删除，不再纳入 active baseline。

当前核心 benchmark：

• ManiFeel
• UniVTAC

LIBERO 和 RoboTwin 保留为非核心历史/辅助数据记录；它们本身没有触觉输入，不作为本项目默认复现实验和导师部署主线。

0. TL;DR

public repo 下载通常不需要 Hugging Face token。若服务器访问频繁或需要上传结果，可先执行 hf auth login。

curl -LsSf https://hf.co/cli/install.sh | bash

export HF_USERNAME=poet70
export PROJECT_ROOT=/data/vla_sft
export DATA_ROOT=$PROJECT_ROOT/data
export CKPT_ROOT=$PROJECT_ROOT/checkpoints
export CODE_ROOT=$PROJECT_ROOT/baselines
export OUTPUT_ROOT=$PROJECT_ROOT/outputs

hf download "$HF_USERNAME/vla-sft-suite" --repo-type model --local-dir "$PROJECT_ROOT/suite"

bash "$PROJECT_ROOT/suite/scripts/bootstrap_cluster.sh" \
  --profile dreamtacvla \
  --bench manifeel \
  --smoke

中国大陆网络环境建议额外设置：

export HF_ENDPOINT=https://hf-mirror.com
export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
export PIP_FALLBACK_INDEX_URL=https://pypi.org/simple

1. 服务器要求

推荐配置：

组件	推荐
GPU	单节点 8 卡用于 DreamZero/Motus；DreamTacVLA 可先单卡验证
显存	DreamZero/Motus 建议 40GB+/GPU；DreamTacVLA 建议 24GB+
磁盘	核心 ManiFeel/UniVTAC 复现建议 200GB+；若下载历史辅助数据和所有官方 checkpoint，建议 1TB+
CPU/RAM	数据转换和 HDF5 读取建议 32 核、256GB RAM 以上
CUDA/Driver	以 PyTorch wheel 支持矩阵为准

当前 Pro6000 审计显示完整归档规模接近：

• 数据：约 232G
• checkpoint：约 164G
• 代码/日志/配置：额外若干 GB

实际核心主线需要本项目上传的内容更小：DreamTacVLA-ready ManiFeel/UniVTAC 数据 archive 约 56G，DreamZero/Motus 通用 ManiFeel archive 约 49.9G，UniVTAC Zarr archive 约 48G，自有 DreamTacVLA JEPA checkpoint 约 1.3G，代码仓直接上传。Wan2.2、DreamZero-DROID、Motus、Qwen3-VL 等第三方 checkpoint 不作为默认上传内容，由脚本从官方源下载。

2. 目标矩阵与当前状态

最终大规模集群目标是 3 个 active baseline × 2 个触觉 benchmark，共 6 组 full SFT。RDP 暂缓/归档。

Baseline	ManiFeel	UniVTAC	当前状态
DreamTacVLA	deployment verified	deployment verified	使用 data-manifeel-dtvla / data-univtac-dtvla
DreamZero	deployment verified	deployment verified	ManiFeel 使用 data-manifeel，UniVTAC 使用 data-univtac / univtac_zarr
Motus	deployment verified	deployment verified	ManiFeel 使用 data-manifeel，UniVTAC 使用 data-univtac / univtac_zarr
RDP	deferred	deferred	暂不处理

注意：当前 Pro6000 更像 baseline 部署和 full-SFT 启动验证环境，不是所有组合都已完成 200k steps full SFT。LIBERO/RoboTwin 不是本项目核心触觉 benchmark，不进入默认复现实验矩阵。

3. 目录结构

建议新服务器统一使用：

/data/vla_sft/
├── suite/          # 本入口仓库
├── baselines/      # baseline 代码
├── data/           # benchmark 数据
├── checkpoints/    # 预训练权重
├── envs/           # Python venv
└── outputs/        # 训练输出

对应环境变量：

export HF_USERNAME=poet70
export PROJECT_ROOT=/data/vla_sft
export DATA_ROOT=$PROJECT_ROOT/data
export CKPT_ROOT=$PROJECT_ROOT/checkpoints
export CODE_ROOT=$PROJECT_ROOT/baselines
export VENV_ROOT=$PROJECT_ROOT/envs
export OUTPUT_ROOT=$PROJECT_ROOT/outputs

4. 下载

Dataset repo 使用 data-* 命名，并只保存 ready-to-train 的处理版数据。checkpoint 默认从官方源下载；只有 DreamTacVLA JEPA 使用本项目自有 repo。详细上传清单见 docs/upload_file_plan.md 和 docs/dataset_upload_plan.md。

只下载某个组合需要的最小集合：

bash scripts/download_artifacts.sh \
  --baseline dreamtacvla \
  --bench manifeel \
  --data-root "$DATA_ROOT" \
  --ckpt-root "$CKPT_ROOT" \
  --code-root "$CODE_ROOT"

只看将要执行什么，不实际下载：

bash scripts/download_artifacts.sh --baseline dreamtacvla --bench manifeel --dry-run

5. 安装环境

每个 baseline 使用独立 venv：

bash scripts/install_env.sh --profile dreamtacvla --code-root "$CODE_ROOT" --venv-root "$VENV_ROOT"

5.1 包源策略

install_env.sh 默认使用清华 PyPI 镜像：

PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
PIP_TRUSTED_HOST=pypi.tuna.tsinghua.edu.cn
PIP_FALLBACK_INDEX_URL=https://pypi.org/simple

脚本只在变量未设置时填入默认值；如果显式设为空，会保留空值，并在调用 pip 时绕过脚本内置镜像。因此新服务器可以按网络条件切换源，不需要改脚本。

如果国内镜像缺包、版本未同步或返回 404，脚本会自动回退到官方 PyPI。典型现象包括：

No matching distribution found
Could not find a version that satisfies the requirement
HTTP error 404

如需完全禁用国内镜像：

PIP_INDEX_URL= PIP_TRUSTED_HOST= bash scripts/install_env.sh --profile dreamtacvla

如需保留国内镜像但更换备用源：

PIP_FALLBACK_INDEX_URL=https://pypi.org/simple bash scripts/install_env.sh --profile dreamtacvla

如需禁止自动回退，便于排查镜像可用性：

PIP_DISABLE_FALLBACK=1 bash scripts/install_env.sh --profile dreamtacvla

PyTorch wheel 源建议单独指定，避免普通 PyPI 镜像缺少 CUDA wheel：

TORCH_INDEX_URL=https://download.pytorch.org/whl/cu128 \
bash scripts/install_env.sh --profile dreamzero

不要把 CPU wheel 源作为 full SFT 训练的默认回退；如果 CUDA 版本不匹配，应根据 nvidia-smi 和目标 PyTorch 支持矩阵改 TORCH_INDEX_URL，然后重新安装对应 baseline 的 venv。

5.2 集群网络策略

脚本只把 AutoDL /etc/network_turbo 当作可选加速。如果节点不是 AutoDL，或没有该文件，脚本会直接跳过，不影响执行。非 AutoDL 集群应由调度系统、登录脚本或容器环境显式注入网络变量，例如：

export http_proxy=http://proxy.example.edu:port
export https_proxy=http://proxy.example.edu:port
export HF_ENDPOINT=https://hf-mirror.com
export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
export PIP_FALLBACK_INDEX_URL=https://pypi.org/simple
export TORCH_INDEX_URL=https://download.pytorch.org/whl/cu130

如果集群可直连官方源，可以不设置 HF_ENDPOINT 和代理。若集群使用私有 PyPI / wheelhouse，把 PIP_INDEX_URL、TORCH_INDEX_URL 指向内部源即可。

AutoDL 环境可继续使用学术加速：

source /etc/network_turbo

不要在部署脚本中写死 http_proxy=http://127.0.0.1:12798。不同 AutoDL 容器的代理地址可能是内网地址，必须以 /etc/network_turbo 实际注入的 http_proxy / https_proxy 为准；脚本内只应 source /etc/network_turbo 并沿用当前环境变量。

如需在 AutoDL 上禁用自动学术加速：

USE_NETWORK_TURBO=0 bash scripts/bootstrap_cluster.sh --profile dreamtacvla --bench manifeel --smoke

5.3 DreamTacVLA 集群环境固化

DreamTacVLA 在本套部署中固定使用 Python 3.11。原因是 mujoco==2.3.7 在 Python 3.12 上容易没有可用 wheel，进而触发源码构建并报：

RuntimeError: MUJOCO_PATH environment variable is not set

install_env.sh 已做保护：

• 优先使用 DREAMTACVLA_PYTHON_BIN 指定的 Python。
• 未指定时优先寻找 python3.11。
• 没有 python3.11 但有 conda 时，自动在 $VENV_ROOT/.python311_base 创建 Python 3.11 底座，再创建标准 venv。
• 若检测到已有 DreamTacVLA venv 不是 Python 3.11，会提前失败并提示重建，避免在大规模集群上跑到一半才失败。

可显式指定 Python：

DREAMTACVLA_PYTHON_BIN=/opt/python/3.11/bin/python3.11 \
bash scripts/install_env.sh --profile dreamtacvla

新节点部署前建议检查：

command -v python3.11 || command -v conda

DreamTacVLA 还依赖 robomimic / diffusion policy 的间接包。install_env.sh 已补充安装：

imageio imageio-ffmpeg diffusers

训练首次构建 ResNet backbone 时会用到 resnet18-f37072fd.pth。为避免运行时因 SSL 证书链或外网抖动下载失败，install_env.sh 会提前下载到：

$TORCH_HOME/hub/checkpoints/resnet18-f37072fd.pth
# 若未设置 TORCH_HOME，则为 ~/.cache/torch/hub/checkpoints/resnet18-f37072fd.pth

下载后会校验 sha256 前缀必须匹配文件名中的 f37072fd。

安装完成后检查：

source "$VENV_ROOT/dreamtacvla/bin/activate"
python - <<'PY'
import torch
print("torch:", torch.__version__)
print("cuda:", torch.version.cuda)
print("available:", torch.cuda.is_available())
PY

6. Smoke Test

新服务器推荐先用公共入口跑真实 SFT 命令。bootstrap_cluster.sh 会完成系统检查、代码/数据/checkpoint 下载、环境安装、Motus 配置渲染，并直接进入真实训练命令。若当前是无卡模式，训练入口会在 CUDA 阶段自然失败；这类 GPU 相关失败可记录为 expected no-GPU stop，等统一开 GPU 后继续验证。

bash scripts/bootstrap_cluster.sh --profile dreamtacvla --bench manifeel --smoke

默认 smoke test 只跑 10 step：

SMOKE_STEPS=10 bash scripts/bootstrap_cluster.sh --profile dreamtacvla --bench manifeel --smoke

已复现过的 DreamTacVLA + ManiFeel 也保留了更强校验的一键入口，它会额外做可续传 archive 下载、sha256/tar 校验、Python 3.11 选择、ResNet18 缓存和 DreamTacVLA loader 补丁：

bash scripts/deploy_verified.sh --profile dreamtacvla --bench manifeel --smoke

六个 deploy_*.sh 入口现在都是 bootstrap_cluster.sh 的薄 wrapper，便于复制到 tmux 中运行：

7. Full SFT

当前真实可启动的 full SFT 链路如下。无卡模式下直接运行这些命令即可，若最终停在 CUDA/no GPU 阶段，记录为 expected no-GPU stop。

DreamTacVLA + ManiFeel：

bash scripts/deploy_dreamtacvla_manifeel.sh --full

DreamTacVLA + UniVTAC：

bash scripts/deploy_dreamtacvla_univtac.sh --full

DreamZero + ManiFeel：

bash scripts/deploy_dreamzero_manifeel.sh --full

Motus + ManiFeel：

bash scripts/deploy_motus_manifeel.sh --full

推荐在 tmux 中跑长任务：

bash scripts/deploy_dreamzero_manifeel.sh --full --tmux dreamzero_manifeel_full
tmux attach -t dreamzero_manifeel_full

默认日志会写到：

$OUTPUT_ROOT/deploy_<profile>_<bench>_<mode>.log

200G 级临时盘建议开启 archive 解压后清理，避免 tar.gz 和解压目录同时长期占用空间：

HF_ARCHIVE_DOWNLOAD_BACKEND=wget \
HF_ARCHIVE_DELETE_AFTER_EXTRACT=1 \
bash scripts/deploy_dreamzero_manifeel.sh --full --tmux dreamzero_manifeel_full

wget/aria2 直链下载默认不把 HF_TOKEN 放入命令参数，避免 token 出现在进程列表。只有下载私有 artifact 且明确接受该风险时，才设置：

export HF_DIRECT_DOWNLOAD_AUTH=1

6 条目标链路均已完成新服务器部署验证。DreamZero/Motus + UniVTAC 依赖 poet70/data-univtac 中的 univtac_zarr artifact；该 artifact 已完成 HF 上传，可按同一套公共入口下载和启动。

8. 多卡/多节点

DreamZero/Motus 使用 torchrun + DeepSpeed。多节点时需要显式设置：

export NNODES=2
export NODE_RANK=0
export GPUS_PER_NODE=8
export MASTER_ADDR=10.0.0.1
export MASTER_PORT=29500

DreamTacVLA 当前以原生 PyTorch 单进程训练为主；若要多卡，需要先改造 DDP，包括 DistributedSampler、rank0 checkpoint、rank-aware logging。

9. Resume

统一建议把输出放到：

$OUTPUT_ROOT/<baseline>_<benchmark>_full

DreamZero resume 示例：

++training_args.resume_from_checkpoint=$OUTPUT_ROOT/dreamzero_manifeel_full/checkpoint-50000

Motus/DreamTacVLA resume 需要以各自训练脚本支持为准。

10. 常见报错

报错	常见原因	处理
NCCL timeout	多卡/多节点网络接口不一致	设置 NCCL_DEBUG=INFO，确认 MASTER_ADDR、端口、网卡
undefined symbol	PyTorch/CUDA/DeepSpeed ABI 不匹配	重建对应 baseline 的独立 venv
flash-attn 编译失败	CUDA_HOME/nvcc/GCC 不匹配	优先使用 wheel；失败时先禁用 flash-attn
file not found	数据或 checkpoint 未下载到脚本期望路径	检查 DATA_ROOT、CKPT_ROOT
HDF5 读取卡住	worker 过多或网络盘慢	降低 dataloader worker，优先本地 NVMe
UniVTAC archive 是分卷	HF 单文件限制 50GB，单包略超限制	download_artifacts.sh 会自动下载 part、校验、合并并解压
hf download 拉大 tar.gz 长时间停在 .incomplete	HF/Xet/代理链路对大单文件不稳定	保留 partial，重试；必要时设置 HF_ARCHIVE_DOWNLOAD_BACKEND=wget 使用 wget -c 可续传下载
token 出现在 wget/aria2 进程参数	直链下载通过 --header Authorization 传 token	public artifact 不需要 token；脚本默认不向直链下载传 token，私有 artifact 才显式设置 HF_DIRECT_DOWNLOAD_AUTH=1
200G 盘部署 DreamZero/Motus 空间不足	ManiFeel 通用包需要约 50G archive + 47G 解压目录，checkpoint 还需约 100G	设置 HF_ARCHIVE_DELETE_AFTER_EXTRACT=1；若仍不足，清理旧 smoke checkpoint 或已验证的 DreamTacVLA 数据前必须先确认
archive 缺少 .sha256	早期数据 repo 只上传了 tar.gz	新版脚本不会直接失败，会提示并用 tar -tzf 检查压缩包结构；新上传 artifact 仍建议提供 .sha256
MUJOCO_PATH environment variable is not set	DreamTacVLA 使用 Python 3.12 安装 mujoco==2.3.7，pip 退回源码构建	使用 Python 3.11 重建 venv；install_env.sh 已自动优先选择 Python 3.11
No module named 'imageio' 或 No module named 'diffusers'	DreamTacVLA 上游 requirements 漏了 robomimic / diffusion policy 间接依赖	重新执行新版 install_env.sh，会补装 imageio imageio-ffmpeg diffusers
CERTIFICATE_VERIFY_FAILED 下载 resnet18-f37072fd.pth	torchvision 运行时临时下载 ResNet18 权重，节点证书链或代理异常	新版 install_env.sh 会提前缓存并校验 ResNet18 权重
Hugging Face 503 或 SSL handshake timeout	官方 Hub 或 AutoDL 学术加速短暂抖动	优先保留本地 archive/cache 后重试；可设置 HF token 提高限额，不要删除已校验通过的 archive
代理 127.0.0.1:12798 connection refused	脚本写死了本机代理，但 AutoDL 实际代理是 network_turbo 注入的内网地址	只 source /etc/network_turbo 并沿用其环境变量，不要硬编码代理地址

11. 当前已验证状态

当前结论：

• 新服务器纯净部署验证：6/6 通过。
• DreamZero/Motus + UniVTAC：依赖 data-univtac 的 Zarr 包已完成 HF 上传。
• 全量 200k SFT 是否完成仍以训练日志和最终 checkpoint 为准，部署验证不等于 full SFT completion。
• RDP：已删除，不再迁移。
• LIBERO/RoboTwin：保留为非核心历史/辅助数据，不作为默认触觉 benchmark。

详见本仓库 docs/hf_repo_index.md、docs/verified_status.md、docs/upload_audit.md、docs/path_strategy.md、docs/pro6000_preflight.md、docs/upload_status.md 和顶层项目中的 MIGRATION_AND_TRAINING_PLAN.md。

12. 维护者上传

上传脚本默认只打印命令，不会真正上传：

bash scripts/upload_from_pro6000.sh

真正公开上传全部代码、数据和 checkpoint 前，需要显式确认：

hf auth login

HF_USERNAME=poet70 \
bash scripts/upload_from_pro6000.sh \
  --execute \
  --allow-public-data \
  --allow-public-checkpoints

数据集和自有 checkpoint 默认使用 tar.gz archive 上传。不要再直接上传大目录树；libero_gear 这类小文件密集目录会触发大量 hash/LFS/commit 往返，实际速度很差。官方 checkpoint 不重复上传。

HF_USERNAME=poet70 \
HF_DATA_UPLOAD_STRATEGY=archive \
HF_CHECKPOINT_UPLOAD_STRATEGY=archive \
HF_HUB_DISABLE_XET=1 \
HF_XET_HIGH_PERFORMANCE=0 \
HF_ARCHIVE_DIR=/root/autodl-tmp/hf_archives \
HF_ARCHIVE_DELETE_AFTER_UPLOAD=1 \
HF_RETRY_MAX=5 \
HF_RETRY_SLEEP=60 \
UNIVTAC_ZARR_SOURCE=/root/autodl-tmp/vla_sft/data/univtac_zarr \
bash scripts/upload_from_pro6000.sh \
  --execute \
  --allow-public-data \
  --skip-code \
  --skip-checkpoints \
  --skip-runs \
  --only-dataset univtac_zarr

等价短命令：

UNIVTAC_ZARR_ARCHIVE=/root/autodl-tmp/univtac_zarr.tar.gz \
bash scripts/upload_univtac_zarr.sh

如果 /root/autodl-tmp/univtac_zarr.tar.gz 已存在，upload_univtac_zarr.sh 会默认直接上传这个现成压缩包，远端文件名仍统一为 univtac-zarr.tar.gz。只有没有现成 archive 时，才用 UNIVTAC_ZARR_SOURCE 指向目录重新打包。

快速闭环可只上传 DreamTacVLA 项目；完整目标矩阵还需要保留 manifeel 通用包供 DreamZero/Motus 使用：

HF_USERNAME=poet70 \
HF_DATA_UPLOAD_STRATEGY=archive \
HF_CHECKPOINT_UPLOAD_STRATEGY=archive \
HF_HUB_DISABLE_XET=1 \
HF_XET_HIGH_PERFORMANCE=0 \
HF_ARCHIVE_DIR=/root/autodl-tmp/hf_archives \
HF_ARCHIVE_DELETE_AFTER_UPLOAD=1 \
bash scripts/upload_from_pro6000.sh \
  --execute \
  --allow-public-data \
  --allow-public-checkpoints \
  --only-code dreamtacvla \
  --only-dataset manifeel_dtvla \
  --only-checkpoint dreamtacvla_jepa \
  --skip-runs

普通 archive 上传到对应 dataset repo 根目录：

<artifact-name>.tar.gz
<artifact-name>.tar.gz.sha256

.sha256 是新 artifact 的推荐/默认格式。若遇到历史 repo 只有 .tar.gz，download_artifacts.sh 会降级为 tar -tzf 结构校验，但这不是密码学完整性校验；面向大规模集群分发时应补齐 checksum 或改用已校验的共享缓存/镜像。

UniVTAC-DTVLA 是例外：原始 tar.gz 为 50,175,952,172 bytes，超过 Hugging Face 单文件 50GB 限制约 176MB。UniVTAC Zarr 若打包后超过 50GB，也会自动按同样规则拆成最少 part。AutoDL 上 Xet 小包可用，但 4GB/50GB 级上传实测会被 137 kill；因此大数据包默认禁用 Xet 走普通 LFS，并提供 manifest、整包 sha256 和 part sha256。导师侧脚本会自动合并。

univtac-dtvla.tar.gz.part-00000
univtac-dtvla.tar.gz.part-00001
univtac-dtvla.tar.gz.sha256
univtac-dtvla.tar.gz.parts.sha256
univtac-dtvla.tar.gz.manifest.txt

当前 Pro6000 /root/autodl-tmp 已扩容，主线方案仍是尽量使用单个 tar.gz 文件；只有超过 HF 单文件限制的 archive 才采用最少 part 数分卷。上传脚本默认设置 HF_HUB_DISABLE_XET=1 走普通 LFS。

如需强制重新打包，加 --recreate-archives。

支持的 --only-dataset key：

manifeel
manifeel_dtvla
univtac_dtvla
univtac_zarr

manifeel 和 univtac_zarr 用于 DreamZero/Motus；manifeel_dtvla 和 univtac_dtvla 用于 DreamTacVLA。LIBERO/RoboTwin 相关 key 只作为非核心历史/辅助数据保留，不建议导师默认下载或训练。

如果 UniVTAC Zarr 不在默认路径 /root/autodl-tmp/vla_sft/data/univtac_zarr，上传前设置：

export UNIVTAC_ZARR_SOURCE=/path/to/univtac_zarr

支持的 --only-code key：

dreamzero
motus
dreamtacvla

支持的 --only-checkpoint key：

dreamtacvla_jepa

Pro6000 上已安装独立 HF CLI 环境时，可先加入 PATH：

export PATH=/root/autodl-tmp/hf_package/hf_cli_conda/bin:$PATH
hf auth login --token "$HF_TOKEN"

当前默认不会上传第三方官方 checkpoint；--skip-checkpoints 只会跳过 DreamTacVLA JEPA 这个自有 checkpoint。

HF_USERNAME=poet70 bash scripts/upload_from_pro6000.sh --execute --allow-public-data --skip-checkpoints

只上传 suite 和代码仓：

HF_USERNAME=poet70 bash scripts/upload_from_pro6000.sh --execute --skip-data --skip-checkpoints --skip-runs