ACT Model Training

ACT (Action Chunking with Transformers) comes from the ALOHA work, and its official implementation is at tonyzhaozh/act. Embodiflow registers this policy under the model identifier act and accepts LeRobot v2 or v3 datasets. Training first converts the LeRobot data into ACT HDF5 episodes inside the container and then runs the training.

Roles and Prerequisites

Roles

Role	Scenario	Dependency
Algorithm engineer	Fine-tune the ACT policy for a single task or a set of similar tasks	Training and dataset module permissions
Project Manager	Track the progress and artifacts of ACT training tasks	Training task view permission
Data provider	Provide datasets that meet the field and dimension requirements	Data export module permissions

Prerequisites

Item	Requirement
Dataset version	LeRobot v2 or v3
Dataset structure	Includes meta/info.json, has parquet files under data/, and stores video fields under videos/
Data fields	Includes observation.state and action, with matching dimensions
Camera fields	The fields with dtype video in features form the visual input and can be specified with camera_keys
Training framework	Native ACT (PyTorch) or LeRobot; native ACT by default
Compute resources	A GPU container; VRAM requirements vary with batch_size and the number of cameras, and the platform sets no fixed threshold
Run name	The output directory for run_name must be empty

Training Task Creation and Parameters

Procedure

1. Create a training task on the training page and select act as the model.
2. Choose a data source: a platform export record, an external URL, or an uploaded LeRobot dataset.
3. Choose the dataset version v2 or v3 to match the actual format of the dataset.
4. Configure the parameters; set run_name and camera_keys explicitly.
5. Choose the compute resources and submit the task.

Training Parameters

Defaults and allowed ranges:

Parameter	Description	Default	Range
batch_size	Batch size	64	≥ 1
num_epochs	Number of training epochs	12000	≥ 0; takes precedence when greater than 0
steps	Alias for num_epochs	0	≥ 0; used only when num_epochs is 0 and steps is greater than 0
learning_rate	Base learning rate	5e-5	> 0
save_interval	Epoch interval for saving	6000	≥ 1; at the default value, half of num_epochs
seed	Random seed	42	Integer
num_workers	Number of DataLoader workers	0	≥ 0; 0 is recommended inside the container
policy_class	Policy type	ACT	Fixed to ACT
kl_weight	Weight of the KL term	10	≥ 0
chunk_size	Action chunk length	100	≥ 1
hidden_dim	Transformer hidden dimension	512	≥ 1
dim_feedforward	FFN hidden dimension	3200	≥ 1
task_name	Task name	auto	auto or a string
run_name	Run name	Empty; a timestamp name is generated	Letters, digits, dots, underscores, and hyphens, up to 128 characters
camera_keys	LeRobot visual fields	Empty; inferred automatically	Comma-separated field names
camera_names	ACT camera names	Empty; generated from camera_keys	Same count as camera_keys and unique
episode_len	Override episode length	0	≥ 0; 0 means auto-detect
idle_threshold	Threshold for filtering idle frames	1e-4	≥ 0
max_episodes	Convert only the first N episodes	0	≥ 0; 0 means all
convert_workers	Number of concurrent conversion workers	0	≥ 0; 0 means an automatic policy with a maximum of 8
keep_converted_hdf5	Keep intermediate HDF5 files	false	Boolean

For multi-GPU training, batch_mode is fixed to fixed_global and is not exposed separately. To validate the data pipeline for the first time, submit a minimal configuration: set num_epochs to 1, batch_size to 8, and max_episodes to 2.

Verification

Training Monitoring

Training logs output Epoch N and Val loss: X. Embodiflow records the epoch as the training step and the validation loss as the loss, and uses them for the loss curve on the training details page.

Metric	Meaning
Epoch	Current training epoch
Val loss	Validation loss

Verification Checklist

Check	Pass criteria
Checkpoint directory	checkpoints/<run_name>/ is created
Checkpoint files	Include policy_last.ckpt and policy_best.ckpt; policy_epoch_<epoch>_seed_<seed>.ckpt is created per save_interval
Dataset statistics	dataset_stats.pkl is created
Run manifest	state_dim, num_episodes, camera_keys, and camera_names in manifest.json match the selected dataset
Loss curve	Val loss decreases over training
Intermediate artifacts	When keep_converted_hdf5 is off, the HDF5 files from conversion are cleaned up after training ends

Error Handling

Symptom	Possible cause	Action	Owner
Startup reports that the run name already exists	A directory with the same run_name under the output directory is not empty	Change run_name and retry	Training configuration owner
Error that camera names and camera field counts differ	camera_names and camera_keys have different counts, or camera names are duplicated	Make the counts equal and the names unique	Training configuration owner
Error that the state and action dimensions differ	observation.state and action in the dataset have different dimensions	Fix the dataset so that both dimensions match	Data provider
Error that no camera field was found	No usable video field in features, or camera_keys is set incorrectly	Check features in meta/info.json and set camera_keys explicitly	Data provider, training configuration owner
Error that the dataset is missing required columns	The parquet files lack episode_index, frame_index, observation.state, or action	Add the missing columns and re-export the dataset	Data provider
Out of VRAM	batch_size and the number of cameras are too large	Lower batch_size	Training configuration owner
Unstable multi-GPU training	Disk and memory pressure during the conversion stage	Keep num_workers at 0 and lower convert_workers	Training configuration owner

Related Pages

Page	Purpose
Model training	Create, monitor, and quota training tasks
LeRobot datasets and training	Data export and training overview
LeRobot v2 and v3 format differences	Differences and migration between the two data formats
Data export	Generate a LeRobot training package