# ╔══════════════════════════════════════════════════════════════════╗
# ║ VLA-Factory Training Recipe — Reference Template ║
# ║ 每个字段都标注了含义、可选值和典型用法。 ║
# ║ 复制此文件作为起点，删除不需要的部分即可。 ║
# ╚══════════════════════════════════════════════════════════════════╝
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 模型 ──────────────────────────────────────────────────────────────
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
model:
name: act # [必填] 注册表中的模型名
# 可选值: act | pi0 | pi05 | openvla-7b | gr00t | octo | smolvla
#
path: null # [可选] 预训练权重路径
# - 指向目录或文件，由模型的 factory 解读
# - null = 从零训练 (适用于 ACT 等小模型)
# - pi0/pi05 仅支持微调，训练时必填 (如 "lerobot/pi0_base")
# - 示例: "outputs/openpi/pi0.5", "openvla/openvla-7b"
# config: # [可选] 逐 run 的模型配置，深度合并到
# # vla_factory/config/model/<name>.yaml 之上 (recipe 优先)
# camera_mapping: # [pi0/pi05 必填] {模型相机角色: 数据集相机名}
# base_0_rgb: front # 角色以 base checkpoint 的 config.json 为准，
# left_wrist_0_rgb: wrist# 用 `vlafactory-cli list --config <recipe>` 查询/校验；
# # 未映射的角色自动用占位图 (mask=0)
# default_task: "..." # [可选] 任务文本兜底 (语言条件模型 pi0/pi05)。
# 取值优先级: 帧级任务文本 (数据集/部署端 task 字段)
# > default_task > "" (空 prompt, 模型仍可运行)。
# 部署时 prompt 由客户端 task 字段传入；数据集缺
# 任务文本或部署端不发 task 时才用到这里的兜底。
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 动作空间 ─────────────────────────────────────────────────────────
# 描述机器人动作向量的语义。框架据此做归一化、delta转换、padding。
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
action_spec:
action_dim: 6 # [必填] 机器人实际动作维度
# SO101 单臂 = 6, ALOHA 双臂 = 14, delta_eef = 7
action_horizon: 100 # [必填] 模型每次推理预测的未来步数
# 也叫 chunk_size
# ACT = 100, PI0 = 50, OpenVLA = 7
action_type: joint_pos # [必填] 动作语义类型
# ┌──────────────┬──────────────────────────────────┐
# │ 值 │ 含义 │
# ├──────────────┼──────────────────────────────────┤
# │ joint_pos │ 绝对关节位置 (ACT, 常见) │
# │ delta_joint │ 关节位置增量 │
# │ delta_eef │ 末端执行器位姿增量 (x,y,z,rx,ry,rz,gripper) │
# │ se3 │ SE(3) 末端位姿 │
# │ tokenized │ 离散化动作 token (OpenVLA) │
# └──────────────┴──────────────────────────────────┘
bounds_low: null # [可选] 每维最小值, 长度 = action_dim
bounds_high: null # [可选] 每维最大值, 长度 = action_dim
# 示例 (6维): [-1, -1, -1, -1, -1, -1]
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 数据 ─────────────────────────────────────────────────────────────
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
data:
source:
path: "" # [必填] 数据集根路径
# 示例: "outputs/lerobot_train_data_100"
format: auto # [可选] 数据格式
# ┌──────────────┬──────────────────────────────┐
# │ 值 │ 说明 │
# ├──────────────┼──────────────────────────────┤
# │ auto │ 自动检测 (推荐) │
# │ lerobot-v3 │ HuggingFace LeRobot v3 格式 │
# │ hdf5 │ HDF5 (Robomimic / ALOHA) │
# │ rlds │ TFRecord RLDS 格式 │
# │ zarr │ Zarr 数组 (BridgeData V2) │
# └──────────────┴──────────────────────────────┘
sampler:
type: sliding_window # 采样策略 (当前仅支持 sliding_window)
n_obs_steps: 1 # 观测窗口帧数
# 大多数模型 = 1; 时序堆叠 = 2-3
action_horizon: 100 # 每个样本包含的未来动作步数
# 通常与 action_spec.action_horizon 一致
split:
strategy: episode # 数据划分策略
# ┌──────────┬──────────────────────────────────────┐
# │ 值 │ 说明 │
# ├──────────┼──────────────────────────────────────┤
# │ episode │ 按 episode 划分 (推荐, 防泄漏) │
# │ random │ 随机打乱划分 (暂未实现) │
# │ task │ 按 task 划分 (多任务数据集, 暂未实现) │
# └──────────┴──────────────────────────────────────┘
train_ratio: 0.9 # 训练集比例 (0.0 - 1.0); 剩余部分自动分配给验证集
seed: 42 # 随机种子
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 微调策略 ─────────────────────────────────────────────────────────
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
finetuning:
strategy: full # [必填] 微调策略
# ┌────────────┬────────────────────────────────────┐
# │ 值 │ 适用场景 │
# ├────────────┼────────────────────────────────────┤
# │ full │ 全参数训练 (ACT从零训练, 或全量微调) │
# │ lora │ LoRA 低秩适配 (大模型推荐) │
# │ freeze │ 冻结指定组件, 训练其余 │
# │ selective │ 只训练指定组件, 冻结其余 │
# └────────────┴────────────────────────────────────┘
# ── strategy == "lora" 时需要 ──
# 字段名与 peft.LoraConfig 对齐（r/lora_alpha/lora_dropout/use_rslora/init_lora_weights
# 透传给 peft）；rank/alpha 作为向后兼容别名也接受。target_components 是 vla 自己的
# 抽象（component → subtree → peft target_modules），因为不同模型 module 名不同。
lora:
r: 16 # LoRA 秩, 越大容量越大. 常用: 8, 16, 32 (peft 名; rank 也接受)
lora_alpha: 16 # 缩放因子, 等效 = lora_alpha / r. 通常设为与 r 相同 (alpha 也接受)
lora_dropout: 0.0 # adapter dropout, 透传 peft
use_rslora: false # rank-stabilized LoRA, 透传 peft
init_lora_weights: gaussian # 初始化方案, 透传 peft (默认 gaussian, 对齐 RLinf openpi LoRA)
target_components: # LoRA 应用到哪些组件 (引用 ModelMetadata.components 的 key)
- llm # PI0 示例: ["llm"] (只 VLM) 或 ["llm", "action_expert"]
- action_expert # OpenVLA 示例: ["llm", "action_head"]
# ── strategy == "freeze" 时需要 ──
# freeze_components: ["vision_encoder"] # 冻结视觉编码器
# ── strategy == "selective" 时需要 ──
# trainable_components: ["action_head"] # 只训练 action head
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 训练参数 ─────────────────────────────────────────────────────────
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
training:
backend: pytorch # 训练后端
# pytorch | jax (预留)
lr: 1.0e-4 # 基础学习率
# ACT: 1e-4 ~ 1e-5
# PI0 LoRA: 2.5e-5
# OpenVLA: 5e-5
lr_backbone: null # [可选] backbone 独立学习率 (通常更低)
# ACT: ResNet 用 1e-5
# null = 与 lr 相同
batch_size: 8 # 每 GPU 批大小
total_steps: 50000 # 总训练步数 (optimizer steps)
gradient_checkpointing: false # 梯度检查点: 省 ~40% 显存, 慢 ~30%
# 大模型 (PI0, OpenVLA) 建议开启
inference_steps: 1 # 推理时的去噪/flow-matching 步数
# 确定性 head (ACT, OpenVLA) = 1
# flow matching (PI0) = 10
# diffusion (Octo) = 10-20
num_workers: 4 # DataLoader 子进程数
# 0 = 单进程 (调试用)
# 4~8 = 多进程并行加载 (推荐, 视频数据集建议 ≥4)
augmentation:
random_crop: true # 随机裁剪
crop_scale: [0.9, 1.0] # 裁剪面积比例范围
color_jitter: 0.1 # 颜色抖动强度 (0.0 = 关闭)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 输出 ─────────────────────────────────────────────────────────────
# 注意: 输出字段必须嵌套在 output: 块下; 顶层的 output_dir: 会被解析器忽略。
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
output:
output_dir: outputs/act_aloha # [必填] checkpoint、日志、最终权重的保存目录
# 示例: "outputs/act_aloha_000"
report_to: none # [可选] 训练日志后端
# ┌──────────────┬────────────────────┐
# │ 值 │ 说明 │
# ├──────────────┼────────────────────┤
# │ none │ 不记录 (默认) │
# │ tensorboard │ TensorBoard │
# │ wandb │ Weights & Biases │
# └──────────────┴────────────────────┘
logging_steps: 200 # [可选] 每隔 N 步记录一次训练指标
save_steps: 20000 # [可选] 每隔 N 步保存一个 checkpoint
save_total_limit: 3 # [可选] 最多保留的 checkpoint 数量
# 超出后删除最旧的
overwrite_output_dir: true # [可选] 训练前是否清空 output_dir
# true = 清空 (重新训练时推荐)
# false = 追加 (断点续训时用)