YOLOE: 실시간 개방형 어휘 탐지 및 세그멘테이션#
Ultralytics YOLOE(실시간으로 모든 것을 보는 모델)는 개방형 어휘 탐지 및 인스턴스 세그멘테이션 모델입니다. 학습 시 고정된 클래스 목록을 사용하는 대신, 추론 시 원하는 카테고리를 텍스트 프롬프트, 시각적 예시 또는 기본 제공되는 4,585개 이름의 어휘로 지정할 수 있습니다. Ultralytics YOLO 아키텍처인 YOLOv8, YOLO11, YOLO26을 기반으로 하며 YOLO-World에서 영감을 받은 YOLOE는 폐쇄형 세트 YOLO에 가까운 속도로 최첨단 제로샷 정확도를 달성합니다.
Watch: How to use Ultralytics YOLOE-26 (New) | Open Vocabulary & Real-Time Seeing Anything 🚀
빠른 시작#
원하는 클래스를 지정하고 실행합니다. YOLOE-26은 학습한 적이 없는 카테고리에 대해서도 바운딩 박스와 인스턴스 세그멘테이션 마스크를 반환합니다.
from ultralytics import YOLOE
model = YOLOE("yoloe-26s-seg.pt")
# "double-decker bus" is not a COCO class; YOLOE resolves it from the words alone
model.set_classes(["double-decker bus", "person"])
results = model.predict("https://ultralytics.com/images/bus.jpg")
results[0].show()처음 set_classes()을 호출하면 텍스트 인코더가 다운로드됩니다. 네트워크에 액세스할 수 없는 머신에 배포하기 전에 설치 및 요구 사항을 확인하세요.
프롬프트 모드 선택#
YOLOE는 세 가지 프롬프트 모드를 지원하며, 선택한 모드에 따라 로드할 체크포인트와 클래스 레이블의 형식이 결정됩니다. 추론 시 제공할 수 있는 항목에 맞는 행을 선택하세요.

| 모드 | 체크포인트 | 제공하는 항목 | 결과의 클래스 이름 | 사용 시점 |
|---|---|---|---|---|
| 텍스트 프롬프트 | *-seg.pt | 문자열 형식의 클래스 이름 | 전달한 이름과 정확히 일치하는 이름 | 대상을 단어로 설명할 수 있을 때 사용합니다. 일반적으로 이 방식을 선택합니다. |
| 시각적 프롬프트 | *-seg.pt | 참조 이미지에 표시한 예시 박스 | 일반적인 object0, object1, … | 대상을 단어로 표현할 수 없을 때 사용합니다. 예를 들어 특정 부품, 로고 또는 결함에 해당합니다. |
| 프롬프트 없음 | *-seg-pf.pt | 없음 | 기본 제공되는 4,585개 이름의 어휘에 포함된 이름 | 목록을 작성하거나 탐색 중이며 사전에 무엇을 찾아야 할지 모를 때 사용합니다. |
- 시각적 프롬프트에는 사용자가 지정한 레이블이 포함되지 않습니다.
visual_prompts의 클래스 ID는 예시를 함께 그룹화하며, 모델은 이를object0,object1등으로 보고합니다. 이를 사용자의 이름에 직접 매핑해야 합니다. - 프롬프트 없는 체크포인트는
set_classes()을 거부합니다.*-seg-pf.pt모델에서 이를 호출하면AssertionError: Prompt-free model does not support setting classes. Please try with Text/Visual prompt models.가 발생합니다. 자체 클래스를 사용해야 할 때는 대신*-seg.pt체크포인트를 로드하세요.
설치 및 요구 사항#
YOLOE는 기본 Ultralytics 패키지에 포함되어 있습니다.
pip install -U ultralytics텍스트 프롬프트를 사용하려면 여기에 텍스트 인코더가 추가로 필요하며, 설치 시가 아니라 처음 사용할 때 다운로드됩니다.
- 처음
set_classes()을 호출하면pip(토크나이저를 제공합니다)를 사용하여 GitHub에서 ultralytics/CLIP을 설치하고, TorchScript 텍스트 인코더를 현재 작업 디렉터리에 다운로드합니다. YOLOE-26은 약 254MB 크기의mobileclip2_b.ts을 다운로드하며, YOLOE-11 및 YOLOE-v8은mobileclip_blt.ts를 다운로드합니다. 실행할 디렉터리에서 다운로드를 한 번 수행하거나 해당 디렉터리에 파일을 복사하세요. 그렇지 않으면 파일이 다시 다운로드됩니다. - 두 단계 모두 네트워크 액세스가 필요하므로 오프라인 또는 에어 갭 머신에 배포하기 전에 프롬프트를 사용한 예측을 한 번 실행하세요.
- 시각적 프롬프트와 프롬프트 없는 체크포인트에는 텍스트 인코더가 전혀 필요하지 않습니다.
YOLOE-26 체크포인트에는 ultralytics 8.4.0 이상이 필요합니다. YOLOE-11 및 YOLOE-v8 제품군은 이전 릴리스에서도 사용할 수 있습니다. 텍스트 프롬프트를 사용한 예측을 한 번 실행하면 체크포인트 다운로드, CLIP 설치, 텍스트 인코더 및 추론으로 이어지는 전체 경로를 테스트할 수 있습니다.
yolo predict model=yoloe-26s-seg.pt source="https://ultralytics.com/images/bus.jpg" classes="person"추론 시 텍스트 인코더를 다운로드하는 과정을 완전히 건너뛰려면 프롬프트를 가중치에 한 번 포함하고 재사용하세요. 프롬프트 임베딩 재사용을 참조하세요.
아키텍처 개요#
YOLOE는 특징 추출을 위한 합성곱 backbone, 멀티스케일 융합을 위한 neck, 클래스와 박스를 예측하는 anchor-free, decoupled head로 구성된 표준 YOLO 구조를 유지하면서 프롬프트 모드별로 하나씩 세 개의 모듈을 추가합니다.
- **재매개변수화 가능한 영역-텍스트 정렬(RepRTA)**은 소규모 보조 네트워크를 통해 CLIP의 텍스트 임베딩을 정제합니다. 이 네트워크는
set_classes()호출마다 한 번 실행되고 내보내기 시 제거되므로 프레임별 비용이 발생하지 않습니다. 모든 forward pass에서 실행되는 작업은 저장된 프롬프트 임베딩을 영역 특징과 비교하는 과정입니다. 대규모 프롬프트 세트에서 발생하는 비용은 제한 사항을 참조하세요. - **의미 활성화 시각적 프롬프트 인코더(SAVPE)**는 예시 박스에서 의미 특징과 활성화 특징을 인코딩하여 해당 예시와 비슷하게 보이는 객체를 기준으로 모델을 조정합니다. 이는 로고나 특정 부품처럼 이름으로 표현하기 어려운 대상을 위한 원샷 경로입니다.
- **지연 영역-프롬프트 대조(LRPC)**는 영역 임베딩을 기본 제공되는 4,585개 이름의 어휘와 비교하므로, 프롬프트 없는 체크포인트는 외부 프롬프트와 텍스트 인코더 없이도 객체를 인식합니다.
인스턴스 세그멘테이션은 YOLOv8-Seg와 마찬가지로 탐지 head의 마스크 브랜치에서 수행되며, 모든 예측에는 results[0].masks의 마스크가 포함됩니다. 모델을 export하면 개방형 세계 모듈이 표준 YOLO head로 재매개변수화되므로, export된 파일은 일반적인 detect/segment 경로를 실행합니다.
사용 가능한 모델#
아래의 모든 체크포인트는 인스턴스 세그멘테이션 모델이며 val, predict, export, track을 지원합니다. 텍스트 또는 시각적 프롬프트에는 *-seg.pt 파일을, 프롬프트 없는 추론에는 *-seg-pf.pt 파일을 로드하세요. 두 파일은 서로 호환되지 않으므로 프롬프트 모드 선택을 참조하세요. train을 지원하는 파일은 *-seg.pt뿐입니다. 프롬프트 없는 체크포인트는 텍스트 프롬프트 모델을 학습하여 생성합니다. 공식 모델을 처음부터 학습하기를 참조하세요.
| 모델 | 텍스트 / 시각적 프롬프트 | 프롬프트 없음 |
|---|---|---|
| YOLOE-26n | yoloe-26n-seg.pt | yoloe-26n-seg-pf.pt |
| YOLOE-26s | yoloe-26s-seg.pt | yoloe-26s-seg-pf.pt |
| YOLOE-26m | yoloe-26m-seg.pt | yoloe-26m-seg-pf.pt |
| YOLOE-26l | yoloe-26l-seg.pt | yoloe-26l-seg-pf.pt |
| YOLOE-26x | yoloe-26x-seg.pt | yoloe-26x-seg-pf.pt |
| YOLOE-11s | yoloe-11s-seg.pt | yoloe-11s-seg-pf.pt |
| YOLOE-11m | yoloe-11m-seg.pt | yoloe-11m-seg-pf.pt |
| YOLOE-11l | yoloe-11l-seg.pt | yoloe-11l-seg-pf.pt |
| YOLOE-v8s | yoloe-v8s-seg.pt | yoloe-v8s-seg-pf.pt |
| YOLOE-v8m | yoloe-v8m-seg.pt | yoloe-v8m-seg-pf.pt |
| YOLOE-v8l | yoloe-v8l-seg.pt | yoloe-v8l-seg-pf.pt |
LVIS에서의 YOLOE 성능#
Ultralytics YOLO26 논문에 따른 640픽셀 LVIS minival의 제로샷 결과입니다.
텍스트 및 시각적 프롬프트#
각 정확도 및 파라미터 셀은 텍스트 프롬프트 / 시각적 프롬프트 순서로 표시하며, FLOPs는 한 번만 제시합니다. 파라미터와 FLOPs는 논문에서 평가한 탐지 구성에 대한 값입니다. 정확도는 논문이 비교 대상의 모든 모델에 대해 보고하는 유일한 프로토콜인 Non-E2E 수치입니다. YOLOE-26 end-to-end head는 텍스트 프롬프트에서 최대 1.1 AP, 시각적 프롬프트에서 최대 2.6 AP만큼 이 수치에 못 미칩니다.
| 모델 | mAP50-95 | mAPr | mAPc | mAPf | 파라미터 (M) | FLOPs (B) |
|---|---|---|---|---|---|---|
| YOLOE-26n | 24.7 / 21.9 | 20.5 / 17.6 | 24.1 / 22.3 | 26.1 / 22.4 | 3.9 / 3.1 | 6.1 |
| YOLOE-26s | 30.8 / 28.6 | 23.9 / 25.1 | 29.6 / 27.8 | 33.0 / 29.9 | 10.7 / 11.0 | 21.9 |
| YOLOE-26m | 35.4 / 33.9 | 31.1 / 33.4 | 34.7 / 34.0 | 36.9 / 33.8 | 21.3 / 25.1 | 70.6 |
| YOLOE-26l | 37.8 / 36.3 | 35.1 / 37.6 | 37.6 / 36.2 | 38.5 / 36.1 | 25.5 / 29.3 | 89.0 |
| YOLOE-26x | 40.6 / 38.5 | 37.4 / 35.3 | 40.9 / 38.8 | 41.0 / 38.8 | 55.2 / 65.2 | 197.7 |
| YOLOE-11s | 27.5 / 26.3 | 21.4 / 22.5 | 26.8 / 27.1 | 29.3 / 26.4 | 10.7 / 10.9 | 22.7 |
| YOLOE-11m | 33.0 / 31.4 | 26.9 / 27.1 | 32.5 / 31.9 | 34.5 / 31.7 | 21.0 / 24.8 | 70.4 |
| YOLOE-11l | 35.2 / 33.7 | 29.1 / 28.1 | 35.0 / 34.6 | 36.5 / 33.8 | 26.0 / 29.8 | 89.5 |
| YOLOE-v8s | 27.9 / 26.2 | 22.3 / 21.3 | 27.8 / 27.7 | 29.0 / 25.7 | 12.3 / 12.6 | 29.8 |
| YOLOE-v8m | 32.6 / 31.0 | 26.9 / 27.0 | 31.9 / 31.7 | 34.4 / 31.1 | 26.4 / 28.4 | 80.7 |
| YOLOE-v8l | 35.9 / 34.2 | 33.2 / 33.2 | 34.8 / 34.6 | 37.3 / 34.1 | 43.5 / 47.3 | 167.6 |
프롬프트 없음#
프롬프트 없는 체크포인트는 프롬프트를 제공하지 않고 기본 제공 어휘를 사용하여 결과를 출력합니다. 각 정확도 셀은 end-to-end / Non-E2E 순서로 표시하며, 이는 논문이 YOLOE-26에 대해 평가한 두 프로토콜입니다. YOLO26 페이지에는 Non-E2E 열의 값이 인용되어 있습니다.
| 모델 | mAP50-95 | mAPr | mAPc | mAPf | 파라미터 (M) | FLOPs (B) |
|---|---|---|---|---|---|---|
| YOLOE-26n-pf | 16.6 / 17.7 | 15.7 / 15.8 | 15.3 / 16.4 | 17.9 / 19.2 | 2.3 | 5.3 |
| YOLOE-26s-pf | 21.4 / 22.6 | 16.2 / 20.2 | 20.1 / 20.9 | 23.5 / 24.5 | 9.0 | 20.8 |
| YOLOE-26m-pf | 25.7 / 26.4 | 26.7 / 24.5 | 24.0 / 25.0 | 26.9 / 27.9 | 19.4 | 68.4 |
| YOLOE-26l-pf | 27.2 / 28.0 | 26.3 / 25.7 | 25.7 / 26.8 | 28.7 / 29.5 | 23.6 | 86.8 |
| YOLOE-26x-pf | 29.9 / 31.1 | 27.5 / 28.9 | 29.1 / 30.7 | 31.1 / 31.7 | 53.1 | 194.4 |
텍스트 및 시각적 프롬프트에서 YOLOE-26 모델은 mAP50-95의 모든 동일한 규모에서 YOLOE-11 및 YOLOE-v8 대응 모델보다 우수하며, 파라미터와 FLOPs는 v8 계열보다 적습니다. 동일한 분할에서 논문은 YOLO-Worldv2에 대해 24.4(S), 32.4(M), 35.5(L)을 보고했으며, Transformer 기반 탐지기 GLIP-T는 26.0, GDINO-T는 27.4, DetCLIP-T는 34.4를 기록했습니다. 각 모델에는 155M~232M개의 파라미터가 포함됩니다. 또한 원본 YOLOE 논문은 새로 소개한 v8 규모 모델에 대해 두 가지 결과를 추가로 제시합니다. LVIS에서 YOLOE-v8s는 학습 비용의 3분의 1과 1.4배의 추론 속도로 YOLO-Worldv2-S를 3.5 AP 앞섭니다. COCO로 전이했을 때 YOLOE-v8l은 폐쇄형 세트 YOLOv8-L보다 거의 4배 짧은 학습 시간으로 0.6 box AP 및 0.4 mask AP 향상을 달성합니다.
YOLO26 논문은 탐지 구성을 평가합니다. 릴리스된 가중치는 세그멘테이션 체크포인트이며 마스크 브랜치, SAVPE 및 텍스트 프로젝션이 추가되어 있으므로, 로드된 yoloe-26l-seg.pt은 위의 25.5M 및 89.0B가 아니라 35.4M 및 142.0B를 보고합니다. 두 경우 모두 FLOPs 수치에는 영역-텍스트 유사도가 포함되지 않으므로 열의 값이 변하지 않더라도 프롬프트 세트의 크기에 따라 실제 비용이 증가합니다. 제한 사항을 참조하세요.
사용 예시#
아래의 모든 YOLOE 예제는 Python API에서 실행됩니다. 텍스트 프롬프트 예측, 검증, export, tracking 및 일반 학습은 CLI에서도 작동합니다. 파인튜닝 레시피와 시각적 프롬프트는 trainer 또는 predictor 클래스를 인수로 전달하며, 이는 Python API에서만 지원됩니다.
학습 사용법#
릴리스된 *-seg.pt 체크포인트를 사용하여 자체 YOLO 데이터셋에서 파인튜닝할 수 있습니다. 이 과정은 대부분 표준 YOLO 학습 절차를 따르며, 차이점은 전달하는 trainer입니다. YOLOEPESegTrainer는 사용자의 클래스 이름을 head에 결합한 후 해당 상태에서 파인튜닝하므로, 자체 레이블을 사용할 때 적합합니다. 기본 trainer는 사용자의 클래스 이름을 대상으로 학습하지 않습니다.
Watch: How to Train YOLOE on Car Parts Segmentation Dataset | Open-Vocabulary Model, Prediction & Export 🚀
from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEPESegTrainer
model = YOLOE("yoloe-26s-seg.pt")
results = model.train(
data="coco128-seg.yaml",
epochs=80,
patience=10,
trainer=YOLOEPESegTrainer, # <- Important: the fine-tuning trainer, not the default
)릴리스된 모든 checkpoint는 segmentation model입니다. detector를 학습하려면 일치하는 YAML에서 model을 생성하고, 동일한 scale의 segmentation weight를 로드한 다음 detection trainer로 교체합니다. 나머지는 변경되지 않습니다.
from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEPETrainer
model = YOLOE("yoloe-26s.yaml").load("yoloe-26s-seg.pt")
results = model.train(data="coco128.yaml", epochs=80, patience=10, trainer=YOLOEPETrainer)Predict 사용법#
text-prompt 호출은 Quick Start에 나와 있습니다. 나머지 두 모드에는 각각 추가 인수가 필요합니다:
Visual prompt는 대상을 설명하는 대신 예시를 model에 보여줍니다. visual_prompts은 예시 box의 bboxes array와 box마다 하나씩 대응하는 class ID의 cls array를 받습니다. ID는 label이 아니라 임시 grouping이므로 0부터 순차적이어야 하며, 결과는 사용자가 선택한 이름이 아니라 object0, object1, …로 반환됩니다.
예시 box는 예측 대상 image 위에 배치할 수 있습니다:
import numpy as np
from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEVPSegPredictor
model = YOLOE("yoloe-26l-seg.pt")
# One example box per target, each with its own class ID
visual_prompts = {
"bboxes": np.array([[221.52, 405.8, 344.98, 857.54], [120, 425, 160, 445]]), # person, glasses
"cls": np.array([0, 1]),
}
results = model.predict(
"ultralytics/assets/bus.jpg",
visual_prompts=visual_prompts,
predictor=YOLOEVPSegPredictor,
)
results[0].show()또는 refer_image으로 전달하는 별도의 reference image 위에 배치할 수 있습니다. 이 경우 bboxes과 cls는 target이 아니라 해당 reference의 object를 설명합니다:
import numpy as np
from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEVPSegPredictor
model = YOLOE("yoloe-26l-seg.pt")
visual_prompts = {"bboxes": np.array([[221.52, 405.8, 344.98, 857.54]]), "cls": np.array([0])} # person
results = model.predict(
"ultralytics/assets/zidane.jpg", # Target image
refer_image="ultralytics/assets/bus.jpg", # Where the example boxes live
visual_prompts=visual_prompts,
predictor=YOLOEVPSegPredictor,
)
results[0].show()
# refer_image also sets the classes permanently, so later calls need no prompts at all
results = model("ultralytics/assets/bus.jpg")
model.export(format="onnx") # And the export keeps themsource이 video 또는 stream인 경우 첫 frame이 자동으로 refer_image이 됩니다. 따라서 전달한 prompt는 해당 frame에 적용되고 video의 나머지 부분에도 계속 적용됩니다. 다른 frame을 선택하려면 refer_image를 명시적으로 전달합니다.
source과 refer_image은 모두 torch tensor를 직접 받을 수 있으며, image가 이미 기존 pipeline에서 생성된 경우 유용합니다. tensor 자체의 pixel coordinate로 box를 지정합니다:
import numpy as np
import torch
from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEVPSegPredictor
model = YOLOE("yoloe-11l-seg.pt")
img_tensor = torch.rand(1, 3, 480, 480) # (1, 3, H, W) float tensor in [0, 1]
visual_prompts = {"bboxes": np.array([[10, 10, 50, 50]]), "cls": np.array([0])}
results = model.predict(
img_tensor,
refer_image=img_tensor,
visual_prompts=visual_prompts,
predictor=YOLOEVPSegPredictor,
imgsz=640,
)여러 image를 한 번에 예측하려면 prompt를 한 단계 더 깊게 중첩합니다. source와 동일한 순서로 각 source image마다 bboxes array 하나와 cls array 하나를 지정합니다.
import numpy as np
from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEVPSegPredictor
model = YOLOE("yoloe-26l-seg.pt")
visual_prompts = {
"bboxes": [
np.array([[221.52, 405.8, 344.98, 857.54], [120, 425, 160, 445]]), # bus.jpg: person, glasses
np.array([[150, 200, 1150, 700]]), # zidane.jpg: person
],
"cls": [np.array([0, 1]), np.array([0])],
}
results = model.predict(
["ultralytics/assets/bus.jpg", "ultralytics/assets/zidane.jpg"],
visual_prompts=visual_prompts,
predictor=YOLOEVPSegPredictor,
)
results[0].show()Val 사용법#
Validation은 다른 model과 마찬가지로 segmentation dataset에서 실행합니다:
from ultralytics import YOLOE
model = YOLOE("yoloe-26l-seg.pt") # or yoloe-26s/m-seg.pt for other sizes
metrics = model.val(data="coco128-seg.yaml")나머지 prompting mode에는 동일한 호출의 두 가지 변형을 사용합니다:
- Visual prompt —
model.val(data="coco128-seg.yaml", load_vp=True)은 dataset 자체에서 category별 visual embedding을 추출합니다. 다른 dataset에서 embedding을 가져오려면refer_data="coco.yaml"을 추가합니다. 이 dataset은 정확히 동일한 category를 포함해야 합니다. - Prompt-free —
*-seg-pf.ptcheckpoint를 로드하고single_cls=True을 전달합니다.
Export 사용법#
Prompt embedding은 한 번 저장한 후 ONNX, OpenVINO, TensorRT, CoreML, LiteRT, RKNN과 같은 static export를 생성할 때 재사용할 수 있습니다. NPZ profile은 export 전에 원래 PyTorch model에서 로드되며, 추가 runtime input이 아닙니다. 또한 exported model에는 NPZ file이 필요하지 않습니다.
set_classes()으로 설정한 class(또는 visual prompt의 경우 refer_image을 통해 설정한 class)는 exported weight에 포함됩니다. 한 번 export하면 model은 더 이상 새 prompt를 받을 수 없습니다. 로드된 export에서 set_classes()를 호출하거나 predict()에 visual_prompts=...을 전달하면 실패합니다. 감지 class를 변경하려면 새 prompt를 설정하여 원래 .pt checkpoint에서 다시 export합니다. Export된 file은 표준 YOLO model처럼 동작하며 YOLOE() 대신 YOLO()으로도 로드할 수 있습니다.
from ultralytics import YOLOE
model = YOLOE("yoloe-26n-seg.pt")
model.set_classes(["person", "bus"])
model.save_prompt_embeddings("person-bus.npz")
# The profile is bound to the source checkpoint and can be reused for later exports.
model = YOLOE("yoloe-26n-seg.pt")
model.load_prompt_embeddings("person-bus.npz")
model.export(format="onnx")동일한 prompt profile로 일치하는 YOLOE architecture에서 생성한 detection-only model도 설정할 수 있습니다. 이렇게 하면 mask branch가 제거되고 prompt로 지정한 class는 유지됩니다:
from ultralytics import YOLOE
model = YOLOE("yoloe-26n.yaml").load("yoloe-26n-seg.pt")
model.load_prompt_embeddings("person-bus.npz")
model.export(format="rknn", name="rk3588", quantize=16)Track 사용법#
Prompt로 지정한 class는 tracking에도 그대로 전달되므로 tracker가 학습한 적 없는 object도 추적할 수 있습니다:
from ultralytics import YOLOE
model = YOLOE("yoloe-26s-seg.pt")
model.set_classes(["forklift", "pallet"])
# persist=True keeps track IDs stable across frames
for result in model.track("path/to/video.mp4", stream=True, persist=True):
print(result.boxes.id)YOLOE 비교#
YOLOE는 closed-set detector와 대규모 open-vocabulary model 사이에 있습니다. 다음 세 가지 비교를 통해 적절한 선택인지 판단할 수 있습니다:
- closed-set YOLO와 비교. Prompt를 설정하면 YOLOE는 일반적인 detect/segment 경로를 통해 예측하고 다른 model과 동일하게 export합니다. YOLOE가 추가하는 기능은 retraining 없이 inference 시점에 class list를 변경할 수 있다는 점입니다. 그 대가로 zero-shot accuracy는 자체 class로 학습한 model보다 훨씬 낮습니다.
- 이전 YOLOE family와 비교. YOLOE-26은 YOLO26의 NMS-free end-to-end head를 상속하며, 이전의 세 가지 scale(s/m/l)에 비해 다섯 가지 scale(n/s/m/l/x)을 지원합니다. 또한 Performance의 모든 일치 scale에서 더 우수한 성능을 보입니다.
- Transformer 기반 open-vocabulary detector와 비교. GLIP과 OWL-ViT는 inference 시 vision-language Transformer를 실행합니다. YOLOE는 prompt를 한 번 encode한 후 convolutional head 내부에서 이를 region feature와 비교합니다.
가장 가까운 대안들은 모두 text prompt를 사용하지만, mask를 반환하는 것은 YOLOE와 SAM 3뿐이며 세 model은 서로 다른 질문에 답합니다:
| YOLOE | SAM 3 | YOLO-World | |
|---|---|---|---|
| 용도 | 이름이 지정된 class의 실시간 detection 및 segmentation | Concept segmentation 및 prompt 기반 tracking | 실시간 open-vocabulary detection |
| 마스크 | 예, *-seg.pt checkpoint 사용 | 예 | 아니요, box만 지원 |
| Visual prompt | 예(SAVPE) | 예 | 아니요 |
| Prompt-free mode | 예, 4,585개 이름 vocabulary | 아니요 | 아니요 |
| 다음과 같은 경우 선택합니다 | 처리량이 필요하고 class 이름을 지정할 수 있는 경우 | 가장 강력한 concept segmentation이 필요하고 compute를 충분히 사용할 수 있는 경우 | 이미 사용 중인 경우 — 아래 migration 참고 |
YOLO-World에서 전환하는 경우? API 형태는 동일합니다. YOLOWorld을 YOLOE로 바꾸고, *-seg.pt checkpoint를 로드한 다음 set_classes() 호출은 그대로 유지합니다. mask와 visual prompt를 사용할 수 있으며, 고정된 class에 대한 export 참고 사항은 두 model 모두에 적용됩니다.
사용 사례 및 애플리케이션#
Open-vocabulary detection은 class별 retraining 단계를 없애며, 이는 target list를 사전에 알 수 없는 경우에 특히 중요합니다:
- Open-world detection — 학습 시 아무도 열거하지 않았던 object를 만나는 robotics 및 security system.
- 예시를 통한 one-shot detection — visual prompt는 단 하나의 reference box에서 특정 부품, logo 또는 defect를 찾아내며 industrial inspection에 유용합니다.
- Long-tail cataloging — 내장된 4,585개 이름 vocabulary는 biodiversity monitoring이나 retail inventory 조사에 충분할 만큼 폭넓습니다.
- Dataset bootstrapping — 사람이 검토하기 전에 image에 box와 mask를 사전 label로 지정한 다음, 그 결과로 빠른 closed-set model을 학습합니다.
- 임의 target의 segmentation — 릴리스된
*-seg.ptcheckpoint는 모든 prediction과 함께 mask를 반환하므로, medical imaging과 satellite analysis에서 별도의 model 없이 pixel 단위로 정밀한 output을 얻을 수 있습니다.
일반적인 방식은 두 모드를 결합합니다. 먼저 prompt-free를 한 번 실행하여 현재 무엇이 있는지 확인한 다음, 중요한 category에는 text prompt로 전환합니다.
제한 사항#
YOLOE는 inference 시 class를 변경할 수 있는 기능을 위해 accuracy를 절충합니다. 사용을 결정하기 전에 알아둘 만한 결과는 다음과 같습니다:
- Zero-shot accuracy는 자체 class로 학습한 model보다 훨씬 낮습니다. Prompt를 적용한 checkpoint는 LVIS minival에서 대략 22-40 mAP 범위에 해당하며, 자체 data로 학습한 closed-set YOLO는 해당 class에서 이를 능가합니다. 학습할 수 없는 class를 다루기 위해 YOLOE를 사용하고, training을 대체하는 용도로 사용하지 마십시오.
- Rare category가 약점입니다. Performance의 mAPr column은 특히 LVIS의 rare class에 대한 accuracy를 보고하며, text prompting에서는 모든 row에서 common 및 frequent column보다 낮습니다. target이 일반적이지 않은 경우 headline mAP가 아니라 이 값을 확인하십시오.
- Prompt는 관계가 아니라 appearance를 설명합니다. Detection은 region feature와 prompt embedding을 비교하여 작동하므로, state, context 또는 comparison에 의존하는 prompt(예: "damaged", "left-most", "the one being carried")에는 비교할 수 있는 신뢰할 만한 단서가 없습니다. 일상적인 category 이름에 가까운 표현을 사용하십시오.
- 대규모 prompt set은 latency를 증가시킵니다. Prompt embedding은 한 번 계산되지만 모든 forward pass에서 region feature와 비교됩니다.
yoloe-26s-seg.pt을 사용하여 CPU에서 측정하면 80개에서 1,203개 class로 늘릴 때 forward pass가 약 19%, 전체 4,585개 이름 vocabulary에서는 약 89% 증가합니다. region-text similarity가 집계되지 않기 때문에 보고된 FLOPs는 전혀 변하지 않으며, 따라서 profile에서도 이를 경고하지 않습니다. - Class 이름은 prompt를 적용하기 전까지 placeholder입니다. 새로 로드한
*-seg.ptcheckpoint는 숫자 이름("0","1", …)으로nc=80을 보고하므로 label을 읽기 전에set_classes()를 호출하십시오. Prompt-free checkpoint는 전체 vocabulary가 이미 채워진 상태로 제공됩니다.
Deployment 참고 사항#
- Hardware. Inference에는 4-8 GB VRAM을 갖춘 NVIDIA GPU가 필요합니다.
n및sscale은 Jetson과 같은 edge GPU에서 실행하거나, 해상도를 낮춰 CPU에서 실행할 수 있습니다. Fine-tuning에는 단일 GPU가 필요합니다. - NMS는 기본적으로 클래스에 구애받지 않습니다(class-agnostic). YOLOE는
agnostic_nms=True을(를) 사용하여 예측합니다. 기본적으로 이는 동일한 클래스 내에서뿐만 아니라 서로 다른 클래스 간의 점수가 낮은 겹치는 박스를 억제하여 하나의 객체가 여러 카테고리에 일치할 때 중복을 방지합니다.nms=False을(를) 사용하면 YOLOE-26은 IoU 억제를 적용하지 않습니다. 애그노스틱 모드는 하나의 앵커가 여러 클래스 레이블을 출력하도록 하는 대신 앵커당 단 하나의 최적 클래스만 유지합니다. 재정의하려면agnostic_nms=False을(를) 전달하십시오. - Batching. Batch inference가 직접 작동하며, 동일한 호출에서도 image마다 visual prompt를 다르게 지정할 수 있습니다.
공식 model을 처음부터 학습하기#
대부분의 독자에게는 이 과정이 필요하지 않습니다. 이는 Objects365, GQA 및 Flickr30k에서 공개된 open-vocabulary checkpoint를 재현하는 과정으로, 8× RTX 4090에서 약 1.4 M개의 training sample을 사용하며, 위의 Train Usage에서 다루는 자체 data fine-tuning과는 관련이 없습니다.
YOLOETrainer을 상속하는 모든 trainer는 compile=True을 거부합니다. 여기에는 기본 YOLOESegTrainer와 아래의 모든 from-scratch trainer가 포함됩니다. compile=False(기본값)를 전달하십시오. 위에서 사용한 두 fine-tuning trainer인 YOLOEPESegTrainer와 YOLOEPETrainer에는 이 제한이 없습니다.
학습에는 segment annotation이 필요합니다. 아래의 처리된 file을 다운로드하거나, 공식 팀이 제공한 script로 직접 생성할 수 있으며, 이 script는 SAM 2.1을 기반으로 합니다. Validation에는 LVIS minival을 사용합니다.
| 데이터셋 | 유형 | 샘플 | 박스 | 처리된 segment annotation |
|---|---|---|---|---|
| Objects365v1 | 탐지 | 609k | 9621k | objects365_train_segm.json |
| GQA | 그라운딩 | 621k | 3681k | final_mixed_train_no_coco_segm.json |
| Flickr30k | 그라운딩 | 149k | 641k | final_flickr_separateGT_train_segm.json |
text-prompt model을 먼저 학습하고, 나머지 두 prompting mode는 이를 개선한 것입니다:
from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOESegTrainerFromScratch
data = {
"train": {
"yolo_data": ["Objects365.yaml"],
"grounding_data": [
{
"img_path": "flickr/full_images/",
"json_file": "flickr/annotations/final_flickr_separateGT_train_segm.json",
},
{
"img_path": "mixed_grounding/gqa/images",
"json_file": "mixed_grounding/annotations/final_mixed_train_no_coco_segm.json",
},
],
},
"val": {"yolo_data": ["lvis.yaml"]},
}
model = YOLOE("yoloe-26l-seg.yaml")
model.train(
data=data, # or the path to a YAML file holding the same structure
batch=128,
epochs=30,
close_mosaic=2,
optimizer="AdamW",
lr0=2e-3,
warmup_bias_lr=0.0,
weight_decay=0.025,
momentum=0.9,
workers=4,
trainer=YOLOESegTrainerFromScratch,
device="0,1,2,3,4,5,6,7",
)visual-prompt 및 prompt-free checkpoint는 학습된 text-prompt model에서 시작하여 각각 하나의 module을 업데이트합니다. YOLOESegVPTrainer은 visual-prompt recipe이고 YOLOEPEFreeTrainer은 prompt-free recipe이지만, 어느 쪽도 자체적으로 class를 동결하지는 않습니다. 선택적 학습은 함께 전달하는 freeze list에서 수행되며, 이 list에는 savpe을 제외한 모든 head child(각각 모든 classification tower)가 지정됩니다. 또한 prompt-free 실행에는 single_cls=True가 추가로 필요합니다. upstream YOLOE repository에 v8-scale model의 전체 recipe가 있습니다.
완료된 prompt-free 실행은 get_vocab 및 set_vocab를 사용하여 inference 시 prompt 없이 이름을 보고하는 checkpoint로 re-parameterize됩니다:
from ultralytics import YOLOE
# Weights written by the prompt-free run and by the text-prompt run it started from. Each
# rerun creates a new directory (train-2, train-3, ...), so take the paths the runs printed.
model = YOLOE("runs/segment/train-2/weights/best.pt") # prompt-free run, its head is already fused
text_model = YOLOE("runs/segment/train/weights/best.pt") # text-prompt run, its head is still unfused
names = list(YOLOE("yoloe-26l-seg-pf.pt").model.names.values()) # the 4,585-name vocabulary, or your own list
vocab = text_model.get_vocab(names)
model.set_vocab(vocab, names)
model.save("yoloe-26l-seg-pf-custom.pt") # never overwrite the released checkpoint인용 및 감사의 글#
YOLOE가 연구 또는 project에 기여했다면 Tsinghua University의 Ao Wang, Lihao Liu, Hui Chen, Zijia Lin, Jungong Han 및 Guiguang Ding이 작성한 원본 논문을 인용해 주십시오:
@misc{wang2025yoloerealtimeseeing,
title={YOLOE: Real-Time Seeing Anything},
author={Ao Wang and Lihao Liu and Hui Chen and Zijia Lin and Jungong Han and Guiguang Ding},
year={2025},
eprint={2503.07465},
archivePrefix={arXiv},
primaryClass={cs.CV},
url={https://arxiv.org/abs/2503.07465},
}자세한 내용은 arXiv에서 원본 YOLOE 논문을 확인할 수 있습니다. Project의 source code와 추가 resource는 GitHub repository에서 확인할 수 있습니다.
FAQ#
Ultralytics YOLOE는 YOLO-World에 없는 두 가지 기능을 추가합니다. visual prompt에서는 예시 box가 class 이름을 대신하며, prompt-free checkpoint는 prompt 없이 내장된 4,585개 이름 vocabulary를 사용해 답합니다. 릴리스된
*-seg.ptcheckpoint의 모든 prediction에는 instance segmentation mask도 포함됩니다. Accuracy 측면에서 원본 YOLOE 논문은 LVIS에서 YOLOE-v8s가 YOLO-Worldv2-S보다 3.5 AP 앞서며, training cost는 3분의 1이고 inference speed는 1.4배 빠르다고 보고합니다. Migration은 한 줄만 변경하면 됩니다. How YOLOE Compares를 참고하십시오.Ultralytics YOLOE는 세 가지 prompting mode를 지원합니다. text prompt는
*-seg.ptcheckpoint에서 string으로 지정하는 class 이름이며 일반적으로 선택하는 방식입니다. visual prompt는 말로 표현하기 어려운 target을 위해 reference image에 있는 하나 이상의 예시 box를 사용합니다. prompt-free inference는 아무것도 입력하지 않고 내장된 4,585개 이름 vocabulary를 사용하는 별도의*-seg-pf.ptcheckpoint로 실행합니다. Text prompt와 visual prompt는 동일한 checkpoint를 공유하며, prompt-free는 별도의 file이므로set_classes()를 거부합니다. 전체 비교는 Choosing a Prompting Mode를 참고하십시오.yoloe-26s-seg.pt부터 시작하십시오. YOLOE-26 family는 모든 일치 scale에서 YOLOE-11 및 YOLOE-v8을 앞서며,sscale은 LVIS minival에서 30 mAP를 넘는 가장 작은 scale입니다. Latency보다 rare category의 accuracy가 더 중요하다면m,l또는x로 높이십시오. 비교할 항목은 Performance의 mAPr column입니다. Edge deployment에서만n으로 낮추십시오. 자체 class 이름 대신 내장 vocabulary를 사용하려면 동일한 scale의*-seg-pf.ptfile을 로드합니다.object0및object1과 같은 label은 prediction이 visual prompt에서 나온 것임을 의미합니다. 이 방식은 사용자의 이름을 유지하는 대신 예시 box를 임시 번호 class로 grouping합니다.visual_prompts["cls"]로 전달하는 class ID는 이 grouping에만 사용됩니다. Model은 이를 할당한 ID 순서에 따라object0,object1등으로 보고하므로 result에서 자체 label에 다시 매핑하십시오. output에 사용자 이름을 표시하려면 text prompt를 사용하십시오.Prompt-free checkpoint(
*-seg-pf.pt)는 자체 내장 vocabulary를 통해 class를 확인하며AssertionError: Prompt-free model does not support setting classes. Please try with Text/Visual prompt models.을 사용한 외부 prompt를 거부합니다. 자체 class list가 필요하면*-seg.ptcheckpoint를 로드하십시오. Choosing a Prompting Mode를 참고하십시오.첫 번째 text prompt를 실행하면 Ultralytics YOLOE가 GitHub에서
pip을 사용해 ultralytics/CLIP을 설치하고 현재 working directory에 TorchScript text encoder를 다운로드합니다. YOLOE-26의 경우 약 254 MB이며, model family별 정확한 asset은 Installation and Requirements를 참고하십시오. Visual prompt와 prompt-free checkpoint에는 둘 다 필요하지 않습니다. Target machine에서 다운로드를 방지하려면 prompt를 한 번 설정하고save_prompt_embeddings()으로 저장하거나 class가 이미 설정된 상태로 model을 export하십시오.아니요. YOLOE는 export 시점에 prompt로 지정한 class를 weight에 포함하므로 로드된 export는
set_classes()과visual_prompts=을 모두 거부합니다. 새 prompt를 설정하여 원래.ptcheckpoint에서 다시 export하십시오. Export된 file은 표준 YOLO model처럼 동작하며YOLO()및YOLOE()로 로드할 수 있습니다.실시간 처리량이 필요하고 class 이름을 지정할 수 있다면 YOLOE를 사용하고, 속도보다 concept의 segmentation quality가 중요하다면 SAM 3를 사용하십시오. 두 model 모두 visual example을 받을 수 있지만 prompt-free mode를 제공하는 것은 YOLOE뿐입니다. 전체 비교는 How YOLOE Compares에 있습니다.