SAM3

Meta の SAM3 モデルを Serverless Cloud API で使用します

Meta の Segment Anything Model 3 推論を、当社の サーバーレス Cloud APIでサポートしています。2 種類の SAM3 エンドポイントを提供しています：

Roboflow での SAM3 モデルのトレーニングは、有料の プラン で利用可能です。これには 従量課金が含まれます。そこから、SAM3 アーキテクチャの「Request Feature」ボタンを使用して、機能を利用するためのアクセスをリクエストできます トレーニングフロー.

ファインチューニング済みの SAM3 モデルは、サーバーレス Cloud API では実行できません。 専用デプロイメント または セルフホスト型 Inferenceにデプロイしてください。ホスト型の sam3 エンドポイントは、このページでは影響を受けません。

• プロンプト可能なコンセプトセグメンテーション (PCS）は、画像内のコンセプトのすべてのインスタンスをセグメント化します。コンセプトはテキストプロンプト、見本ボックス、またはその両方で記述されます。

• プロンプト可能なビジュアルセグメンテーション (PVS）は、SAM2 と同様の方式で、ポイントまたはボックスからリクエストごとに 1 つのオブジェクトを対話的にセグメント化します。

この表を使用してエンドポイントを選択してください：

あなたが持っているもの	あなたが望むもの	使用するもの
テキストによる説明（例：「person」）	一致するすべてのインスタンスのマスク	/sam3/concept_segment
1 つの見本オブジェクトを囲むボックス	類似するすべてのインスタンスのマスク	/sam3/concept_segment
含めるまたは除外するオブジェクト用のテキストと見本ボックス	一致するすべてのインスタンスのマスク	/sam3/concept_segment
特定の 1 つのオブジェクト上のクリックまたはボックス	そのオブジェクトだけのマスク	/sam3/visual_segment

あなたの API キー を api_key クエリパラメータとして、すべてのリクエストに渡します。

コンセプトセグメンテーション（PCS）

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

内の各エントリ prompts は 1 つのコンセプトを記述します。レスポンスには 1 つの prompt_results エントリがプロンプトごとに含まれ、それぞれに見つかったすべてのインスタンスが保持されます。リクエストでは最大 16 個のプロンプトを受け付けます。

テキストプロンプト

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"]), "instances")

画像は次の形式でインライン送信することもできます {"type": "base64", "value": "<BASE64_IMAGE>"}.

見本ボックスプロンプト

テキストの代わりに、見本（1 つの見本オブジェクトを囲むボックス）でプロンプトを指定できます。モデルはボックスで囲まれたオブジェクトだけでなく、見本に一致するすべてのインスタンスを検出します。

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",
}

ボックスは絶対ピクセル座標を使用します。次の 2 つの形式が受け付けられます：

• {"x": ..., "y": ..., "width": ..., "height": ...} ここで x, y は左上隅です

• {"x0": ..., "y0": ..., "x1": ..., "y1": ...} 明示的な角の指定用

box_labels は、 boxes が設定されている場合に必須で、ボックスごとに 1 つのエントリが必要です： 1 はポジティブな見本を示します（このようなオブジェクトを検出）。 0 はネガティブな見本を示します（このようなオブジェクトを除外）。

テキストと見本を組み合わせたプロンプト

1 つのプロンプトにテキストと見本ボックスの両方を含めることができます。これは、視覚的な例でテキストコンセプトを絞り込む場合や、ネガティブな見本で類似物を除外する場合に便利です：

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",
}

ここでは、モデルは最初の（ポジティブな）見本に一致する人物をセグメント化しながら、2 番目の（ネガティブな）見本に類似するインスタンスを抑制します。

ビジュアルセグメンテーション（PVS）

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

PVS は、クリックまたはボックスで指定された 1 つの特定オブジェクトをセグメント化します。対話的な、人間参加型のマスク調整に使用してください。コンセプトのすべてのインスタンスが必要な場合は PCS を使用してください。

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"]), "polygons")

プロンプトには ポイント、 ボックス、またはその両方を含めることができます：

• ポイント は絶対ピクセル座標です。 "positive": true はクリックした領域を含め、 false はその領域を除外します。マスクを調整するには、さらにポイントを追加してください。

• ボックス は中心基準の座標を使用します： x, y はボックスの中心であり、左上基準の PCS ボックスとは異なります。

レスポンスには、プロンプトに対する信頼度が最も高い 1 つのマスクが含まれます。 multimask_output はモデルが生成する内部マスク候補の数を制御します（true の場合は 3 つ）が、レスポンスには常に最良の候補が選択されます。

リクエストごとに 1 つのプロンプトを送信してください。現在、1 つの PVS リクエストに複数のプロンプトを含めても、返される予測は 1 つだけです。

OpenCV を使用した対話型デモについては、こちらの GitHub Gistを参照してください。これはこの動画で使用されています：

推論速度

レイテンシーの測定には Roboflow Inference を使用し、NVIDIA L4 1 台、バッチサイズ 1、ウォームアップ後の平均値です。

モデル	レイテンシー（ms）
sam3	251.4

単一テキストプロンプトによるコンセプトセグメンテーションで測定。

エンドポイント

SAM3 PCS (promptable concept segmentation)

post

Concept Segmentation (Text Prompts)

Allows you to segment objects using text prompts.

Image Input: The image field accepts either:

• {"type": "url", "value": "<IMAGE_URL>"} - A publicly accessible image URL

• {"type": "base64", "value": "<BASE64_DATA>"} - Base64 encoded image data

Prompts: Each prompt in the prompts array should have type: "text" and a text field with the object description.

クエリパラメータ

api_keystring必須

Your Roboflow API Key. Get one at https://app.roboflow.com/settings/api

本文

formatstringオプション

One of 'polygon', 'rle'

Default: polygon

image_idstringオプション

Optional ID for caching embeddings.

output_prob_threshnumberオプション

Score threshold for outputs.

Default: 0.5

model_idstringオプション

The model ID of SAM3. Use 'sam3/sam3_final' to target the generic base model.

Default: sam3/sam3_final

nms_iou_thresholdnumberオプション

IoU threshold for cross-prompt NMS. If not set, NMS is disabled. Must be in [0.0, 1.0] when set.

レスポンス

200

Successful Response

application/json

timenumber必須

The time in seconds it took to produce the segmentation including preprocessing

422

Validation Error

application/json

post/sam3/concept_segment

POST /sam3/concept_segment?api_key=text HTTP/1.1
Host: serverless.roboflow.com
Content-Type: application/json
Accept: */*
Content-Length: 206

{
  "image": {
    "type": "url",
    "value": "https://media.roboflow.com/notebooks/examples/dog.jpeg"
  },
  "prompts": [
    {
      "type": "text",
      "text": "person"
    },
    {
      "type": "text",
      "text": "car"
    }
  ],
  "output_prob_thresh": 0.5,
  "format": "polygon"
}

{
  "prompt_results": [
    {
      "prompt_index": 0,
      "echo": {
        "prompt_index": 0,
        "type": "text",
        "text": "dog",
        "num_boxes": 0
      },
      "predictions": [
        {
          "masks": [
            [
              [
                345,
                251
              ],
              [
                344,
                252
              ],
              [
                343,
                253
              ]
            ]
          ],
          "confidence": 0.89453125,
          "format": "polygon"
        }
      ]
    }
  ],
  "time": 0.221
}

SAM3 PVS (promptable visual segmentation)

post

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": "<IMAGE_URL>"} - A publicly accessible image URL

• {"type": "base64", "value": "<BASE64_DATA>"} - 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.

クエリパラメータ

api_keystring必須

Your Roboflow API Key. Get one at https://app.roboflow.com/settings/api

本文

SAM2 visual segmentation request.

image_idstringオプション

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.

Example: image_id

formatstringオプション

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: jsonExample: json

sam2_version_idstringオプション

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_largeExample: hiera_large

multimask_outputbooleanオプション

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: trueExample: true

save_logits_to_cachebooleanオプション

If True, saves the low-resolution logits to the cache for potential future use.

Default: false

load_logits_from_cachebooleanオプション

If True, attempts to load previously cached low-resolution logits for the given image and prompt set.

Default: false

レスポンス

200

Successful Response

application/json

timenumber必須

The time in seconds it took to produce the segmentation including preprocessing

422

Validation Error

application/json

post/sam3/visual_segment

POST /sam3/visual_segment?api_key=text HTTP/1.1
Host: serverless.roboflow.com
Content-Type: application/json
Accept: */*
Content-Length: 294

{
  "image": {
    "type": "url",
    "value": "http://www.example-image-url.com"
  },
  "image_id": "image_id",
  "prompts": [
    {
      "prompts": [
        {
          "points": [
            {
              "positive": true,
              "x": 100,
              "y": 100
            }
          ]
        }
      ]
    }
  ],
  "format": "json",
  "sam2_version_id": "hiera_large",
  "multimask_output": true,
  "save_logits_to_cache": false,
  "load_logits_from_cache": false
}

{
  "prompt_results": [
    {
      "prompt_index": 1,
      "predictions": []
    }
  ],
  "time": 1
}

Inference（セルフホスト型）で使用

SAM3 は独自のハードウェアでも実行でき、 inference パッケージでインプロセスとして読み込むか、GPU コンテナから提供できます。

Docker で実行

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

サーバーは同じ /sam3/concept_segment および /sam3/visual_segment 上記で文書化されたエンドポイントを次の場所で公開します http://localhost:9001.

Python でモデルを読み込む

pip install "inference-gpu[sam3]"

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"),
    # 1 つの見本オブジェクトをボックスで囲み、類似するすべてのインスタンスをセグメント化。
    # 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 スタイルのポイントおよびボックスインターフェースを実装しています：

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 で使用

2 つの SAM3 画像ブロックが Workflows:

• SAM 3 で利用できます。コンセプトセグメンテーションを実行します。必要なクラスを class_names に入力します（例： ["person", "vehicle"]）。このブロックは、他のステップで利用できるインスタンスセグメンテーション予測を出力します。

• SAM 3 Interactive はプロンプト可能なビジュアルセグメンテーションを実行します。ラベル付きポイント（種類： 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ごとに 1 つ維持されます。このブロックには WORKFLOWS_STEP_EXECUTION_MODE=local、GPU、および永続的な WebRTC セッションが必要です。

• プロンプトのスケジューリングはありません。 コンセプトプロンプトはセッションごとに一度登録されます。ストリームの再開時または class_names が変更された場合にのみ、セッションは再シードされます。検出器駆動型（ボックスプロンプト）の動画トラッキングには、 SAM2 ページの SAM2 Video Tracker ブロックを使用してください。これは sam3trackervideo を model_id.

• としても受け付けます。モデル。 model_id のデフォルトは sam3videoで、フレームごとのストリーミングインターフェースを公開する SAM3 video の HuggingFace transformers ポートです。ネイティブの sam3 パッケージの動画予測器は動画全体を事前に必要とするため、ライブストリームには使用できません。

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/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",
)

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 アセット（メッシュおよびガウシアンスプラット）に変換します。

SAM3-3D はベータ版です。 SAM3_3D_OBJECTS_ENABLED フラグが設定されている場合にのみ利用可能で、32 GB 以上の VRAM を搭載した GPU が必要です。また、 inference パッケージまたはローカルの Inference サーバー経由で実行されます（サーバーレス Cloud API にはありません）。

依存関係をインストールします（Python 3.10 推奨）：

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

または、3D 対応 GPU コンテナをビルドして実行します：

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 辞書、または sv.Detections オブジェクトとして、SAM2 または別のセグメンテーションモデルから受け付けられます。

出力。 mesh_glb （統合シーンメッシュ、GLB）、 gaussian_ply （統合ガウシアンスプラット、PLY）、 objects （オブジェクトごとの mesh_glb, gaussian_ply、および metadata （回転、平行移動、スケールを含む）、および time.

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,  # ポリゴン、バイナリマスク、または 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 - 点とボックスによるプロンプト付きセグメンテーションに加え、検出器を起点としたビデオトラッキング。

• Segment Anything (SAM) - 元の単一オブジェクトモデル。