SAM2

Meta の SAM2 モデルを Serverless Cloud API 経由で使用します

Metaの Segment Anything Model 2 当社の推論 Serverless Cloud API。SAM2 は、ポイントとバウンディングボックスをプロンプトとして受け付ける、プロンプト指定可能な視覚セグメンテーションモデルです。SAM2 のエンドポイントは 2 つあります:

• /sam2/embed_image、画像埋め込みを生成してキャッシュします

• /sam2/segment_image、与えられたプロンプトに対するインスタンスセグメンテーションマスクを返します

コード例

HTTP エンドポイントを直接使って SAM2 を実行するには、 curlまたは inference-sdk ラッパーを使用します。

HTTP（curl）

1

API キーを取得する

Roboflow アカウントを作成し、キーを次の場所で見つけてください。 Roboflow API 設定ページ そしてシェルから使えるようにします。

export ROBOFLOW_API_KEY="your-key-here"

2

モデルを実行する

次の /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"
  }'

SDK（Python）

1

API キーを取得する

Roboflow アカウントを作成し、キーを次の場所で見つけてください。 Roboflow API 設定ページ そしてシェルから使えるようにします。

export ROBOFLOW_API_KEY="your-key-here"

2

依存関係をインストールする

これらのパッケージはモデルを呼び出し、その結果を描画します:

pip install -U inference-sdk supervision opencv-python

3

モデルを実行する

単一の正のポイントプロンプトでセグメンテーションエンドポイントを呼び出し、返されたポリゴンを 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 1台のNVIDIA L4、バッチサイズ1、ウォームアップ後の平均で測定。

モデル	レイテンシ（ms）
sam2	177.7

で測定 segment_image の hiera_large のチェックポイント。SAM2 は画像埋め込みをキャッシュするため、この図では呼び出しごとに新しい画像を使い、エンコードとデコードの全コストを反映しています。すでにエンコード済みの画像に再度プロンプトする方が大幅に高速です。

設定してください api_url をデプロイ先に合わせてください：

• https://serverless.roboflow.com Serverless Cloud API 用です。

• http://localhost:9001 ローカルの Inference サーバー。

• あなたの 専用デプロイメント プライベートエンドポイント用の URL。

埋め込みのキャッシュやボックスプロンプトを含む追加の使用方法については、 推論ドキュメント.

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

SAM2 は inference パッケージから直接読み込むことも、自分で実行する GPU コンテナから提供することもできます。画像を自前のハードウェアに保持したい場合や、同じ画像に何度も再プロンプトする場合に適した方法です。

Dockerで実行

inference リポジトリのルートから 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 を flash attention で使う場合、 既知の問題 があり、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 Video Tracker ブロック（roboflow_core/segment_anything_2_video@v1）は SAM2 のストリーミング動画予測器をフレームごとに実行し、動画ごとの時間的メモリを保持することで、オブジェクト ID がフレーム間で維持されます。上流の検出器からのバウンディングボックスを入力すると、各ボックスをマスクに変換して以後のフレームで追跡し、その tracker_id SAM2 がオブジェクトを追跡している限り安定したままです。マスクには、それを生成した検出のクラス名、クラス ID、信頼度が引き継がれます。

• ステートフルでローカル専用です。 このブロックは、 video_metadata.video_identifierごとに 1 つの追跡セッションを保持するため、 WORKFLOWS_STEP_EXECUTION_MODE=local多くのストリームを多重化できますが、セッションはプロセスメモリ内に存在します。

• 必要です。 prompt_mode は、検出ボックスをプロンプトとして消費するタイミングを制御します: first_frame （デフォルト）セッションごとに 1 回だけプロンプトし、その後は静かに追跡します; 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 Video Tracker ブロックを次の SAM3 ページ.

Workflows での実行モード

画像 Workflow で使用すると、SAM2 は 2 つのモードのいずれかで動作します:

• ローカル実行：モデルはあなたの Inference サーバー上で実行されます（GPU を強く推奨）。

• リモート実行: モデルはリモートの Inference サーバー上で HTTP 経由で呼び出され、 sam2_segment_image() クライアントメソッド

こちらも参照

• SAM3 - テキストプロンプトから概念のすべてのインスタンスをセグメント化します。

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