1. RF-DETR Medium 模型概述
RF-DETR Medium 是基于 Transformer 架构的目标检测模型,由 RoboFlow 团队开发并开源。作为 DETR(Detection Transformer)系列模型的改进版本,它在保持端到端检测优势的同时,通过优化训练策略和模型结构,显著提升了检测精度和推理速度。
这个模型特别适合需要平衡精度和速度的场景,比如:
- 实时视频流中的多目标跟踪
- 工业质检中的缺陷检测
- 无人机航拍图像分析
- 智能零售中的商品识别
提示:RF-DETR 系列提供多种规模模型(Small/Medium/Large),Medium 版本在 640x640 输入分辨率下能达到 45 FPS 的推理速度,mAP 约 42.5,是性价比很高的选择。
2. 环境准备与安装
2.1 基础环境配置
推荐使用 Python 3.8-3.10 版本,过高版本可能导致依赖冲突。先创建并激活虚拟环境:
bash复制conda create -n rfdetr python=3.9 -y
conda activate rfdetr
2.2 安装核心依赖
RF-DETR 需要特定版本的 PyTorch 和 CUDA。根据你的显卡配置选择:
bash复制# CUDA 11.7 版本
pip install torch==2.0.1+cu117 torchvision==0.15.2+cu117 --extra-index-url https://download.pytorch.org/whl/cu117
# 或者 CPU 版本
pip install torch==2.0.1+cpu torchvision==0.15.2+cpu --extra-index-url https://download.pytorch.org/whl/cpu
然后安装 RF-DETR 包:
bash复制pip install rfdetr supervision
注意:supervision 是 RoboFlow 提供的标注工具库,版本需 ≥0.15.0。如果遇到 OpenCV 冲突,可以先安装 opencv-python-headless。
2.3 验证安装
运行以下代码检查环境是否正常:
python复制from rfdetr import RFDETRMedium
model = RFDETRMedium()
print(model.__class__.__name__) # 应输出 "RFDETRMedium"
3. 图像检测全流程解析
3.1 基础检测实现
原始示例代码已经展示了基本用法,我们来深入解析每个关键环节:
python复制import requests
import supervision as sv
from PIL import Image
from rfdetr import RFDETRMedium
from rfdetr.assets.coco_classes import COCO_CLASSES
# 模型初始化(首次运行会自动下载预训练权重)
model = RFDETRMedium() # 约 245MB 的权重文件
# 加载测试图片(这里使用 RoboFlow 提供的示例)
image = Image.open(requests.get("https://media.roboflow.com/dog.jpg", stream=True).raw)
# 执行预测(threshold 过滤低置信度检测框)
detections = model.predict(image, threshold=0.5)
# 生成标签文本
labels = [f"{COCO_CLASSES[class_id]}" for class_id in detections.class_id]
# 可视化标注
annotated_image = sv.BoxAnnotator().annotate(image, detections)
annotated_image = sv.LabelAnnotator().annotate(annotated_image, detections, labels)
# 显示结果(Jupyter 可直接显示,脚本需保存或调用系统查看器)
annotated_image.show()
3.2 关键参数调优
模型预测时有几个重要参数可以调整:
python复制detections = model.predict(
image,
threshold=0.5, # 置信度阈值 (0-1)
iou_threshold=0.45, # NMS 的 IoU 阈值
max_detections=300 # 最大检测数量
)
典型调优策略:
- 高精度场景:threshold=0.7, iou_threshold=0.3
- 实时场景:threshold=0.3, iou_threshold=0.6
- 密集小目标:max_detections=500
3.3 自定义视觉样式
通过 supervision 可以灵活调整标注样式:
python复制# 自定义框和标签样式
box_annotator = sv.BoxAnnotator(
thickness=2,
color=sv.Color(r=0, g=255, b=0) # 绿色边框
)
label_annotator = sv.LabelAnnotator(
text_color=sv.Color.WHITE,
text_scale=0.5,
text_thickness=1
)
annotated_image = box_annotator.annotate(image, detections)
annotated_image = label_annotator.annotate(annotated_image, detections, labels)
4. 视频流检测实战
4.1 基础视频处理
原始示例展示了视频文件处理,我们扩展更多实用场景:
python复制import cv2
import supervision as sv
from rfdetr import RFDETRMedium
model = RFDETRMedium()
# 支持多种视频源
video_source = 0 # 摄像头设备号
# video_source = "input.mp4" # 视频文件路径
# video_source = "rtsp://..." # 网络视频流
cap = cv2.VideoCapture(video_source)
if not cap.isOpened():
raise RuntimeError("无法打开视频源")
# 获取视频属性(用于保存输出)
fps = cap.get(cv2.CAP_PROP_FPS)
width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
# 创建视频写入器(如需保存)
# writer = cv2.VideoWriter('output.mp4',
# cv2.VideoWriter_fourcc(*'mp4v'),
# fps, (width, height))
while True:
ret, frame = cap.read()
if not ret:
break
# 转换颜色空间 BGR→RGB
frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
# 执行预测
detections = model.predict(frame_rgb, threshold=0.5)
# 标注
labels = [COCO_CLASSES[class_id] for class_id in detections.class_id]
annotated_frame = sv.BoxAnnotator().annotate(frame, detections)
annotated_frame = sv.LabelAnnotator().annotate(annotated_frame, detections, labels)
# 显示/保存
cv2.imshow("RF-DETR", annotated_frame)
# writer.write(annotated_frame)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
cap.release()
# writer.release()
cv2.destroyAllWindows()
4.2 性能优化技巧
视频检测需要特别注意性能:
-
帧采样策略:
python复制frame_skip = 2 # 每3帧处理1帧 frame_count = 0 while True: ret, frame = cap.read() frame_count += 1 if frame_count % frame_skip != 0: continue # ...处理逻辑... -
分辨率调整:
python复制new_width = 640 scale = new_width / width frame = cv2.resize(frame, (new_width, int(height * scale))) -
异步处理(高级用法):
python复制from threading import Thread class ProcessingThread(Thread): def __init__(self, frame): super().__init__() self.frame = frame self.result = None def run(self): self.result = model.predict(self.frame) # 在主循环中 processing = None if processing is None or not processing.is_alive(): processing = ProcessingThread(frame_rgb) processing.start()
5. 常见问题与解决方案
5.1 模型加载失败
问题现象:
- 首次运行时卡在下载权重
- 报错 SSL 证书错误
解决方案:
- 手动下载权重:
bash复制
wget https://github.com/roboflow-ai/rfdetr/releases/download/v1.6.0/rfdetr_medium.pth - 指定本地权重路径:
python复制model = RFDETRMedium(weights_path="path/to/rfdetr_medium.pth")
5.2 CUDA 内存不足
问题现象:
- 报错
CUDA out of memory
优化方案:
- 减小输入尺寸:
python复制image = image.resize((512, 512)) - 启用内存节省模式:
python复制model = RFDETRMedium(use_memory_efficient=True) - 使用 CPU 模式:
python复制model = RFDETRMedium(device="cpu")
5.3 检测结果不理想
典型场景:
- 小目标漏检
- 重叠目标识别错误
调优方法:
- 调整 NMS 参数:
python复制detections = model.predict(image, iou_threshold=0.3) - 后处理增强:
python复制# 使用 supervision 的过滤功能 detections = detections[detections.confidence > 0.6] - 自定义类别映射:
python复制# 只检测人、车等特定类别 CLASS_IDS = [0, 2, 5] # COCO 类别ID detections = detections[np.isin(detections.class_id, CLASS_IDS)]
6. 高级应用扩展
6.1 自定义数据集训练
虽然 RF-DETR Medium 提供了预训练权重,但针对特定场景可以微调:
- 准备 COCO 格式数据集
- 修改训练配置:
python复制from rfdetr import RFDETRTrainer trainer = RFDETRTrainer( model_size="medium", dataset_dir="your_dataset/", epochs=50, batch_size=8, learning_rate=1e-4 ) trainer.train() - 保存自定义权重:
python复制trainer.save("custom_weights.pth")
6.2 多模型集成
结合 RF-DETR 与其他模型提升效果:
python复制from rfdetr import RFDETRMedium
from yolov8 import YOLOv8 # 假设已安装
detr_model = RFDETRMedium()
yolo_model = YOLOv8()
# 融合两个模型的检测结果
def ensemble_predict(image):
detr_dets = detr_model.predict(image)
yolo_dets = yolo_model.predict(image)
# 简单的框融合策略
all_boxes = np.concatenate([detr_dets.xyxy, yolo_dets.xyxy])
all_scores = np.concatenate([detr_dets.confidence, yolo_dets.confidence])
# 使用 NMS 融合重复框
keep_indices = sv.detection.utils.non_max_suppression(
all_boxes, all_scores, iou_threshold=0.5
)
return sv.Detections(
xyxy=all_boxes[keep_indices],
confidence=all_scores[keep_indices],
class_id=np.zeros(len(keep_indices)) # 示例简化
)
6.3 部署优化
生产环境部署建议:
- ONNX 导出:
python复制torch.onnx.export( model, torch.randn(1, 3, 640, 640), "rfdetr_medium.onnx", opset_version=12 ) - TensorRT 加速:
bash复制
trtexec --onnx=rfdetr_medium.onnx \ --saveEngine=rfdetr_medium.trt \ --fp16 - API 服务化(使用 FastAPI):
python复制from fastapi import FastAPI, UploadFile import io app = FastAPI() model = RFDETRMedium() @app.post("/detect") async def detect(image: UploadFile): img_data = await image.read() img = Image.open(io.BytesIO(img_data)) detections = model.predict(img) return {"detections": detections.to_dict()}
在实际项目中,我发现 RF-DETR Medium 在保持较高精度的同时,内存占用比同精度级别的 YOLO 模型更低。特别是在处理长视频时,连续运行 2-3 小时也不会出现明显的内存增长。对于需要 7x24 小时运行的应用场景,建议配合定时重启机制(比如每处理 10000 帧后自动重启进程),这样可以有效避免长时间运行可能带来的微小内存泄漏问题。