For the complete documentation index, see llms.txt. This page is also available as Markdown.

SAM3

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

当社は Meta の Segment Anything Model 3 の推論を 当社の Serverless Cloud API 経由でサポートしています。2 種類の SAM3 エンドポイントを提供しています:

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

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

この表を使ってエンドポイントを選んでください:

あなたが持っているのは
欲しいのは
使用するのは

テキストによる説明(例: "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、ウォームアップ後の平均です。

モデル
レイテンシ(ms)

sam3

251.4

単一のテキストプロンプトによる概念セグメンテーションで測定しました。

SAM3 API エンドポイント

SAM3 PCS (promptable concept segmentation)

post
/sam3/concept_segment

Run the SAM3 PCS (promptable concept segmentation) to generate segmentations for image data.

クエリパラメータ
api_keystring · ヌル許容オプション

Roboflow API Key that will be passed to the model during initialization for artifact retrieval

countinferenceboolean · ヌル許容オプション
service_secretstring · ヌル許容オプション
sourcestring · ヌル許容オプション

The source of the inference request

source_infostring · ヌル許容オプション

The detailed source information of the inference request

本文
idstring必須
api_keystring · ヌル許容オプション

Roboflow API Key that will be passed to the model during initialization for artifact retrieval

usage_billablebooleanオプションDefault: true
startnumber · ヌル許容オプション
sourcestring · ヌル許容オプション
source_infostring · ヌル許容オプション
stream_pipeline_context_idstring · ヌル許容オプション

Internal stream-pipeline frame pairing id. Not part of the public API.

disable_model_monitoringboolean · ヌル許容オプション

If true, disables model monitoring for this request

Default: false
model_idstring · ヌル許容オプション

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

Default: sam3/sam3_final
formatstring · ヌル許容オプション

One of 'polygon', 'rle'

Default: polygon
image_idstring · ヌル許容オプション

Optional ID for caching embeddings.

output_prob_threshnumber · ヌル許容オプション

Score threshold for outputs.

Default: 0.5
nms_iou_thresholdnumber · ヌル許容オプション

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

レスポンス
200

Successful Response

application/json
inference_idstring · ヌル許容オプション

Unique identifier of inference

frame_idinteger · ヌル許容オプション

The frame id of the image used in inference if the input was a video

timenumber必須

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

post/sam3/concept_segment
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"
        }
      ]
    }
  ]
}

SAM3 PVS (promptable visual segmentation)

post
/sam3/visual_segment

Run the SAM3 PVS (promptable visual segmentation) to generate segmentations for image data.

クエリパラメータ
api_keystring · ヌル許容オプション

Roboflow API Key that will be passed to the model during initialization for artifact retrieval

countinferenceboolean · ヌル許容オプション
service_secretstring · ヌル許容オプション
sourcestring · ヌル許容オプション

The source of the inference request

source_infostring · ヌル許容オプション

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.

idstring必須
api_keystring · ヌル許容オプション

Roboflow API Key that will be passed to the model during initialization for artifact retrieval

usage_billablebooleanオプションDefault: true
startnumber · ヌル許容オプション
sourcestring · ヌル許容オプション
source_infostring · ヌル許容オプション
stream_pipeline_context_idstring · ヌル許容オプション

Internal stream-pipeline frame pairing id. Not part of the public API.

disable_model_monitoringboolean · ヌル許容オプション

If true, disables model monitoring for this request

Default: false
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
model_idstring · ヌル許容オプション
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
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
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. 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.

Default: trueExample: true
save_logits_to_cachebooleanオプション

If 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

Default: false
load_logits_from_cachebooleanオプション

If 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

Default: false
レスポンス
200

Successful Response

application/json
inference_idstring · ヌル許容オプション

Unique identifier of inference

frame_idinteger · ヌル許容オプション

The frame id of the image used in inference if the input was a video

timenumber必須

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

post/sam3/visual_segment
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) - 元の単一オブジェクトモデル。

最終更新

役に立ちましたか?