Vla Sft Suite

--- license: other tags: - robotics - tactile - vla - sft - deployment --- # 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`。 ```bash 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 索引。 中国大陆网络环境建议额外设置: ```bash 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 | 20-step 验证:DreamTacVLA 单卡、DreamZero 双卡、Motus 双 80G 卡;正式训练建议按集群资源扩展到多卡/多节点 | | 显存 | DreamTacVLA 约 14.3G;DreamZero 约 41.3G/GPU;Motus 双 A800 验证峰值约 78.9G/GPU,建议 80G 级 GPU | | 磁盘 | 核心 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 | 暂不处理 | 注意: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. 目录结构 建议新服务器统一使用: ```text /data/vla_sft/ ├── suite/ # 本入口仓库 ├── baselines/ # baseline 代码 ├── data/ # benchmark 数据 ├── checkpoints/ # 预训练权重 ├── envs/ # Python venv └── outputs/ # 训练输出 ``` 对应环境变量: ```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 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 bash scripts/download_artifacts.sh \ --baseline dreamtacvla \ --bench manifeel \ --data-root "$DATA_ROOT" \ --ckpt-root "$CKPT_ROOT" \ --code-root "$CODE_ROOT" ``` 只看将要执行什么,不实际下载: ```bash bash scripts/download_artifacts.sh --baseline dreamtacvla --bench manifeel --dry-run ``` ## 5. 安装环境 每个 baseline 使用独立 venv: ```bash bash scripts/install_env.sh --profile dreamtacvla --code-root "$CODE_ROOT" --venv-root "$VENV_ROOT" ``` ### 5.1 包源策略 `install_env.sh` 默认使用清华 PyPI 镜像: ```bash 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。典型现象包括: ```text No matching distribution found Could not find a version that satisfies the requirement HTTP error 404 ``` 如需完全禁用国内镜像: ```bash PIP_INDEX_URL= PIP_TRUSTED_HOST= bash scripts/install_env.sh --profile dreamtacvla ``` 如需保留国内镜像但更换备用源: ```bash PIP_FALLBACK_INDEX_URL=https://pypi.org/simple bash scripts/install_env.sh --profile dreamtacvla ``` 如需禁止自动回退,便于排查镜像可用性: ```bash PIP_DISABLE_FALLBACK=1 bash scripts/install_env.sh --profile dreamtacvla ``` PyTorch wheel 源建议单独指定,避免普通 PyPI 镜像缺少 CUDA wheel: ```bash 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 集群应由调度系统、登录脚本或容器环境显式注入网络变量,例如: ```bash 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 环境可继续使用学术加速: ```bash 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 上禁用自动学术加速: ```bash 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,进而触发源码构建并报: ```text 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: ```bash DREAMTACVLA_PYTHON_BIN=/opt/python/3.11/bin/python3.11 \ bash scripts/install_env.sh --profile dreamtacvla ``` 新节点部署前建议检查: ```bash command -v python3.11 || command -v conda ``` DreamTacVLA 还依赖 robomimic / diffusion policy 的间接包。`install_env.sh` 已补充安装: ```text imageio imageio-ffmpeg diffusers ``` 训练首次构建 ResNet backbone 时会用到 `resnet18-f37072fd.pth`。为避免运行时因 SSL 证书链或外网抖动下载失败,`install_env.sh` 会提前下载到: ```text $TORCH_HOME/hub/checkpoints/resnet18-f37072fd.pth # 若未设置 TORCH_HOME,则为 ~/.cache/torch/hub/checkpoints/resnet18-f37072fd.pth ``` 下载后会校验 sha256 前缀必须匹配文件名中的 `f37072fd`。 安装完成后检查: ```bash source "$VENV_ROOT/dreamtacvla/bin/activate" python - _ _ .log ``` 200G 级临时盘建议开启 archive 解压后清理,避免 `tar.gz` 和解压目录同时长期占用空间: ```bash 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 且明确接受该风险时,才设置: ```bash export HF_DIRECT_DOWNLOAD_AUTH=1 ``` 6 条目标链路均已完成新服务器部署验证。DreamZero/Motus + UniVTAC 依赖 `poet70/data-univtac` 中的 `univtac_zarr` artifact;该 artifact 已完成 HF 上传,可按同一套公共入口下载和启动。 ## 8. 多卡/多节点 DreamZero/Motus 使用 `torchrun` + DeepSpeed。多节点时需要显式设置: ```bash 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 统一建议把输出放到: ```bash $OUTPUT_ROOT/ _ _full ``` DreamZero resume 示例: ```bash ++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/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 bash scripts/upload_from_pro6000.sh ``` 真正公开上传全部代码、数据和 checkpoint 前,需要显式确认: ```bash 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 不重复上传。 ```bash 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 ``` 等价短命令: ```bash UNIVTAC_ZARR_ARCHIVE=/root/autodl-tmp/univtac_zarr.tar.gz \ bash scripts/upload_univtac_zarr.sh ``` 如果...