SAM 설치와 실행
SAM 3는 Ultralytics 라이브러리를 통해 설치하고 사용할 수 있다. YOLO와 동일한 인터페이스를 사용하기 때문에 YOLO에 익숙하다면 빠르게 시작할 수 있다.
| 항목 | 내용 |
|---|---|
| 필요 환경 | Python 3.8+ / GPU 권장 / ultralytics 8.3.237+ |
| 설치 명령 | pip install -U ultralytics |
| 모델 크기 | ~3.4GB |
문서 탐색
설치 방법
기본 설치
pip install -U ultralyticsCLIP 오류 발생 시
SAM 3의 텍스트 프롬프트 기능은 CLIP 모델을 내부적으로 사용한다. 기존에 다른 버전의 CLIP이 설치되어 있으면 충돌이 발생할 수 있다.
pip uninstall clip -y
pip install git+https://github.com/ultralytics/CLIP.git참고: Ultralytics가 관리하는 CLIP 포크 버전을 사용해야 SAM 3와 정상적으로 호환된다.
모델 가중치 다운로드
SAM 3는 YOLO와 달리 자동 다운로드가 지원되지 않는다. 사용 전에 직접 가중치 파일을 다운로드해야 한다.
- https://huggingface.co/facebook/sam3 접속
- 접근 권한 요청 (Meta 이용 약관 동의)
sam3.pt파일 다운로드- 코드에서 사용할 경로에 파일 배치
텍스트 프롬프트로 세그멘테이션
SAM 3의 핵심 기능이다. 찾고 싶은 객체 이름을 텍스트로 전달하면 이미지 내 모든 해당 객체를 자동으로 세그멘테이션한다.
from ultralytics.models.sam import SAM3SemanticPredictor
overrides = dict(
conf=0.25,
task="segment",
mode="predict",
model="sam3.pt",
half=True, # FP16으로 메모리 절약
save=True # 결과 이미지 저장
)
predictor = SAM3SemanticPredictor(overrides=overrides)
# 이미지 로드 (Feature 추출은 한 번만 실행됨)
predictor.set_image("drone_railway.jpg")
# 텍스트 프롬프트로 세그멘테이션
results = predictor(text=["rail", "sleeper", "catenary pole"])이미지 예시(Exemplar) 프롬프트
텍스트 대신 참고할 객체 영역을 바운딩 박스로 지정할 수도 있다. 특정 결함처럼 텍스트로 설명하기 어려운 경우에 유용하다.
predictor.set_image("drone_railway.jpg")
# 참고할 객체의 바운딩 박스 좌표 [x1, y1, x2, y2]
results = predictor(bboxes=[[480.0, 290.0, 590.0, 650.0]])비디오 텍스트 추적
드론 영상처럼 비디오 파일에서도 텍스트 프롬프트로 객체를 추적할 수 있다.
from ultralytics.models.sam import SAM3VideoSemanticPredictor
predictor = SAM3VideoSemanticPredictor(overrides=dict(
conf=0.25,
task="segment",
mode="predict",
imgsz=640,
model="sam3.pt",
half=True,
save=True
))
results = predictor(
source="railway_video.mp4",
text=["rail", "obstacle"],
stream=True # 메모리 효율적인 스트리밍 처리
)
for result in results:
# 프레임별 처리
print(result.boxes)SAM 2 호환 모드 (포인트/박스 프롬프트)
기존 SAM 2 방식의 포인트/박스 프롬프트도 SAM 3에서 그대로 사용할 수 있다.
from ultralytics import SAM
model = SAM("sam3.pt")
# 바운딩 박스 프롬프트
results = model.predict("railway.jpg", bboxes=[100, 150, 300, 400])
results[0].show()지원 태스크 정리
| 태스크 | 프롬프트 | 출력 | 용도 |
|---|---|---|---|
| 개념 세그멘테이션 (PCS) | 텍스트, 이미지 예시 | 모든 매칭 인스턴스 마스크 | 자동 라벨링, 탐색 |
| 시각 세그멘테이션 (PVS) | 포인트, 박스, 마스크 | 단일 객체 마스크 | 정밀 세그멘테이션 |
| 비디오 추적 | 텍스트 + 박스 | 프레임별 추적 마스크 | 영상 분석 |
초보자 팁: 철도 점검 프로젝트를 처음 시작한다면 텍스트 프롬프트(PCS)부터 시작하는 것을 권장한다. 학습 데이터 없이 바로 결과를 확인할 수 있어 프로토타이핑에 최적이다.