SAM3
Meta の SAM3 モデルを Serverless Cloud API 経由で使用します
当社は Meta の Segment Anything Model 3 の推論を 当社の Serverless Cloud API 経由でサポートしています。2 種類の SAM3 エンドポイントを提供しています:
プロンプト指定可能な概念セグメンテーション (PCS)は、画像内の概念の各インスタンスをセグメントします。概念は、テキストプロンプト、例示ボックス、またはその両方で記述されます。
プロンプト指定可能な視覚セグメンテーション (PVS)は、SAM2 と同様のスタイルで、クリックまたはボックスから 1 回のリクエストにつき 1 つのオブジェクトを対話的にセグメントします。
この表を使ってエンドポイントを選んでください:
テキストによる説明(例: "person")
一致する各インスタンスのマスク
/sam3/concept_segment
1 つの例示オブジェクトの周囲のボックス
類似する各インスタンスのマスク
/sam3/concept_segment
オブジェクトを含める/除外するためのテキストと例示ボックス
一致する各インスタンスのマスク
/sam3/concept_segment
1 つの特定オブジェクト上のクリックまたはボックス
そのオブジェクトのみのマスク
/sam3/visual_segment
あなたの API キーを で Authorization: Bearer ヘッダーに入れて、すべてのリクエストで送信してください。従来の api_key クエリパラメータもまだ使えますが、推奨されません。
SAM3 概念セグメンテーション(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": "人"},
{"type": "text", "text": "バックパック"},
],
"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"]), "インスタンス")画像はインラインでも送信できます: {"type": "base64", "value": "<BASE64_IMAGE>"}.
例示ボックスプロンプト
テキストの代わりに、例示として 1 つの例示オブジェクトの周囲のボックスを使ってプロンプトできます。モデルは、ボックスで囲ったオブジェクトだけでなく、例に一致するすべてのインスタンスを見つけます。
ボックスは絶対ピクセル座標を使用します。受け付ける形式は 2 つあります:
{"x": ..., "y": ..., "width": ..., "height": ...}ここでx,yは左上隅です{"x0": ..., "y0": ..., "x1": ..., "y1": ...}明示的な角を指定する場合
box_labels は boxes が設定されている場合に必要で、ボックスごとに 1 件のエントリを持つ必要があります: 1 は正の例示を示します(これに似たオブジェクトを見つける)。 0 は負の例示を示します(これに似たオブジェクトを除外する)。
テキストと例示を組み合わせたプロンプト
1 つのプロンプトに、テキストと例示ボックスの両方を含めることができます。これは、テキストの概念を視覚例で絞り込んだり、負の例示で似たものを除外したりするのに便利です:
ここでは、モデルは最初の(正の)例示に一致する人をセグメントし、2 番目の(負の)例示に似たインスタンスを抑制します。
SAM3 視覚セグメンテーション(PVS)
POST https://serverless.roboflow.com/sam3/visual_segment
PVS は、クリックまたはボックスで示された 1 つの特定オブジェクトをセグメントします。対話的な人間ループ内のマスク微調整に使い、概念の各インスタンスが欲しい場合は PCS を使ってください。
1 つのプロンプトには ポイント、 ボックス、またはその両方を含められます:
ポイントは絶対ピクセル座標です。"positive": trueはクリックした領域を含めますfalseはそれを除外します。マスクを微調整するには、さらにポイントを追加してください。ボックスは中心基準の座標を使用します:x,yはボックスの中心です。PCS のボックスは左上基準であるのとは異なります。
レスポンスには、そのプロンプトに対する信頼度が最も高い単一のマスクが含まれます。 multimask_output は、モデルが生成する内部マスク候補の数を制御します(true の場合は 3 つ)が、レスポンスには常に最良の候補が選択されます。
OpenCV を使った対話型デモについては、この GitHub Gistを参照してください。これは次の動画で使われました:
SAM3 の推論速度
レイテンシは Roboflow Inference を使って測定しました。1x NVIDIA L4、バッチサイズ 1、ウォームアップ後の平均です。
sam3
251.4
単一のテキストプロンプトによる概念セグメンテーションで測定しました。
SAM3 API エンドポイント
Run the SAM3 PCS (promptable concept segmentation) to generate segmentations for image data.
Roboflow API Key that will be passed to the model during initialization for artifact retrieval
The source of the inference request
The detailed source information of the inference request
Roboflow API Key that will be passed to the model during initialization for artifact retrieval
trueInternal stream-pipeline frame pairing id. Not part of the public API.
If true, disables model monitoring for this request
falseThe model ID of SAM3. Use 'sam3/sam3_final' to target the generic base model.
sam3/sam3_finalOne of 'polygon', 'rle'
polygonOptional ID for caching embeddings.
Score threshold for outputs.
0.5IoU threshold for cross-prompt NMS. If None, NMS is disabled. Must be in [0.0, 1.0] when set.
Successful Response
Unique identifier of inference
The frame id of the image used in inference if the input was a video
The time in seconds it took to produce the segmentation including preprocessing
Validation Error
POST /sam3/concept_segment HTTP/1.1
Host: serverless.roboflow.com
Content-Type: application/json
Accept: */*
Content-Length: 474
{
"id": "text",
"api_key": "text",
"usage_billable": true,
"start": 1,
"source": "text",
"source_info": "text",
"stream_pipeline_context_id": "text",
"disable_model_monitoring": false,
"model_id": "sam3/sam3_final",
"format": "polygon",
"image": {
"type": "url",
"value": "http://www.example-image-url.com"
},
"image_id": "text",
"output_prob_thresh": 0.5,
"prompts": [
{
"type": "text",
"text": "text",
"output_prob_thresh": 1,
"boxes": [
{
"x": 1,
"y": 1,
"width": 1,
"height": 1
}
],
"box_labels": [
1
]
}
],
"nms_iou_threshold": 1
}{
"inference_id": "text",
"frame_id": 1,
"time": 1,
"resolved_model": {
"model_id": "text",
"model_package_id": "text",
"backend": "text",
"quantization": "text"
},
"prompt_results": [
{
"prompt_index": 1,
"echo": {
"prompt_index": 1,
"type": "text",
"text": "text",
"num_boxes": 1
},
"predictions": [
{
"masks": [
[
[
1
]
]
],
"confidence": 1,
"format": "polygon"
}
]
}
]
}Run the SAM3 PVS (promptable visual segmentation) to generate segmentations for image data.
Roboflow API Key that will be passed to the model during initialization for artifact retrieval
The source of the inference request
The detailed source information of the inference request
SAM segmentation request.
Attributes: format (Optional[str]): The format of the response. image (InferenceRequestImage): The image to be segmented. image_id (Optional[str]): The ID of the image to be segmented used to retrieve cached embeddings. point_coords (Optional[List[List[float]]]): The coordinates of the interactive points used during decoding. point_labels (Optional[List[float]]): The labels of the interactive points used during decoding.
Roboflow API Key that will be passed to the model during initialization for artifact retrieval
trueInternal stream-pipeline frame pairing id. Not part of the public API.
If true, disables model monitoring for this request
falseThe version ID of SAM to be used for this request. Must be one of hiera_tiny, hiera_small, hiera_large, hiera_b_plus
hiera_largeExample: hiera_largeThe 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.
jsonExample: jsonThe 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.
image_idIf 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. If only a single mask is needed, the model's predicted quality score can be used to select the best mask. For non-ambiguous prompts, such as multiple input prompts, multimask_output=False can give better results.
trueExample: trueIf True, saves the low-resolution logits to the cache for potential future use. This can speed up subsequent requests with similar prompts on the same image. This feature is ignored if DISABLE_SAM2_LOGITS_CACHE env variable is set True
falseIf True, attempts to load previously cached low-resolution logits for the given image and prompt set. This can significantly speed up inference when making multiple similar requests on the same image. This feature is ignored if DISABLE_SAM2_LOGITS_CACHE env variable is set True
falseSuccessful Response
Unique identifier of inference
The frame id of the image used in inference if the input was a video
The time in seconds it took to produce the segmentation including preprocessing
Validation Error
POST /sam3/visual_segment HTTP/1.1
Host: serverless.roboflow.com
Content-Type: application/json
Accept: */*
Content-Length: 479
{
"id": "text",
"api_key": "text",
"usage_billable": true,
"start": 1,
"source": "text",
"source_info": "text",
"stream_pipeline_context_id": "text",
"disable_model_monitoring": false,
"sam2_version_id": "hiera_large",
"model_id": "text",
"format": "json",
"image": {
"type": "url",
"value": "http://www.example-image-url.com"
},
"image_id": "image_id",
"prompts": [
{
"prompts": [
{
"points": [
{
"positive": true,
"x": 100,
"y": 100
}
]
}
]
}
],
"multimask_output": true,
"save_logits_to_cache": false,
"load_logits_from_cache": false
}{
"inference_id": "text",
"frame_id": 1,
"time": 1,
"resolved_model": {
"model_id": "text",
"model_package_id": "text",
"backend": "text",
"quantization": "text"
},
"predictions": [
{
"masks": [
[
[
1
]
]
],
"confidence": 1,
"format": "polygon"
}
]
}セルフホスト型 Inference で SAM3 を実行する
SAM3 は独自のハードウェアでも実行できます。 inference パッケージでインプロセスに読み込むことも、GPU コンテナから提供することもできます。
Docker で実行する
サーバーは、上記でドキュメント化された同じ /sam3/concept_segment および /sam3/visual_segment エンドポイントを http://localhost:9001.
Python でモデルを読み込む
重みは初回使用時に自動的にダウンロードされます。
Python での対話型セグメンテーション
Sam3ForInteractiveImageSegmentation は、SAM2 スタイルのポイントとボックスのインターフェースを実装しており、人間ループ内のマスク微調整に使えます:
Workflows で SAM3 を使う
Workflows では 2 つの SAM3 画像ブロックが利用できます Workflows:
SAM 3 は概念セグメンテーションを実行します。
class_namesに欲しいクラスを入力してください(例えば["人", "車両"])すると、ブロックは他のステップで利用できるインスタンスセグメンテーション予測を出力します。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 セッションが必要です。プロンプトのスケジューリングはありません。 概念プロンプトはセッションごとに 1 回だけ登録されます。セッションが再シードされるのは、ストリームが再開したとき、または
class_names変更されたときだけです。検出器駆動(ボックスプロンプト)のビデオトラッキングには、 SAM2 ページ上の SAM2 Video Tracker ブロックを使ってください。そこではsam3trackervideoもmodel_id.として受け付けます。
model_idデフォルトはsam3videoで、SAM3 video の HuggingFace transformers 版であり、フレームごとのストリーミングインターフェースを提供します。ネイティブsam3パッケージのビデオ予測器は、動画全体を事前に必要とし、ライブストリームには使えません。
SAM3-3D(ベータ版)
SAM3-3D は 2D 画像とマスクを 3D アセットに変換します: メッシュと Gaussian splat です。
依存関係をインストールします(Python 3.10 推奨):
または、3D 対応 GPU コンテナをビルドして実行します:
入力。 RGB 画像と mask_inputです。これがオブジェクト領域を定義します。マスクは二値配列((H, W) または (N, H, W))、COCO 形式のフラットなポリゴン、点対ポリゴン、RLE 辞書、または sv.Detections オブジェクト(SAM2 または別のセグメンテーションモデルから)として受け付けられます。
出力。 mesh_glb (統合シーンメッシュ、GLB)、 gaussian_ply (統合 Gaussian splat、PLY)、 objects (オブジェクトごとの mesh_glb, gaussian_ply、および メタデータ (回転、平行移動、スケールを含む)、と 時間.
設定 SPARSE_ATTN_BACKEND および ATTN_BACKEND へ flash_attn パイプラインを高速化します。Workflows では、SAM3-3D はローカル実行とリモート実行を次の方法でサポートします sam3_3d_infer() クライアントメソッド、または /sam3_3d/infer エンドポイント。
関連項目
SAM2 - 点とボックスによるプロンプト付きセグメンテーション、および検出器で初期化された動画追跡。
Segment Anything (SAM) - 元の単一オブジェクトモデル。
最終更新
役に立ちましたか?