feat(datasets): add weighted multi-source batch sampler

CHANGELOG.md

@@ -20,6 +20,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - Restored peak GPU memory (`max_mem` in MB) in the training progress bar, dropped during the PyTorch Lightning migration (PR #794) along with `rfdetr.engine`. Only covers `trainer.fit()` (training and its periodic in-training validation) — PTL's own progress-bar classes never call `get_metrics()` outside `trainer.state.fn == "fit"`, so a standalone `RFDETR.evaluate()` progress bar shows no metrics at all, not just `max_mem`, same as before this change. ([#974](https://github.com/roboflow/rf-detr/issues/974))
 
+- `WeightedMultiSourceBatchSampler` (`rfdetr.datasets.multi_source`) fixes the per-source composition of every training batch when training on a `ConcatDataset` of several datasets, so a small hand-labelled set is not drowned out by a large public one. Sources are recycled with reshuffling when they run out mid-epoch, epoch length can be driven by the largest or smallest source, and batches are sharded across DDP ranks. Opt-in: no existing training path changes. ([#1287](https://github.com/roboflow/rf-detr/pull/1287))
+
+### Documentation
+
+- Cookbook for mixing Roboflow Universe datasets with `WeightedMultiSourceBatchSampler` (`docs/cookbooks/multi-source-batch-sampler.ipynb`).
+
 ### Changed
 
 - `RFDETR.predict()` now converts PIL and uint8 NumPy inputs from HWC byte storage to contiguous CHW floating-point storage with one dtype/layout allocation and in-place scaling. The default source-image path reuses its already-materialized PIL array, while non-uint8 NumPy inputs retain torchvision's conversion path. The `[0, 1]` range-scan skip for those same two input types is unaffected: the fused conversion divides `uint8` storage by 255 and carries the same guarantee `to_tensor` did.

docs/cookbooks/NOTES.md

@@ -49,6 +49,7 @@ For newly added or updated notebooks, write markdown cells in plain, notebook-po
 
 | File                                | Card title                                      | Version |
 | ----------------------------------- | ----------------------------------------------- | ------- |
+| `multi-source-batch-sampler.ipynb`  | Mix Universe datasets with a fixed batch ratio  | v1.10.0 |
 | `custom-augmentations.ipynb`        | Custom Augmentations and Live Training Progress | v1.5.0  |
 | `custom-optimizer-scheduler.ipynb`  | Custom Optimizer and LR Scheduler               | v1.9.0  |
 | `export-coreml.ipynb`               | Export to Native CoreML & Run Inference         | v1.9.0  |

docs/cookbooks/cards.yaml

@@ -1,4 +1,10 @@
 cards:
+  - href: multi-source-batch-sampler/
+    name: "Mix Universe datasets with a fixed batch ratio"
+    labels: [TRAINING, PYTORCH LIGHTNING]
+    version: v1.10.0
+    author: Maryyyyyyyam142
+    description: "Train RF-DETR on several Roboflow Universe datasets at once, with WeightedMultiSourceBatchSampler holding a fixed per-source ratio in every batch."
   - href: train-coco2017/
     name: "Train RF-DETR Nano on COCO2017"
     labels: [TRAINING, COCO2017, PYTORCH LIGHTNING]