lightly-ai / lightly-ai/lightly-train

[DOC] Guide: evaluating pretraining/distillation on a custom detection dataset

Open
#924 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Python
Stars
1.7k
Forks
116
Avg merge
2d 21h
Merged PRs (30d)
6

Description

### 📍 Location of the issue

- File/Section: New guide — no existing page covers this. Closest existing material: the FAQ entry ["Can I train on labeled images?"](https://docs.lightly.ai/train/stable/faq.html#can-i-train-on-labeled-images) and the tutorial [Object Detection with Ultralytics' YOLOv26](https://docs.lightly.ai/train/stable/tutorials/yolo/index.html)
- Link (if applicable): https://docs.lightly.ai/train/stable/faq.html#can-i-train-on-labeled-images

### ✏️ Suggested Improvement

When evaluating pretraining or distillation on a custom dataset, several setup choices can make results hard to interpret: the initialization of each training run, the labeled subset used for fine-tuning, random seeds, training budget, and whether validation and test images are excluded from the unlabeled pretraining set.

The FAQ documents the validation-leakage rule, and the YOLOv26 tutorial demonstrates a from-scratch vs. pretrained comparison. I could not find a single consolidated guide describing an endorsed, reproducible protocol for running this comparison on a user's own detection dataset.

**Proposal (documentation only):** an "Evaluating pretraining on your own data" guide, extending an existing object-detection workflow and documenting maintainer-recommended guidance for:

- How to choose and clearly report the compared configurations and their initialization
- How to match training budgets and which hyperparameters to report
- How to create reproducible, seeded labeled subsets
- When multiple seeds are warranted for small labeled subsets
- How to keep validation and test images out of the unlabeled pretraining set
- A results-table template covering raw metrics and run configuration — I can populate it with a reference run on VOC if that would be useful

The guide would not prescribe that pretraining must outperform a baseline; the goal is to make comparisons reproducible and interpretable.

**Non-goals:**

- Training orchestration, sweep tooling, or AutoML
- ROI, annotation-cost, or pass/fail claims
- Sample selection, near-duplicate detection, or dataset curation
- New dataset parsers, package APIs, or product features

A small example script for persisted, seeded splits could be a separate discussion later if there is interest.

### 💬 Additional Notes

Related discussions: #71, #371, #433, #471, #922. Each asks a variant of this question and was answered individually in its thread — from #371: "The best way of truly knowing whether pretraining helps is to actually do the whole fine-tuning."

**Questions:**

1. Does the work mentioned in #71 ("we are actively working on this") already cover this, or is there internal documentation I should align with?
2. Which reference workflow should the guide build on — `train_object_detection`, the Ultralytics YOLO tutorial, or another supported workflow?
3. For the comparison baselines, should the guide cover random initialization, public COCO-pretrained initialization, or both?
4. Would a docs-only PR be useful now, or is this outside the current roadmap?

I will wait for direction before opening a PR.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the FAQ entry “Can I train on labeled images?” and the Ultralytics YOLOv26 tutorial, then review related issues #71, #371, #433, #471, and #922. First resolve which workflow and baselines maintainers endorse. Done means a documentation guide with reproducible setup guidance and a results-table template, without adding product features or orchestration.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
computer-vision, documentation, machine-learning
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.