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

导师集群交付文档：

• docs/README.md：文档索引和推荐阅读顺序。
• docs/部署指南.md：从 HF 下载到 6 条 full-config SFT 启动的主流程。
• docs/directory_layout.md：标准目录、环境变量、数据/checkpoint/output 命名。
• docs/experiment_params.md：6 条链路参数、资源需求、显存记录。
• docs/full_sft_readiness_checklist.md：从 20-step 验证切到正式长跑前的风险和检查清单。
• docs/troubleshooting.md：部署问题、原因、修复和预防。
• docs/verification_report.md：2026-07-06 双 A800 6x20 验证报告。
• docs/hf_repo_index.md：Hugging Face 仓库和 artifact 索引。

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

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. 服务器要求

推荐配置：

当前 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 暂缓/归档。

注意：2026-07-06 已在全新双 A800 服务器上完成 6 条链路的 Hugging Face 下载、部署、环境安装、数据/权重准备和 full-config 20-step 启动验证。该验证证明训练入口可启动，不等于 200k steps full SFT 已完成。LIBERO/RoboTwin 不是本项目核心触觉 benchmark，不进入默认复现实验矩阵。

正式长跑前请先阅读 docs/full_sft_readiness_checklist.md。尤其要确认 FULL_STEPS 已从 20 改为正式步数、DreamZero/Motus 最终 checkpoint 保存没有继续被跳过、Motus 使用 80G 级 GPU 且不与其他大训练并行。

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/archive/upload_file_plan.md 和 docs/archive/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。

推荐在 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. 常见报错

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/archive/verified_status.md、docs/archive/upload_audit.md、docs/archive/path_strategy.md、docs/archive/pro6000_preflight.md、docs/archive/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