本文记录了在复现 LingBot-VA 在 RoboTwin 数据集上的 post-training 过程中遇到的六个典型问题。这些问题具有一定的通用性，并非局限于特定机器环境，希望能为后续研究者提供参考。

---

1. 训练初始化 checkpoint 的选择

• 训练初始化应当使用 lingbot-va-base
  https://huggingface.co/robbyant/lingbot-va-base

---

2. 训练数据格式并非原始 RoboTwin 数据

若直接使用 RoboTwin 的原始数据集（如包含原始视频和轨迹的目录），训练流程将无法正常启动。

LingBot-VA 的 post-training 依赖于经过预处理的 LeRobot 格式数据，具体包括：

• meta/info.json（LeRobot 元数据）
• latents/ 目录（预提取的潜在表示）

换言之，训练不直接消费原始轨迹，而是消费已经完成特征提取的数据产物。在开始训练前，应确认数据目录中包含上述两项。若缺失，则需要先完成数据预处理链路，而非修改训练配置。

---

3. Attention 机制的环境假设与兼容性问题

训练代码中默认使用了 flex attention，但并非所有 PyTorch 版本都支持该特性。常见的现象是：

• 模型初始化时报 flex attention is unavailable
• 即使将 attn_mode 改为 "torch"，训练仍在第一步崩溃于 FlexAttnFunc.init_mask() 内部的 and_masks / or_masks 为 None

根本原因：修改 attn_mode 仅影响模型构造阶段，但训练前向逻辑中仍无条件执行了 flex 专属的 mask 初始化代码。

兼容性处理方案：

• 在模型加载时：若检测到 HAS_FLEX_ATTENTION == False，则自动回退到 attn_mode = "torch"
• 在训练前向中：仅当 attn_mode == "flex" 时才调用 FlexAttnFunc.init_mask(...)，"torch" 分支应完全跳过该逻辑

这样可以保证在不同 PyTorch 构建下训练均能正常进行。

---

4. FSDP 在不同 PyTorch 版本下的行为差异

在多卡训练（例如双卡或更多）时，错误往往不在模型加载阶段出现，而是在第一步反向传播或梯度同步时爆发。典型错误包括：

• 'WanTransformer3DModel' object has no attribute 'set_requires_gradient_sync'
• 部分模块（如 patch_embedding_mlp）仍留在 CPU，导致 device 不一致
• 输入 tensor 为 bfloat16，而部分参数仍为 float32，引发 dtype 不匹配

问题本质：代码假设 FSDP 的 API 行为与作者环境完全一致，并且根模块会被自动放置到正确的设备与数据类型上。实际环境中往往并非如此。

通用解决方案：

• 梯度累积时，若对象不支持 set_requires_gradient_sync，则回退使用 self.transformer.no_sync()
• 在执行 FSDP 分片之前，显式地将整个模型移动到目标设备并转换为目标数据类型：.to(device=device, dtype=param_dtype)

这一步对于避免 step 0 的各种隐晦错误至关重要。

---

5. “能启动”不等于“跑通”：真正的 smoke test 标准

许多实践者将以下现象误判为训练已正常工作：

• 模型与数据集初始化成功
• 日志打印 Starting training for ...
• 进度条开始显示

然而对于 LingBot-VA 的训练链路，最容易出错的位置恰好是 第一步前向与反向计算。仅能启动程序并不代表训练能够稳定进行。

建议的验证标准：

• 能够稳定完成 step 0
• 能够连续运行至少 step 10+ 而不再崩溃
• GPU 显存占用稳定，loss 正常输出并下降

只有满足上述条件，才能认为训练环境已基本正确配置。

---

6. Checkpoint 保存策略：模型快照而非完整断点恢复

仓库默认按固定步长间隔保存 checkpoint，但保存的内容主要为：

• transformer 权重
• config.json

不包括：

• optimizer 状态
• scheduler 状态
• 完整的 training state（如当前 step、随机数状态等）

因此，这些 checkpoint 更适合用于评测、推理、或作为新的初始化权重继续训练，而不支持中断后无缝恢复训练。若需要支持断点续训，使用者应自行扩展保存逻辑，补全 optimizer、scheduler 及训练元信息。

---

推荐的复现流程

为避免早期被多卡问题卡住，建议按以下顺序推进：

1. 准备正确的 base checkpoint
2. 准备符合 LeRobot + latents 要求的 训练数据
3. 单卡环境先行调试，目标是通过 step 0 及前若干步
4. 单卡稳定后，再切换到 2 卡或多卡 环境
5. 运行数千步后，验证 checkpoint 保存与评测链路是否正常

这一顺序有助于逐步隔离问题，降低调试复杂度。

---

总结

复现 LingBot-VA 的 post-training 过程，其主要难点不在于命令行的使用，而在于训练代码中隐含的多项环境假设。本文归纳的三个核心要点如下：

• 训练初始化必须使用 lingbot-va-base，避免误用评测模型
• 训练数据必须是经过预处理的 LeRobot + latents 格式，而非原始 RoboTwin 数据
• 真正的兼容性问题大多暴露在 step 0，特别是 attention 与 FSDP 相关的环境差异

提前理解并处理上述问题，可显著降低复现成本。