> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/models/ko/supported-models/rf-detr.md).

# RF-DETR

RF-DETR은 Roboflow의 실시간 객체 탐지 및 인스턴스 세그멘테이션 모델이며, 키포인트 탐지와 시맨틱 세그멘테이션 변형도 제공합니다. Roboflow에서 학습하고, Serverless C를 통해 실행하세요

## RF-DETR 객체 감지

RF-DETR은 Roboflow의 트랜스포머 기반 실시간 감지 모델입니다. COCO로 사전 학습된 객체 감지 체크포인트를 사용해 다음을 통해 추론을 실행하거나 [서버리스 클라우드 API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api)를 사용하거나 [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted).

### RF-DETR 객체 감지 API

아래 단계에서는 RF-DETR을 다음을 통해 실행하고 [서버리스 클라우드 API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api) 를 사용해 결과를 시각화합니다: [supervision](https://supervision.roboflow.com/).

{% stepper %}
{% step %}
**API 키 가져오기**

Roboflow 계정을 만들고 [Roboflow API 설정 페이지](https://app.roboflow.com/settings/api) 에서 키를 찾아 셸에서 사용할 수 있도록 설정합니다:

```bash
export ROBOFLOW_API_KEY="your-key-here"
```

{% endstep %}

{% step %}
**종속 항목 설치**

다음 두 패키지는 모델을 호출하고 결과를 그리는 데 사용됩니다:

```bash
pip install -U inference-sdk supervision
```

{% endstep %}

{% step %}
**모델 실행**

샘플 이미지에서 `rfdetr-small` 을 실행하고 상자와 레이블을 표시합니다:

```python
import os
import cv2
import supervision as sv
from inference_sdk import InferenceHTTPClient, InferenceConfiguration

image_url = "https://media.roboflow.com/quickstart/traffic.jpg"
image = sv.load_image_from_url(image_url)

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key=os.environ["ROBOFLOW_API_KEY"],
).configure(InferenceConfiguration(api_key_transport="header"))
result = client.infer(image, model_id="rfdetr-small")

detections = sv.Detections.from_inference(result)

annotated = sv.BoxAnnotator().annotate(image.copy(), detections)
annotated = sv.LabelAnnotator().annotate(annotated, detections)

cv2.imwrite("traffic-annotated.png", annotated)
```

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-ccf613f155ad9e3e50d2520e5d45bbd68dff5bde%2Frf-detr-detection.webp?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="info" %}
설정 `api_url` 을 배포 대상에 맞게 지정합니다:

* `https://serverless.roboflow.com` 는 서버리스 클라우드 API에 사용합니다.
* `http://localhost:9001` 은 로컬 [Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 서버에 사용합니다.
* 비공개 엔드포인트에는 [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) URL을 사용합니다.
  {% endhint %}

### RF-DETR 객체 감지 모델 및 벤치마크

추론을 실행할 때 다음 별칭 중 하나를 `model_id` 로 전달하세요. SDK는 각 별칭을 해당하는 Roboflow 프로젝트 버전으로 변환합니다.

<table data-search="false"><thead><tr><th>별칭</th><th>입력 크기</th><th>mAP50-95</th><th>ONNX 지연 시간(ms)*</th><th>TensorRT FP16(ms)*</th></tr></thead><tbody><tr><td><code>rfdetr-nano</code></td><td>384x384</td><td>48.4</td><td>9.7</td><td>6.2</td></tr><tr><td><code>rfdetr-small</code></td><td>512x512</td><td>53.0</td><td>12.9</td><td>8.3</td></tr><tr><td><code>rfdetr-medium</code></td><td>576x576</td><td>54.7</td><td>16.3</td><td>9.5</td></tr><tr><td><code>rfdetr-large</code></td><td>704x704</td><td>56.5</td><td>25.6</td><td>11.6</td></tr><tr><td><code>rfdetr-xlarge</code></td><td>700x700</td><td>58.6</td><td>41.6</td><td>14.9</td></tr><tr><td><code>rfdetr-2xlarge</code></td><td>880x880</td><td>60.1</td><td>53.4</td><td>21.7</td></tr></tbody></table>

## RF-DETR 인스턴스 분할

RF-DETR은 박스와 함께 마스크를 예측하는 인스턴스 분할 체크포인트도 제공합니다. 이를 실행하려면 [서버리스 클라우드 API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api)를 사용하거나, [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted).

### RF-DETR 인스턴스 분할 API

위에 나온 대로 API 키를 설정하고 종속 항목을 설치한 다음, 분할 체크포인트를 실행하고 마스크를 그리세요.

```python
import os
import cv2
import supervision as sv
from inference_sdk import InferenceHTTPClient

image_url = "https://media.roboflow.com/quickstart/traffic.jpg"
image = sv.load_image_from_url(image_url)

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key=os.environ["ROBOFLOW_API_KEY"],
)
result = client.infer(image, model_id="rfdetr-seg-preview")

detections = sv.Detections.from_inference(result)

annotated = sv.MaskAnnotator().annotate(image.copy(), detections)
annotated = sv.LabelAnnotator().annotate(annotated, detections)

cv2.imwrite("traffic-annotated.png", annotated)
```

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-ef481717e6be56837c022e17751f42458d9f288d%2Frf-detr-segmentation.webp?alt=media" alt=""><figcaption></figcaption></figure>

### RF-DETR 인스턴스 분할 모델 및 벤치마크

추론을 실행할 때 다음 별칭 중 하나를 `model_id` 로 전달하세요. SDK는 각 별칭을 해당하는 Roboflow 프로젝트 버전으로 변환합니다. 수치는 COCO val에서 측정한 마스크 mAP입니다. `val`.

<table data-search="false"><thead><tr><th>별칭</th><th>입력 크기</th><th>마스크 mAP50-95</th><th>ONNX 지연 시간(ms)*</th><th>TensorRT FP16(ms)*</th></tr></thead><tbody><tr><td><code>rfdetr-seg-nano</code></td><td>312x312</td><td>40.3</td><td>15.8</td><td>10.5</td></tr><tr><td><code>rfdetr-seg-small</code></td><td>384x384</td><td>43.1</td><td>19.3</td><td>11.9</td></tr><tr><td><code>rfdetr-seg-medium</code></td><td>432x432</td><td>45.3</td><td>23.9</td><td>14.1</td></tr><tr><td><code>rfdetr-seg-large</code></td><td>504x504</td><td>47.1</td><td>30.1</td><td>15.4</td></tr><tr><td><code>rfdetr-seg-xlarge</code></td><td>624x624</td><td>48.8</td><td>51.2</td><td>19.1</td></tr><tr><td><code>rfdetr-seg-2xlarge</code></td><td>768x768</td><td>49.9</td><td>89.6</td><td>25.6</td></tr></tbody></table>

## RF-DETR 시맨틱 분할

RF-DETR 시맨틱 분할은 각 픽셀에 클래스를 할당합니다. 같은 클래스에 속하는 영역은 개별 객체로 나뉘지 않고 같은 레이블을 공유합니다. 사전 학습된 체크포인트는 ADE20K의 150개 장면 클래스(예: 하늘, 건물, 도로, 자동차, 사람)를 포함합니다. 이를 실행하려면 [서버리스 클라우드 API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api)또는 다음을 사용해 자체 호스팅할 수 있습니다. [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted).

### RF-DETR 시맨틱 세그멘테이션 API

위에 나온 대로 API 키를 설정하고 종속 항목을 설치한 다음(supervision 0.32.0 이상), 사전 학습된 체크포인트를 실행하고 클래스에 주석을 그립니다.

```python
import os

import cv2
import supervision as sv
from inference_sdk import InferenceHTTPClient, InferenceConfiguration

image_url = "https://media.roboflow.com/docs/mountain-lake-boats.jpg"
image = sv.load_image_from_url(image_url)

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key=os.environ["ROBOFLOW_API_KEY"],
).configure(InferenceConfiguration(
    api_key_transport="header",
    client_downsizing_disabled=True,
))
result = client.infer(image, model_id="rfdetr-pretrains/rfdetr-sem-large-ade20k")

detections = sv.Detections.from_inference(result)

palette = sv.ColorPalette.from_hex([
    "#22C55E", "#38BDF8", "#8B5CF6", "#F59E0B", "#EC4899",
    "#EF4444", "#2563EB", "#14B8A6", "#A3E635", "#FDE047",
])
annotated = sv.MaskAnnotator(
    color=palette, opacity=0.35, color_lookup=sv.ColorLookup.INDEX
).annotate(image.copy(), detections)
annotated = sv.PolygonAnnotator(color=sv.Color.WHITE, thickness=2).annotate(
    annotated, detections
)
annotated = sv.LabelAnnotator(
    color=palette,
    color_lookup=sv.ColorLookup.INDEX,
    text_position=sv.Position.CENTER_OF_MASS,
    text_scale=0.8,
    smart_position=True,
).annotate(annotated, detections)

cv2.imwrite("lake-annotated.png", annotated)
print(detections.data["class_name"])
```

`sv.Detections.from_inference` 는 결과의 각 클래스를 해당 클래스의 모든 픽셀을 덮는 하나의 탐지 항목으로 변환하므로, 어떤 마스크 어노테이터로든 그릴 수 있습니다. 클래스 이름은 결과의 `class_map`에서 가져오며, 클래스 ID 0(배경)은 제외됩니다. 마스크가 입력 이미지 크기와 일치하도록 클라이언트 측 크기 축소를 비활성화하세요.

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-afa78b6bde2a63ba07fb99e000a029cf0fb7c00e%2Frf-detr-semantic-segmentation.webp?alt=media" alt="Wooden boats on a mountain lake with RF-DETR semantic segmentation predictions: water, boats, a pier, trees, and rocks each in their own color and labeled"><figcaption><p>위 예시에서 출력된 사전 학습 RF-DETR Large ADE20K 결과. 사진: <a href="https://www.pexels.com/photo/wooden-boat-and-a-scenic-view-of-a-lake-and-mountains-14211208/">Christian Thöni</a>, <a href="https://www.pexels.com/license/">Pexels 라이선스</a>. 자른 이미지.</p></figcaption></figure>

### RF-DETR 시맨틱 세그멘테이션 모델 및 학습

추론을 실행할 때 다음 모델 ID 중 하나를 `model_id` 로 전달합니다. 각 모델은 ADE20K로 사전 학습되었습니다.

<table data-search="false"><thead><tr><th>모델 ID</th><th>입력 크기</th></tr></thead><tbody><tr><td><code>rfdetr-pretrains/rfdetr-sem-nano-ade20k</code></td><td>312x312</td></tr><tr><td><code>rfdetr-pretrains/rfdetr-sem-small-ade20k</code></td><td>384x384</td></tr><tr><td><code>rfdetr-pretrains/rfdetr-sem-medium-ade20k</code></td><td>432x432</td></tr><tr><td><code>rfdetr-pretrains/rfdetr-sem-large-ade20k</code></td><td>500x500</td></tr><tr><td><code>rfdetr-pretrains/rfdetr-sem-xlarge-ade20k</code></td><td>560x560</td></tr><tr><td><code>rfdetr-pretrains/rfdetr-sem-2xlarge-ade20k</code></td><td>880x880</td></tr></tbody></table>

직접 정의한 클래스를 세그멘테이션하려면 [시맨틱 세그멘테이션 프로젝트](https://docs.roboflow.com/models/ko/supported-tasks/semantic-segmentation.md#fine-tuning-a-semantic-segmentation-model)를 만든 다음, RF-DETR과 크기를 선택하세요. [사용자 지정 학습](https://docs.roboflow.com/models/ko/train/train-a-model.md#web-app). 또한 [신경망 아키텍처 탐색](https://docs.roboflow.com/models/ko/train/neural-architecture-search.md) 을 사용해 정확도와 지연 시간 요구 사항에 맞는 모델을 비교할 수 있습니다. 위 표의 박스 또는 마스크 mAP 대신 [평균 교집합 대비 합집합(mIoU)](https://docs.roboflow.com/models/ko/evaluate/evaluate-trained-models.md)으로 시맨틱 분할 정확도를 평가하세요.

## RF-DETR 키포인트 감지

RF-DETR 키포인트 감지는 COCO 사람 키포인트 데이터로 사전 학습된 프리뷰 체크포인트입니다. 다음을 통해 실행하거나 [서버리스 클라우드 API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api)를 사용하거나, 다음을 사용해 자체 호스팅할 수 있습니다. [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted).

{% hint style="info" %}
이 체크포인트는 프리뷰 버전입니다. 이후 릴리스에서 정확도와 출력 형식이 변경될 수 있습니다.
{% endhint %}

### RF-DETR 키포인트 감지 API

위 안내에 따라 API 키를 설정하고 종속 항목을 설치한 다음, `rfdetr-keypoint-preview` 를 실행해 키포인트를 표시합니다:

```python
import os
import cv2
import numpy as np
import supervision as sv
from inference_sdk import InferenceHTTPClient

COCO_KEYPOINTS = [
    "nose", "left_eye", "right_eye", "left_ear", "right_ear",
    "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
    "left_wrist", "right_wrist", "left_hip", "right_hip",
    "left_knee", "right_knee", "left_ankle", "right_ankle",
]

image_url = "https://media.roboflow.com/notebooks/examples/person-walking.png"
image = sv.load_image_from_url(image_url)

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key=os.environ["ROBOFLOW_API_KEY"],
)
result = client.infer(image, model_id="rfdetr-keypoint-preview")

# 각 예측에는 모델이 확인할 수 있는 키포인트만 나열되므로, 해당 키포인트를
# 스켈레톤이 요구하는 COCO 슬롯 17개에 배치하고, 누락된 키포인트는 보이지 않음으로 표시합니다.
xy, visible = [], []
for prediction in result["predictions"]:
    found = {point["class"]: (point["x"], point["y"]) for point in prediction["keypoints"]}
    xy.append([found.get(name, (0, 0)) for name in COCO_KEYPOINTS])
    visible.append([name in found for name in COCO_KEYPOINTS])

key_points = sv.KeyPoints(xy=np.array(xy, dtype=np.float32), visible=np.array(visible))

annotated = sv.EdgeAnnotator(color=sv.Color.GREEN, thickness=3).annotate(image.copy(), key_points)
annotated = sv.VertexAnnotator(color=sv.Color.RED, radius=5).annotate(annotated, key_points)
cv2.imwrite("person-walking-annotated.png", annotated)
```

<figure><img src="https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-58cd1b0b1df35e71787197ce73cd5294b67a9a74%2Frf-detr-keypoint.webp?alt=media" alt=""><figcaption></figcaption></figure>

### RF-DETR 키포인트 감지 모델 및 벤치마크

추론을 실행할 때 별칭을 `model_id` 로 전달하세요. 정확도는 COCO `val` 에서 표준 COCO 키포인트 지표인 객체 키포인트 유사도(OKS)로 측정한 AP50-95입니다. 따라서 위의 박스 및 마스크 mAP와 비교할 수 없습니다.

<table data-search="false"><thead><tr><th>별칭</th><th>입력 크기</th><th>키포인트 AP50-95</th><th>매개변수(M)</th><th>지연 시간(ms)†</th></tr></thead><tbody><tr><td><code>rfdetr-keypoint-preview</code></td><td>576x576</td><td>71.8</td><td>126.4</td><td>9.7</td></tr></tbody></table>

Roboflow는 아직 이 체크포인트용 사전 빌드 TensorRT 엔진을 제공하지 않으므로, Inference는 `inference-models[trt10]` 추가 항목을 설치해도 ONNX Runtime에서 실행합니다. 표에 표시된 지연 시간에 도달하려면 다음을 사용해 직접 엔진을 빌드해야 합니다. [rfdetr](https://github.com/roboflow/rf-detr) 패키지.

***

† 키포인트 정확도와 지연 시간은 다음에 게시된 수치입니다. [RF-DETR 벤치마크](https://rfdetr.roboflow.com/latest/#keypoints): 배치 크기 1에서 NVIDIA T4 1개로 측정한 TensorRT FP16 지연 시간이며, 모델만 측정한 값입니다. 위 표와는 GPU와 파이프라인이 다르므로 두 지연 시간 수치를 직접 비교할 수 없습니다.

\* 지연 시간은 다음을 사용해 측정했습니다. [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 를 NVIDIA L4 1개, 배치 크기 1에서 사용했으며, 1,000회 추론(워밍업 100회)의 평균값입니다. 기본 `inference-gpu` 설치는 CUDA 실행 공급자를 통해 ONNX를 실행합니다. 여기에 `inference-models[trt10]` 추가 항목을 지정하면 사전 빌드된 TensorRT FP16 엔진이 자동으로 선택됩니다. COCO의 `val2017`에서 FP16의 정확도는 FP32와 비교해 mAP 차이가 0.2 이내입니다. 정확도는 게시된 COCO `val` 사양을 기준으로 합니다(자세한 내용은 [RF-DETR 발표](https://blog.roboflow.com/rf-detr/)).

## 사용자 지정 가중치 업로드

Roboflow 외부에서 학습한 RF-DETR 모델을 실행하려면 다음을 사용해 해당 가중치를 프로젝트에 업로드하세요. [Roboflow CLI](https://docs.roboflow.com/reference/platform/cli/install-and-set-up-the-cli):

```bash
roboflow upload_model -p my-project -v 1 -t rfdetr-medium -m ./output -f checkpoint_best_total.pth
```

학습한 변형 모델에 맞게 `-t` 값을 설정하세요(예: `rfdetr-small`, `rfdetr-seg-medium`). Python SDK 및 학습 버전 요구 사항은 다음을 참조하세요. [사용자 지정 가중치 업로드](https://docs.roboflow.com/models/ko/model-weights/upload-custom-weights.md) .

## 라이선스

RF-DETR은 모델 크기에 따라 두 가지 라이선스를 적용합니다.

* **Apache 2.0** (Nano, Small, Medium, Large 감지 모델, 모든 크기의 분할 모델 및 키포인트 모델): 자체 호스팅 및 클로즈드 소스 제품을 포함해 상업적 용도로 무료로 사용할 수 있습니다. 라이선스 비용이 없으며 코드를 오픈 소스로 공개할 필요도 없습니다.
* **PML 1.0** (XL 및 2XL 감지 모델, 모든 크기의 시맨틱 분할 모델, RF-DETR Pose 키포인트 모델; Roboflow Platform Model License): Roboflow에 배포하면 상업적 사용이 포함됩니다. 상업적 목적으로 자체 호스팅하려면 Enterprise 추가 기능이 필요합니다.

자세한 내용은 [모델 라이선스](https://docs.roboflow.com/models/ko/model-licenses.md) 를 참조하세요.
