9.3 lerobot-train 模型训练

lerobot-train

lerobot-train \
  --dataset.repo_id=your_name/so101-test \
  --policy.type=act \
  --output_dir=outputs/train/act_so101 \
  --job_name=act_so101_test \
  --policy.device=cuda \
  --batch_size=8 \
  --steps=100000 \
  --policy.push_to_hub=false \
  --wandb.enable=false

参数	类型	默认值	说明
--dataset.repo_id	str	必填	训练数据集 ID
--policy.type	str	必填	策略类型：act / diffusion / vqbet / smolvla / pi0 / pi05 等
--policy.device	str	None	训练设备：cuda / cpu / mps
--policy.use_amp	bool	False	启用自动混合精度（AMP）
--policy.pretrained_path	str	None	预训练权重路径（微调模式）
--output_dir	str	None	输出目录（checkpoints + 配置）
--job_name	str	None	任务名称（未设置则自动生成）
--resume	bool	False	从 checkpoint 恢复训练
--seed	int	1000	随机种子
--num_workers	int	4	DataLoader 工作进程数
--batch_size	int	8	训练批次大小
--steps	int	100000	总训练步数
--eval_freq	int	20000	评估间隔（步）
--log_freq	int	200	日志打印间隔（步）
--save_checkpoint	bool	True	保存 checkpoint
--save_freq	int	20000	Checkpoint 保存间隔（步）
--wandb.enable	bool	False	启用 WandB 日志
--wandb.project	str	lerobot	WandB 项目名
--policy.push_to_hub	bool	False	推送模型到 Hugging Face Hub
--policy.repo_id	str	None	上传用的 Hub repo ID
--dataset.episodes	list[int]	None	指定训练用的 episode 索引
--dataset.image_transforms.enable	bool	False	启用图像数据增强
--dataset.streaming	bool	False	从 Hub 流式加载数据
--use_policy_training_preset	bool	True	使用策略内置的优化器/调度器预设
--rename_map	dict	{}	重命名观测键名

WandB 日志配置

参数	类型	默认值	说明
--wandb.enable	bool	False	启用 WandB 日志
--wandb.project	str	lerobot	WandB 项目名
--wandb.entity	str	None	WandB 实体/用户名
--wandb.notes	str	None	运行备注
--wandb.mode	str	None	online / offline / disabled

策略模型选择

--policy.type	说明	推荐场景	额外依赖
act	Action Chunking Transformers	新手首选，训练稳定	无
diffusion	Diffusion Policy	复杂动作序列	无
vqbet	VQ-BeT	离散化动作预测	无
smolvla	SmolVLA 轻量级 VLA	语言指令引导	pip install -e ".[smolvla]"
tdmpc	TD-MPC	基于模型的规划控制	无
pi0	视觉-语言-动作流模型	通用机器人控制	pip install -e ".[pi]"
pi0fast	Pi0 快速版	推理速度优先	pip install -e ".[pi]"
sac	Soft Actor-Critic	RL 从零训练	无

---

ACT 参数

lerobot-train \
  --policy.type=act \
  --policy.chunk_size=100 \
  --policy.n_action_steps=100 \
  --policy.dim_model=512 \
  --policy.dim_feedforward=3200 \
  --policy.n_encoder_layers=4 \
  --policy.n_decoder_layers=7 \
  --policy.n_heads=8 \
  --policy.dropout=0.1 \
  --policy.lr=1e-5 \
  --policy.lr_backbone=1e-5 \
  --policy.weight_decay=1e-4 \
  --policy.warmup_steps=1000

参数	类型	默认值	说明
--policy.n_obs_steps	int	1	观测历史步数
--policy.chunk_size	int	100	动作预测块大小
--policy.n_action_steps	int	100	每次执行的动作步数
--policy.dim_model	int	512	Transformer 隐藏维度
--policy.n_heads	int	8	多头注意力头数
--policy.dim_feedforward	int	3200	FFN 扩展维度
--policy.feedforward_activation	str	relu	FFN 激活函数
--policy.n_encoder_layers	int	4	Encoder 层数
--policy.n_decoder_layers	int	7	Decoder 层数
--policy.pre_norm	bool	False	Transformer pre-norm
--policy.dropout	float	0.1	Dropout 概率
--policy.vision_backbone	str	resnet18	视觉骨干网络
--policy.pretrained_backbone_weights	str	ResNet18_Weights...	预训练权重
--policy.replace_final_stride_with_dilation	bool	False	替换 ResNet 末层 stride 为 dilation
--policy.use_vae	bool	False	使用 VAE 变分目标（引入额外 Transformer 解码器）
--policy.latent_dim	int	32	VAE 潜在维度
--policy.n_vae_encoder_layers	int	4	VAE Encoder 层数
--policy.temporal_ensemble_coeff	float	None	时序集成系数（推理时平滑用）
--policy.kl_weight	float	1.0	KL 散度损失权重
--policy.lr	float	1e-5	学习率
--policy.lr_backbone	float	1e-5	视觉 Backbone 学习率
--policy.weight_decay	float	1e-4	权重衰减
--policy.warmup_steps	int	1000	学习率预热步数

---

Diffusion 参数

lerobot-train \
  --policy.type=diffusion \
  --policy.horizon=16 \
  --policy.n_action_steps=8 \
  --policy.n_obs_steps=2 \
  --policy.down_dims="[512,256,128]" \
  --policy.num_train_timesteps=100 \
  --policy.num_inference_steps=10

参数	类型	默认值	说明
--policy.n_obs_steps	int	2	观测历史步数
--policy.horizon	int	16	扩散模型动作预测长度
--policy.n_action_steps	int	8	每次执行的动作步数
--policy.vision_backbone	str	resnet18	视觉骨干网络
--policy.crop_shape	tuple[int,int]	None	图像裁剪尺寸 (H, W)
--policy.crop_is_random	bool	True	训练时随机裁剪
--policy.pretrained_backbone_weights	str	None	预训练权重
--policy.use_group_norm	bool	False	使用 GroupNorm 替代 BatchNorm
--policy.spatial_softmax_num_keypoints	int	32	SpatialSoftmax 关键点数
--policy.use_separate_rgb_encoders_per_camera	bool	False	每路相机独立编码器
--policy.down_dims	list[int]	[512,256,128]	UNet 各层特征维度
--policy.kernel_size	int	5	UNet 卷积核大小
--policy.n_groups	int	8	GroupNorm 组数
--policy.diffusion_step_embed_dim	int	128	扩散步嵌入维度
--policy.use_film_scale_modulation	bool	True	UNet 条件调制方式
--policy.noise_scheduler_type	str	DDPM	噪声调度器：DDPM / DDIM
--policy.num_train_timesteps	int	100	前向扩散步数
--policy.beta_schedule	str	squaredcos...	Beta 调度
--policy.beta_start	float	0.0001	起始 beta 值
--policy.beta_end	float	0.02	终止 beta 值
--policy.prediction_type	str	epsilon	预测类型：epsilon / sample
--policy.clip_sample	bool	True	裁剪采样输出
--policy.clip_sample_range	float	1.0	裁剪范围
--policy.num_inference_steps	int	10	推理时逆向扩散步数（步数越少推理越快）
--policy.do_mask_loss_for_padding	bool	True	对填充动作做 loss mask
--policy.lr	float	1e-4	学习率
--policy.lr_backbone	float	1e-5	Backbone 学习率
--policy.weight_decay	float	1e-6	权重衰减
--policy.warmup_steps	int	1000	预热步数

---

VQBeT 参数

参数	类型	默认值	说明
--policy.n_obs_steps	int	1	观测历史步数
--policy.n_action_pred_token	int	5	动作预测 token 总数（当前+未来）
--policy.action_chunk_size	int	50	每个 token 对应的动作块大小
--policy.vision_backbone	str	resnet18	视觉骨干网络
--policy.crop_shape	tuple	(84,84)	图像裁剪尺寸
--policy.crop_is_random	bool	True	训练时随机裁剪
--policy.pretrained_backbone_weights	str	None	预训练权重
--policy.use_group_norm	bool	True	使用 GroupNorm
--policy.spatial_softmax_num_keypoints	int	32	SpatialSoftmax 关键点数
--policy.n_vqvae_training_steps	int	100000	Residual VQ 训练步数
--policy.vqvae_n_embed	int	16	每层码本向量数
--policy.vqvae_embedding_dim	int	256	码本向量维度
--policy.vqvae_enc_hidden_dim	int	128	VQ-VAE Encoder/Decoder 隐藏维度
--policy.gpt_block_size	int	200	minGPT 最大 block 大小
--policy.gpt_input_dim	int	256	GPT 输入维度
--policy.gpt_output_dim	int	256	GPT 输出维度
--policy.gpt_n_layer	int	3	GPT 层数
--policy.gpt_n_head	int	4	GPT 注意力头数
--policy.gpt_hidden_dim	int	512	GPT 隐藏维度
--policy.dropout	float	0.1	Dropout 概率
--policy.mlp_hidden_dim	int	512	Offset/Bin 预测头隐藏维度
--policy.offset_loss_weight	float	1.0	Offset 损失权重
--policy.primary_code_loss_weight	float	1.0	主码本损失权重
--policy.secondary_code_loss_weight	float	1.0	次码本损失权重
--policy.bet_softmax_temperature	float	1.0	推理采样温度
--policy.sequentially_select	bool	True	是否串行选择主/次码本

---

SmolVLA 参数

lerobot-train \
  --policy.type=smolvla \
  --policy.chunk_size=50 \
  --policy.n_action_steps=50 \
  --policy.vlm_model_name="HuggingFaceTB/SmolVLM2-500M-Video-Instruct" \
  --policy.freeze_vision_encoder=true \
  --policy.train_expert_only=true \
  --batch_size=64 \
  --steps=20000

参数	类型	默认值	说明
--policy.n_obs_steps	int	1	观测历史步数
--policy.chunk_size	int	50	动作预测块大小
--policy.n_action_steps	int	50	每次执行的动作步数
--policy.max_state_dim	int	32	最大状态维度（零填充）
--policy.max_action_dim	int	32	最大动作维度（零填充）
--policy.resize_imgs_with_padding	tuple	(512,512)	图像 resize + padding 尺寸
--policy.empty_cameras	int	0	无相机时的占位图像数
--policy.tokenizer_max_length	int	48	Tokenizer 最大长度
--policy.num_steps	int	10	生成步数
--policy.use_cache	bool	True	KV Cache 加速推理
--policy.vlm_model_name	str	SmolVLM2-500M...	VLM 骨干模型
--policy.load_vlm_weights	bool	False	加载 VLM 预训练权重
--policy.freeze_vision_encoder	bool	True	冻结视觉编码器
--policy.train_expert_only	bool	True	仅训练 Expert 层
--policy.train_state_proj	bool	True	训练状态投影层
--policy.add_image_special_tokens	bool	False	图像特征前后加特殊 token
--policy.attention_mode	str	cross_attn	注意力模式
--policy.prefix_length	int	-1	前缀长度
--policy.pad_language_to	str	max_length	语言填充策略
--policy.optimizer_lr	float	1e-4	优化器学习率
--policy.optimizer_weight_decay	float	1e-10	优化器权重衰减
--policy.optimizer_grad_clip_norm	float	10	梯度裁剪
--policy.scheduler_warmup_steps	int	1000	调度器预热步数
--policy.scheduler_decay_steps	int	30000	调度器衰减步数
--policy.scheduler_decay_lr	float	2.5e-6	衰减后最低学习率

---

TD-MPC 参数

参数	类型	默认值	说明
--policy.n_obs_steps	int	1	观测历史步数
--policy.n_action_repeats	int	1	每步动作重复次数
--policy.horizon	int	10	MPC 规划视野
--policy.n_action_steps	int	1	每次执行的动作步数
--policy.image_encoder_hidden_dim	int	64	图像编码器通道数
--policy.state_encoder_hidden_dim	int	256	状态编码器隐藏维度
--policy.latent_dim	int	128	观测潜在嵌入维度
--policy.q_ensemble_size	int	5	Q 函数集成数量
--policy.mlp_dim	int	512	MLP 隐藏维度
--policy.discount	float	0.99	折扣因子 γ
--policy.use_mpc	bool	True	使用 MPC；关闭则直接用 policy 采样
--policy.cem_iterations	int	6	CEM 迭代次数
--policy.max_std	float	1.0	CEM 高斯最大标准差
--policy.min_std	float	0.1	CEM 高斯最小标准差
--policy.n_gaussian_samples	int	512	CEM 每轮高斯采样数
--policy.n_pi_samples	int	64	CEM 每轮 Policy 采样数
--policy.uncertainty_regularizer_coeff	float	1.0	不确定性正则化系数
--policy.n_elites	int	64	CEM 精英样本数
--policy.elite_weighting_temperature	float	0.5	精英加权温度
--policy.gaussian_mean_momentum	float	0.1	高斯均值动量更新
--policy.max_random_shift_ratio	float	0.05	图像随机偏移比例
--policy.reward_coeff	float	0.1	Reward 损失权重
--policy.expectile_weight	float	0.9	Expectile 回归权重 τ
--policy.value_coeff	float	0.1	Value 损失权重
--policy.consistency_coeff	float	20.0	Consistency 损失权重
--policy.advantage_scaling	float	1.0	优势缩放因子
--policy.pi_coeff	float	1.0	Policy 损失权重
--policy.lr	float	1e-3	学习率
--policy.weight_decay	float	1e-4	权重衰减

---

Pi0 / Pi0-Fast 参数

Pi0 和 Pi0-FAST 是 Physical Intelligence 开源的视觉-语言-动作流匹配模型，约 23 亿参数。安装依赖：

pip install -e ".[pi]"

---

Pi0 完整参数

--policy.type=pi0

参数	类型	默认值	说明
--policy.n_obs_steps	int	1	观测历史步数
--policy.chunk_size	int	50	动作预测块大小（每推理一次生成 50 步动作）
--policy.n_action_steps	int	50	每次执行的动作步数，必须 ≤ chunk_size
--policy.max_state_dim	int	32	状态向量最大维度（不足自动补齐）
--policy.max_action_dim	int	32	动作向量最大维度（不足自动补齐）
--policy.resize_imgs_with_padding	tuple	(224, 224)	图像预处理尺寸，padding 方式保持宽高比
--policy.empty_cameras	int	0	额外空相机数量（pi0_aloha_sim 会用）
--policy.adapt_to_pi_aloha	bool	False	适配 Pi Aloha 关节空间坐标系
--policy.use_delta_joint_actions_aloha	bool	False	动作为关节增量（delta），夹爪仍为绝对值
--policy.tokenizer_max_length	int	48	输入 tokenizer 最大序列长度
--policy.proj_width	int	1024	投影层宽度（视觉 → 语言特征空间）
--policy.num_steps	int	10	扩散解码步数
--policy.use_cache	bool	True	推理时启用 KV 缓存
--policy.attention_implementation	str	eager	注意力实现：eager（默认）/ fa2（FlashAttention）/ flex
--policy.freeze_vision_encoder	bool	True	冻结视觉编码器（微调时建议开启）
--policy.train_expert_only	bool	False	仅训练 Expert 分支
--policy.train_state_proj	bool	True	训练状态投影层

优化器 — AdamW：

参数	默认值	说明
--policy.optimizer_lr	2.5e-5	峰值学习率
--policy.optimizer_betas	(0.9, 0.95)	AdamW β 参数
--policy.optimizer_eps	1e-8	数值稳定常数
--policy.optimizer_weight_decay	1e-10	权重衰减系数

调度器 — CosineDecayWithWarmup：

参数	默认值	说明
--policy.scheduler_warmup_steps	1000	线性预热步数
--policy.scheduler_decay_steps	30000	余弦衰减总步数
--policy.scheduler_decay_lr	2.5e-6	衰减终点学习率

归一化策略：

模态	方式	说明
VISUAL	IDENTITY	图像不做归一化
STATE	MEAN_STD	状态用数据集均值/方差归一化
ACTION	MEAN_STD	动作用数据集均值/方差归一化

显存需求：16 GB 最低，24 GB+ 推荐。Pi0 约 23 亿参数，训练时冻结视觉编码器。建议 --batch_size=8 --steps=100000。

---

Pi0-FAST 完整参数

--policy.type=pi0fast

Pi0-FAST 是 Pi0 的轻量推理优化版，chunk_size 更小、推理频率更高，适合需要实时控制的场景。

参数	类型	默认值	说明
--policy.n_obs_steps	int	1	观测历史步数
--policy.chunk_size	int	10	动作预测块大小（每推理一次生成 10 步动作）
--policy.n_action_steps	int	5	每次执行的动作步数
--policy.max_state_dim	int	32	状态向量最大维度
--policy.max_action_dim	int	32	动作向量最大维度
--policy.resize_imgs_with_padding	tuple	(224, 224)	图像预处理尺寸
--policy.interpolate_like_pi	bool	False	是否使用 Pi 风格插值
--policy.empty_cameras	int	0	额外空相机数量
--policy.adapt_to_pi_aloha	bool	False	适配 Pi Aloha 关节空间
--policy.use_delta_joint_actions_aloha	bool	False	关节动作为增量
--policy.tokenizer_max_length	int	48	Tokenizer 最大长度
--policy.proj_width	int	1024	投影层宽度
--policy.max_decoding_steps	int	256	最大解码步数
--policy.fast_skip_tokens	int	128	跳过 PaliGemma 末尾 128 个特殊 token
--policy.max_input_seq_len	int	256	最大输入序列长度
--policy.use_cache	bool	True	推理 KV 缓存
--policy.freeze_vision_encoder	bool	True	冻结视觉编码器
--policy.freeze_lm_head	bool	True	冻结 LM head 输出层
--policy.precision	str	bfloat16	训练精度
--policy.grad_clip_norm	float	1	梯度裁剪范数
--policy.relaxed_action_decoding	bool	True	宽松模式：允许 action token 填充/截断

优化器 — AdamW：

参数	默认值	说明
--policy.optimizer_lr	1e-4	峰值学习率
--policy.optimizer_betas	(0.9, 0.95)	AdamW β 参数
--policy.optimizer_eps	1e-8	数值稳定常数
--policy.optimizer_weight_decay	1e-5	权重衰减系数
--policy.grad_clip_norm	1	梯度裁剪范数

调度器 — CosineDecayWithWarmup：

参数	默认值	说明
--policy.scheduler_warmup_steps	1000	线性预热步数
--policy.scheduler_decay_steps	30000	余弦衰减总步数
--policy.scheduler_decay_lr	2.5e-6	衰减终点学习率

显存需求：12 GB 最低，16 GB+ 推荐。Pi0-FAST 的 chunk_size=10 / n_action_steps=5，推理频率可达 ~5 Hz。freeze_lm_head 减少可训参数、降低显存占用。适合部署在边缘设备或需要更高控制频率的场景。

---

Pi0 vs Pi0-FAST 对比

特性	Pi0	Pi0-FAST
动作块大小	50	10
执行步数	50	5
峰值学习率	2.5e-5	1e-4
权重衰减	1e-10	1e-5
梯度裁剪	无	1
冻结 LM head	—	True
推理频率	~1-2 Hz	~5 Hz
适用场景	多任务泛化、复杂任务	推理速度优先、实时控制

通用训练参数（--batch_size=8 --steps=100000 等）继承自 TrainPipelineConfig，详见上一节的通用参数表。

SAC 参数

参数	类型	默认值	说明
--policy.n_obs_steps	int	1	观测历史步数
--policy.n_action_steps	int	1	每次执行步数
--policy.lr	float	1e-4	Actor 学习率
--policy.lr_critic	float	1e-3	Critic 学习率
--policy.lr_alpha	float	1e-3	Alpha 学习率
--policy.gamma	float	0.99	折扣因子
--policy.tau	float	0.005	目标网络软更新率
--policy.reward_scale	float	1.0	奖励缩放
--policy.batch_size	int	256	训练批次大小
--policy.buffer_size	int	1000000	Replay Buffer 大小
--policy.learning_starts	int	100	开始训练的步数
--policy.grad_clip_norm	float	10.0	梯度裁剪

SAC 是纯 RL 算法（无需示教数据），在真实机器人上从头训练收敛慢，适合仿真环境。