SAM3 Linux 部署操作记录

1. 适用环境

本流程已在以下环境验证：

• 操作系统：Kylin Linux Advanced Server V10
• GPU：NVIDIA GeForce RTX 4090
• NVIDIA Driver：580.105.08
• 系统显示的 CUDA Driver Runtime：13.0
• Conda 环境 Python：3.12.13
• PyTorch：2.10.0+cu128
• CUDA：12.8
• SAM 3 源码目录：/opt/proj/sam3
• 模型目录：/opt/proj/sam3/models/sam3

本流程适用于服务器无法直接访问 GitHub 和 Hugging Face，需要通过其他可联网机器下载源码和权重后再上传部署的场景。

---

2. 前置检查

在服务器上确认 GPU、驱动和 Python 状态：

cat /etc/os-release
python3 --version
nvidia-smi

重点确认：

• GPU 能被 nvidia-smi 识别；
• NVIDIA 驱动正常；
• 显存充足，SAM 3 在 RTX 4090 24GB 上可正常加载；
• 不建议直接使用系统 Python 或 Conda base 环境。

---

3. 创建 Conda 环境

建议使用 Python 3.12。

conda create -n sam3 python=3.12 -y --override-channels \
  -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main \
  -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r

进入环境并确认：

conda activate sam3
python --version
which python

预期类似：

Python 3.12.x
/root/anaconda3/envs/sam3/bin/python

---

4. 安装 PyTorch 和 CUDA 依赖

使用清华 PyPI 镜像安装：

pip install torch==2.10.0 torchvision \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn

安装完成后，验证 PyTorch 是否可以使用 GPU：

python - <<'PY'
import torch

print("torch:", torch.__version__)
print("torch cuda:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())

if torch.cuda.is_available():
    print("gpu:", torch.cuda.get_device_name(0))
    x = torch.randn(1024, 1024, device="cuda")
    y = x @ x
    print("cuda test:", y.shape, y.device)
PY

预期关键输出：

cuda available: True
gpu: NVIDIA GeForce RTX 4090
cuda test: torch.Size([1024, 1024]) cuda:0

---

5. 在可联网机器下载 SAM 3 源码

服务器无法访问 GitHub 时，在另一台可联网机器上执行：

git clone https://github.com/facebookresearch/sam3.git
tar -czf sam3-source.tar.gz sam3

将 sam3-source.tar.gz 上传到服务器，例如上传到：

/opt/proj/

在服务器解压：

cd /opt/proj
tar -xzf sam3-source.tar.gz
cd sam3

最终源码目录建议为：

/opt/proj/sam3

目录中应包含：

assets/
examples/
sam3/
scripts/
pyproject.toml
README.md

---

6. 安装 SAM 3 源码及基础依赖

进入源码根目录：

cd /opt/proj/sam3
conda activate sam3

安装源码：

pip install -e . \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn

---

7. 修复当前源码缺失的运行依赖

当前 SAM 3 源码在实际导入时，可能还需要补充以下依赖。

7.1 修复 pkg_resources 缺失

如果报错：

ModuleNotFoundError: No module named 'pkg_resources'

安装兼容版本的 setuptools：

pip install --force-reinstall "setuptools<82" \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn

说明：

• setuptools 82+ 中可能没有可用的 pkg_resources；
• 当前 SAM 3 源码仍引用 pkg_resources；
• 安装 setuptools<82 可解决该问题。

7.2 安装 einops

如果报错：

ModuleNotFoundError: No module named 'einops'

执行：

pip install einops \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn

7.3 安装 pycocotools

如果报错：

ModuleNotFoundError: No module named 'pycocotools'

执行：

pip install pycocotools \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn

7.4 安装 psutil

如果报错：

ModuleNotFoundError: No module named 'psutil'

执行：

pip install psutil \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn

---

8. 验证 SAM 3 Python 模块导入

在 /opt/proj/sam3 目录执行：

python - <<'PY'
import sam3
from sam3.model_builder import build_sam3_image_model, build_sam3_video_predictor
from sam3.model.sam3_image_processor import Sam3Processor

print("sam3 import: OK")
print("image model builder: OK")
print("video predictor builder: OK")
print("image processor: OK")
PY

预期输出：

sam3 import: OK
image model builder: OK
video predictor builder: OK
image processor: OK

以下警告目前不影响使用：

pkg_resources is deprecated as an API
Importing from timm.models.layers is deprecated

---

9. 在可联网机器下载模型权重

SAM 3 官方模型权重需要从 Hugging Face 的 facebook/sam3 获取。

下载机器需要满足：

• 能访问 Hugging Face；
• Hugging Face 账号已获得 facebook/sam3 的访问授权；
• 已接受相关模型许可协议。

建议下载并保留以下文件：

sam3.pt
config.json
configuration.json
processor_config.json
merges.txt
vocab.json
tokenizer.json
tokenizer_config.json
special_tokens_map.json

其中最关键的文件：

sam3.pt

model.safetensors 与 sam3.pt 是两种权重格式。对于本部署流程使用的官方源码，优先使用：

sam3.pt

不需要同时保留：

model.safetensors

可不传的文件：

README.md
LICENSE
.gitattributes

---

10. 上传并放置模型文件

建议将模型统一放到：

/opt/proj/sam3/models/sam3

创建目录：

mkdir -p /opt/proj/sam3/models/sam3

将模型文件上传或解压到该目录后，目录结构应类似：

/opt/proj/sam3/models/sam3/
├── sam3.pt
├── config.json
├── configuration.json
├── processor_config.json
├── merges.txt
├── vocab.json
├── tokenizer.json
├── tokenizer_config.json
└── special_tokens_map.json

检查文件：

ls -lh /opt/proj/sam3/models/sam3

注意：

• sam3.pt 约 3.45 GB；
• 确保传输完成后文件大小正常；
• 不建议从非官方来源下载模型权重。

---

11. 离线加载本地模型验证

进入源码根目录：

cd /opt/proj/sam3
conda activate sam3

加载本地模型并放到 GPU：

python - <<'PY'
import torch
from sam3.model_builder import build_sam3_image_model

model = build_sam3_image_model(
    bpe_path="/opt/proj/sam3/sam3/assets/bpe_simple_vocab_16e6.txt.gz",
    checkpoint_path="/opt/proj/sam3/models/sam3/sam3.pt",
    load_from_HF=False,
    device="cuda",
    eval_mode=True,
)

print("local checkpoint load: OK")
print("model device:", next(model.parameters()).device)
PY

预期输出：

local checkpoint load: OK
model device: cuda:0

这一步成功表示：

• SAM 3 Python 环境正常；
• 本地模型权重可读取；
• CUDA 可用；
• 模型已经加载到 NVIDIA GPU；
• 服务器无需访问 Hugging Face 即可进行本地推理。

---

12. 最终目录建议

建议最终保持以下结构：

/opt/proj/sam3/
├── assets/
├── examples/
├── models/
│   └── sam3/
│       ├── sam3.pt
│       ├── config.json
│       ├── configuration.json
│       ├── processor_config.json
│       ├── merges.txt
│       ├── vocab.json
│       ├── tokenizer.json
│       ├── tokenizer_config.json
│       └── special_tokens_map.json
├── sam3/
├── scripts/
├── pyproject.toml
├── README.md
└── README_TRAIN.md

---

13. 常用启动命令

每次使用前：

conda activate sam3
cd /opt/proj/sam3

快速确认 GPU：

python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

快速确认 SAM 3 可导入：

python -c "import sam3; print('SAM 3 import OK')"

---

14. 已验证结果

本次部署已成功验证：

PyTorch CUDA available: True
GPU: NVIDIA GeForce RTX 4090
SAM 3 import: OK
Local checkpoint load: OK
Model device: cuda:0

至此，SAM 3 离线推理环境部署完成。