Deploy ML models across your fleet

Deploy a trained ML model to one machine or your entire fleet using the same fragment workflow you use for modules. When you retrain and upload a new model version, machines configured to track that version update automatically.

When to use this

Use this page when you have a trained model in the Viam registry and want to deploy it to multiple machines. If you are deploying to a single machine for the first time, start with deploy a model to a machine.

Prerequisites

• A trained ML model in the Viam registry. See train a model.
• At least one machine with a camera configured. See add a camera.
• A fragment for your fleet. If you don’t have one yet, create one first.

How model deployment works

ML models are deployed as registry packages, the same way modules are. A machine needs two services to run a model:

1. ML model service: loads the model file and runs inference.
2. Vision service: connects the ML model service to a camera and returns detections or classifications.

You configure both services in a fragment, apply the fragment to your machines, and every machine downloads the model and starts running inference.

1. Add the model and vision service to a fragment

1. Navigate to your fragment at app.viam.com/fragments.
2. Click + and add an ML model service (for example, search for tflite and add tflite_cpu).
3. In the ML model service card, under Deployment, select Deploy model on machine.
4. Click Select model and choose your trained model from the registry.
5. Click + again and add a vision service. Search for mlmodel and add the mlmodel vision service.
6. Configure the vision service to use the ML model service you just added.
7. Click Save.

2. Choose a version strategy

Each ML model package has a version field in the fragment configuration.

• Track latest: leave the version at the default. When you upload a retrained model, machines update automatically on their next config sync.
• Pin to a specific version: set the version string to prevent automatic updates until you are ready.
• Use fragment tags: create stable and development tags on the fragment. Test new models on development machines before promoting to production. See reuse configuration for the tag workflow.

To control the timing of updates, configure a maintenance window so models are not swapped while a machine is actively processing. See manage versions.

3. Apply the fragment to machines

Apply the fragment to your machines through the Viam app, provisioning, or CLI. See deploy software for the steps.

4. Verify the deployment

1. Navigate to a machine’s CONTROL tab.
2. Find the vision service card and test it with a live camera feed to confirm detections or classifications appear.
3. Check the LOGS tab for errors from the ML model service or vision service.

Update or roll back a model across the fleet

When you retrain and upload a new model version:

• Tracking latest: machines update on their next config sync (or within the maintenance window).
• Using fragment tags: update the fragment configuration with the new model version, save to create a new revision, then move the stable tag to the new revision.
• Pinned to a version: update the version string in the fragment and save.

Rolling back follows the same pattern in reverse: change the version pin or move the tag back to a previous revision. Viam does not automatically roll back if a new model performs worse, so you change the pin or tag manually.