# Roboflow RF-DETR

## 概述

[RF-DETR](https://github.com/roboflow/rf-detr) 是 Roboflow 基于 Transformer 的目标检测和实例分割模型系列。在 Luxonis 设备上，当前的部署工作流程针对 RVC4。

此集成展示了从官方 RF-DETR 检查点到设备上推理的主要路径：

 * 将模型导出为 `ONNX`，
 * 将其打包为 [NN Archive](/software-v3/ai-inference/nn-archive.md)，
 * 使用 [HubAI](/software-v3/ai-inference/conversion/rvc-conversion/online/hubai.md) 将其转换为 RVC4 存档，以及
 * 使用 [DepthAI 节点](/software-v3/ai-inference/inference/depthai-nodes.md) 运行它。

链接的教程已通过 RF-DETR `1.7.1` 和 RF-DETR Nano 验证，但只要存在相关模块，相同的通用方法也可用于其他 RF-DETR 变体。

如果您只需要一个即用型模型，RF-DETR Nano 已在 [模型库](/software-v3/ai-inference/model-source/zoo.md) 中提供：[RF-DETR Nano
模型卡](https://models.luxonis.com/luxonis/rf-detr-nano/aim_XhzwWA4gawZ1a5g5ayirrb) 和 [RF-DETR Nano
实例分割模型卡](https://models.luxonis.com/luxonis/rf-detr-nano-instance-segmentation/aim_VWNN4569rNtANS9owXTJCJ)。
以下步骤主要关注检测模型，但相同的过程也可应用于实例分割变体，如链接的笔记本中所示。

## 用法

> **Note**
> 有关完整的端到端笔记本，请参阅 [RF-DETR RVC4 转换教程](https://github.com/luxonis/ai-tutorials/blob/main/conversion/rfdetr_rvc4_conversion.ipynb)。

您可以在 Colab 中运行导出、存档创建和 HubAI 转换步骤。最终的推理步骤必须在可以访问 RVC4 设备的机器上运行。

### 主要步骤

 1. 安装所需的包并在已知良好版本下克隆官方 `rf-detr` 存储库。
 2. 在导出之前应用一个小的运行时类注入，以便生成的 ONNX 图与 RVC4 转换流程兼容，而无需修改上游 RF-DETR 源代码树。
 3. 将模型导出为 `ONNX`，输入固定为 `384x384`，`opset` 为 `17`。
 4. 创建一个 [NN Archive](/software-v3/ai-inference/nn-archive.md)，描述模型输入、输出、预处理以及运行时使用的 `RFDETRParser` 头。
 5. 使用 [HubAI SDK](/cloud/hubai/model-registry/hubai-sdk.md) 将存档转换为 RVC4。
 6. 使用 [DepthAI 推理管道](/software-v3/ai-inference/inference.md) 运行生成的 `.rvc4.tar.xz` 存档。

### 导出兼容性更改

在导出之前，RF-DETR 需要一个小的兼容性补丁，以便生成的 ONNX 图可以干净地转换为 RVC4。

本教程通过类注入在运行时应用这些更改，而不是通过编辑上游 RF-DETR 源代码：

 * 窗口化 DINOv2 主干在图像窗口合并回完整的空间特征图时进行调整，
 * `MSDeformAttn` 模块在多尺度可变形注意力计算采样位置和注意力权重时进行调整。

这些更改不会重新训练模型，也不会修改权重。它们只是以更利于导出和转换的形式表达相同的计算。

### 导出到 ONNX

导出步骤从官方 RF-DETR 模型开始，应用运行时兼容性补丁，并写入 ONNX 模型：

```python
from rfdetr import RFDETRNano
from rvc4_class_injection import apply_rvc4_class_injection

model = RFDETRNano()
apply_rvc4_class_injection(model, require=True, verbose=True)

model.export(
    output_dir="onnx_model",
    shape=(384, 384),
    batch_size=1,
    dynamic_batch=False,
    opset_version=17,
    format="onnx",
)
```

### 创建 NN Archive

生成的存档应描述 `input` 张量、`dets` 和 `labels` 输出以及 `RFDETRParser` 头，以便可以自动配置运行时解析：

```python
from luxonis_ml.nn_archive.archive_generator import ArchiveGenerator

generator = ArchiveGenerator(
    archive_name="rfdetr-nano-onnx",
    save_path=".",
    cfg_dict=cfg_dict,
    executables_paths=["onnx_model/rfdetr-nano.onnx"],
)

archive_path = generator.make_archive()
```

有关存档配置的完整示例，包括预处理值和 COCO 类元数据，请参阅教程笔记本。

### 将 NN Archive 转换为 RVC4

ONNX NNArchive 准备好后，使用 HubAI 进行转换：

```python
import os
from hubai_sdk import HubAIClient

client = HubAIClient(api_key=os.environ["HUBAI_API_KEY"])

response = client.convert.RVC4(
    path="rfdetr-nano-onnx.tar.xz",
    name="rfdetr-nano-rvc4",
    quantization_mode="FP16_STANDARD",
    tool_version="2.41.0",
    output_dir=".",
)

print(response.downloaded_path)
```

这将生成可部署的 RVC4 存档，通常命名为 `rfdetr-nano-onnx.rvc4.tar.xz`。

### 小型推理示例

因为 [NN Archive](/software-v3/ai-inference/nn-archive.md) 已经声明了 `RFDETRParser`，所以
[`ParsingNeuralNetwork`](/software-v3/ai-inference/inference/depthai-nodes.md) 可以自动连接解析器：

```python
from pathlib import Path

import depthai as dai
from depthai_nodes.node.parsing_neural_network import ParsingNeuralNetwork

MODEL_PATH = Path("rfdetr-nano-onnx.rvc4.tar.xz")
nn_archive = dai.NNArchive(str(MODEL_PATH))
visualizer = dai.RemoteConnection(httpPort=8082)

with dai.Pipeline() as pipeline:
    cam = pipeline.create(dai.node.Camera).build(sensorFps=10)
    cam_out = cam.requestOutput(
        size=(384, 384),
        fps=10,
        type=dai.ImgFrame.Type.BGR888i,
    )

    nn_with_parser = pipeline.create(ParsingNeuralNetwork).build(
        input=cam_out,
        nn_source=nn_archive,
    )

    visualizer.addTopic(topicName="rgb", output=nn_with_parser.passthrough)
    visualizer.addTopic(topicName="detections", output=nn_with_parser.out)

    pipeline.start()
    visualizer.registerPipeline(pipeline)

    while pipeline.isRunning():
        pipeline.processTasks()
```

有关包含设备检查、模型验证和即用型本地可视化器流程的完整脚本，请使用上面链接的教程。
