2026.10.04 開発

SAM 2（SAM2）の使い方：インストールから画像・動画セグメンテーションのPython実装まで

Q: SAM 2はGPUが無いCPUだけの環境でも動きますか？

build_sam2 には device 引数があり、 "cpu" を指定すればCPUでも読み込めます。ただし、公式のサンプルはCUDAとbfloat16を前提にしており、CPUでは1枚の推論に時間がかかります。検証はtinyかsmallで行い、largeや動画の追跡はGPU環境で動かすのが現実的です。前述のコードを流用する場合は、 torch.autocast("cuda", ...) の行も外してください。

Q: 動画の途中で追跡が外れたときはどう直しますか？

外れたフレームの番号を frame_idx に指定し、同じ obj_id で add_new_points_or_box を呼び、正しい位置に点を追加します。そのうえで propagate_in_video をもう一度実行する手順が、修正をそのフレームの前後に反映させる方法です。最初からやり直す場合は reset_state で推論状態を初期化します。

SAM 2（SAM2）の使い方：インストールから画像・動画セグメンテーションのPython実装まで

SAM 2（Segment Anything Model 2）は、Metaが2024年7月に公開した、画像と動画の両方で任意の物体を切り出せるセグメンテーションモデルです。クリックした点や囲んだボックスを手がかりに、対象のマスクを返します。動画では、最初のフレームで指定した物体を後続のフレームでも追い続ける仕組みです。本記事では、SAM 2のインストール、画像でマスクを得るPythonコード、動画で物体を追跡するコード、公式リポジトリ・Hugging Face・Ultralyticsという3つの導入経路の違いを、公式のソースコードと論文を根拠に順に説明します。最後に、後継のSAM 3へ移らずにSAM 2を使い続ける条件も示します。

まとめ：SAM 2を動かす最短経路と、SAM 3ではなくSAM 2を選ぶ条件

SAM 2を動かす最短の手順は、公式リポジトリをクローンしてpip install -e .でインストールし、SAM 2.1のチェックポイントを取得してSAM2ImagePredictorに点を1つ渡すことです。必要な環境は、Python 3.10以上、PyTorch 2.5.1以上、NVIDIA GPUです。動画を扱う場合はbuild_sam2_video_predictorで予測器を作り、1フレーム目の指定をpropagate_in_videoで全フレームへ広げます。

モデルは4サイズあり、まずは中間のbase_plusで試し、精度が足りなければlarge、速度が足りなければsmallかtinyに切り替えます。Windowsでは、公式がWSL上のUbuntuを強く推奨している点を最初に押さえてください。

後継のSAM 3はテキストで対象を指定できますが、SAM 2にはSAM 3に無い利点があります。チェックポイントがApache 2.0ライセンスで公開されていることです。点やボックスによる指定で足りて、ライセンスを単純に保ちたい案件では、2026年10月時点でもSAM 2が有力な選択肢です。

SAM 2の概要：画像と動画を1つのモデルで切り出すMetaのセグメンテーション基盤

SAM 2が何をするモデルかを先に押さえます。初代SAMとの違いは「動画への対応」の一点に集約されます。

初代SAMからの変更点：動画のフレームをまたいで物体を覚えるストリーミングメモリ

初代SAMは静止画専用でした。SAM 2は、過去のフレームで得た物体の特徴をメモリに蓄え、次のフレームの推論で参照する仕組みを足しています。これにより、物体が一時的に隠れても追跡を続けられます。論文「SAM 2: Segment Anything in Images and Videos」によれば、動画では従来手法より3分の1の操作回数で同等の精度に届き、画像では初代SAMより6倍高速です。

学習には、Metaが新たに構築した動画データセットSA-Vを使っています。Metaの公式ページによると、SA-Vは約5.1万本の動画と60万を超えるマスクレット（時間方向に連続したマスク）で構成され、含まれているのは47か国の映像です。ピクセル単位で領域を分類する手法そのものは、セマンティックセグメンテーションの仕組みと代表モデルの解説で扱っています。SAM 2は、クラスを決めずにユーザーの指定した物体を切り出す点がこれと異なります。

SAM 2.1の4サイズ比較：パラメータ数・FPS・SA-V精度で選ぶチェックポイント

2024年9月30日に、改良版のチェックポイントであるSAM 2.1が公開されました。2026年10月時点で新規に使うなら2.1系を選びます。公式リポジトリのREADMEに掲載されている4サイズの値は次のとおりです。

チェックポイント	パラメータ数	速度（FPS）	SA-V test（J&F）
sam2.1_hiera_tiny	38.9M	91.2	76.5
sam2.1_hiera_small	46M	84.8	76.6
sam2.1_hiera_base_plus	80.8M	64.1	78.2
sam2.1_hiera_large	224.4M	39.5	79.5

表から読み取れるのは、tinyとsmallの精度差が0.1ポイントしかないことです。largeはtinyより精度が3ポイント高い代わりに、速度は半分以下になります。リアルタイム処理が要るならtiny、オフラインでアノテーションの下書きを作るならlargeという分け方が素直です。

Apache 2.0で商用利用できる点と、SAM 3のライセンスとの違い

SAM 2のチェックポイント、デモコード、学習コードはApache 2.0ライセンスで公開されています。Apache 2.0は、著作権表示とライセンス文を添えれば商用製品へ組み込めるライセンスです。後継のSAM 3は独自のSAM Licenseに変わり、利用条件の確認項目が増えました。モデルごとの差分はSAM 3の解説記事にあるSAM 2との比較にまとめています。受託案件で顧客の法務確認を短く済ませたい場合、この違いはモデルの精度差より効いてきます。

SAM 2の導入条件：Python 3.10とPyTorch 2.5.1以上

SAM 2はpipのパッケージ名だけで入れる形式ではなく、リポジトリをクローンして編集可能モードでインストールします。事前に、PyTorch公式の手順で、GPUのCUDAに合ったPyTorch 2.5.1以上とtorchvision 0.20.1以上を入れておきます。

GitHubのクローンから本体導入とチェックポイント取得までの公式手順

GitHubからクローンした後、pip install -e .で本体を入れるのが次の公式手順です。本体のインストールとSAM 2.1のチェックポイント取得まで完了します。download_ckpts.shは4サイズすべてをcheckpointsディレクトリに保存します。

git clone https://github.com/facebookresearch/sam2.git
cd sam2
pip install -e .
# Jupyterのサンプルノートブックも動かす場合
pip install -e ".[notebooks]"
cd checkpoints && ./download_ckpts.sh && cd ..

インストール時に、マスクの小さな穴を埋める後処理用のCUDA拡張がビルドされます。GPUとCUDAの関係が曖昧な場合は、CUDAの仕組みとバージョンの解説を先に読んでおくと、次のh3の対処が理解しやすくなります。

Windowsで詰まる箇所：WSL推奨とCUDA拡張のビルド失敗時の回避策

公式のINSTALL.mdは、Windowsでの利用にWSL上のUbuntuを強く推奨しています。ネイティブのWindowsでも動く場合はありますが、コンパイラ周りで詰まりやすいためです。よく出るエラーと対処は次の4つです。

CUDA拡張のビルドに失敗する：SAM2_BUILD_CUDA=0 pip install -e ".[notebooks]"で拡張のビルドを省く
MissingConfigExceptionで設定ファイルが見つからない：リポジトリのルートをPYTHONPATHに加える
CUDA_HOMEの未設定エラー：CUDAのパスをCUDA_HOMEに明示するか、pip install --no-build-isolation -e .を使う
SAM 2.1のチェックポイントが読めない：最新のコードに更新し、アンインストールしてから入れ直す

CUDA拡張を省いても推論そのものはできます。失われるのは小さな穴を除去する後処理だけなので、検証段階では省いて先に進んで構いません。

SAM2ImagePredictorによる点・ボックス指定の画像マスク生成

画像の推論にはSAM2ImagePredictorを使います。以下のPythonコードは、点やボックスの指定からマスクを得るための実装例です。set_imageで画像の特徴量を一度だけ計算し、その後はpredictに指定を変えて何度でも渡せる構造です。

点プロンプト1つで対象を切り出し、3つの候補マスクとスコアを受け取る最小コード

次のコードは、画像の座標（500, 375）にある物体を切り出します。point_labelsの1は「この点は対象の内側」という意味です。

import numpy as np
import torch
from PIL import Image
from sam2.build_sam import build_sam2
from sam2.sam2_image_predictor import SAM2ImagePredictor

checkpoint = "./checkpoints/sam2.1_hiera_large.pt"
model_cfg = "configs/sam2.1/sam2.1_hiera_l.yaml"
predictor = SAM2ImagePredictor(build_sam2(model_cfg, checkpoint))

image = np.array(Image.open("input.jpg").convert("RGB"))
with torch.inference_mode(), torch.autocast("cuda", dtype=torch.bfloat16):
    predictor.set_image(image)
    masks, scores, _ = predictor.predict(
        point_coords=np.array([[500, 375]]),
        point_labels=np.array([1]),
        multimask_output=True,
    )

best = masks[np.argmax(scores)]
print(masks.shape, scores)

multimask_output=Trueでは、マスクを3つ返します。点1つでは「タイヤだけ」「車体全体」のように対象の範囲が曖昧になるため、候補を複数出してスコアで選ばせる設計です。set_imageはRGBでHWC形式のNumPy配列か、PILの画像を受け付けます。OpenCVで読んだBGRの配列をそのまま渡すと色の順序がずれるので注意してください。

ボックス指定と対象外の点を組み合わせて誤検出を減らす指定方法

点1つで意図しない範囲が返るときは、ボックスで範囲を絞り、含めたくない部分に「対象外」の点を打ちます。point_labelsの0が対象外を表します。

with torch.inference_mode(), torch.autocast("cuda", dtype=torch.bfloat16):
    masks, scores, _ = predictor.predict(
        point_coords=np.array([[575, 750]]),
        point_labels=np.array([0]),
        box=np.array([425, 600, 700, 875]),
        multimask_output=False,
    )

ボックスは左上と右下の座標（x0, y0, x1, y1）で渡します。対象がはっきりしている場合はmultimask_output=Falseにしてマスクを1つに絞ると、後段の処理を単純にすることが可能です。物体検出モデルの出力したボックスをそのまま渡せば、検出結果を輪郭レベルの切り抜きに変換する用途にも使えます。

SAM2AutomaticMaskGeneratorによる全物体の自動抽出設定

指定なしで画像内の物体をすべて切り出すなら、SAM2AutomaticMaskGeneratorを使います。画像全体に格子状の点を打ち、点ごとのマスクを重複除去してまとめる方式です。

from sam2.automatic_mask_generator import SAM2AutomaticMaskGenerator

sam2 = build_sam2(model_cfg, checkpoint)
generator = SAM2AutomaticMaskGenerator(
    sam2,
    points_per_side=32,
    pred_iou_thresh=0.8,
    stability_score_thresh=0.95,
)
records = generator.generate(image)
print(len(records), sorted(records[0].keys()))

ここに書いた3つの値は、automatic_mask_generator.pyの既定値と同じです。戻り値は辞書のリストで、segmentation（マスク）、bbox（XYWH形式のボックス）、area、predicted_iou、stability_scoreなどのキーを持ちます。細かな物体を拾い漏らすときに増やす設定値は、格子状の点の密度を決めるpoints_per_sideです。ただし点の数は2乗で増えるため、64にすると処理量は約4倍になります。

SAM2VideoPredictorで1フレーム目の指定を伝播する動画処理

動画では、あるフレームで物体を指定すると、SAM 2がその物体を前後のフレームで追跡します。画像の予測器とは別に、動画用の予測器を作ります。

MP4またはJPEG連番を読み込み、init_stateで推論状態を作る前処理

動画の読み込み関数が受け付けるのは、MP4ファイルと、00000.jpgのようにフレーム番号をファイル名にしたJPEGのディレクトリです。それ以外の形式を渡すと「Only MP4 video and JPEG folder are supported」というエラーになります。公式のサンプルはJPEGのディレクトリを使っており、ffmpegで次のように書き出せます。

mkdir frames
ffmpeg -i input.mp4 -q:v 2 -start_number 0 frames/'%05d.jpg'

JPEGに書き出しておくと、フレームを間引いたり、一部の区間だけを切り出したりする調整がファイル操作だけで済みます。

動画内の物体IDと点の指定から全フレームへの追跡を実行するコード

次のコードは、add_new_points_or_boxで0フレーム目の座標（210, 350）にある物体にIDの1を付け、propagate_in_videoで動画全体を追跡します。

import numpy as np
import torch
from sam2.build_sam import build_sam2_video_predictor

checkpoint = "./checkpoints/sam2.1_hiera_large.pt"
model_cfg = "configs/sam2.1/sam2.1_hiera_l.yaml"
predictor = build_sam2_video_predictor(model_cfg, checkpoint)

with torch.inference_mode(), torch.autocast("cuda", dtype=torch.bfloat16):
    state = predictor.init_state(video_path="./frames")
    predictor.add_new_points_or_box(
        inference_state=state,
        frame_idx=0,
        obj_id=1,
        points=np.array([[210, 350]], dtype=np.float32),
        labels=np.array([1], dtype=np.int32),
    )
    results = {}
    for frame_idx, obj_ids, mask_logits in predictor.propagate_in_video(state):
        results[frame_idx] = {
            obj_id: (mask_logits[i] > 0.0).cpu().numpy()
            for i, obj_id in enumerate(obj_ids)
        }

print(len(results))

propagate_in_videoが返すのはマスクそのものではなくロジットです。二値化では、0より大きい画素を対象とみなす処理が必要です。複数の物体を追う場合は、obj_idを2、3と変えてadd_new_points_or_boxを物体の数だけ呼びます。途中のフレームで追跡が外れたら、そのフレームのframe_idxで点を追加して伝播をやり直します。この修正の流れが、論文の「少ない操作回数」の中身です。

長尺の動画でGPUメモリが足りないときのoffload設定とvos_optimized

sam2_video_predictor.pyのinit_stateには、offload_video_to_cpuとoffload_state_to_cpuという引数があります。前者はフレーム画像を、後者は推論状態をCPU側のメモリに置き、GPUメモリの消費を抑えます。数千フレームの動画でメモリ不足になったときに、まず試す設定はこの2つをTrueにすることです。転送の分だけ処理は遅くなります。

速度を上げたい場合は、2024年12月11日の更新で加わったbuild_sam2_video_predictor(..., vos_optimized=True)を使います。モデル全体をtorch.compileでコンパイルする設定で、初回はコンパイルの待ち時間がかかります。同じ予測器で多くの動画を続けて処理するバッチ用途に向く設定です。

公式・Hugging Face・Ultralyticsの3経路の導入比較

ここまでのコードは公式リポジトリの書き方です。重みの取得方法やコードの短さを優先するなら、別の経路もあります。

Hugging Faceの重みを直接取得する実装とモデルIDの命名規則

公式の予測器には、Hugging Faceに公開された重みを直接読み込むfrom_pretrainedが用意されています。チェックポイントのダウンロードと設定ファイルの指定を省けます。

from sam2.sam2_image_predictor import SAM2ImagePredictor
from sam2.sam2_video_predictor import SAM2VideoPredictor

image_predictor = SAM2ImagePredictor.from_pretrained("facebook/sam2.1-hiera-large")
video_predictor = SAM2VideoPredictor.from_pretrained("facebook/sam2.1-hiera-large")

モデルIDはfacebook/sam2.1-hiera-のあとにtiny、small、base-plus、largeのいずれかを付けます。初版の重みを使う場合は、sam2.1をsam2に置き換えます。Hugging Face Hubの仕組みやトークンの扱いは、Hugging Faceでできることと使い方の解説を参照してください。

Ultralyticsのsam2.1_b.ptによる短い実装と制御上の限界

YOLOシリーズで知られるUltralyticsのパッケージもSAM 2に対応しています。Ultralyticsのドキュメントに沿えば、ボックス指定の推論が3行で書けます。

from ultralytics import SAM

model = SAM("sam2.1_b.pt")
results = model("input.jpg", bboxes=[100, 100, 200, 200])

手軽な反面、Ultralyticsで使えるのは推論だけで、メモリ管理の引数や追跡途中の修正といった細かな制御は公式リポジトリほど自由ではありません。また、Ultralyticsのパッケージ自体はAGPL-3.0ライセンスです。SAM 2のApache 2.0という利点を製品で生かしたいなら、公式リポジトリから直接使う構成を選びます。

経路	コード量	動画の細かな制御	パッケージのライセンス
公式リポジトリ	多い	すべて可能	Apache 2.0
公式＋from_pretrained	やや少ない	すべて可能	Apache 2.0
Ultralytics	最少	限定的	AGPL-3.0

検証の初日はUltralyticsで挙動を確かめ、製品に組み込む段階で公式リポジトリに移す、という二段構えも現実的です。

業務でSAM 2を使う判断：SAM 3へ移行すべき場面と、SAM 2に留まる条件

SAM 3が出た今、新規にSAM 2を選ぶ理由があるかを言い切ります。結論は「指定方法とライセンスで決まる」です。

SAM 2に留まるのが妥当な条件：点とボックスの指定で足り、ライセンスを優先する場合

次の条件がそろうなら、SAM 2.1を選びます。対象の位置を人か別のモデルが指定できること。商用製品への組み込みで、ライセンスをApache 2.0に揃えたいこと。既にSAM 2で組んだパイプラインが動いていること。物体検出モデルが出したボックスを輪郭に変換する用途は、まさにこの条件に当てはまります。検出側の手法の選び方は物体検出の仕組みと代表手法の比較で扱っています。

SAM 2を採用しない場面：テキストでの指定や全インスタンスの自動抽出が要件の場合

「画像内の作業員をすべて切り出す」のように、物体の種類を言葉で指定して全インスタンスを取りたいなら、SAM 2は向きません。SAM 2にはテキストで指定する機能が無く、自動マスク生成では物体の種類を区別しないためです。この要件ではSAM 3を使うか、対象クラスを学習させた専用モデルを作ります。同じ理由で、点を打つ人手を確保できない全自動の検品ラインに、SAM 2を単体で据えるのも避けるべきです。

アノテーション工数を減らす下書き用途から始め、業務専用モデルへ移る進め方

業務でSAM 2が最も効果を出しやすいのは、教師データの作成です。作業者がポリゴンを手で描く代わりに点を1つ打ち、SAM 2のマスクを修正するだけにすれば、1枚あたりの作業量が減ります。作業手順と品質管理の考え方はアノテーションの種類とやり方の解説に記載した内容のとおりです。こうして集めたデータで軽量な専用モデルを学習させれば、本番ではSAM 2を使わずに高速な推論ができます。下書きから専用モデルの構築、業務システムへの組み込みまでを一括で外部に任せたい場合は、画像認識AIモデル構築で相談できます。

よくある質問

SAM 2を動かす前に多い疑問を、実装者の立場から短く答えます。

SAM 2はGPUが無いCPUだけの環境でも動きますか？

build_sam2にはdevice引数があり、"cpu"を指定すればCPUでも読み込めます。ただし、公式のサンプルはCUDAとbfloat16を前提にしており、CPUでは1枚の推論に時間がかかります。検証はtinyかsmallで行い、largeや動画の追跡はGPU環境で動かすのが現実的です。前述のコードを流用する場合は、torch.autocast("cuda", ...)の行も外してください。

SAM 2とSAM 2.1はどちらを使えばよいですか？

新規ならSAM 2.1です。2024年9月30日に公開された改良版のチェックポイントで、READMEの表ではSA-Vの精度がSAM 2より上がっています。コードは共通で、設定ファイルをconfigs/sam2.1/配下、チェックポイントをsam2.1_hiera_*.ptに変えるだけです。読み込みに失敗する場合は、リポジトリを最新にしてから入れ直してください。

SAM 2は商用利用できますか？

できます。チェックポイント、デモコード、学習コードはApache 2.0ライセンスで公開されています。製品に同梱する場合は、ライセンス文と著作権表示を添えてください。注意点は周辺のパッケージです。Ultralytics経由で使う場合、Ultralyticsのパッケージ自体はAGPL-3.0なので、製品の配布形態によっては別途の確認が要ります。

SAM 2でテキストを入力して物体を指定できますか？

できません。SAM 2が受け付ける指定は、点、ボックス、マスクの3種類です。「犬」「ヘルメット」のように言葉で対象を指定したい場合は、テキスト指定に対応した後継のSAM 3を使うか、物体検出モデルでボックスを作ってからSAM 2に渡す二段構成にします。後者なら、ライセンスをApache 2.0系で揃えたまま言葉による指定に近い処理を組めます。

動画の途中で追跡が外れたときはどう直しますか？

外れたフレームの番号をframe_idxに指定し、同じobj_idでadd_new_points_or_boxを呼び、正しい位置に点を追加します。そのうえでpropagate_in_videoをもう一度実行する手順が、修正をそのフレームの前後に反映させる方法です。最初からやり直す場合はreset_stateで推論状態を初期化します。