SAM2

Meta의 SAM2 모델을 서버리스 클라우드 API를 통해 사용

Meta의 것을 지원합니다 Segment Anything Model 2 당사의 Serverless Cloud API. SAM2는 점과 바운딩 박스를 프롬프트로 받는, 프롬프트 지정 가능한 시각적 세그멘테이션 모델입니다. SAM2 엔드포인트는 두 가지를 제공합니다:

/sam2/embed_image, 이미지 임베딩을 생성하고 캐시합니다
/sam2/segment_image, 주어진 프롬프트에 대한 인스턴스 세그멘테이션 마스크를 반환합니다

코드 예시

다음과 함께 HTTP 엔드포인트를 통해 SAM2를 직접 실행하세요 curl, 또는 다음을 사용하여 inference-sdk 래퍼.

API 키 받기

Roboflow 계정을 만들고, 다음에서 키를 찾으세요. Roboflow API 설정 페이지 에서 다음과 같이 셸에서 사용할 수 있도록 합니다:

export ROBOFLOW_API_KEY="your-key-here"

모델 실행

다음을 호출합니다. /sam2/segment_image 엔드포인트를 다음과 함께 curl:

curl --location 'https://serverless.roboflow.com/sam2/segment_image' \
  --header 'Content-Type: application/json' \\
  --data '{
    "api_key": "'"$ROBOFLOW_API_KEY"'",
    "image": {"type": "url", "value": "https://media.roboflow.com/quickstart/traffic.jpg"},
    "prompts": {"prompts": [{"points": [{"x": 520, "y": 470, "positive": true}]}]},
    "sam2_version_id": "hiera_tiny"
  }'

API 키 받기

Roboflow 계정을 만들고, 다음에서 키를 찾으세요. Roboflow API 설정 페이지 에서 다음과 같이 셸에서 사용할 수 있도록 합니다:

export ROBOFLOW_API_KEY="your-key-here"

의존성 설치

이 패키지들은 모델을 호출하고 그 결과를 그립니다:

pip install -U inference-sdk supervision opencv-python

모델 실행

단일 양성 점 프롬프트로 세그멘테이션 엔드포인트를 호출하고, 반환된 폴리곤을 supervision으로 검출 결과로 변환한 뒤, 입력 이미지 위에 마스크를 그린 주석 PNG를 저장합니다:

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

image = sv.load_image_from_url("https://media.roboflow.com/quickstart/traffic.jpg")
height, width = image.shape[:2]

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key=os.environ["ROBOFLOW_API_KEY"],
)

result = client.sam2_segment_image(
    inference_input=image,
    prompts=[
        {"points": [{"x": 520, "y": 470, "positive": True}]}
    ],
    sam2_version_id="hiera_tiny",
)

detections = sv.Detections.from_sam3(sam3_result=result, resolution_wh=(width, height))

annotated = sv.MaskAnnotator().annotate(image.copy(), detections)
cv2.imwrite("traffic_annotated.png", annotated)

sv.Detections.from_sam3 SAM2와 SAM3가 모두 반환하는 폴리곤 예측을 읽어들이므로, 같은 호출로 두 모델의 출력 모두를 디코딩합니다.

추론 속도

지연 시간 측정 기준: Roboflow Inference 1x NVIDIA L4, 배치 크기 1에서 워밍업 후 평균값.

모델

지연 시간(ms)

sam2

177.7

측정 기준 segment_image 에서 hiera_large 체크포인트. SAM2는 이미지 임베딩을 캐시하므로, 이 수치는 매 호출마다 새 이미지를 사용하며 전체 인코드와 디코드 비용을 반영합니다. 이미 인코딩된 이미지를 다시 프롬프트하는 것은 훨씬 더 빠릅니다.

설정 api_url 를 배포 대상에 맞게:

https://serverless.roboflow.com 서버리스 클라우드 API용입니다.
http://localhost:9001 로컬 Inference 서버용.
당신의 전용 배포 비공개 엔드포인트용 URL.

임베딩 캐싱과 박스 프롬프트를 포함한 추가 사용 세부 정보는 추론 문서.

Inference(자가 호스팅)에서 사용

SAM2는 다음과 함께 직접 로드할 수도 있습니다. inference 패키지로 로드하거나, 직접 실행하는 GPU 컨테이너에서 서비스할 수 있습니다. 이미지를 자체 하드웨어에 보관하고 싶거나, 같은 이미지를 여러 번 다시 프롬프트할 때 적합한 방법입니다.

Docker에서 실행

의 루트에서 SAM2 이미지를 빌드하세요 inference 저장소:

docker build -f docker/dockerfiles/Dockerfile.sam2 -t sam2 .

그다음 SAM2 엔드포인트를 노출하는 서버를 시작하세요:

docker run -it --rm -v /tmp/cache/:/tmp/cache/ --gpus=all --net=host sam2

해당 서버를 api_url 에 가리키면(http://localhost:9001) 위의 코드 예제는 수정 없이 그대로 작동합니다.

플래시 어텐션이 적용된 SAM2에는 알려진 문제가 있습니다 L4와 A100을 포함한 일부 GPU에서 그렇습니다. 해당 스레드의 수정 사항을 적용하거나, 이미 이를 처리하는 위의 Docker 이미지를 사용하세요.

Python에서 모델 로드

import os

os.environ["API_KEY"] = "YOUR_API_KEY"

from inference.core.entities.requests.sam2 import Sam2PromptSet
from inference.core.utils.postprocess import masks2poly
from inference.models.sam2 import SegmentAnything2

model = SegmentAnything2(model_id="sam2/hiera_large")

image_path = "./hand.png"

# 이미지 임베딩을 미리 계산하고 캐시합니다
embedding, img_shape, image_id = model.embed_image(image_path)

# 캐시된 임베딩을 사용해 세그멘테이션합니다
raw_masks, raw_low_res_masks = model.segment_image(image_path)
raw_masks = raw_masks >= model.predictor.mask_threshold
poly_masks = masks2poly(raw_masks)

임베딩은 자동으로 캐시되므로, 필요해질 것을 알게 되는 즉시 이미지를 임베딩하고 이후에는 저렴하게 다시 프롬프트할 수 있습니다.

마스크를 다듬으려면, 음성 점("positive": False)을 보내 영역을 제외하세요:

prompt = Sam2PromptSet(
    prompts=[{"points": [{"x": 250, "y": 800, "positive": False}]}]
)

refined_masks, refined_low_res_masks = model.segment_image(image_path, prompts=prompt)
refined_masks = refined_masks >= model.predictor.mask_threshold

사용 가능 model_id 값: sam2/hiera_tiny, sam2/hiera_small, sam2/hiera_b_plus, sam2/hiera_large.

Workflows의 비디오 추적

해당 SAM2 비디오 트래커 블록(roboflow_core/segment_anything_2_video@v1)는 SAM2의 스트리밍 비디오 예측기를 프레임 단위로 실행하여, 비디오별 시간적 메모리를 유지하므로 객체의 ID가 프레임 간에 지속됩니다. 상위 단계 검출기의 바운딩 박스를 입력하면 각 박스를 마스크로 변환해 이후 프레임에서 추적하고, 그 세그멘테이션 예측의 tracker_id SAM2가 객체를 추적하는 동안 유지됩니다. 마스크는 그것들을 유도한 검출의 클래스 이름, 클래스 ID, 신뢰도를 상속합니다.

상태를 유지하며 로컬에서만 동작합니다. 이 블록은 video_metadata.video_identifier마다 하나의 추적 세션을 유지하므로 여러 스트림을 다중화할 수 있지만, 세션은 프로세스 메모리 안에 존재합니다. WORKFLOWS_STEP_EXECUTION_MODE=local가 필요하며, GPU와 지속적인 WebRTC 세션이 필요합니다. 별도의 무상태 HTTP 요청에는 적합하지 않습니다.
프롬프트 스케줄링. prompt_mode 는 검출기 박스가 프롬프트로 소비되는 시점을 제어합니다: first_frame (기본값) 세션당 한 번 프롬프트를 넣고 그다음에는 조용히 추적합니다; every_n_frames 매 prompt_interval 프레임마다 다시 시드하여 장면에 들어온 객체를 포착합니다; every_frame 모든 프레임마다 다시 시드하여, 안정적인 추적기 ID를 가진 프레임별 검출-마스크 어댑터처럼 동작합니다.
모델 변형. model_id Hiera 백본을 선택합니다: sam2video/tiny, sam2video/small (기본값), sam2video/base-plus, sam2video/large. 이 블록은 또한 sam3trackervideo을 지원합니다. 이는 훨씬 더 큰 백본을 사용하는 SAM3의 시각적 프롬프트 기반 추적기입니다. 더 높은 연산 비용으로 긴 비디오와 혼잡한 장면에서 ID를 더 잘 유지합니다: 최고 품질 계층으로 취급하고, sam2video 크기를 속도 계층으로 보세요.

from inference_sdk import InferenceHTTPClient
from inference_sdk.webrtc import StreamConfig, VideoFileSource

WORKFLOW = {
    "version": "1.0",
    "inputs": [{"type": "InferenceImage", "name": "image"}],
    "steps": [
        {
            "type": "roboflow_core/roboflow_object_detection_model@v2",
            "name": "detector",
            "images": "$inputs.image",
            "model_id": "yolov8n-640",
        },
        {
            "type": "roboflow_core/segment_anything_2_video@v1",
            "name": "tracker",
            "images": "$inputs.image",
            "boxes": "$steps.detector.predictions",
            "prompt_mode": "every_n_frames",
            "prompt_interval": 30,
        },
    ],
    "outputs": [
        {
            "type": "JsonField",
            "name": "predictions",
            "selector": "$steps.tracker.predictions",
        }
    ],
}

client = InferenceHTTPClient(
    api_url="http://localhost:9001",
    api_key="YOUR_API_KEY",
)

session = client.webrtc.stream(
    source=VideoFileSource("path/to/video.mp4"),
    workflow=WORKFLOW,
    config=StreamConfig(data_output=["predictions"]),
)

@session.on_data("predictions")
def handle_predictions(predictions, metadata):
    print(predictions)

session.run()

텍스트 프롬프트만으로, 상위 검출기가 없는 개방형 어휘 비디오 추적은 SAM3 페이지.

워크플로의 실행 모드

이미지 워크플로에서 사용될 때 SAM2는 다음 두 모드 중 하나로 실행됩니다:

로컬 실행: 모델은 귀하의 Inference 서버에서 실행됩니다(GPU 사용을 강력히 권장).
원격 실행: 모델이 sam2_segment_image() 클라이언트 메서드를 통해 원격 Inference 서버에서 HTTP로 호출됩니다.

참고

SAM3 - 텍스트 프롬프트로 개념의 모든 인스턴스를 세그멘트합니다.
Segment Anything (SAM) - 원래의 단일 객체 모델.

이전Segment Anything(SAM)다음SAM3

마지막 업데이트 4일 전

도움이 되었나요?