lightly-ai / lightly-ai/lightly-train
[DOC] Guide: evaluating pretraining/distillation on a custom detection dataset
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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