wehub-resource-sync
16031aae96
CPU tests Workflow / Testing (ubuntu-latest, 3.12) (push) Failing after 1s
CPU tests Workflow / Testing (ubuntu-latest, 3.13) (push) Failing after 0s
Mypy Type Check / Type Check (push) Failing after 0s
Docs/Test WorkFlow / Test docs build (push) Failing after 1s
PR Conflict Labeler / labeling (push) Failing after 1s
Dependency resolution / Resolve [tflite] extra — Python 3.12 (push) Failing after 0s
Smoke Tests / try-all-models (ubuntu-latest, 3.10) (push) Failing after 0s
Smoke Tests / try-all-models (ubuntu-latest, 3.13) (push) Failing after 1s
CPU tests Workflow / build-pkg (push) Failing after 1s
CPU tests Workflow / Testing (ubuntu-latest, 3.10) (push) Failing after 0s
CPU tests Workflow / Testing (ubuntu-latest, 3.11) (push) Failing after 0s
Smoke Tests / try-all-models (macos-latest, 3.10) (push) Has been cancelled
Smoke Tests / try-all-models (macos-latest, 3.13) (push) Has been cancelled
Smoke Tests / try-all-models (windows-latest, 3.10) (push) Has been cancelled
Smoke Tests / try-all-models (windows-latest, 3.13) (push) Has been cancelled
CPU tests Workflow / Testing (macos-latest, 3.10) (push) Has been cancelled
CPU tests Workflow / Testing (macos-latest, 3.13) (push) Has been cancelled
CPU tests Workflow / Testing (windows-latest, 3.10) (push) Has been cancelled
CPU tests Workflow / Testing (windows-latest, 3.13) (push) Has been cancelled
CPU tests Workflow / testing-guardian (push) Has been cancelled
GPU tests Workflow / Testing (push) Has been cancelled
405 lines
14 KiB
Markdown
405 lines
14 KiB
Markdown
---
|
|
description: Per-version migration guide for RF-DETR. Covers breaking changes and deprecated APIs for each release series.
|
|
---
|
|
|
|
# Migration Guide
|
|
|
|
Read each section between your current version and your target — every section covers
|
|
only the delta between two adjacent releases.
|
|
|
|
```
|
|
1.4.x → 1.5 → 1.6 → 1.7 → 1.8
|
|
```
|
|
|
|
You can apply all changes in one go; working through sections one release at a time
|
|
and verifying between each step is optional but makes failures easier to isolate.
|
|
Deprecated APIs emit a `DeprecationWarning` until the version marked for removal.
|
|
See the [Changelog](../changelog.md) for the full list of changes in each release.
|
|
|
|
---
|
|
|
|
## Upgrade 1.8 → 1.9
|
|
|
|
### Planned for Removal in v1.9
|
|
|
|
The following APIs were deprecated in earlier releases and will be removed in v1.9. They still work in the current release (v1.8.x) but emit `DeprecationWarning`. Update your code before upgrading.
|
|
|
|
!!! warning "Planned for removal: `rfdetr.util.*` and `rfdetr.deploy.*` import paths"
|
|
|
|
Deprecated since v1.6. Use the canonical replacements listed in the [Upgrade 1.5 → 1.6](#upgrade-15--16) section.
|
|
|
|
```python
|
|
# These imports still work in v1.8 but emit DeprecationWarning; update before v1.9
|
|
from rfdetr.util.coco_classes import COCO_CLASSES # → rfdetr.assets.coco_classes
|
|
from rfdetr.util.misc import get_rank # → rfdetr.utilities
|
|
from rfdetr.deploy import export_onnx # → rfdetr.export.main
|
|
```
|
|
|
|
!!! warning "Planned for removal: `build_namespace(model_config, train_config)`"
|
|
|
|
Deprecated since v1.7. Use `build_model_from_config` and `build_criterion_from_config` instead.
|
|
|
|
!!! warning "Planned for removal: `load_pretrain_weights(nn_model, model_config, train_config)` with `train_config`"
|
|
|
|
Deprecated since v1.7. Drop the `train_config` positional argument.
|
|
|
|
!!! warning "Planned for removal: `start_epoch` kwarg in `train()`"
|
|
|
|
Deprecated since v1.7. PyTorch Lightning resumes automatically via `resume=`.
|
|
|
|
!!! warning "Planned for removal: `do_benchmark` kwarg in `train()`"
|
|
|
|
Deprecated since v1.7. Use the `rfdetr.export.benchmark` module instead.
|
|
|
|
!!! warning "Planned for removal: `callbacks` dict kwarg in `train()`"
|
|
|
|
Deprecated since v1.7. Pass PTL `Callback` objects directly via the Lightning API instead.
|
|
|
|
!!! warning "Planned for removal: misplaced config fields"
|
|
|
|
The following `TrainConfig` and `ModelConfig` fields moved to their correct config class in v1.7 and the deprecated compatibility shims will be removed in v1.9. Update any direct references:
|
|
|
|
| Field | Removed from | Use in |
|
|
| ------------------- | ------------- | ------------- |
|
|
| `group_detr` | `TrainConfig` | `ModelConfig` |
|
|
| `ia_bce_loss` | `TrainConfig` | `ModelConfig` |
|
|
| `segmentation_head` | `TrainConfig` | `ModelConfig` |
|
|
| `num_select` | `TrainConfig` | `ModelConfig` |
|
|
| `cls_loss_coef` | `ModelConfig` | `TrainConfig` |
|
|
|
|
---
|
|
|
|
## Upgrade 1.7 → 1.8
|
|
|
|
### Breaking changes
|
|
|
|
!!! note "Breaking in v1.8.2: default keypoint schema changed to active-first `[17]`"
|
|
|
|
New checkpoints created from v1.8.2 onwards use `class_id=0` for person. Legacy `[0, 17]` checkpoints
|
|
are still supported — RF-DETR auto-detects the schema from the checkpoint at load time.
|
|
|
|
If your post-processing code offsets class IDs by 1 (common for background-first models), update it:
|
|
|
|
```python
|
|
# Before (background-first [0, 17]: person was at class_id=1)
|
|
class_name = "person" if detection.class_id == 1 else "other"
|
|
|
|
# After (active-first [17]: person is at class_id=0)
|
|
class_name = "person" if detection.class_id == 0 else "other"
|
|
```
|
|
|
|
Use `detection.data["class_name"]` for schema-agnostic name resolution.
|
|
|
|
!!! warning "Breaking: `rfdetr.datasets.aug_config` renamed to `rfdetr.datasets.aug_configs`"
|
|
|
|
The augmentation config module was renamed (singular → plural). If you import from it directly:
|
|
|
|
```python
|
|
# Before
|
|
from rfdetr.datasets.aug_config import AUG_AGGRESSIVE
|
|
|
|
# After
|
|
from rfdetr.datasets.aug_configs import AUG_AGGRESSIVE
|
|
```
|
|
|
|
All preset constants (`AUG_AGGRESSIVE`, `AUG_CONSERVATIVE`, etc.) are unchanged.
|
|
|
|
!!! warning "Breaking: `supervision>=0.29.0` now required"
|
|
|
|
Required for `sv.KeyPoints` support. `pip install rfdetr==1.8.0` pulls this automatically.
|
|
If another dependency pins `supervision<0.29.0`, resolve the conflict manually.
|
|
|
|
!!! warning "Breaking: `pyDeprecate` constraint narrowed to `>=0.9,<0.10`"
|
|
|
|
Was `>=0.6,<0.8`. If another package pins an older version, resolve with:
|
|
|
|
```bash
|
|
pip install "rfdetr==1.8.0" "pyDeprecate>=0.9,<0.10"
|
|
```
|
|
|
|
---
|
|
|
|
## Upgrade 1.6 → 1.7
|
|
|
|
### Breaking changes
|
|
|
|
!!! warning "Breaking: `peft` removed from the default install"
|
|
|
|
LoRA fine-tuning now requires the `lora` extra. If you use LoRA adapters during
|
|
training, update your install command.
|
|
|
|
```bash
|
|
# Before
|
|
pip install rfdetr
|
|
|
|
# After
|
|
pip install 'rfdetr[lora]'
|
|
```
|
|
|
|
!!! warning "Breaking: `predict()` stores source image in `detections.metadata`"
|
|
|
|
**`predict()` stores the source image in `detections.metadata`, not `detections.data`.**
|
|
|
|
```python
|
|
# Before (1.6.4 and earlier)
|
|
source = detections.data["source_image"]
|
|
|
|
# After
|
|
source = detections.metadata["source_image"]
|
|
```
|
|
|
|
!!! warning "Breaking: `pyDeprecate` constraint changed to `>=0.6,<0.8`"
|
|
|
|
Was `>=0.3,<0.6`. If another package pins an older version, resolve with:
|
|
|
|
```bash
|
|
pip install "rfdetr==1.7.0" "pyDeprecate>=0.6,<0.8"
|
|
```
|
|
|
|
### Deprecated in v1.7 → Remove in v1.9
|
|
|
|
!!! note "Deprecated: `build_namespace()` split into two functions"
|
|
|
|
**`build_namespace(model_config, train_config)`** — use `build_model_from_config` or
|
|
`build_criterion_from_config` instead.
|
|
|
|
```python
|
|
# Before (deprecated)
|
|
from rfdetr.models import build_namespace
|
|
|
|
ns = build_namespace(model_config, train_config)
|
|
|
|
# After
|
|
from rfdetr.models import build_model_from_config, build_criterion_from_config
|
|
|
|
model = build_model_from_config(model_config)
|
|
criterion = build_criterion_from_config(model_config, train_config)
|
|
```
|
|
|
|
!!! note "Deprecated: `load_pretrain_weights()` no longer takes `train_config`"
|
|
|
|
**`load_pretrain_weights(nn_model, model_config, train_config)`** — drop the
|
|
`train_config` positional argument.
|
|
|
|
```python
|
|
# Before (deprecated)
|
|
from rfdetr.models import load_pretrain_weights
|
|
|
|
load_pretrain_weights(nn_model, model_config, train_config)
|
|
|
|
# After
|
|
from rfdetr.models import load_pretrain_weights
|
|
|
|
load_pretrain_weights(nn_model, model_config)
|
|
```
|
|
|
|
!!! note "Deprecated: config fields moved between `ModelConfig` and `TrainConfig`"
|
|
|
|
**Config fields placed in the wrong config object.** Move them as shown:
|
|
|
|
| Field | Was in | Move to |
|
|
| ------------------- | ------------- | ------------- |
|
|
| `group_detr` | `TrainConfig` | `ModelConfig` |
|
|
| `ia_bce_loss` | `TrainConfig` | `ModelConfig` |
|
|
| `segmentation_head` | `TrainConfig` | `ModelConfig` |
|
|
| `num_select` | `TrainConfig` | `ModelConfig` |
|
|
| `cls_loss_coef` | `ModelConfig` | `TrainConfig` |
|
|
|
|
```python
|
|
# Before (deprecated)
|
|
train_config = TrainConfig(group_detr=13, cls_loss_coef=2.0)
|
|
|
|
# After
|
|
model_config = ModelConfig(group_detr=13)
|
|
train_config = TrainConfig(cls_loss_coef=2.0)
|
|
```
|
|
|
|
### Deprecated in v1.7 → Remove in v2.0
|
|
|
|
!!! note "Deprecated: `RFDETRBase` replaced by size-specific classes"
|
|
|
|
**`RFDETRBase`** defaulted to the small variant and is replaced by size-specific
|
|
classes. Choose the variant that matches your previous model size. If you used
|
|
`RFDETRBase()` without arguments, switch to `RFDETRSmall()`.
|
|
|
|
```python
|
|
# Before (deprecated)
|
|
from rfdetr import RFDETRBase
|
|
|
|
model = RFDETRBase()
|
|
|
|
# After — pick one
|
|
from rfdetr import RFDETRNano, RFDETRSmall, RFDETRMedium, RFDETRLarge
|
|
|
|
model = RFDETRSmall()
|
|
```
|
|
|
|
!!! note "Deprecated: `RFDETRSegPreview` replaced by size-specific segmentation classes"
|
|
|
|
**`RFDETRSegPreview`** defaulted to the small variant and is replaced by size-specific
|
|
segmentation classes. If you used `RFDETRSegPreview()` without arguments, switch to
|
|
`RFDETRSegSmall()`.
|
|
|
|
```python
|
|
# Before (deprecated)
|
|
from rfdetr import RFDETRSegPreview
|
|
|
|
model = RFDETRSegPreview()
|
|
|
|
# After — pick one
|
|
from rfdetr import RFDETRSegNano, RFDETRSegSmall, RFDETRSegMedium, RFDETRSegLarge
|
|
|
|
model = RFDETRSegSmall()
|
|
```
|
|
|
|
---
|
|
|
|
## Upgrade 1.5 → 1.6
|
|
|
|
### Breaking changes
|
|
|
|
!!! warning "Breaking: `transformers` minimum version raised to `>=5.1.0`"
|
|
|
|
**`transformers` minimum version raised to `>=5.1.0,<6.0.0`.**
|
|
|
|
Projects pinned to `transformers<5.0.0` must upgrade. If upgrading is not possible,
|
|
pin `rfdetr<1.6.0`.
|
|
|
|
```bash
|
|
pip install 'transformers>=5.1.0,<6.0.0'
|
|
```
|
|
|
|
!!! warning "Breaking: PyPI extras renamed"
|
|
|
|
**PyPI extras renamed.**
|
|
|
|
Update your `pip install` commands and `requirements*.txt` files.
|
|
|
|
| Old extra | New extra |
|
|
| -------------------- | ----------------- |
|
|
| `rfdetr[metrics]` | `rfdetr[loggers]` |
|
|
| `rfdetr[onnxexport]` | `rfdetr[onnx]` |
|
|
|
|
```bash
|
|
# Before
|
|
pip install 'rfdetr[metrics]'
|
|
pip install 'rfdetr[onnxexport]'
|
|
|
|
# After
|
|
pip install 'rfdetr[loggers]'
|
|
pip install 'rfdetr[onnx]'
|
|
```
|
|
|
|
!!! warning "Breaking: `draw_synthetic_shape()` now returns a tuple"
|
|
|
|
**`draw_synthetic_shape()` now returns `(image, polygon)` instead of `image`.**
|
|
|
|
Update every call site that unpacks only the image.
|
|
|
|
```python
|
|
# Before
|
|
img = draw_synthetic_shape(...)
|
|
|
|
# After
|
|
img, polygon = draw_synthetic_shape(...)
|
|
```
|
|
|
|
### Deprecated in v1.6 → Removed in v1.8
|
|
|
|
!!! note "Deprecated: `simplify` and `force` arguments in `RFDETR.export()`"
|
|
|
|
**`RFDETR.export(..., simplify=..., force=...)`** — both arguments are no-ops.
|
|
Remove them from your calls.
|
|
|
|
```python
|
|
# Before (deprecated)
|
|
model.export("model.onnx", simplify=True, force=True)
|
|
|
|
# After
|
|
model.export("model.onnx")
|
|
```
|
|
|
|
### Deprecated in v1.6 → Remove in v1.9
|
|
|
|
!!! note "Deprecated: `rfdetr.util.*` and `rfdetr.deploy.*` import paths"
|
|
|
|
Backward-compatibility shims are still active but emit `DeprecationWarning` on import.
|
|
Replace with the canonical paths listed in the table below.
|
|
|
|
| Deprecated module | Canonical replacement |
|
|
| --------------------------------- | ---------------------------------- |
|
|
| `rfdetr.util.coco_classes` | `rfdetr.assets.coco_classes` |
|
|
| `rfdetr.util.misc` | `rfdetr.utilities` |
|
|
| `rfdetr.util.logger` | `rfdetr.utilities.logger` |
|
|
| `rfdetr.util.box_ops` | `rfdetr.utilities.box_ops` |
|
|
| `rfdetr.util.files` | `rfdetr.utilities.files` |
|
|
| `rfdetr.util.package` | `rfdetr.utilities.package` |
|
|
| `rfdetr.util.get_param_dicts` | `rfdetr.training.param_groups` |
|
|
| `rfdetr.util.drop_scheduler` | `rfdetr.training.drop_schedule` |
|
|
| `rfdetr.util.visualize` | `rfdetr.visualize.data` |
|
|
| `rfdetr.deploy` | `rfdetr.export` |
|
|
| `rfdetr.models.segmentation_head` | `rfdetr.models.heads.segmentation` |
|
|
|
|
**Examples:**
|
|
|
|
```python
|
|
# Before (deprecated)
|
|
from rfdetr.util.coco_classes import COCO_CLASSES
|
|
from rfdetr.util.misc import get_rank, get_world_size, is_main_process, save_on_master
|
|
from rfdetr.util.logger import get_logger
|
|
from rfdetr.util.box_ops import box_cxcywh_to_xyxy, generalized_box_iou
|
|
from rfdetr.util.get_param_dicts import get_param_dict
|
|
from rfdetr.util.drop_scheduler import drop_scheduler
|
|
from rfdetr.util.visualize import save_gt_predictions_visualization
|
|
from rfdetr.deploy import export_onnx
|
|
from rfdetr.models.segmentation_head import SegmentationHead
|
|
|
|
# After
|
|
from rfdetr.assets.coco_classes import COCO_CLASSES
|
|
from rfdetr.utilities.distributed import get_rank, get_world_size, is_main_process, save_on_master
|
|
from rfdetr.utilities.logger import get_logger
|
|
from rfdetr.utilities.box_ops import box_cxcywh_to_xyxy, generalized_box_iou
|
|
from rfdetr.training.param_groups import get_param_dict
|
|
from rfdetr.training.drop_schedule import drop_scheduler
|
|
from rfdetr.visualize.data import save_gt_predictions_visualization
|
|
from rfdetr.export.main import export_onnx
|
|
from rfdetr.models.heads.segmentation import SegmentationHead
|
|
```
|
|
|
|
---
|
|
|
|
## Upgrade 1.4 → 1.5
|
|
|
|
### Breaking changes
|
|
|
|
!!! warning "Breaking: `ModelConfig` rejects unknown keyword arguments"
|
|
|
|
**`ModelConfig` now raises `ValidationError` on unknown keyword arguments.**
|
|
|
|
Previously, unrecognised fields were silently ignored. Remove or rename any
|
|
unrecognised keys you pass to `ModelConfig(...)`.
|
|
|
|
```python
|
|
# Before — silently accepted
|
|
config = ModelConfig(unknown_field=True)
|
|
|
|
# Now raises ValidationError — remove the unknown key
|
|
config = ModelConfig()
|
|
```
|
|
|
|
### Deprecated in v1.5 → Removed in v1.7
|
|
|
|
!!! note "Deprecated: `OPEN_SOURCE_MODELS` replaced by `ModelWeights` enum"
|
|
|
|
**`OPEN_SOURCE_MODELS` constant** — use the `ModelWeights` enum instead. A
|
|
`DeprecationWarning` is emitted on access. See the
|
|
[API reference](../reference/rfdetr.md) for available enum values.
|
|
|
|
```python
|
|
# Before (deprecated)
|
|
from rfdetr import OPEN_SOURCE_MODELS
|
|
|
|
# After
|
|
from rfdetr.assets.model_weights import ModelWeights
|
|
```
|