마크다운으로 보기

RF-DETR

조밀 그리드 대신 고정된 객체 집합을 예측하는 detection transformer이므로 추론 시 NMS가 필요하지 않습니다. LibreYOLO는 네 가지 작업을 지원합니다.

작업
detection, instance segmentation, pose, oriented boxes
크기
n, s, m, l for detection and oriented boxes; n through xx for segmentation; x for pose
설치
pip install "libreyolo[rfdetr]"
지원 티어
플래그십, v1.0.0부터 지원. 기능을 여기에서 먼저 설계하고 GPU로 완전히 검증합니다.
업스트림
Roboflow의 RF-DETR, Apache-2.0. 논문, 소스
라이선스
코드 MIT, 가중치 Apache-2.0. 상업적 사용
LibreRFDETRs, 512 px 동영상 객체 탐지.

설치

RF-DETR에는 백본용 transformers를 설치하는 전용 extra가 필요합니다.

bash
pip install "libreyolo[rfdetr]"

이것이 없으면 Python이나 CLI에서 RF-DETR 체크포인트나 모델 이름을 불러올 때 이 설치 명령을 알려 주는 오류와 함께 멈춥니다.

예측

처음 사용할 때 Hugging Face에서 가중치를 다운로드해 로컬에 캐시합니다.

Python
from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreRFDETRs.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(box.cls, box.conf, box.xyxy)
CLI
libreyolo predict model=LibreRFDETRs.pt source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg save=True
동영상
from libreyolo import LibreYOLO model = LibreYOLO("LibreRFDETRs.pt") # 라이브러리가 받는 모든 소스: 파일, 폴더, URL, 웹캠 인덱스,# RTSP 스트림 또는 .streams 목록for result in model.predict("clip.mp4", stream=True, save=True):    print(len(result.boxes))

반환되는 Results 객체는 모든 계열이 반환하는 것과 같으므로 탐지기를 바꾸려면 한 줄만 변경하면 됩니다. conf와 max_det은 쿼리 선택을 필터링하며 조정할 NMS 단계가 없습니다. 소스, 스트리밍, 결과 처리는 예측을 참조합니다.

탐지, 분할, 회전 바운딩 박스 경로는 안티앨리어싱 없이 부동소수점 OpenCV 이중 선형 크기 조정을 사용하며, 자세 추정은 안티앨리어싱 크기 조정을 유지합니다. 직사각형 imgsz=(height, width)는 작업의 패치/윈도 그리드 조건을 충족해야 합니다. 체크포인트 목록에는 UI 탐지기도 포함됩니다. 이벤트 히스토그램은 기록된 입력 프로파일을 사용합니다.

변형

n부터 l까지 네 가지 탐지 크기와 하나의 구조를 공유하는 네 가지 작업이 있습니다. 분할, 자세 추정, 회전 박스는 다른 헤드와 함께 탐지 디코더를 재사용하므로 같은 인수를 받습니다. 분할에는 x와 xx가 추가되고, 자세 추정은 x 크기로만 제공됩니다. 크기별 매개변수 수는 비슷하며 주로 입력 해상도가 다릅니다.

체크포인트입력(px)mAP 50-95파라미터(M)
LibreRFDETRn38451.430.47
LibreRFDETRs51255.232.11
LibreRFDETRm57657.433.69
LibreRFDETRl70458.633.93

COCO val2017, 500 images. LibreYOLO 벤치마크 도구로 측정하고 Vision Analysis에 공개했습니다. 이곳에서 하드웨어와 런타임별 지연 시간을 비교하고 전체 실행 기록을 확인할 수 있습니다.

학습

네 작업 모두 공개된 체크포인트에서 학습을 시작합니다. pretrained=False는 대신 백본을 포함한 전체 네트워크를 다시 초기화하고 처음부터 학습합니다.

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreRFDETRs.pt")model.train(data="my-dataset.yaml", epochs=50, imgsz=512, batch=8, lr0=1e-4)
CLI
libreyolo train model=LibreRFDETRs.pt data=my-dataset.yaml \  epochs=50 imgsz=512 batch=8 lr0=1e-4
LoRA
from libreyolo import LibreYOLO model = LibreYOLO("LibreRFDETRs.pt")model.train(data="my-dataset.yaml", epochs=50, lora=True)
다중 GPU
libreyolo train model=LibreRFDETRs.pt data=my-dataset.yaml \  epochs=50 device=0,1 batch=-1

두 인수는 CNN 탐지기보다 더 중요합니다. transformer 탐지기는 YOLO 모델이 견디는 학습률에서 발산하므로 lr0를 1e-4 이하로 유지합니다. 변경할 이유가 없다면 imgsz를 체크포인트 기본 해상도로 유지합니다. 입력 크기는 백본 패치 크기와 창 개수의 곱으로 나누어떨어져야 합니다. LibreYOLO는 실행 전에 이를 검사하고 가장 가까운 유효 크기를 알려줍니다.

분할 파인튜닝은 분할 체크포인트에서 시작합니다. RF-DETR에는 탐지에서 분할로의 전이가 없기 때문입니다. libreyolo train model=LibreRFDETRn-seg.pt task=segment는 그 체크포인트를 불러오며, 탐지 체크포인트에 task=segment를 쓰면 오류와 함께 멈춥니다.

데이터셋, 증강, 다중 GPU, 로거는 학습을 참조합니다.

새 실행의 기본값은 output_dir=None이며, exist_ok=False에 따라 번호가 증가하는 runs/train/rfdetr_exp로 결정됩니다. 재개된 실행은 체크포인트의 실행 디렉터리에 계속 기록합니다. 다중 클래스 자세 데이터셋은 클래스 인덱스 또는 이름을 키로 하는 kpt_names를 사용하며, 빈 목록은 바운딩 박스만 있는 클래스를 나타냅니다. 예측은 키포인트를 kpt_shape에 맞게 패딩하며, 키포인트 mAP 적합도는 바운딩 박스만 있는 클래스를 평가하지 않습니다.

검증

val()은 학습에 사용한 형식의 데이터셋을 대상으로 측정한 mAP 50, mAP 50-95, mAP 75, COCO 평균 재현율을 포함하는 metrics/ 키 사전을 반환합니다.

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreRFDETRs.pt") # val()은 객체가 아닌 일반 dict를 반환합니다.metrics = model.val(data="my-dataset.yaml", imgsz=512) print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])print(metrics["metrics/mAP75"], metrics["metrics/AR100"])
CLI
libreyolo val model=LibreRFDETRs.pt data=my-dataset.yaml imgsz=512
COCO 기준 평가
# 번들 COCO yaml에는 내장 다운로드 스크립트가 있으므로 데이터셋이 이미# 로컬에 있지 않다면 명시적 권한이 필요합니다.libreyolo val model=LibreRFDETRn.pt data=coco.yaml imgsz=384 \  allow_download_scripts=True

내보내기

작업ONNXTorchScriptExecuTorchTensorRTOpenVINOPaddleMNNRKNNncnnTFLiteCoreMLCore AI
DetectionDetection to ONNX: 지원함Detection to TorchScript: 지원함Detection to ExecuTorch: 지원함Detection to TensorRT: 지원함. Runtime parity coverage lives in tests/e2e/test_tensorrt.py.Detection to OpenVINO: 지원함. Runtime parity coverage lives in tests/e2e/test_openvino.py.Detection to Paddle: 지원하지 않음Detection to MNN: 지원함Detection to RKNN: 지원하지 않음Detection to ncnn: 지원하지 않음Detection to TFLite: 지원하지 않음Detection to CoreML: 지원함. Conversion is available, but runtime parity requires a macOS runner.Detection to Core AI: 지원함
Instance segmentationInstance segmentation to ONNX: 지원함Instance segmentation to TorchScript: 지원함Instance segmentation to ExecuTorch: 지원함Instance segmentation to TensorRT: 지원함. A published Apache-2.0 trained segmentation checkpoint exports and reloads, but public top-k class membership changes.Instance segmentation to OpenVINO: 지원함. After Hungarian query alignment, the converted-runtime element match rate is 69.0%, below the validation bar.Instance segmentation to Paddle: 지원하지 않음Instance segmentation to MNN: 지원하지 않음Instance segmentation to RKNN: 지원하지 않음Instance segmentation to ncnn: 지원하지 않음Instance segmentation to TFLite: 지원하지 않음Instance segmentation to CoreML: 지원하지 않음Instance segmentation to Core AI: 지원하지 않음
PosePose to ONNX: 지원함Pose to TorchScript: 지원함Pose to ExecuTorch: 지원함Pose to TensorRT: 지원함. A published Apache-2.0 trained pose checkpoint exports and reloads, but matched public boxes fall to 0.704 IoU with 41.4-pixel coordinate drift.Pose to OpenVINO: 지원함. After Hungarian query alignment, the converted-runtime element match rate is 72.75%, below the validation bar.Pose to Paddle: 지원하지 않음Pose to MNN: 지원하지 않음Pose to RKNN: 지원하지 않음Pose to ncnn: 지원하지 않음Pose to TFLite: 지원하지 않음Pose to CoreML: 지원하지 않음Pose to Core AI: 지원하지 않음
Oriented boxesOriented boxes to ONNX: 지원함Oriented boxes to TorchScript: 지원함Oriented boxes to ExecuTorch: 지원함Oriented boxes to TensorRT: 지원함. A deterministic synthetic OBB fixture exports and reloads, but public top-k class membership changes.Oriented boxes to OpenVINO: 지원함. After Hungarian query alignment, the converted-runtime element match rate is 91.25%, below the validation bar.Oriented boxes to Paddle: 지원하지 않음Oriented boxes to MNN: 지원하지 않음Oriented boxes to RKNN: 지원하지 않음Oriented boxes to ncnn: 지원하지 않음Oriented boxes to TFLite: 지원하지 않음Oriented boxes to CoreML: 지원하지 않음Oriented boxes to Core AI: 지원하지 않음

내보낸 아티팩트는 파일 접미사에 따라 LibreYOLO()로 다시 불러오므로 .onnx 또는 .engine 파일은 체크포인트처럼 동작하며 동일한 Results를 반환합니다. LibreYOLO가 설치되지 않은 기본 런타임에서 그래프를 실행할 수도 있지만 이 경우 전처리와 후처리를 직접 작성해야 합니다.

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreRFDETRs.pt")model.export(format="onnx", imgsz=512)model.export(format="tensorrt", imgsz=512, half=True) # 모든 형식에서 받는 인수:##   format    "onnx" | "torchscript" | "executorch" | "tensorrt"#             | "openvino" | "paddle" | "mnn" | "rknn" | "ncnn"#             | "tflite" | "coreml" | "coreai".#             "engine"은 tensorrt, "litert"는 tflite의 별칭입니다.#   imgsz     int 또는 (height, width). 기본값은 체크포인트의 기본 해상도입니다.#   batch     int, 기본값 1.#   half      bool, FP16으로 내보냅니다. 기본값 False.#   int8      bool, INT8로 내보냅니다. 기본값 False. `data`가 필요합니다.#   data      int8 보정에 사용하는 데이터셋 YAML 경로입니다.#   fraction  float, 사용할 보정 집합 비율입니다. 기본값 1.0.#   dynamic   bool, 동적 축입니다. 기본값 True.#   simplify  bool, ONNX 그래프 단순화를 실행합니다. 기본값 True.#   opset     int, ONNX opset입니다. 미지정 시 계열별로 선택합니다.#   device    str, 추적할 장치입니다. 기본값은 모델 장치입니다.#   output_path  str, 기본값은 체크포인트에서 파생한 이름입니다.#   verbose   bool, 기본값 False.#   allow_download_scripts  bool, 기본값 False. 다운로드해야 하는 데이터셋#             YAML의 내장 Python 실행을 허용합니다.## 일부 형식은 RKNN 대상 플랫폼 같은 전용 인수를 추가로 받습니다.# 각 형식 페이지에서 이를 설명합니다.
CLI
libreyolo export model=LibreRFDETRs.pt format=onnx imgsz=512libreyolo export model=LibreRFDETRs.pt format=tensorrt imgsz=512 half=True
내보낸 파일 사용
from libreyolo import LibreYOLO, SAMPLE_IMAGE # 팩토리는 파일 접미사에 따라 라우팅하므로 내보낸 아티팩트도# 다른 체크포인트처럼 불러와 동일한 Results 객체를 반환합니다.model = LibreYOLO("LibreRFDETRs.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)
LibreYOLO 없이 실행
import numpy as npimport onnxruntime as ort # 그래프를 직접 실행하려면 전처리와 후처리를 직접 수행해야 합니다.# 연결하기 전에 시그니처를 확인합니다.session = ort.InferenceSession("weights/LibreRFDETRs.onnx")name = session.get_inputs()[0].nameoutputs = session.run(None, {name: np.zeros((1, 3, 512, 512), dtype=np.float32)}) for meta, array in zip(session.get_outputs(), outputs):    print(meta.name, array.shape)

ONNX 입력과 출력

텐서input float32 [batch, 3, height, width]
색상RGB
스케일링픽셀 / 255
정규화평균 [0.485,0.456,0.406], 표준편차 [0.229,0.224,0.225]
크기 조정custom, bilinear

The input tensor is named input, not images.

Square input only. Export rejects a non-square imgsz. The default size comes from the checkpoint and is stored in the imgsz metadata key: 384 for LibreRFDETRn, 312 for LibreRFDETRn-seg, 576 for LibreRFDETRx-pose.

A custom imgsz must be a multiple of patch size x windows: 32 for detection and OBB, 12 for segmentation n, 24 for the other segmentation sizes and for pose.

Stretch the whole image to width x height. There is no letterbox and no padding, so the aspect ratio is not kept.

Detection, segmentation and OBB: convert the 8-bit RGB image to float32 and divide by 255 first, then resize the float image with cv2.resize INTER_LINEAR (half-pixel centers, no antialiasing). Resizing the 8-bit image before dividing is close but moves scores by up to about 0.01.

Pose resizes differently: divide by 255 the same way, then resize the float image with antialiased bilinear, as torch.nn.functional.interpolate does with mode bilinear, align_corners False and antialias True. This is the filter of Pillow's BILINEAR, which widens by the shrink factor, but in float with no rounding to 8 bits. Per axis, let s = in_size / out_size and f = max(s, 1). Output pixel i has center c = (i + 0.5) * s. It reads source pixels j from int(c - f + 0.5) to int(c + f + 0.5) - 1, clipped to the image, each with weight max(0, 1 - |j + 0.5 - c| / f). Divide the weights by their sum.

The pose model is sensitive to this. On the test image, cv2.resize INTER_LINEAR or INTER_AREA adds 3 to 9 detections, and Pillow on the 8-bit image adds one and moves keypoints by more than 4 px.

Then subtract the mean and divide by the std per channel.

nms=True is not available for this family: export raises NotImplementedError.

Detection, 기본 내보내기
출력형태의미
dets[batch, queries, 4]Boxes as cx, cy, w, h, normalized 0 to 1 of the input. 300 queries.
labels[batch, queries, columns]Raw class logits per query, sigmoid not applied. The COCO checkpoints have 91 columns, where column k is COCO category id k. For other checkpoints column j is class j.

후처리

  1. Apply sigmoid to labels.
  2. Flatten the scores of one image to queries x columns and take the top k over all of them, with k equal to queries (300). For flat index i, the query is i // columns and the column is i % columns. One query can yield several classes.
  3. Keep the entries whose score is strictly above the confidence threshold (0.25 by default). There is no NMS.
  4. When labels has 91 columns and nc is 80 (the COCO checkpoints), the column is a COCO category id. Class i is the i-th id, counting from 0, in this list: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 27, 28, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 67, 70, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 84, 85, 86, 87, 88, 89, 90. Drop entries whose id is not in the list. With any other column count the column is the class.
  5. Convert the query's box to x1 = cx - w / 2, y1 = cy - h / 2, x2 = cx + w / 2, y2 = cy + h / 2.
  6. Map boxes back to the original image: multiply x by the original width and y by the original height. The input was stretched, so no pad offset applies. LibreYOLO does not clip these boxes.
Instance segmentation, 기본 내보내기
출력형태의미
dets[batch, queries, 4]Boxes as cx, cy, w, h, normalized 0 to 1 of the input. 100 queries for sizes n and s, 200 for m and l, 300 for x and xx.
labels[batch, queries, columns]Raw class logits per query, sigmoid not applied. 91 columns for the COCO checkpoints, where column k is COCO category id k.
masks[batch, queries, mask_h, mask_w]Raw mask logits per query over the whole input, at a quarter of the input size: 78 x 78 at 312 x 312.

후처리

  1. Select, threshold, map classes and decode boxes exactly as for detection, with k equal to queries.
  2. Take the mask of each kept query and resize the logits straight to the original image size with bilinear, half-pixel centers and no antialiasing (cv2.resize INTER_LINEAR on the float logits gives the same).
  3. A pixel is foreground when its resized logit is above 0.
Pose, 기본 내보내기
출력형태의미
dets[batch, queries, 4]Boxes as cx, cy, w, h, normalized 0 to 1 of the input. 100 queries.
labels[batch, queries, columns]Raw class logits per query, sigmoid not applied, with the keypoint class term already added inside the graph. Column 0 is an empty slot and column j + 1 is class j, so the person checkpoint has 2 columns.
keypoints[batch, queries, columns * num_keypoints, 8]One block of num_keypoints rows per label column, 2 x 17 = 34 rows here. Each row is x, y normalized 0 to 1 of the input, findable logit, visible logit, log_l11, l21, log_l22 and a class logit term. The num_keypoints_per_class metadata key ([0, 17]) says how many rows of each block are real keypoints.

후처리

  1. Apply sigmoid to labels. Flatten to queries x columns and take the top k over all of them, with k equal to queries (100). For flat index i, the query is i // columns and the column is i % columns.
  2. For each entry take its column's keypoint block: rows column * num_keypoints onward, of which the first num_keypoints_per_class[column] are used.
  3. Rescore each entry whose column has keypoints. Per used keypoint, with a = log_l11, b = l21, d = log_l22 and p = sigmoid(findable logit): sigma = exp(-2a) + exp(-2d) + b^2 * exp(-2a - 2d). Then trace = log(sum of p * sigma / sum of p) over the used keypoints, and score = score * exp(-0.2 * trace). Scores can go above 1.
  4. Drop entries whose column is 0. The class is column - 1.
  5. Keep the entries whose new score is strictly above the confidence threshold (0.25 by default). There is no NMS.
  6. Decode and map the box as for detection. LibreYOLO does not clip these boxes.
  7. Keypoint x is x * original width and keypoint y is y * original height. Keypoint confidence is sigmoid(findable logit). LibreYOLO does not use the visible logit.
Oriented boxes, 기본 내보내기
출력형태의미
dets[batch, queries, 4]Rotated boxes as cx, cy, w, h, normalized 0 to 1 of the input. 300 queries.
labels[batch, queries, columns]Raw class logits per query, sigmoid not applied. Column j is class j. The 6-class checkpoint has 7 columns: the last one is not a class and LibreYOLO does not drop it.
angles[batch, queries, 1]Rotation in radians from -pi / 2 to pi / 2, tanh already applied, measured on the square input. The width side points along (cos(angle), sin(angle)) with y pointing down.

후처리

  1. Select and threshold as for detection, with k equal to queries (300). The column is the class.
  2. The stretch scales x and y by different amounts, so map each box back through its corners. In normalized input units, with c = cos(angle) and s = sin(angle), the corners are (cx, cy) - u - v, + u - v, + u + v and - u + v, with u = (c * w / 2, s * w / 2) and v = (-s * h / 2, c * h / 2).
  3. Multiply corner x by the original width and corner y by the original height.
  4. Fit cv2.minAreaRect to the 4 corners and convert its angle to radians. Raise w and h to at least 1e-4. If h > w, swap them and add pi / 2 to the angle. Then wrap the angle to [-pi / 2, pi / 2) with angle = (angle + pi / 2) mod pi - pi / 2.
  5. The result is cx, cy, w, h, angle in original-image pixels, with w the long side.

직접 구현한 코드를 확인하려면 같은 파일을 LibreYOLO로 실행하세요. LibreYOLO("model.onnx").predict("image.jpg")가 기준 결과를 반환합니다. LibreYOLO 1.7.0으로 검증함.

체크포인트

이 계열에 공개된 모든 가중치 파일입니다.

파일입력(px)가중치 라이선스
Detection
LibreRFDETRl.pt704apache-2.0
LibreRFDETRm.pt576apache-2.0
LibreRFDETRn.pt384apache-2.0
LibreRFDETRs.pt512apache-2.0
LibreRFDETRm-ui.ptmit
Instance segmentation
LibreRFDETRn-seg.pt312apache-2.0
LibreRFDETRs-seg.pt384apache-2.0
LibreRFDETRm-seg.pt432apache-2.0
LibreRFDETRl-seg.pt504apache-2.0
LibreRFDETRx-seg.pt624apache-2.0
LibreRFDETRxx-seg.pt768apache-2.0
Pose
LibreRFDETRx-pose.pt576apache-2.0
Oriented boxes
LibreRFDETRn-obb.pt384cc-by-4.0
LibreRFDETRs-obb.pt512cc-by-4.0
LibreRFDETRm-obb.pt576cc-by-4.0
LibreRFDETRl-obb.pt704cc-by-4.0

위의 모든 파일은 현재 LibreYOLO 조직에 있으며 처음 사용할 때 내려받습니다.

라이선스

내려받는 특정 가중치의 Hugging Face 저장소에서 라이선스를 확인하십시오. LibreYOLO 조직의 모든 체크포인트에는 라이선스가 있으며 한 계열 안에서도 항상 같지는 않습니다. 해당 저장소가 신뢰할 수 있는 기준입니다. 아래 요약은 이 페이지를 마지막으로 검증했을 때 적용된 내용을 설명합니다.

관련 라이선스에 관한 설명이며 법률 자문이 아닙니다. 상업적으로 중요한 사안이라면 라이선스를 직접 읽고 별도의 법률 자문을 받으십시오.

원작
RF-DETR, Roboflow
업스트림 라이선스
Apache-2.0
업스트림 소스
github.com/roboflow/rf-detr
LibreYOLO 코드
MIT
가중치
Apache-2.0, huggingface.co/LibreYOLO에 다시 게시됨
해석
Apache-2.0 is a permissive license, so these weights can be used in commercial and closed-source products. It asks you to keep its license text and attribution notices with any copy of the weights you redistribute, and it grants a patent license. It places no obligation on your own application code, and weights you train yourself on your own data are yours.

인용

@inproceedings{robinson2026rfdetr,
  title     = {RF-DETR: Real-Time Detection Transformer},
  author    = {Robinson, Isaac and Robicheaux, Peter and Popov, Matvei and Ramanan, Deva and Peri, Neehar},
  booktitle = {International Conference on Learning Representations (ICLR)},
  year      = {2026},
  url       = {https://arxiv.org/abs/2511.09554}
}

github.com/roboflow/rf-detr#citation에 있는 저자의 인용 블록에서 복사했습니다.

LibreYOLO v1.6.0에서 검증되었습니다. 이 페이지의 지원 표, 체크포인트, 벤치마크 수치는 출시된 라이브러리와 공개된 가중치에서 생성되며 수동으로 작성되지 않습니다.