LoginSignup
4
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@GeneLab_999

SAM3を使おうとしたら依存関係地獄で泣いた、Ultralytics最高！という話

Posted at

ねらい・対象・ゴール・TL;DR

ねらい: Meta AIの最新セグメンテーションモデル「SAM3」を使おうとしたときの地獄体験と、Ultralytics経由なら天国だったという話を共有する

対象:

  • SAMシリーズを使ってみたいけどインストールで詰まっている人
  • CUDA、PyTorchのバージョン地獄に苦しんでいる人
  • 「もっと楽にAIモデル使いたいんだけど」と思っている人

ゴール: SAM/SAM2/SAM3の公式インストール地獄を理解し、Ultralyticsという救済措置の存在を知る

TL;DR: Meta AI公式のSAMリポジトリからインストールしようとするとCUDA、PyTorch、NumPyのバージョン地獄に陥る。Ultralyticsならpip install ultralyticsしてからfrom ultralytics import SAMで3行で動く。SAM3もUltralytics 8.3.237で統合済み。

はじめに：「SAM3動かしたい」から始まった地獄の1日

2025年11月19日、Meta AIがSAM3（Segment Anything Model 3）をリリースした。

"SAM 3 was released by Meta on November 20th, 2025 and is fully integrated into Ultralytics as of version 8.3.237"

— Ultralytics SAM3ドキュメントより

テキストプロンプトで「yellow school bus」って打つだけで、画像内の全ての黄色いスクールバスをセグメンテーションしてくれる。これは面白そうだ。

よし、動かしてみよう。

公式リポジトリをクローンして...

git clone https://github.com/facebookresearch/sam3.git
cd sam3
pip install -e .

ここから地獄が始まった。

地獄その1：CUDA_HOME環境変数

最初に出てきたエラーがこれ。

"OSError: CUDA_HOME environment variable is not set. Please set it to your CUDA install root."

— GitHub Issue #41より

「CUDA_HOMEが設定されてないぞ」と怒られる。

よし、設定しよう。

export CUDA_HOME=/usr/local/cuda-12.1

再実行。まだダメ。

echo $CUDA_HOME  # 設定されてる
nvcc --version   # CUDA 12.1

環境変数は正しく設定されてるのに、なぜ？

答え：pipのビルド環境が隔離されているから。--no-build-isolationフラグが必要だった。

pip install --no-build-isolation -e .

...まだエラー。

地獄その2：NumPyがない（？）

"UserWarning: Failed to initialize NumPy: No module named 'numpy'"

— GitHub Issue #172より

「NumPyがない」と言われる。いや、入ってるって。

python -c "import numpy; print(numpy.__version__)"
# 1.26.4

入ってる。なのに「No module named 'numpy'」。

これはpipのビルド時に一時的な仮想環境が作られて、そこにNumPyがインストールされていないために起きる。

解決策：

pip install numpy  # 念のため再インストール
pip install --no-cache-dir --no-build-isolation -e .

...次のエラー。

地獄その3：PyTorchのバージョン不整合

"This usually happens because you have multiple versions of dependencies (PyTorch or CUDA) in your environment."

— SAM2 INSTALL.mdより

PyTorchとCUDAのバージョンが合っていないらしい。

undefined symbol: _ZN3c1015SmallVectorBaseIjE8grow_podEPKvmm

こんなシンボルエラーが出る。

SAM2/SAM3はPyTorch 2.5.1以上を要求する。でもCUDA 12.1用のPyTorch 2.5.1がうまく動かないことがある。

"We have been building SAM 2 against PyTorch 2.5.1 internally. However, a few user comments (e.g. #22, #14) suggested that downgrading to PyTorch 2.1.0 might resolve this problem."

— SAM2 INSTALL.mdより

和訳: 内部ではPyTorch 2.5.1でSAM2をビルドしている。しかし、いくつかのユーザーコメント（#22、#14など）によると、PyTorch 2.1.0にダウングレードすると問題が解決する可能性がある。

最新版を使えって言ったり、ダウングレードしろって言ったり。どっちなんだ。

地獄その4：CUDAカーネルのアーキテクチャ

CUDA error: no kernel image is available for execution on the device

今度はCUDAカーネルがGPUアーキテクチャに対応していないと言われる。

"A possible cause could be that the CUDA kernel is somehow not compiled towards your GPU's CUDA capability."

— SAM2 INSTALL.mdより

和訳: 考えられる原因として、CUDAカーネルがGPUのCUDA Capabilityに対してコンパイルされていない可能性がある。

解決策として、環境変数でアーキテクチャを明示的に指定する必要がある：

export TORCH_CUDA_ARCH_LIST="9.0 8.0 8.6 8.9 7.0 7.2 7.5 6.0"

どのアーキテクチャを指定すればいいかは、自分のGPUによる。RTX 4090なら8.9、RTX 3090なら8.6...。調べるのも面倒くさい。

地獄その5：Windowsユーザーへの仕打ち

"If you are installing on Windows, it's strongly recommended to use Windows Subsystem for Linux (WSL) with Ubuntu."

— SAM2 INSTALL.mdより

和訳: Windowsにインストールする場合、WSL（Windows Subsystem for Linux）とUbuntuの使用を強く推奨する。

Windowsネイティブでの動作はほぼ保証されていない。WSLを使えと。

Windows勢、切り捨てられてる。

累計5時間、結局動かなかった

振り返ってみると：

  1. CUDA_HOME設定 → 30分
  2. NumPy問題 → 1時間
  3. PyTorchバージョン試行錯誤 → 2時間
  4. CUDAアーキテクチャ問題 → 1時間
  5. その他細々としたエラー → 30分

累計5時間。そして結局、安定して動く環境を構築できなかった。

救世主登場：Ultralyticsという選択肢

疲れ果てた頃、ふとUltralyticsのドキュメントを見た。

"SAM 3 is fully integrated into the Ultralytics package as of version 8.3.237 (PR #22897). Install or upgrade with pip install -U ultralytics to access all SAM 3 features including text-based concept segmentation, image exemplar prompts, and video tracking."

— Ultralytics SAM3ドキュメントより

和訳: SAM3はUltralyticsパッケージのバージョン8.3.237（PR #22897）で完全に統合された。pip install -U ultralyticsでインストールまたはアップグレードすれば、テキストベースのコンセプトセグメンテーション、画像エグゼンプラープロンプト、ビデオトラッキングを含むすべてのSAM3機能にアクセスできる。

...え、それだけ？

Ultralyticsでのインストール

pip install -U ultralytics

これだけ。CUDAの設定？PyTorchのバージョン？全部Ultralyticsがよしなにやってくれる。

SAM3を動かす

from ultralytics import SAM

# SAM3モデルをロード
model = SAM("sam3.pt")

# 画像に対してテキストプロンプトでセグメンテーション
results = model("image.jpg", text=["yellow school bus"])

3行。たった3行で動いた。

あの5時間はなんだったんだ。

UltralyticsでSAM/SAM2/SAM3を使う完全ガイド

Ultralyticsには歴代のSAMモデルが全て統合されている。

対応モデル一覧

モデル ファイル名 特徴
SAM (オリジナル) sam_b.pt, sam_l.pt, sam_h.pt 2023年リリース、画像のみ
Mobile-SAM mobile_sam.pt 軽量版SAM
SAM2 sam2_t.pt, sam2_s.pt, sam2_b.pt, sam2_l.pt 2024年、動画対応
SAM2.1 sam2.1_t.pt, sam2.1_s.pt, sam2.1_b.pt, sam2.1_l.pt 改良版SAM2
SAM3 sam3.pt 2025年、テキストプロンプト対応

SAM2の使い方（画像）

from ultralytics import SAM

# SAM2モデルをロード
model = SAM("sam2.1_b.pt")

# バウンディングボックスでプロンプト
results = model("path/to/image.jpg", bboxes=[100, 100, 200, 200])

# ポイントでプロンプト
results = model(points=[900, 370], labels=[1])

# 複数ポイント
results = model(points=[[400, 370], [900, 370]], labels=[1, 1])

"from ultralytics import SAM"

— Ultralytics SAM2ドキュメントより

SAM2の使い方（動画）

from ultralytics import SAM

model = SAM("sam2.1_b.pt")

# 動画全体をセグメンテーション
model("path/to/video.mp4")

動画にも対応。フレームごとの処理をUltralyticsが勝手にやってくれる。

SAM3の使い方（テキストプロンプト）

from ultralytics.models.sam import SAM3SemanticPredictor

# 設定
overrides = dict(
    conf=0.25,
    task="segment",
    mode="predict",
    model="sam3.pt",
    half=True,  # FP16で高速化
)

predictor = SAM3SemanticPredictor(overrides=overrides)

# 画像を設定
predictor.set_image("path/to/image.jpg")

# テキストでクエリ
results = predictor(text=["person", "bus", "glasses"], save=True)

# 複雑な記述も可能
results = predictor(text=["person with red cloth", "person with blue cloth"], save=True)

"Find and segment all instances of a concept using a text description."

— Ultralytics SAM3ドキュメントより

和訳: テキスト記述を使用して、コンセプトの全てのインスタンスを検出してセグメンテーションする。

「赤い服を着た人」と「青い服を着た人」を別々にセグメンテーションできる。これがSAM3の真骨頂だ。

なぜUltralyticsは楽なのか

理由1：依存関係の解決を自動化

Ultralyticsパッケージは、PyTorch、NumPy、OpenCVなどの依存関係を適切なバージョンで管理している。ユーザーが手動でバージョンを合わせる必要がない。

理由2：モデルの自動ダウンロード

model = SAM("sam2.1_b.pt")  # 初回実行時に自動ダウンロード

チェックポイントファイルを手動でダウンロードする必要がない（SAM3は例外で手動ダウンロード必要）。

理由3：統一されたAPI

YOLO、SAM、FastSAM、RT-DETR...。全て同じようなAPIで使える。

from ultralytics import YOLO, SAM, FastSAM

# どれも同じパターン
model = YOLO("yolov8n.pt")
model = SAM("sam2.1_b.pt")
model = FastSAM("FastSAM-s.pt")

# 推論も同じ
results = model("image.jpg")

理由4：本番環境向けの最適化

"The SAM 2 model you downloaded from Ultralytics is optimized for size and performance, which is why it is smaller than Meta's original release."

— Ultralytics GitHub Discussionより

和訳: Ultralyticsからダウンロードしたモデルは、サイズとパフォーマンスのために最適化されており、Meta公式リリースよりも小さい。

Metaの公式sam_hiera_large.ptが857MBなのに対し、Ultralytics版は429MB。半分のサイズで同等の性能。

公式 vs Ultralytics：比較表

項目 Meta公式リポジトリ Ultralytics
インストール難易度 地獄 天国
CUDA設定 手動で必須 自動
PyTorchバージョン管理 手動 自動
チェックポイントダウンロード 手動 自動（SAM3除く）
Windows対応 WSL推奨 ネイティブ対応
ドキュメント 研究者向け 実用向け
API統一性 なし YOLO等と統一
サポート GitHub Issue Discord + GitHub

"The fastest and highest-performance way to deploy SAM2 to Modelbit is using the Ultralytics package to run SAM2."

— Modelbit Documentation より

和訳: SAM2をModelbitにデプロイする最も速くて高性能な方法は、UltralyticsパッケージでSAM2を実行することだ。

本番環境へのデプロイでもUltralyticsが推奨されている。

SAM3の凄さ：何ができるようになったのか

せっかくなので、SAM3で何ができるようになったか整理しておこう。

SAM1（2023年）

  • ポイント、バウンディングボックス、マスクでプロンプト
  • 単一オブジェクトのセグメンテーション
  • 画像のみ対応

SAM2（2024年）

  • SAM1の機能 + 動画対応
  • フレーム間でオブジェクトを追跡
  • オクルージョン（遮蔽）にも対応

SAM3（2025年）

"SAM3's breakthrough takes it from a geometry-focused tool into a concept-level vision foundation model."

— Edge AI and Vision Alliance記事より

和訳: SAM3のブレークスルーは、幾何学に焦点を当てたツールからコンセプトレベルのビジョン基盤モデルへと進化させた。

新機能：

  • テキストプロンプト: 「yellow school bus」と入力するだけ
  • コンセプトセグメンテーション: 同じカテゴリの全インスタンスを一括検出
  • 画像エグゼンプラー: 「この画像のこの部分と似たもの」で検索
  • 27万コンセプト対応: 従来ベンチマークの50倍以上

"The system handles 270,000 unique concepts over 50 times more than existing benchmarks"

— AI Films記事より

和訳: このシステムは27万のユニークなコンセプトを扱う。既存のベンチマークの50倍以上だ。

実践：Ultralyticsで今すぐSAMを動かす

理論はいい。今すぐ動かそう。

環境構築（3分）

# 仮想環境作成
python -m venv sam-env
source sam-env/bin/activate  # Windows: sam-env\Scripts\activate

# Ultralyticsインストール
pip install ultralytics

これで完了。

SAM2で画像セグメンテーション

from ultralytics import SAM
import cv2

# モデルロード（初回は自動ダウンロード）
model = SAM("sam2.1_b.pt")

# 画像読み込み
image_path = "your_image.jpg"

# ポイントプロンプトでセグメンテーション
results = model(image_path, points=[[500, 300]], labels=[1])

# 結果を保存
for result in results:
    result.save("output.jpg")

YOLOとSAMの連携

YOLOで物体検出 → SAMで精密セグメンテーション、という連携も簡単。

from ultralytics import YOLO, SAM

# YOLOで検出
yolo = YOLO("yolov8n.pt")
detections = yolo("image.jpg")

# 検出結果からバウンディングボックスを取得
boxes = detections[0].boxes.xyxy.tolist()

# SAMでセグメンテーション
sam = SAM("sam2.1_b.pt")
for box in boxes:
    results = sam("image.jpg", bboxes=[box])

まとめ：依存関係地獄からの解放

SAMシリーズを使いたいなら、Meta公式リポジトリに手を出す前にUltralyticsを試そう。

公式リポジトリの場合:

  • CUDA_HOME設定
  • PyTorchバージョン調整
  • NumPy互換性問題
  • CUDAアーキテクチャ設定
  • Windowsは実質非対応
  • 累計数時間〜数日の試行錯誤

Ultralyticsの場合:

  • pip install ultralytics
  • from ultralytics import SAM
  • 終わり

この差は歴然だ。

研究者が最新のモデルをすぐに使えるようにする。それがUltralyticsの哲学なんだと思う。

依存関係地獄で泣いた僕からのアドバイス：Ultralyticsを使え。

君の大切な時間を、環境構築ではなくモデルの活用に使ってほしい。

参考リンク

この記事が役に立ったら、ぜひフォローといいねをお願いします。依存関係地獄で苦しんでいる仲間がいたら、この記事をシェアしてあげてください。

4
3
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
4
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?