[Eliza Farley (elizafarley)]

Jira: DOCS-5068 (stage 1 of DOCS-5063) and DOCS-4213. The plan in DOCS-5063 is up to date with this PR.

The Train ML models section no longer assumes every model is an image classifier or object detector. It's organized around the stages every model goes through, and it covers robot policies and Other models alongside vision models.

Changes

Overview (train/overview.md), rewritten:

• When to use an existing or uploaded model instead of training
• Types of models: the five task types, each with an example, example base models, and which training method takes it
• How training works: the training loop (new diagram, static/train/training-flywheel.svg) from capturing data to retraining, with an Evaluate stage
• Built-in or custom training: when to use each, a comparison table, and what the framework decides
• What's next replaces the section cards

Built-in training (train/train-a-model.md), retitled "Train a vision model with built-in training":

• The intro scopes the page to vision models and links to Built-in or custom training for everything else
• Prerequisites, with the dataset minimums moved here from create-a-dataset.md
• A Choose a framework table (TFLite or TensorFlow)
• Steps for starting and monitoring a job, each with Viam app, CLI, Python and Go tabs. A last step verifies the model and links to evaluation.
• The Upload your training script and Parse command line inputs sections are removed. The Viam app links to their anchors, so the anchors are kept as empty <span id> elements.

Custom training (train/custom-training-scripts.md), retitled "Train a model with a custom training script", is now a standard how-to:

• Prerequisites (CLI 1.15.0 or later for robot_policy, Docker)
• Seven numbered steps: find an existing script in the registry, plan the script (dataset type, model it produces, container), write, test locally, upload, submit, and verify
• Troubleshooting
• Covers every task type and the Registry framework, with labels.txt guidance for models you want to evaluate
• File formats move to the new reference page. Existing anchors are kept.

Training dataset formats (train/dataset-formats.md) replaces train/sequence-dataset-format.md, with an alias. It covers the training script arguments, the binary and sequence dataset files, and the training job environment.

Evaluate a model (train/evaluate-a-model.md) is a new how-to. It runs a classification or detection model on a labeled test dataset from the dataset's Evaluations page, and reads precision, recall and F1 for each label.

Deploy a model (train/deploy-a-model.md):

• A new What runs the model section is now the only framework and hardware table, and covers the Registry framework
• Deploy the model covers every framework, with Viam app (model page or CONFIGURE tab), Python and Go tabs. The Python and Go tabs add the module, package and resource with update_robot_part, including for a Registry model.
• The vision service is optional, for classification and detection models only
• New Verify the model loaded and Troubleshooting sections. Use the model in code is removed; What's next links the vision pipeline, the ML model service API and fleet deployment.

Create a dataset (train/create-a-dataset.md):

• Add data and Export a dataset have one tab per interface, and each tab says what it supports for binary and sequence datasets
• Prepare a dataset for training (labeling, quality recommendations, verification) applies to both dataset types and both training methods

Annotate data (train/annotate-data.md), renamed from annotate-images.md with an alias:

• Viam app, Python and Go tabs for tagging images and drawing bounding boxes
• A new Tag sequences section, with Python, Go and TypeScript tabs

Other pages:

• Link and wording updates: vision/configure.md, vision/overview.md, vision/deploy-and-maintain/retrain.md (links evaluation), deploy-custom-model.md, batch-inference.md, train/automate-annotation.md (Run model > Get auto-predictions), train/custom-containers.md, data/sequences.md, data/sequences-tutorial.md, data/tag-data.md, and the ML glossary term
• vision/deploy-and-maintain/deploy-from-registry.md drops its framework table and links to What runs the model. Its #model-framework-support heading stays, because the Viam app links to it.
• assets/train/task-types.png is removed

Not in this PR

Removing the duplication between Train ML models and the vision Deploy and maintain models section happens in a follow-up PR, #5492, stacked on this one. This PR only replaces the framework table in deploy-from-registry.md with a link. #5492 gives model versions one home in train/deploy-a-model.md, merges vision/deploy-and-maintain/roll-out-to-fleet.md into fleet/deploy-ml-models.md, and changes the vision pages to link to Train instead of restating it.

Verification

Verified against source (app origin/main at 0678a15, 47c502e and d951608; rdk origin/main):

• Task type names (Single label classification, Multi label classification, Object detection, Robot policy, Other = UNSPECIFIED): app ui/src/lib/ml-model.ts:385-399
• Built-in training rejects Robot policy and unspecified task types: app mltraining/internal_ml_training_service.go:196-202. It's disabled for sequence datasets: training-first-screen.svelte:24,95-110.
• Dataset minimums (80% labeled, 10 per label, 15 total for detection) are skipped for custom jobs: app mltraining/training_job_manager.go:810, constants at internal_ml_training_service.go:37-43. The two-label minimum applies only to multi label classification: ml_training_service.go:251.
• SDK jobs always train TFLite: app mltraining/ml_training_service.go:227-231
• Completion and failure emails: mltraining/training_job_manager.go:1037-1053,1430-1448
• A custom job takes its task type, framework and module resources from the training script: app mltraining/ml_training_service.go:389-424
• Frameworks and the module each deploys with: app ui/src/lib/ml-model.ts:526-533, ui/src/lib/rdk/ml-model.ts:226-268
• Deploy dialog: one name per module resource for Registry; the vision step only for non-Registry deploys; Include Vision service defaults on only for vision types: deploy-model-dialog.svelte:460-465,547-567,728-742,933, ui/src/lib/ml-model-deploy.ts:97-108
• A manual Registry deploy sets model_path to ${packages.ml_model.<name>}: app ui/src/lib/ml-model.ts:106-117,172-174, ui/src/lib/rdk/ml-model.ts:31-32,124-140
• Auto-predictions and cloud inference accept only vision types in TF, TFLite or ONNX: app ui/src/lib/inference.ts:47-67
• Viam-managed containers: app etc/migrations/add_training_containers/viam_containers.json
• Registry filter for training scripts (?type=Training+Script): app ui/src/routes/registry/registry-context.svelte.ts:43-59
• CLI --type includes robot_policy and unspecified: rdk cli/ml_training.go:709-721. robot_policy shipped in CLI v1.15.0 (rdk#6674).
• viam dataset export --only-jsonl: rdk cli/dataset.go:265,374-386, utils machinelearning/image_metadata_to_JSON.go:124-150
• UpdateSequence replaces sequence_tags and requires a field mask: app domains/datamanagement/sequences.go
• The Viam app can't download a sequence dataset: sequence-dataset-sidebar.svelte:319-329
• TypeScript can add images to a dataset: viam-typescript-sdk src/app/data-client.ts:1056
• DATA > MODELS lists models with an Active Training section, and a model's details page lists its versions: app routes/(auth-required)/models/models-page-main.svelte, [registry_item_name]/model-versions-table.svelte

Evaluate a model (app d951608, api, rdk, Python and TypeScript SDKs):

• Entry points Run model > Evaluate model performance and Evaluations > New evaluation: dataset-sidebar.svelte:198-218,661-766, evaluations-page-main.svelte
• Accepted models (no Robot policy or unspecified; TF, TFLite or ONNX only): ui/src/lib/evaluation.ts:12-35, mlinference/batch_evaluation_job_topic.go
• Thresholds (defaults 0.5, IoU for detection only, fixed after start): evaluation-config-dialog.svelte, mlinference/internal_ml_inference_service.go:178-183
• JPEG and PNG only: batch_evaluation_job_topic.go:205. Read-only: batch_evaluation_job_topic.go:150.
• Scoring: mlinference/evaluation/evaluate.go:20-180, accumulator.go:47-97
• Billing (each image is one cloud inference): batch_worker_common.go:215, ml_inference_service.go:321
• No CLI, SDK or public API: no EvaluationJob in rdk, api, viam-python-sdk or viam-typescript-sdk
• Statuses, columns and per-class breakdown: evaluations/evaluation-status-pill.svelte, evaluation-job-row.svelte, evaluations-table.svelte, class-metrics-table.svelte. Failure messages: batch_worker_common.go:55-85.

Code samples tested (Python SDK 0.85.2, rdk/CLI 1.15.0, TypeScript SDK 0.79.0, in a test org; test data cleaned up afterwards):

• Every Python, Go and TypeScript sample type-checks or compiles against the current SDKs.
• Run live: creating binary and sequence datasets and adding images and sequences (Python, Go, TypeScript, CLI); tagging images, drawing bounding boxes and tagging sequences (Python, Go, TypeScript); exporting both dataset types, with layouts matching dataset-formats.md; listing and getting training jobs and reading logs (Python, Go, CLI); viam train containers list.
• Deploy a model: the Python and Go samples write the expected module, package and service entries to a machine part. A Python write with a stale last_known_update is rejected with FAILED_PRECONDITION.
• Custom training: the binary script ran in Docker with viam training-script test-local and wrote model.tflite and labels.txt. The sequence script ran against a real export, and every image path resolved. Both ran without Docker with the commands on the page.
• Fixed from testing: the binary "Run without Docker" command now runs from the export directory, since dataset.jsonl image paths are relative to it, and viam dataset data add filter uses --location-ids.
• The flags in viam train submit managed, viam train submit custom from-registry and viam training-script upload match the CLI's help.

Not run: training jobs weren't submitted and no training script was uploaded. The deployed model wasn't loaded on a running machine. The evaluation flow wasn't clicked through in the Viam app.

Checks: prettier 3.2.5, markdownlint, vale 3.12.0, frontmatter_rules.py and make build-prod pass. docs-skills checkers report no errors on the pages this PR restructures. The remaining warnings are kept:

• overview.md: EX-01, because the title is the section's name.
• train-a-model.md: HT-17, because "Choose a framework" names the choice.
• evaluate-a-model.md: HT-01 ("Evaluate" is a verb) and HT-03 (the intro note is deliberate).
• custom-training-scripts.md: HT-16, because the page is 2,011 words.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	277560c
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6aee0eb57c1b58dc0e4967b4
😎 Deploy Preview	https://deploy-preview-5487--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 42 (🟢 up 7 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 60 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[viambot]

It looks like the following files may have been renamed. Please ensure you set all needed aliases:

 rename docs/train/{annotate-images.md => annotate-data.md} (54%)
 rename docs/train/{sequence-dataset-format.md => dataset-formats.md} (45%)

[Jeremy Rose (jeremyrose-viam)]

General note: the CLI reference needs the same test-local fix this PR makes in custom-training-scripts.md.

This PR's test-local example (--dataset-root=. plus --dataset-file=<destination>/dataset.jsonl, run from the directory where viam dataset export ran) matches how the CLI behaves. viam dataset export --destination=X records each image path in dataset.jsonl as X/data/<file>, relative to the directory you ran the export from, and test-local mounts --dataset-root as the container's working directory (checked against rdk v1.15.0: cli/dataset.go, cli/ml_training.go).

docs/cli/datasets-and-training.md still shows the old form, and it contradicts that:

viam dataset export ... --destination=./my-dataset      # l.121–131

viam training-script test-local \
  --dataset-root=./my-dataset/ \                        # l.276
  --dataset-file=dataset.jsonl \                        # l.278
  ...

With that export, the JSONL paths are my-dataset/data/<file>, so with --dataset-root=./my-dataset/ they resolve to my-dataset/my-dataset/data/<file> and the images aren't found. Suggested fix, run from the directory where the export ran:

viam training-script test-local \
  --dataset-root=. \
  --dataset-file=my-dataset/dataset.jsonl \
  --training-script-directory=./my-training-script/ \
  --container-id=<container-id> \
  --model-output-directory=./output/

Since the new page and the CLI reference would otherwise disagree on the same command, it seems worth fixing the reference in this PR.

[Jeremy Rose (jeremyrose-viam)]

The old overview documented dataset snapshotting at train time ("Each time you train a model from a dataset, Viam snapshots the dataset's contents at that point..."). This PR removes that section and nothing restates it. Suggested wording here, since this is where it happens:

Suggested change

	[Built-in training](/train/train-a-model/) needs no code; a [custom training script](/train/custom-training-scripts/) runs your own code.
	[Built-in training](/train/train-a-model/) needs no code; a [custom training script](/train/custom-training-scripts/) runs your own code.
	When you start a training job, Viam snapshots the dataset's contents at that point, so the model is trained on exactly the images and labels the dataset held at that moment.
	You can keep adding, labeling and removing data afterward without affecting models you've already trained.
	To train on the changes, start a new training job.

Worth confirming that snapshotting applies to custom-script jobs as well as built-in training.

[Eliza Farley (elizafarley)]

Fixed in 277560c. Stage 3 now says Viam snapshots the dataset when the job starts, so later changes don't affect running jobs or trained models. I said "data and labels" so it also covers sequence datasets. Confirmed it applies to custom-script jobs too: the backend builds the training dataset when it processes the job, for built-in and custom jobs alike.

[Jeremy Rose (jeremyrose-viam)]

The old overview had an "Automatic deployment" section ("If a machine is already configured to use that model, Viam automatically deploys the new version... No manual download or restart is needed."). This PR reduces it to "pick it up". Suggested wording, which also fixes the "struggles to the dataset" adjacency:

Suggested change

	You add data from the cases where the model struggles to the dataset, train a new version, and machines configured to use the model pick it up.
	In cases where the model struggles, you add data to the dataset and train a new version.
	When training completes, a machine that is already configured to use the model gets the new version automatically.
	It pulls the latest version the next time it checks for updates, with no manual download or restart.

Worth confirming whether this applies only to machines whose package entry uses version: latest, since the deploy page's examples pin that field.

[Eliza Farley (elizafarley)]

Fixed in 277560c, using your wording for the first sentence. The auto-update sentence is limited to machines whose config uses the model's latest version. One note: the deploy page's examples use "version": "latest" rather than pinning it, so the two pages agree.

[Jeremy Rose (jeremyrose-viam)]

GetSequence returns a struct whose SequenceTags slice may have spare capacity, so append onto it can write into the fetched sequence's backing array. Copying first matches what the Python (list(...) + [...]) and TypeScript ([...]) examples already do:

Suggested change

	SequenceTags: append(sequence.SequenceTags, "pick-up-cup"),
	SequenceTags: append(slices.Clone(sequence.SequenceTags), "pick-up-cup"),

This needs import "slices".

[Eliza Farley (elizafarley)]

Fixed in 277560c. sequenceFromProto passes the proto slice straight through, so the clone is needed. I left out import "slices" because the Go snippets on this page don't show their imports.

[Jeremy Rose (jeremyrose-viam)]

updateSequence takes its arguments positionally (id, resources, sequenceTags, startTime, endTime, fieldMask), so the undefined placeholders can't be removed. Labeling them shows which argument each one is:

Suggested change

	undefined,
	[...sequence.sequenceTags, "pick-up-cup"],
	undefined,
	undefined,
	undefined, // resources
	[...sequence.sequenceTags, "pick-up-cup"],
	undefined, // startTime
	undefined, // endTime

[Eliza Farley (elizafarley)]

Fixed in 277560c.

[Jeremy Rose (jeremyrose-viam)]

Go and TypeScript both say the field mask is required, but this tab doesn't mention it. In the Python SDK, update_sequence builds the field mask itself from whichever arguments are not None (verified in viam-sdk 0.85.2). A one-line note keeps the three tabs consistent:

Suggested change

```

The SDK builds the field mask from the arguments you pass, so you don't set it yourself.

[Eliza Farley (elizafarley)]

Fixed in 277560c. Confirmed against update_sequence on the Python SDK's main branch.

[Jeremy Rose (jeremyrose-viam)]

This PR removes the "list your organization's datasets from code" snippets (list_datasets_by_organization_id / ListDatasetsByOrganizationID), and nothing replaces them. Both methods exist in the current SDKs (checked viam-python-sdk v0.85.2 and rdk v1.15.0), and custom-training-scripts.md still tells readers to "get the dataset ID" from the DATASETS tab or viam dataset list, so SDK-only users no longer have a documented way to enumerate datasets. Suggested restoration, in the page's existing snippet style:

Suggested change

	background, camera angle, and distance your machine uses.
	background, camera angle, and distance your machine uses.
	To list your organization's datasets and their IDs from code:
	{{< tabs >}}
	{{% tab name="Python" %}}
	```python
	async def main():
	viam_client = await connect()
	data_client = viam_client.data_client
	datasets = await data_client.list_datasets_by_organization_id(
	organization_id="YOUR-ORG-ID",
	)
	for ds in datasets:
	print(f"Dataset: {ds.name}, ID: {ds.id}")
	viam_client.close()
	```
	{{% /tab %}}
	{{% tab name="Go" %}}
	```go
	datasets, err := dataClient.ListDatasetsByOrganizationID(ctx, "YOUR-ORG-ID")
	if err != nil {
	logger.Fatal(err)
	}
	for _, ds := range datasets {
	fmt.Printf("Dataset: %s, ID: %s\n", ds.Name, ds.ID)
	}
	```
	{{% /tab %}}
	{{< /tabs >}}

If you'd rather not repeat it here, a one-line pointer to the data client API reference would also work. This section is also an odd home for it: the snippet is about finding IDs, not verifying quality, so the Create a dataset section might suit it better.

[Eliza Farley (elizafarley)]

Fixed in 277560c with the lighter option, placed in the Create a dataset section as you suggested: one line pointing to the DATASETS tab, viam dataset list, and ListDatasetsByOrganizationID in the data client API reference.

[Jeremy Rose (jeremyrose-viam)]

The old table in deploy-from-registry.md carried a note that GPU-capable ML model services (such as Triton on Jetson) can be configured to use either the CPU or the dedicated GPU at runtime. That note is gone from this PR, and the new sentence says "Nvidia GPU" without saying Triton is the Jetson option. Suggested wording restores both:

Suggested change

	To run a TensorFlow, PyTorch or ONNX model on an Nvidia GPU, configure the [`triton`](https://app.viam.com/module/viam/mlmodelservice-triton-jetpack) ML model service instead.
	To run a TensorFlow, PyTorch or ONNX model on an Nvidia GPU, such as a Jetson, configure the [`triton`](https://app.viam.com/module/viam/mlmodelservice-triton-jetpack) ML model service instead.
	You can configure `triton` to use either the CPU or the dedicated GPU at runtime.

[Eliza Farley (elizafarley)]

Fixed in 277560c: the sentence now names the Jetson and adds that triton can use either the CPU or the GPU at runtime.

[viambot]

It looks like the following files may have been renamed. Please ensure you set all needed aliases:

 rename docs/train/{annotate-images.md => annotate-data.md} (53%)
 rename docs/train/{sequence-dataset-format.md => dataset-formats.md} (45%)

[Eliza Farley (elizafarley)]

Re the test-local note on the CLI reference: fixed in 277560c. docs/cli/datasets-and-training.md now uses --dataset-root=. and --dataset-file=my-dataset/dataset.jsonl, and says to run it from the directory where viam dataset export ran.

[Eliza Farley (elizafarley)]

Docs review: Needs changes

This PR restructures Train ML models around the training loop. It adds Evaluate a model and Training dataset formats, and rewrites the built-in, custom, deploy, dataset and annotation pages. The content checks out against source. One release question is left: the evaluation UI and the new Run model menu are behind a feature flag that defaults to off, and the code can't tell whether it's on for all orgs.

CI: All required checks passing

Docs health: No regressions. Both new pages are scored, and no untouched page got worse. automate-annotation.md and create-a-dataset.md have small UI-score increases, which aren't shown on the dashboard.

Needs owner sign-off

Claim	Where	Owning team	Why unverified
Datasets show Run model > Evaluate model performance and an Evaluations page	docs/train/evaluate-a-model.md:81-96, overview.md:54-56, links from custom-training-scripts.md, retrain.md	Data / Machine Learning	app dataset-sidebar.svelte:198,735 and evaluations/+page.svelte:15-21 show these only when ENABLE_MODEL_EVALUATION is on. data/feature_models.go:359 sets FallbackValue: false, and the rollout state is stored outside the repo.
Auto-predictions start from Run model > Get auto-predictions	docs/train/automate-annotation.md:29	Data / Machine Learning	The same flag controls this. With it off, dataset-sidebar.svelte:716 shows a standalone Get auto-predictions button, which is what the page said before this PR. If the flag isn't on for every org, this step is wrong for users who don't have it.

If the flag isn't fully rolled out, hold the merge until it is, or keep the old auto-predictions step and mark evaluation as limited availability.

Nits

• docs/train/overview.md:11: updated: "2026-11-02", but this PR rewrote the page through 2026-11-06. Fix: bump it to the merge date.

Verified against source (14 claims, spot-checked on top of the PR's own verification list)

• GetRobotPart returns (*RobotPart, string, error) and RobotConfig is map[string]interface{}: viamrobotics/rdk app/app_client.go:120,1581
• UpdateRobotPart(ctx, id, name, robotConfig) has no last-known-update check in Go: rdk app/app_client.go:1762
• Python update_robot_part accepts last_known_update; RobotPart exposes robot_config and last_updated: viam-python-sdk src/viam/app/app_client.py:233-241,1584-1590
• test-local mounts the dataset root as the working directory: rdk cli/ml_training.go:1008
• test-local passes only --dataset_file: rdk cli/ml_training.go:1124
• Training containers are linux/x86_64 and run under Rosetta on ARM: rdk cli/ml_training.go:993-1002
• --dataset-root, --dataset-file, --custom-args, --container-id flags: rdk cli/ml_training.go:41-45
• --module-resource flag: rdk cli/app.go:131
• with-upload uses --model-type and always uploads as private: rdk cli/ml_training.go:34,115
• upload takes --type and --framework: rdk cli/ml_training.go:528-538
• --type=unspecified: rdk cli/ml_training.go:710
• Evaluation failure messages: app mlinference/batch_worker_common.go:61,69
• Metric colors (green ≥85%, yellow ≥70%, red below): app evaluations/evaluation-utils.ts:9-12
• ListDatasetsByOrganizationID anchor resolves on the data client page through dataset.md: docs/reference/apis/data-client.md:170

Automated review by Claude. Rerunning the review updates this comment.

[github-actions]

🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs'