> 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/sam3.md).

# SAM3

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

우리는 Meta의 [Segment Anything Model 3](https://github.com/facebookresearch/sam3) 추론은 우리의 [Serverless Cloud API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api). 우리는 두 가지 서로 다른 SAM3 엔드포인트를 제공합니다:

{% hint style="info" %}
Roboflow에서 SAM3 모델을 학습하는 기능은 유료 [요금제](https://docs.roboflow.com/platform/billing-and-plans#plans) 을 포함하는 [사용량 기반 과금](https://docs.roboflow.com/platform/billing-and-plans#credits). 이후 SAM3 아키텍처의 "Request Feature" 버튼으로 액세스를 요청하여 해당 기능을 사용할 수 있습니다 [학습 흐름](https://docs.roboflow.com/models/ko/readme.md).

미세 조정된 SAM3 모델은 Serverless Cloud API에서 실행할 수 없습니다. 다음에 배포하세요: [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) 또는 [자가 호스팅 추론](https://docs.roboflow.com/deployment/self-hosted/self-hosted). 호스팅된 `sam3` 이 페이지의 엔드포인트는 영향을 받지 않습니다.
{% endhint %}

* [프롬프트 가능한 개념 분할](#sam3-concept-segmentation-pcs) (**PCS**), 이미지 내 개념의 모든 인스턴스를 분할합니다. 개념은 텍스트 프롬프트, 예시 박스 또는 둘 다로 설명됩니다.
* [프롬프트 가능한 시각 분할](#sam3-visual-segmentation-pvs) (**PVS**), SAM2 방식처럼 포인트나 박스를 사용해 요청당 하나의 객체를 대화형으로 분할합니다.

엔드포인트를 선택하려면 이 표를 사용하세요:

<table data-search="false"><thead><tr><th>보유한 것</th><th>원하는 것</th><th>사용</th></tr></thead><tbody><tr><td>텍스트 설명(예: "person")</td><td>일치하는 모든 인스턴스의 마스크</td><td><code>/sam3/concept_segment</code></td></tr><tr><td>예시 객체 하나를 둘러싼 박스</td><td>유사한 모든 인스턴스의 마스크</td><td><code>/sam3/concept_segment</code></td></tr><tr><td>객체를 포함하거나 제외하기 위한 텍스트와 예시 박스</td><td>일치하는 모든 인스턴스의 마스크</td><td><code>/sam3/concept_segment</code></td></tr><tr><td>특정 객체 하나를 클릭하거나 박스로 지정</td><td>해당 객체만의 마스크</td><td><code>/sam3/visual_segment</code></td></tr></tbody></table>

다음 항목을 보내세요: [API 키](https://app.roboflow.com/settings/api) 다음 형식의 `Authorization: Bearer` 헤더를 모든 요청에 포함하세요. 기존의 `api_key` 쿼리 파라미터도 계속 작동하지만 권장되지 않습니다.

## SAM3 개념 분할(PCS)

`POST https://serverless.roboflow.com/sam3/concept_segment`

다음 항목의 각 항목은 `prompts` 하나의 개념을 설명합니다. 응답에는 하나의 `prompt_results` 프롬프트당 항목이 포함되며, 각 항목에는 발견된 모든 인스턴스가 들어 있습니다. 요청은 최대 16개의 프롬프트를 허용합니다.

### 텍스트 프롬프트

```python
import os
import requests

payload = {
    "image": {"type": "url", "value": "https://media.roboflow.com/inference/people-walking.jpg"},
    "prompts": [
        {"type": "text", "text": "person"},
        {"type": "text", "text": "backpack"},
    ],
    "output_prob_thresh": 0.5,
    "format": "polygon",  # 또는 "rle"
}

response = requests.post(
    "https://serverless.roboflow.com/sam3/concept_segment",
    headers={"Authorization": f"Bearer {os.environ['ROBOFLOW_API_KEY']}"},
    json=payload,
)
for prompt_result in response.json()["prompt_results"]:
    print(prompt_result["echo"], len(prompt_result["predictions"]), "instances")
```

이미지도 다음과 같이 인라인으로 보낼 수 있습니다: `{"type": "base64", "value": "<BASE64_IMAGE>"}`.

### 예시 박스 프롬프트

텍스트 대신 예시로 프롬프트를 줄 수 있습니다. 즉, 하나의 예시 객체를 둘러싼 박스입니다. 이 모델은 박스로 지정된 객체뿐 아니라 예시와 일치하는 모든 인스턴스를 찾습니다.

```python
payload = {
    "image": {"type": "url", "value": "https://media.roboflow.com/inference/people-walking.jpg"},
    "prompts": [
        {
            "type": "visual",
            "boxes": [{"x": 1409, "y": 705, "width": 112, "height": 183}],
            "box_labels": [1],
        }
    ],
    "output_prob_thresh": 0.5,
    "format": "polygon",
}
```

박스는 절대 픽셀 좌표를 사용합니다. 두 가지 형식을 사용할 수 있습니다:

* `{"x": ..., "y": ..., "width": ..., "height": ...}` 여기서 `x`, `y` 는 왼쪽 위 모서리입니다
* `{"x0": ..., "y0": ..., "x1": ..., "y1": ...}` 명시적인 모서리 좌표용

`box_labels` 다음 경우에 필요합니다: `boxes` 가 설정되면 박스마다 하나의 항목이 있어야 합니다: `1` 양성 예시를 표시합니다(이와 같은 객체를 찾음), `0` 음성 예시를 표시합니다(이와 같은 객체를 제외함).

### 텍스트와 예시를 결합한 프롬프트

하나의 프롬프트에 텍스트와 예시 박스를 함께 넣을 수 있습니다. 이는 시각적 예시로 텍스트 개념의 범위를 좁히거나, 음성 예시로 비슷하게 생긴 대상을 제외하는 데 유용합니다:

```python
payload = {
    "image": {"type": "url", "value": "https://media.roboflow.com/inference/people-walking.jpg"},
    "prompts": [
        {
            "type": "visual",
            "text": "person",
            "boxes": [
                {"x": 1409, "y": 705, "width": 112, "height": 183},
                {"x": 1216, "y": 496, "width": 124, "height": 184},
            ],
            "box_labels": [1, 0],
        }
    ],
    "output_prob_thresh": 0.5,
    "format": "polygon",
}
```

여기서 모델은 첫 번째(양성) 예시와 일치하는 사람들을 분할하는 동시에 두 번째(음성) 예시와 유사한 인스턴스는 억제합니다.

## SAM3 시각 분할(PVS)

`POST https://serverless.roboflow.com/sam3/visual_segment`

PVS는 클릭이나 박스로 지정된 특정 객체 하나를 분할합니다. 대화형 사람 개입형 마스크 정제를 위해 사용하세요. 개념의 모든 인스턴스가 필요할 때는 PCS를 사용하세요.

```python
import os
import requests

payload = {
    "image": {"type": "url", "value": "https://media.roboflow.com/inference/people-walking.jpg"},
    "prompts": {
        "prompts": [
            {
                "points": [{"x": 1465, "y": 796, "positive": True}],
                "box": {"x": 1465, "y": 796, "width": 112, "height": 183},
            }
        ]
    },
    "multimask_output": False,
    "format": "json",
}

response = requests.post(
    "https://serverless.roboflow.com/sam3/visual_segment",
    headers={"Authorization": f"Bearer {os.environ['ROBOFLOW_API_KEY']}"},
    json=payload,
)
prediction = response.json()["predictions"][0]
print(prediction["confidence"], len(prediction["masks"]), "polygons")
```

프롬프트에는 `points`, `box`, 또는 둘 다:

* `points` 는 절대 픽셀 좌표입니다. `"positive": true` 클릭한 영역을 포함하며, `false` 해당 영역을 제외합니다. 마스크를 세분화하려면 포인트를 더 추가하세요.
* `box` 중심 기준 좌표를 사용합니다: `x`, `y` 는 박스 중심입니다. 반면 PCS 박스는 왼쪽 위 기준입니다.

응답에는 해당 프롬프트에 대한 단일 최고 신뢰도 마스크가 포함됩니다. `multimask_output` 모델이 내부적으로 몇 개의 마스크 후보를 생성할지 제어합니다(true일 때는 3개). 하지만 응답에는 항상 가장 좋은 후보가 선택됩니다.

{% hint style="warning" %}
요청당 프롬프트 하나만 보내세요. 현재 하나의 PVS 요청에 여러 프롬프트를 넣어도 예측은 하나만 반환됩니다.
{% endhint %}

OpenCV를 사용하는 대화형 데모는 다음을 참조하세요: [GitHub Gist](https://gist.github.com/Erol444/4cbc33c6ac52d83c63f6f9d86ca8a7a4)이 비디오에서 사용된 것입니다:

{% embed url="<https://www.youtube.com/watch?v=01xrBzqHZ6c>" %}

## SAM3 추론 속도

지연 시간 측정 기준 [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 1개의 NVIDIA L4, 배치 크기 1, 워밍업 이후 평균 기준.

<table data-search="false"><thead><tr><th>모델</th><th>지연 시간(ms)</th></tr></thead><tbody><tr><td><code>sam3</code></td><td>251.4</td></tr></tbody></table>

단일 텍스트 프롬프트로 개념 분할을 수행해 측정했습니다.

## SAM3 API 엔드포인트

{% openapi src="/files/3fecd621ce163105fc360d141533eec93cdcf714" path="/sam3/concept\_segment" method="post" %}
[sam3.json](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-c718b36dd4197f87a2e72c28664c6d11516aefc8%2Fsam3.json?alt=media)
{% endopenapi %}

{% openapi src="/files/3fecd621ce163105fc360d141533eec93cdcf714" path="/sam3/visual\_segment" method="post" %}
[sam3.json](https://2225311784-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-c718b36dd4197f87a2e72c28664c6d11516aefc8%2Fsam3.json?alt=media)
{% endopenapi %}

## 자가 호스팅 Inference로 SAM3 실행

SAM3는 자체 하드웨어에서도 실행할 수 있으며, 다음을 사용해 프로세스 내에서 로드하거나 [`inference`](https://docs.roboflow.com/deployment/self-hosted/self-hosted) 패키지로 실행할 수 있고, GPU 컨테이너에서 서빙할 수도 있습니다.

### Docker에서 실행

```bash
docker run -it --rm -p 9001:9001 --gpus=all roboflow/inference-server:latest
```

서버는 동일한 `/sam3/concept_segment` 및 `/sam3/visual_segment` 위에 문서화된 엔드포인트를 다음 주소에서 제공합니다: `http://localhost:9001`.

### Python에서 모델 로드

```bash
pip install "inference-gpu[sam3]"
```

```python
import os

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

from inference.core.entities.requests.sam3 import Sam3Prompt
from inference.models.sam3 import SegmentAnything3

model = SegmentAnything3(model_id="sam3/sam3_final")

prompts = [
    # 개념의 모든 인스턴스를 분할
    Sam3Prompt(type="text", text="person"),
    # 예시 객체 하나를 박스로 지정하고 유사한 모든 인스턴스를 분할합니다.
    # box_labels: 1 = 양성 예시, 0 = 음성 예시.
    Sam3Prompt(
        type="visual",
        boxes=[Sam3Prompt.Box(x=1409, y=705, width=112, height=183)],
        box_labels=[1],
    ),
]

response = model.segment_image(
    image="path/to/your/image.jpg",
    prompts=prompts,
    output_prob_thresh=0.5,
    format="polygon",  # 또는 "rle", "json"
)

for prompt_result in response.prompt_results:
    print(prompt_result.echo.text, len(prompt_result.predictions), "instances")
```

가중치는 처음 사용할 때 자동으로 다운로드됩니다.

### Python에서의 대화형 분할

`Sam3ForInteractiveImageSegmentation` SAM2 스타일의 포인트 및 박스 인터페이스를 구현하여, 사람 개입형 마스크 정제를 지원합니다:

```python
from inference.models.sam3 import Sam3ForInteractiveImageSegmentation

model = Sam3ForInteractiveImageSegmentation(model_id="sam3/sam3_final")

embedding, img_shape, image_id = model.embed_image(image="path/to/image.jpg")

masks, scores, logits = model.segment_image(
    image_id=image_id,
    prompts={"points": [{"x": 500, "y": 400, "positive": True}]},
)
```

## Workflows에서 SAM3 사용

Workflows에는 두 개의 SAM3 이미지 블록이 있습니다 [Workflows](https://docs.roboflow.com/workflows):

* **SAM 3** 개념 분할을 실행합니다. 원하는 클래스를 다음에 입력하세요: `class_names` (예를 들어 `["person", "vehicle"]`) 그러면 이 블록은 다른 단계가 사용할 수 있는 인스턴스 분할 예측을 출력합니다.
* **SAM 3 Interactive** 프롬프트 가능한 시각 분할을 실행합니다. 라벨이 지정된 포인트를 제공하세요(kind `labeled_points`), 예를 들어 `[{"x": 320, "y": 240, "positive": true}]`, 그리고 필요에 따라 다른 모델의 탐지를 다음에 연결할 수 있습니다: `boxes` 필드. 각 박스는 별도의 프롬프트가 되며, 해당 클래스 이름이 예측 마스크로 전달됩니다.

### 비디오 추적

다음 **SAM3 Video Tracker** 블록(`roboflow_core/sam3_video@v1`)은 SAM3의 스트리밍 개념 추적기를 프레임 단위로 실행합니다. 개념을 다음에 텍스트로 제공하세요: `class_names`, 그리고 모델은 모든 프레임에서 탐지와 추적을 융합해 수행합니다. 개념과 일치하는 객체는 안정적인 `tracker_id`, 그리고 탐지기 기반 추적과 달리 스트림 도중 장면에 들어오는 객체도 재프롬프트 없이, 상위 탐지 모델 없이 자동으로 포착됩니다. 각 마스크는 일치한 개념을 클래스 이름으로, 모델의 탐지 점수를 신뢰도로 포함합니다( `threshold`, 기본값 `0.5`).

* **상태 유지형이며 로컬 전용입니다.** 추적 세션은 각 `video_metadata.video_identifier`. 블록에는 다음이 필요합니다: `WORKFLOWS_STEP_EXECUTION_MODE=local`, GPU, 그리고 지속적인 WebRTC 세션.
* **프롬프트 스케줄링 없음.** 개념 프롬프트는 세션당 한 번 등록되며, 세션은 스트림이 재시작되거나 `class_names` 가 변경될 때에만 다시 시드됩니다. 탐지기 기반(박스 프롬프트) 비디오 추적에는 [SAM2 페이지의](https://docs.roboflow.com/models/ko/supported-models/sam2.md), 여기에 다음도 허용됩니다: `sam3trackervideo` 으로 `model_id`.
* **모델.** `model_id` 기본값은 `sam3video`이며, 프레임별 스트리밍 인터페이스를 제공하는 HuggingFace transformers로 포팅한 SAM3 video 버전입니다. 네이티브 `sam3` 패키지의 비디오 예측기는 전체 비디오를 미리 필요로 하며 라이브 스트림에는 사용할 수 없습니다.

```python
from inference_sdk import InferenceHTTPClient, InferenceConfiguration
from inference_sdk.webrtc import StreamConfig, VideoFileSource

WORKFLOW = {
    "version": "1.0",
    "inputs": [{"type": "InferenceImage", "name": "image"}],
    "steps": [
        {
            "type": "roboflow_core/sam3_video@v1",
            "name": "tracker",
            "images": "$inputs.image",
            "class_names": ["person", "forklift"],
            "threshold": 0.5,
        },
    ],
    "outputs": [
        {
            "type": "JsonField",
            "name": "predictions",
            "selector": "$steps.tracker.predictions",
        }
    ],
}

client = InferenceHTTPClient(
    api_url="http://localhost:9001",
    api_key="YOUR_API_KEY",
).configure(InferenceConfiguration(api_key_transport="header"))

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-3D(베타)

SAM3-3D는 2D 이미지와 마스크를 3D 자산인 메쉬와 가우시안 스플랫으로 변환합니다.

{% hint style="warning" %}
SAM3-3D는 베타 버전입니다. 다음이 `SAM3_3D_OBJECTS_ENABLED` 플래그로 설정된 경우에만 사용할 수 있으며, 32GB 이상의 VRAM을 가진 GPU가 필요하고, 다음을 통해 실행됩니다: `inference` 패키지 또는 로컬 Inference 서버( Serverless Cloud API에는 없습니다).
{% endhint %}

종속성을 설치하세요(Python 3.10 권장):

```bash
pip install --no-cache-dir --no-build-isolation -r requirements/requirements.sam3_3d.txt
```

또는 3D 지원 GPU 컨테이너를 빌드하고 실행하세요:

```bash
docker build -t roboflow/roboflow-inference-server-gpu:dev -f docker/dockerfiles/Dockerfile.onnx.gpu.3d .
docker run --gpus all -p 9001:9001 roboflow/roboflow-inference-server-gpu:dev
```

**입력.** RGB 이미지와 `mask_input`이 포함된, 객체 영역을 정의합니다. 마스크는 다음 형식의 이진 배열로 허용됩니다(`(H, W)` 또는 `(N, H, W)`), COCO 평면 다각형, 점 쌍 다각형, RLE dict 또는 `sv.Detections` SAM2 또는 다른 분할 모델의 객체.

**출력.** `mesh_glb` (결합된 장면 메쉬, GLB), `gaussian_ply` (결합된 가우시안 스플랫, PLY), `objects` (객체별 `mesh_glb`, `gaussian_ply`및 `metadata` 회전, 이동, 스케일 정보가 포함된), 그리고 `시간`.

```python
import os

os.environ["SAM3_3D_OBJECTS_ENABLED"] = "true"
os.environ["SPARSE_ATTN_BACKEND"] = "flash_attn"
os.environ["ATTN_BACKEND"] = "flash_attn"

from inference import get_model
from inference.core.entities.requests.sam3_3d import Sam3_3D_Objects_InferenceRequest

model = get_model("sam3-3d-objects", api_key="YOUR_API_KEY")

request = Sam3_3D_Objects_InferenceRequest(
    image={"type": "file", "value": "image.jpg"},
    mask_input=mask_polygons,  # polygons, binary masks, or RLE
)

response = model.infer_from_request(request)

if response.mesh_glb is not None:
    with open("out_mesh.glb", "wb") as f:
        f.write(response.mesh_glb)

for index, obj in enumerate(response.objects):
    if obj.gaussian_ply is not None:
        with open(f"out_object_{index}.ply", "wb") as f:
            f.write(obj.gaussian_ply)
```

설정 `SPARSE_ATTN_BACKEND` 및 `ATTN_BACKEND` 로 `flash_attn` 파이프라인을 가속합니다. Workflows에서 SAM3-3D는 로컬 실행과 원격 실행을 다음을 통해 `sam3_3d_infer()` 클라이언트 메서드 또는 `/sam3_3d/infer` 엔드포인트.

## 참고하세요

* [SAM2](https://docs.roboflow.com/models/ko/supported-models/sam2.md) - 포인트 및 박스 프롬프트 분할, 그리고 검출기 기반 비디오 추적.
* [Segment Anything (SAM)](https://docs.roboflow.com/models/ko/supported-models/sam.md) - 원래의 단일 객체 모델.
