> 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/roboflow/roboflow-ko/deploy/supported-models/sam3.md). # SAM3 우리는 Meta의 [Segment Anything Model 3](https://github.com/facebookresearch/sam3) 추론을 [Serverless Hosted API](/roboflow/roboflow-ko/deploy/serverless-hosted-api-v2.md). Roboflow에서는 두 가지 SAM3 엔드포인트를 제공합니다: {% hint style="info" %} Roboflow에서 SAM3 모델을 학습하려면 유료 [플랜](/roboflow/roboflow-ko/billing/plans.md) 포함하는 [사용량 기반 과금](/roboflow/roboflow-ko/billing/credits.md). 그다음 SAM3 architecture의 "Request Feature" 버튼으로 기능 사용 권한을 요청할 수 있습니다 [학습 흐름](/roboflow/roboflow-ko/train/train.md). {% endhint %} * [프롬프트 가능 개념 세분화](#concept-segmentation-pcs) (**PCS**), 이미지 내 개념의 모든 인스턴스를 분할합니다. 개념은 텍스트 프롬프트, 예시 박스 또는 둘 다로 설명됩니다. * [프롬프트 가능 시각 세분화](#visual-segmentation-pvs) (**PVS**), SAM2 스타일로 점이나 박스를 사용해 요청당 하나의 객체를 대화형으로 분할합니다. 이 표를 사용해 엔드포인트를 선택하세요:
보유 중인 것원하는 것사용
텍스트 설명(예: "person")일치하는 모든 인스턴스의 마스크/sam3/concept_segment
하나의 예시 객체를 둘러싼 박스유사한 모든 인스턴스의 마스크/sam3/concept_segment
객체를 포함하거나 제외하기 위한 텍스트와 예시 박스일치하는 모든 인스턴스의 마스크/sam3/concept_segment
특정 하나의 객체를 클릭하거나 박스로 지정그 객체만의 마스크/sam3/visual_segment
당신의 [API 키](https://app.roboflow.com/settings/api) 로 `api_key` 쿼리 매개변수로 모든 요청에 전달하세요. ## 개념 세분화 (PCS) `POST https://serverless.roboflow.com/sam3/concept_segment` 의 각 항목은 `프롬프트` 하나의 개념을 설명합니다. 응답에는 각 프롬프트당 하나의 `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", params={"api_key": os.environ["ROBOFLOW_API_KEY"]}, json=payload, ) for prompt_result in response.json()["prompt_results"]: print(prompt_result["echo"], len(prompt_result["predictions"]), "개체") ``` 이미지는 다음과 같이 인라인으로도 보낼 수 있습니다: `{"type": "base64", "value": ""}`. ### 예시 박스 프롬프트 텍스트 대신 하나의 예시 객체를 둘러싼 박스인 exemplar로 프롬프트를 지정할 수 있습니다. 모델은 박스에 둘러싸인 객체뿐 아니라 예시에 일치하는 모든 인스턴스를 찾습니다. ```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", } ``` 여기서 모델은 첫 번째(양성) 예시에 일치하는 사람을 분할하면서 두 번째(음성) 예시와 유사한 인스턴스는 억제합니다. ## 시각 세분화 (PVS) `POST https://serverless.roboflow.com/sam3/visual_segment` PVS는 클릭이나 박스로 지정된 특정 하나의 객체를 분할합니다. 대화형 human-in-the-loop 마스크 정제에는 이것을 사용하고, 개념의 모든 인스턴스를 원할 때는 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", params={"api_key": os.environ["ROBOFLOW_API_KEY"]}, json=payload, ) prediction = response.json()["predictions"][0] print(prediction["confidence"], len(prediction["masks"]), "폴리곤") ``` 프롬프트에는 `점`, `박스` 또는 둘 다를 포함할 수 있습니다: * `점` 는 절대 픽셀 좌표입니다. `"positive": true` 클릭한 영역을 포함하고, `false` 는 이를 제외합니다. 마스크를 정제하려면 점을 더 추가하세요. * `박스` 는 중심 기준 좌표를 사용합니다: `x`, `y` 는 박스 중심이며, 좌상단 기준인 PCS 박스와는 다릅니다. 응답에는 프롬프트에 대한 가장 높은 신뢰도의 단일 마스크가 포함됩니다. `multimask_output` 는 모델이 내부적으로 생성하는 마스크 후보 수를 제어합니다(true일 때 3개). 하지만 응답에는 항상 가장 좋은 후보가 선택됩니다. {% hint style="warning" %} 요청당 프롬프트 하나를 보내세요. 현재 하나의 PVS 요청에 여러 프롬프트를 보내면 하나의 예측만 반환됩니다. {% endhint %} OpenCV를 사용하는 대화형 데모는 이 [GitHub Gist](https://gist.github.com/Erol444/4cbc33c6ac52d83c63f6f9d86ca8a7a4), 이 비디오에서 사용되었습니다: {% embed url="" %} ## 추론 속도 다음과 같이 측정한 지연 시간 [Roboflow Inference](https://inference.roboflow.com/) NVIDIA L4 1개, 배치 크기 1, 워밍업 후 평균.
모델지연 시간(ms)
sam3251.4
단일 텍스트 프롬프트의 개념 세분화로 측정했습니다. ## 엔드포인트 ## SAM3 PCS (promptable concept segmentation) > \*\*Concept Segmentation (Text Prompts)\*\*\ > \ > Allows you to segment objects using text prompts.\ > \ > \*\*Image Input\*\*: The \`image\` field accepts either:\ > \- \`{"type": "url", "value": "\"}\` - A publicly accessible image URL\ > \- \`{"type": "base64", "value": "\"}\` - Base64 encoded image data\ > \ > \*\*Prompts\*\*: Each prompt in the \`prompts\` array should have \`type: "text"\` and a \`text\` field with the object description. ```json {"openapi":"3.1.0","info":{"title":"Roboflow SAM3 API","version":"0.64.4"},"servers":[{"url":"https://serverless.roboflow.com"}],"paths":{"/sam3/concept_segment":{"post":{"summary":"SAM3 PCS (promptable concept segmentation)","description":"**Concept Segmentation (Text Prompts)**\n\nAllows you to segment objects using text prompts.\n\n**Image Input**: The `image` field accepts either:\n- `{\"type\": \"url\", \"value\": \"\"}` - A publicly accessible image URL\n- `{\"type\": \"base64\", \"value\": \"\"}` - Base64 encoded image data\n\n **Prompts**: Each prompt in the `prompts` array should have `type: \"text\"` and a `text` field with the object description.","operationId":"sam3_segment_image_sam3_concept_segment_post","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","title":"API Key"},"description":"Your Roboflow API Key. Get one at https://app.roboflow.com/settings/api"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sam3SegmentationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sam3SegmentationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Sam3SegmentationRequest":{"properties":{"image":{"$ref":"#/components/schemas/InferenceRequestImage","description":"The image to be segmented."},"prompts":{"items":{"$ref":"#/components/schemas/Sam3Prompt"},"type":"array","minItems":1,"title":"Prompts","description":"List of prompts (text and/or visual)"},"format":{"type":"string","title":"Format","description":"One of 'polygon', 'rle'","default":"polygon"},"image_id":{"type":"string","title":"Image Id","description":"Optional ID for caching embeddings."},"output_prob_thresh":{"type":"number","title":"Output Prob Thresh","description":"Score threshold for outputs.","default":0.5},"model_id":{"type":"string","title":"Model Id","description":"The model ID of SAM3. Use 'sam3/sam3_final' to target the generic base model.","default":"sam3/sam3_final"},"nms_iou_threshold":{"type":"number","title":"Nms Iou Threshold","description":"IoU threshold for cross-prompt NMS. If not set, NMS is disabled. Must be in [0.0, 1.0] when set."}},"type":"object","required":["image","prompts"],"title":"Sam3SegmentationRequest"},"InferenceRequestImage":{"properties":{"type":{"type":"string","title":"Type","description":"The type of image data provided, one of `url`, `base64`"},"value":{"type":"string","title":"Value","description":"Image data corresponding to the image type, if type = 'url' then value is a string containing the url of an image, else if type = 'base64' then value is a string containing base64 encoded image data."}},"type":"object","required":["type"],"title":"InferenceRequestImage","description":"Image data for inference request.\n\nAttributes:\n type (str): The type of image data provided, one of 'url', 'base64', or 'numpy'.\n value (Optional[Any]): Image data corresponding to the image type."},"Sam3Prompt":{"properties":{"type":{"type":"string","title":"Type","description":"Hint: `text` or `visual`"},"text":{"type":"string","title":"Text","description":"Text prompt describing the object to segment"},"output_prob_thresh":{"type":"number","title":"Output Prob Thresh","description":"Score threshold for this prompt's outputs. Overrides request-level threshold if set."},"boxes":{"items":{"anyOf":[{"$ref":"#/components/schemas/Box"},{"$ref":"#/components/schemas/BoxXYXY"}]},"type":"array","title":"Boxes","description":"Absolute pixel boxes as either XYWH or XYXY entries"},"box_labels":{"items":{"anyOf":[{"type":"integer"},{"type":"boolean"}]},"type":"array","title":"Box Labels","description":"List of 0/1 or booleans for boxes"}},"type":"object","required":["type"],"title":"Sam3Prompt","description":"Unified prompt that can contain text and/or geometry. Absolute pixel coordinates are used for boxes."},"Sam3SegmentationResponse":{"properties":{"prompt_results":{"items":{"$ref":"#/components/schemas/Sam3PromptResult"},"type":"array","title":"Prompt Results","description":"Results for each prompt in the request"},"time":{"type":"number","title":"Time","description":"The time in seconds it took to produce the segmentation including preprocessing"}},"type":"object","required":["prompt_results","time"],"title":"Sam3SegmentationResponse"},"Sam3PromptResult":{"properties":{"prompt_index":{"type":"integer","title":"Prompt Index","description":"Index of the prompt this result corresponds to"},"echo":{"$ref":"#/components/schemas/Sam3PromptEcho","description":"Echo of the original prompt for reference"},"predictions":{"items":{"$ref":"#/components/schemas/Sam3SegmentationPrediction"},"type":"array","title":"Predictions","description":"Segmentation predictions for this prompt"}},"type":"object","required":["prompt_index","predictions"],"title":"Sam3PromptResult"},"Sam3PromptEcho":{"properties":{"prompt_index":{"type":"integer","title":"Prompt Index"},"type":{"type":"string","title":"Type","description":"The prompt type (`text` or `visual`)"},"text":{"type":"string","title":"Text","description":"The text prompt if type is `text`"},"num_boxes":{"type":"integer","title":"Num Boxes","description":"Number of bounding boxes in the prompt"}},"type":"object","title":"Sam3PromptEcho"},"Sam3SegmentationPrediction":{"properties":{"format":{"type":"string","title":"Format","description":"The format of the mask data, either `polygon` or `rle`"},"confidence":{"type":"number","title":"Confidence","description":"Confidence score for this prediction"},"masks":{"items":{"items":{"items":{"type":"number"},"type":"array","minItems":2,"maxItems":2},"type":"array"},"type":"array","title":"Masks","description":"Array of polygons, each polygon is an array of [x, y] coordinate points"}},"type":"object","required":["format","confidence","masks"],"title":"Sam3SegmentationPrediction"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## SAM3 PVS (promptable visual segmentation) > \*\*Interactive Segmentation (SAM 2 Style)\*\*\ > \ > SAM 3 also supports interactive segmentation using points and boxes.\ > \ > \*\*Image Input\*\*: The \`image\` field accepts either:\ > \- \`{"type": "url", "value": "\"}\` - A publicly accessible image URL\ > \- \`{"type": "base64", "value": "\"}\` - Base64 encoded image data\ > \ > \> \*\*Note\*\*: NumPy arrays are NOT supported on the serverless API. Use URL or base64 encoding only.\ > \ > \*\*Prompts\*\*: Support point-based prompts with positive/negative clicks for interactive segmentation. ```json {"openapi":"3.1.0","info":{"title":"Roboflow SAM3 API","version":"0.64.4"},"servers":[{"url":"https://serverless.roboflow.com"}],"paths":{"/sam3/visual_segment":{"post":{"summary":"SAM3 PVS (promptable visual segmentation)","description":"**Interactive Segmentation (SAM 2 Style)**\n\nSAM 3 also supports interactive segmentation using points and boxes.\n\n**Image Input**: The `image` field accepts either:\n- `{\"type\": \"url\", \"value\": \"\"}` - A publicly accessible image URL\n- `{\"type\": \"base64\", \"value\": \"\"}` - Base64 encoded image data\n\n> **Note**: NumPy arrays are NOT supported on the serverless API. Use URL or base64 encoding only.\n\n**Prompts**: Support point-based prompts with positive/negative clicks for interactive segmentation.","operationId":"sam3_visual_segment_sam3_visual_segment_post","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string","title":"API Key"},"description":"Your Roboflow API Key. Get one at https://app.roboflow.com/settings/api"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sam2SegmentationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sam2SegmentationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Sam2SegmentationRequest":{"properties":{"image":{"$ref":"#/components/schemas/InferenceRequestImage","description":"The image to be segmented."},"image_id":{"type":"string","title":"Image Id","description":"The ID of the image to be segmented used to retrieve cached embeddings. If an embedding is cached, it will be used instead of generating a new embedding. If no embedding is cached, a new embedding will be generated and cached."},"prompts":{"$ref":"#/components/schemas/Sam2PromptSet","description":"A list of prompts for masks to predict. Each prompt can include a bounding box and / or a set of postive or negative points."},"format":{"type":"string","title":"Format","description":"The format of the response. Must be one of 'json', 'rle', or 'binary'. If binary, masks are returned as binary numpy arrays. If json, masks are converted to polygons. If rle, masks are converted to RLE format.","default":"json"},"sam2_version_id":{"type":"string","title":"Sam2 Version Id","description":"The version ID of SAM to be used for this request. Must be one of hiera_tiny, hiera_small, hiera_large, hiera_b_plus","default":"hiera_large"},"multimask_output":{"type":"boolean","title":"Multimask Output","description":"If true, the model will return three masks. For ambiguous input prompts (such as a single click), this will often produce better masks than a single prediction.","default":true},"save_logits_to_cache":{"type":"boolean","title":"Save Logits To Cache","description":"If True, saves the low-resolution logits to the cache for potential future use.","default":false},"load_logits_from_cache":{"type":"boolean","title":"Load Logits From Cache","description":"If True, attempts to load previously cached low-resolution logits for the given image and prompt set.","default":false}},"type":"object","required":["image"],"title":"Sam2SegmentationRequest","description":"SAM2 visual segmentation request."},"InferenceRequestImage":{"properties":{"type":{"type":"string","title":"Type","description":"The type of image data provided, one of `url`, `base64`"},"value":{"type":"string","title":"Value","description":"Image data corresponding to the image type, if type = 'url' then value is a string containing the url of an image, else if type = 'base64' then value is a string containing base64 encoded image data."}},"type":"object","required":["type"],"title":"InferenceRequestImage","description":"Image data for inference request.\n\nAttributes:\n type (str): The type of image data provided, one of 'url', 'base64', or 'numpy'.\n value (Optional[Any]): Image data corresponding to the image type."},"Sam2SegmentationResponse":{"properties":{"prompt_results":{"items":{"$ref":"#/components/schemas/Sam2PromptResult"},"type":"array","title":"Prompt Results","description":"Results for each prompt in the request"},"time":{"type":"number","title":"Time","description":"The time in seconds it took to produce the segmentation including preprocessing"}},"type":"object","required":["prompt_results","time"],"title":"Sam2SegmentationResponse"},"Sam2PromptResult":{"properties":{"prompt_index":{"type":"integer","title":"Prompt Index","description":"Index of the prompt this result corresponds to"},"predictions":{"items":{"$ref":"#/components/schemas/Sam2SegmentationPrediction"},"type":"array","title":"Predictions","description":"Segmentation predictions for this prompt"}},"type":"object","required":["prompt_index","predictions"],"title":"Sam2PromptResult"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ```