RobbyantModels Best Practices

Draft pending review

Based on the capabilities of release 930. Example screenshots will be added after the final release.

1. Scope

This guide is for project teams preparing data, fine-tuning models, and deploying models in RobbyantModels. You can collect data on a robot or import existing LeRobot data, then deploy training outputs to a robot or download them for local use.

At the end of this workflow, you should have:

• A published dataset version available for training.
• A successfully trained model artifact in My Models.
• An on-device model instance running on the target device.
• A delivery record linking the dataset, training task, model, and deployment instance.

2. End-to-end workflow

Stage	Main operations	Output	Prerequisites for the next stage
Environment setup	Register the device, connect Robby OSAgent, deploy the runtime, and check configuration and calibration	A device ready for collection or deployment	Device configuration is ready; for on-device operations, the device must be online and the runtime healthy
Data preparation	Generate data through collection tasks, or import existing data locally or from OSS	Initial dataset version	Import succeeds and Episode and version information are accessible
Data publication	Replay, inspect quality, convert formats if needed, and publish a version	Published dataset version	The version is compatible with the base model, robot model, and robot configuration
Model fine-tuning	Configure data, base model, parameters, and outputs, then run training	Training Run, Checkpoints, and exported model	Training succeeds and the target Checkpoint is exported
Model delivery	Choose on-device deployment or direct download	On-device instance or download package	Service invocation or physical robot validation succeeds

Projects using existing data without online on-device OTA can skip data collection and on-device environment setup. Complete environment setup if field data collection or on-device deployment is required.

3. Before you start

3.1. Account and service

• Register a RobbyantStudio account.
• Activate the RobbyantModels service.

3.2. Balance and authorization

• In Billing Center, confirm that available credits cover data processing, model fine-tuning, and inference acceleration.
• For closed-source models, confirm that you have an available License.
• For on-device deployment of closed-source models, ensure there are enough Licenses for all target devices.

3.3. Devices and data

• For on-device projects, prepare the device SN, robot model, and robot configuration.
• Confirm the data source: platform collection, local upload, or OSS import.
• Prepare the target task, scenario conditions, operating steps, and acceptance examples.

3.4. Consistent naming

Use the same task name for datasets, training tasks, models, and deployment instances, adding version and environment information. For example:

Object	Example name
Dataset	end-cap-grasp-v1
Training task	end-cap-grasp-v1-train
Exported model	end-cap-grasp-model-v1
On-device deployment	end-cap-grasp-r2-prod

Names may be used for long-term traceability. Avoid names such as test1 or new-task for production tasks because they do not identify the purpose.

4. Prepare devices and runtimes

For platform collection or on-device deployment, open Environment Setup, select a Robbyant robot or an ecosystem robot, and follow the device onboarding wizard. The workflow differs according to the device source.

4.1. Robbyant R2

4.1.1. Confirm and activate the device

1. Confirm the devices assigned to your account in the device list.
2. Use the RobbyantGo mobile app to scan the code, connect the target device to the network, and activate it.

The device SN identifies the device. The robot model and robot configuration are used to check data and model compatibility.

4.1.2. Deploy the runtime

1. Open Runtime in the device details.
2. Select a compatible image and deploy it to the device.
3. Monitor the task and wait for image download, runtime startup, and health checks to finish.
4. Confirm that the runtime status is Running normally.

If deployment fails, open the latest runtime task to inspect the failed stage and its cause. Resolve connection, image, or resource issues, then select Retry deployment.

4.1.3. Check the device configuration

In the device details, confirm that:

• The robot configuration is ready.
• The motion-control mapping is available.
• The current calibration results are available.
• No configuration change task is running.
• No model instance on the device conflicts with this deployment.

4.2. Ecosystem robots

4.2.1. Register the device

1. Enter the device name and SN.
2. Select the robot model and robot configuration.
3. Submit, open the device details, and confirm that the configuration shown on the platform matches the physical device.

The device SN identifies the device. The robot model and robot configuration are used to check data and model compatibility.

4.2.2. Connect Robby OSAgent

1. Follow the Environment Setup instructions to connect Robby OSAgent on the device.
2. Return to the console and check the connection status and latest heartbeat.
3. Keep Robby OSAgent online when deploying, upgrading, or uninstalling.

Offline devices can be selected for collection tasks, but runtime delivery and model OTA deployment cannot be performed on them.

4.2.3. Deploy the runtime

1. Open Runtime in the device details.
2. Select a compatible image and deploy it to the device.
3. Monitor the task and wait for image download, runtime startup, and health checks to finish.
4. Confirm that the runtime status is Running normally.

If deployment fails, open the latest runtime task to inspect the failed stage and its cause. Resolve connection, image, or resource issues, then select Retry deployment.

4.2.4. Check the device configuration

In the device details, confirm that:

• The robot configuration is ready.
• The motion-control mapping is available.
• The current calibration results are available.
• No configuration change task is running.
• No model instance on the device conflicts with this deployment.

4.3. Bind a closed-source model License

1. Open License Management.
2. Select an available License that is not bound to a device.
3. Select Bind device, choose an activated device that is not bound to another License, and confirm.
4. Check the License status, bound device, and authorization period.

One License can be bound to only one device. Before changing devices, unbind the original device in License Management, then bind the new one.

5. Collect or import data

5.1. Collect data with the platform

Open Data Collection and select Create collection task.

1. Enter the task name, target Episode count, and scenario description.
2. Select a device whose robot configuration is ready and whose calibration is available.
3. Review the camera and joint-data configuration loaded on the page.
4. Add task steps in their actual execution order.
5. After creating the task, monitor collection progress in its details.
6. Open successfully generated Episodes and spot-check camera views, task steps, state data, and action data.
7. When collection is complete, select Create dataset.
8. Confirm the prefilled dataset name, collection task, robot model, robot configuration, and data format, then submit.

Collection task steps must match field operations. Use the same step definitions for all Episodes in a task to make subsequent playback and quality inspection consistent.

5.2. Import existing data

Open Data Management and select Create dataset.

1. Enter the dataset name and version description.
2. Select the robot model and robot configuration.
3. Select the actual data format.
4. Choose local upload or OSS import.
5. For local import, select a ZIP package or folder.
6. For OSS import, follow the instructions to configure read-only access to the target Bucket, then enter the OSS path.
7. Submit and wait for import to finish.
8. Open the dataset details and inspect the Episode count, data overview, hardware information, and Camera mapping.

The selected format must match the source data. Changing the format option is not a substitute for data conversion.

6. Inspect and publish training data

Open the dataset details and select the version to use for training. Process the data in the following order.

6.1. Replay Episodes

1. Spot-check Episodes from the beginning, middle, and end of the task.
2. Switch between cameras and verify that the content and time ranges are complete.
3. Check that robot state, action commands, and task steps change in sync with the same time cursor.
4. Check for warnings about missing segments, abnormal values, and time synchronization.
5. Mark problematic intervals. Episodes confirmed to be unusable can be removed from the version.

6.2. Run quality inspection

• For batch inspection, create an algorithm-based inspection task and wait for completion.
• To check individual entries, use manual quality inspection to review each Episode.
• Resolve issues that block publication, then recheck the results.

6.3. Confirm the training scope

Before publication, review the Episodes to include in training. Keep entries that pass inspection, remove irreparable entries, and record the data scope and known limitations of this version.

6.4. Convert the data format

If the selected base model is incompatible with the current data format:

1. Open Data Conversion from the dataset details.
2. Confirm the source dataset and version.
3. Select the target format and enter the target dataset name.
4. Create the conversion task and wait for completion.
5. Open the generated target dataset and recheck the data volume, Episodes, and format.

Conversion creates a new target dataset. Use the converted version for subsequent training instead of the incompatible source version.

6.5. Publish the version

Before publishing, confirm that:

• Import or conversion is complete.
• The Episode count matches the training scope.
• Quality issues have been resolved.
• The data format is compatible with the base model.
• The robot model and robot configuration are correct.

Select Publish version and record the dataset name and version number. Training tasks display only published versions that meet the current model's compatibility requirements.

7. Create and run a fine-tuning task

Open Model Fine-tuning and create a model post-training task.

7.1. Configure the task

1. Enter a unique task name.
2. Select the robot model and robot configuration.
3. Select the published dataset version and the components participating in training.
4. Check the Camera mapping displayed on the page.
5. Choose the validation set method: none, automatic split from the training set, or a separately selected compatible version.
6. Select the training input: a base model, My Models, or resume from a Checkpoint.
7. Select full-parameter fine-tuning and confirm Batch Size, Learning Rate, Epochs, and other parameters.
8. Set the number of Checkpoints to retain and the retention policy.
9. Enable automatic export, enter the exported model name, and select the export policy.

For additional training, select My Models. To continue an existing task, resume from the target Checkpoint and check the learning rate as prompted.

7.2. Prepare on-device deployment artifacts

If on-device deployment is required, enable Automatically generate deployable on-device weights in the training output settings, then select:

• Target robot model.
• Quantization method.
• Quantized model name.

Training, model export, and inference acceleration have separate statuses. A failed acceleration task does not delete the successfully trained original model; acceleration can be retried independently.

7.3. Review costs and start training

Once required fields are complete, the page displays estimated Token usage and credit costs. Confirm sufficient available balance and select Start training. Charges are settled according to actual task usage. Frozen and settled amounts can be viewed in Billing Center.

7.4. Review training results

Open the training task details, select the current Run, and check:

• Details: progress, Loss, datasets, and training configuration.
• Events: resource allocation and status changes.
• Logs: information, warnings, and errors.
• Metrics: training and evaluation curves.
• Outputs: Checkpoints, export status, and exported models.
• Inference Acceleration: task progress and target artifacts.

If training fails, inspect events and error logs first. Adjust data or parameters based on the cause, then retry. After successful training, confirm that the target Checkpoint has been exported to My Models.

8. Manage model artifacts

Open My Models and locate the artifact by model name, base model, and model type.

Open the model details and verify:

• Source training task and Run.
• Source dataset and version.
• Base model family and version.
• Robot model and robot configuration.
• Whether the model contains original weights or an inference acceleration artifact.
• Supported compute hardware and file size.

Original weights can be used for further training or downloaded (open-source models only; post-training artifacts of closed-source models do not support weight downloads). For on-device deployment, select an inference acceleration artifact matching the target device. Models without robot configuration information support direct download only.

Retain the source model, training task, and target Checkpoint until deployment validation is complete.

9. Deploy a model

9.1. On-device deployment

On-device deployment requires an inference acceleration artifact and an eligible device.

1. In My Models, select an inference acceleration artifact, select Deploy, then On-device deployment. Alternatively, create an instance from the on-device deployment page under Model Deployment.
2. Select the target device from the device list.
3. If a device is unavailable, inspect the reason shown on the page.
4. Verify the model name, file size, target device, and deployment method.
5. Confirm that the device is not performing a critical task, then submit the OTA deployment.
6. Monitor delivery progress, operation history, and instance logs in the deployment details.
7. After completion, confirm deployment status Deployment succeeded and service status Running.
8. Validate on the physical robot using the project's acceptance examples. Record the model version, device SN, robot configuration, and test results.

Device selection checks the robot model, robot configuration, mapping, calibration, License, online status, runtime, and existing model instances. Resolve the blocking reasons shown on the page, then select the device again.

9.2. Direct download

1. Select the target model in My Models and select Deploy.
2. Select Direct download.
3. Confirm the model name, supported robot models, file size, and download link validity period.
4. Download the model and runtime, or copy the download URL.
5. Save the model ID, version, file verification information, and device used.

If the download link expires, return to the model page to generate another link.

10. Validate the service

10.1. Production validation

Complete these checks for on-device services:

• Deployment status is Deployment succeeded.
• Service status is Running.
• The device is online and the runtime is healthy.
• Physical robot acceptance examples pass.

11. Troubleshooting

11.1. A dataset version is missing from the training task

Check in order:

1. Is the dataset version published?
2. Is its format compatible with the base model version?
3. Do the robot model and robot configuration match the training task?
4. Does the page show a reason why it is disabled?

For an incompatible format, create a conversion task and use the resulting target dataset version.

11.2. On-device deployment is unavailable

Confirm that the model is an inference acceleration artifact and includes the target robot model, robot configuration, and supported compute hardware. If information is missing, complete inference acceleration first or use direct download.

11.3. A device cannot be selected for on-device deployment

Follow the blocking reasons displayed on the page and check:

1. Robot model and robot configuration.
2. Motion-control mapping and calibration results.
3. Configuration change tasks in progress.
4. Whether the closed-source model License is valid and bound.
5. Whether the device and Robby OSAgent are online.
6. Runtime health.
7. Active model instances already on the device.

11.4. Training or inference acceleration fails

Open the task's Events and Logs to identify the failed stage and error. Adjust data or parameters before retrying training. If acceleration fails, keep the original model and retry the acceleration task independently.

11.5. Deployment fails or the service behaves abnormally

Resolve the blockers shown in the deployment details before retrying:

• For on-device deployment, check connectivity, runtime, License, instance logs, and remaining resources.

11.6. A License is expired or unbound

Open License Management to renew or bind a valid License. Once authorization is restored, repeat the affected closed-source model operation.