> 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/models/ja/supported-models/sam3.md).

# SAM3

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

Meta の [Segment Anything Model 3](https://github.com/facebookresearch/sam3) 推論を当社の [サーバーレス Cloud API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api)でサポートしています。SAM3 のエンドポイントは 2 種類あります:

{% hint style="info" %}
Roboflow で SAM3 モデルを学習できるのは、有料の [プラン](https://docs.roboflow.com/platform/billing-and-plans#plans) で、 [使用量ベース課金](https://docs.roboflow.com/platform/billing-and-plans#credits)が含まれます。そこから、SAM3 アーキテクチャの「Request Feature」ボタンでアクセスをリクエストし、この機能の [学習フロー](https://docs.roboflow.com/models/ja/readme.md).

微調整済みの SAM3 モデルは Serverless Cloud API では実行できません。 [専用デプロイ](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) または [セルフホスト型 Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted)にデプロイしてください。ここにホストされている `sam3` エンドポイントは影響を受けません。
{% endhint %}

* [プロンプト指定可能なコンセプトセグメンテーション](#sam3-concept-segmentation-pcs) (**PCS**）は、画像内のコンセプトのすべてのインスタンスをセグメント化します。コンセプトはテキストプロンプト、例示ボックス、またはその両方で記述されます。
* [プロンプト指定可能なビジュアルセグメンテーション](#sam3-visual-segmentation-pvs) (**PVS**）は、SAM2 のように、ポイントまたはボックスから 1 回のリクエストにつき 1 つのオブジェクトを対話的にセグメント化します。

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

<table data-search="false"><thead><tr><th>あなたが持っているのは</th><th>あなたが望むのは</th><th>使う</th></tr></thead><tbody><tr><td>テキスト説明（例: "person"）</td><td>一致する各インスタンスのマスク</td><td><code>/sam3/concept_segment</code></td></tr><tr><td>1 つの例示オブジェクトの周囲のボックス</td><td>類似する各インスタンスのマスク</td><td><code>/sam3/concept_segment</code></td></tr><tr><td>オブジェクトを含めたり除外したりするためのテキストと例示ボックス</td><td>一致する各インスタンスのマスク</td><td><code>/sam3/concept_segment</code></td></tr><tr><td>1 つの特定オブジェクト上のクリックまたはボックス</td><td>そのオブジェクトのみのマスク</td><td><code>/sam3/visual_segment</code></td></tr></tbody></table>

送信する [API キー](https://app.roboflow.com/settings/api) を `Authorization: Bearer` ヘッダーに入れて、すべてのリクエストで送信してください。従来の `api_key` クエリパラメータも引き続き使えますが、推奨されません。

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

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

の各エントリは `prompts` で 1 つのコンセプトを表します。レスポンスには各プロンプトごとに 1 つの `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",
    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"]), "instances")
```

画像はインラインでも送信できます `{"type": "base64", "value": "<BASE64_IMAGE>"}`.

### 例示ボックスプロンプト

テキストの代わりに、例示として 1 つの例示オブジェクトの周囲のボックスでプロンプトを与えることができます。モデルは、そのボックス内のオブジェクトだけでなく、例示に一致するすべてのインスタンスを見つけます。

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

ボックスは絶対ピクセル座標を使用します。受け付ける形式は 2 つあります:

* `{"x": ..., "y": ..., "width": ..., "height": ...}` ここで `x`, `y` は左上隅
* `{"x0": ..., "y0": ..., "x1": ..., "y1": ...}` の明示的な角

`box_labels` は `boxes` が設定されている場合に必要で、ボックスごとに 1 つのエントリが必要です: `1` は正の例示を示します（このようなオブジェクトを見つける）、 `0` は負の例示を示します（このようなオブジェクトを除外する）。

### テキストと例示を組み合わせたプロンプト

1 つのプロンプトにテキストと例示ボックスの両方を含めることができます。これは、視覚的な例でテキスト概念を絞り込んだり、負の例示で似たものを除外したりするのに便利です:

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

ここでは、モデルは 1 つ目の（正の）例示に一致する人物をセグメント化し、2 つ目の（負の）例示に似たインスタンスは抑制します。

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

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

PVS は、クリックまたはボックスで示された 1 つの特定オブジェクトをセグメント化します。対話的な人間参加型のマスク精緻化にはこれを使い、コンセプトのすべてのインスタンスが欲しい場合は 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",
    headers={"Authorization": f"Bearer {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 のボックスとは異なります。

レスポンスには、そのプロンプトに対する信頼度最高の単一マスクが含まれます。 `multimask_output` は、モデルが生成する内部マスク候補の数を制御します（true のときは 3 つ）が、レスポンスには常に最良の候補が選ばれます。

{% hint style="warning" %}
1 回のリクエストにつき 1 つのプロンプトを送信してください。1 つの PVS リクエストに複数のプロンプトを含めても、現在は 1 つの予測しか返されません。
{% endhint %}

OpenCV を使った対話型デモは、こちらの [GitHub Gist](https://gist.github.com/Erol444/4cbc33c6ac52d83c63f6f9d86ca8a7a4)をご覧ください。これはこの動画で使用されました:

{% embed url="<https://www.youtube.com/watch?v=01xrBzqHZ6c>" %}

## SAM3 の推論速度

遅延は [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) で、1x NVIDIA L4、バッチサイズ 1、ウォームアップ後の平均として測定しました。

<table data-search="false"><thead><tr><th>モデル</th><th>レイテンシ（ms）</th></tr></thead><tbody><tr><td><code>sam3</code></td><td>251.4</td></tr></tbody></table>

単一のテキストプロンプトからのコンセプトセグメンテーションで測定しました。

## SAM3 API エンドポイント

{% openapi src="/files/b8a4b7a3c3ea6c3860af7071c01d5edfb0559874" path="/sam3/concept\_segment" method="post" %}
[sam3.json](https://1194881119-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-c718b36dd4197f87a2e72c28664c6d11516aefc8%2Fsam3.json?alt=media)
{% endopenapi %}

{% openapi src="/files/b8a4b7a3c3ea6c3860af7071c01d5edfb0559874" path="/sam3/visual\_segment" method="post" %}
[sam3.json](https://1194881119-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-c718b36dd4197f87a2e72c28664c6d11516aefc8%2Fsam3.json?alt=media)
{% endopenapi %}

## セルフホスト型 Inference で SAM3 を実行

SAM3 は自分のハードウェア上でも実行でき、 [`inference`](https://docs.roboflow.com/deployment/self-hosted/self-hosted) パッケージでプロセス内に読み込むか、GPU コンテナから提供できます。

### Docker で実行

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

サーバーは、上記で文書化されている同じ `/sam3/concept_segment` と `/sam3/visual_segment` エンドポイントを `http://localhost:9001`.

### Python でモデルを読み込む

```bash
pip install "inference-gpu[sam3]"
```

```python
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 風のポイントとボックスのインターフェースを実装し、人間参加型のマスク精緻化に使えます:

```python
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 で SAM3 を使う

Workflows には 2 つの SAM3 画像ブロックがあります [Workflows](https://docs.roboflow.com/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`を維持し、検出器で種付けしたトラッキングとは異なり、ストリーム途中でシーンに入ってきたオブジェクトも再プロンプトや上流の検出モデルなしで自動的に拾われます。各マスクには、一致したコンセプトがクラス名として付与され、モデルの検出スコアが信頼度として付与されます（ `しきい値`でフィルタリング、既定 `0.5`).

* **ステートフルでローカル専用です。** 各 `video_metadata.video_identifier`ごとに 1 つのトラッキングセッションが保持されます。このブロックには `WORKFLOWS_STEP_EXECUTION_MODE=local`、GPU、永続的な WebRTC セッションが必要です。
* **プロンプトのスケジューリングはありません。** コンセプトプロンプトはセッションごとに 1 回だけ登録されます。セッションは、ストリームが再開するか `class_names` が変化したときにのみ再シードされます。検出器駆動（ボックスポロンプト付き）のビデオトラッキングには、 [SAM2 ページ](https://docs.roboflow.com/models/ja/supported-models/sam2.md)も同様に `sam3trackervideo` を `model_id`.
* **として受け付けます。** `model_id` は既定で `sam3video`になっており、SAM3 video の HuggingFace transformers 移植版で、フレームごとのストリーミングインターフェースを公開します。ネイティブの `sam3` パッケージの video predictor は動画全体を事前に必要とし、ライブストリームには使えません。

```python
from inference_sdk import InferenceHTTPClient, InferenceConfiguration
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",
).configure(InferenceConfiguration(api_key_transport="header"))

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 アセットに変換します: メッシュと Gaussian splat。

{% hint style="warning" %}
SAM3-3D はベータ版です。利用できるのは `SAM3_3D_OBJECTS_ENABLED` フラグが設定されている場合のみで、32 GB 以上の VRAM を持つ GPU が必要です。また、 `inference` パッケージまたはローカル Inference サーバーを介して実行されます（Serverless Cloud API にはありません）。
{% endhint %}

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

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

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

```bash
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` （結合された Gaussian splat、PLY）、 `objects` （オブジェクトごとの `mesh_glb`, `gaussian_ply`、および `metadata` （回転、平行移動、スケールを含む）、そして `時間`.

```python
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](https://docs.roboflow.com/models/ja/supported-models/sam2.md) - ポイントとボックスによるプロンプト付きセグメンテーションに加え、検出器を初期種としたビデオトラッキング。
* [Segment Anything（SAM）](https://docs.roboflow.com/models/ja/supported-models/sam.md) - 元の単一オブジェクトモデル。
