企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 基础模型
• 深度学习
• 预训练

本文以 Meta Segment Anything Model 2（SAM 2）官方安装文档（INSTALL.md）为核心，结合仓库内 setup.py、pyproject.toml 等源码细节，系统讲解 SAM 2 在 Linux / WSL 环境下的完整安装流程。读者将掌握：如何满足 Python、PyTorch、CUDA 的环境要求，如何通过pip install -e完成可编辑安装，如何在构建 CUDA 扩展失败时依旧正常使用 SAM 2 的图像与视频推理，以及如何强制构建扩展以启用掩码后处理，并逐一解决安装与运行阶段的高频报错。

环境要求（Requirements）

官方推荐的运行环境组合如下，这是确保所有特性（尤其是torch.compile）可用的前提：

几点补充说明：

• 更老版本的 Python 或 PyTorch 也可能正常工作，但上述版本是官方强烈推荐组合，只有满足它们才能使用全部特性（如torch.compile与 Flash Attention v2 相关的注意路径）。源码层面，pyproject.toml 的构建依赖与 setup.py 的REQUIRED_PACKAGES都声明了torch>=2.5.1。
• PyTorch 的 CUDA 版本与系统 CUDA Toolkit 版本必须匹配：安装时 SAM 2 需要用 NVCC 编译自定义 CUDA 内核，运行时则依赖 PyTorch 链接的 CUDA 运行时。安装 CUDA Toolkit 后，可用nvcc --version检查其版本。

标准安装步骤

在仓库根目录执行：

pip install -e ".[notebooks]"

该命令做了两件事：

1. 可编辑安装（-e）：以开发模式将sam2包链接进当前 Python 环境，后续from sam2 import ...即可直接导入，同时将仓库根目录（含sam2_configs配置模块）纳入sys.path。
2. 安装 notebooks 附加依赖：[notebooks]对应 setup.py 中的EXTRA_PACKAGES["notebooks"]，包括matplotlib、jupyter、opencv-python与eva-decord，用于运行仓库下的 notebooks/ 示例（图像/视频预测器、自动掩码生成器）。

如果不运行示例 notebook，只做推理，可以省略附加依赖，但官方推荐直接使用".[notebooks]"。安装完成后，仓库根目录会出现sam2包的.so编译产物（若 CUDA 扩展构建成功），并可通过 checkpoints/download_ckpts.sh 下载 SAM 2.1 的四个检查点（tiny / small / base_plus / large）。

跳过 CUDA 扩展安装

若构建环境没有 GPU 或 CUDA Toolkit，可以在安装时通过环境变量跳过 CUDA 扩展的编译：

# 跳过 SAM 2 CUDA 扩展 SAM2_BUILD_CUDA=0 pip install -e ".[notebooks]"

从源码看，setup.py 中的BUILD_CUDA = os.getenv("SAM2_BUILD_CUDA", "1") == "1"，当该变量为0时，get_extensions() 直接返回空列表，不编译任何 CUDA 内核。

代价：运行时的后处理步骤（去除输出掩码中的小孔洞与细小碎块）会被跳过。该步骤依赖 CUDA 扩展提供的连通域分析，但绝大多数情况下不影响结果质量——跳过它只是少了这一层"锦上添花"的清理。

构建 SAM 2 CUDA 扩展

默认行为：允许构建失败

默认情况下，即使 CUDA 扩展构建失败，安装也会继续完成。这一策略在 setup.py 中由SAM2_BUILD_ALLOW_ERRORS（默认"1"）控制。具体机制：

• get_extensions() 中CUDAExtension("sam2._C", srcs, extra_compile_args=compile_args)负责编译sam2/csrc/connected_components.cu，生成sam2._C模块；
• 若编译抛出异常且BUILD_ALLOW_ERRORS为真，会打印CUDA_ERROR_MSG警告（提示 "Failed to build the SAM 2 CUDA extension due to the error above"）并返回空扩展列表；
• 若为假，则直接raise e终止安装。

此外，setup.py 还定义了BuildExtensionIgnoreErrors类，在finalize_options、build_extensions、get_ext_filename三个环节都捕获异常并跳过，保证"安装不因扩展失败而中断"。需要注意，这些错误信息只有在pip install -v（verbose 模式）下才会显示。

判断扩展是否构建失败：如果在安装日志中看到Failed to build the SAM 2 CUDA extension due to the error above，或在运行时看到Skipping the post-processing step due to the error above，说明 CUDA 扩展未成功构建。此时：

• 图像与视频应用依然可以正常使用；
• 仅掩码后处理（去除小孔洞与小碎块）被跳过，多数场景下对结果无实质影响。

强制构建扩展以启用后处理

若希望启用后处理，需要在具备 GPU 的机器上以严格模式重装：

pip uninstall -y SAM-2 && \ rm -f ./sam2/*.so && \ SAM2_BUILD_ALLOW_ERRORS=0 pip install -v -e ".[notebooks]"

要点：

• pip uninstall -y SAM-2：包名是SAM-2（见 setup.py），必须完整卸载旧安装；
• rm -f ./sam2/*.so：清理旧的扩展编译产物（若残留旧.so，可能导致加载到旧二进制）；
• SAM2_BUILD_ALLOW_ERRORS=0：一旦 CUDA 扩展构建失败立即报错退出，避免"静默降级"；
• -v：输出详细构建日志，便于定位问题。

构建前务必确认：PyTorch 已先安装，且 CUDA Toolkit 版本与 PyTorch 的 CUDA 版本匹配（默认命令下通常是 CUDA 12.1），并用nvcc --version验证。

CUDA 扩展的底层职责

该扩展只包含一个源文件 sam2/csrc/connected_components.cu，导出一个函数get_connected_componnets（注意源码中保留了这一拼写），用于对二值掩码做8-连通域分析：返回每个前景像素的连通域标签（labels）与所在连通域面积（counts），要求输入为 CUDA 上的uint8张量、形状[N, 1, H, W]，且 H、W 为偶数。

Python 侧封装位于 sam2/utils/misc.py 的get_connected_components。它被以下后处理逻辑使用：

• fill_holes_in_mask_scores：将面积不超过max_area的背景连通域（小孔洞）以 0.1 的掩码分数填充为前景；若 CUDA 内核异常，会打印 "Skipping the post-processing step" 警告并返回原掩码；
• sam2/utils/amg.py 的remove_small_regions，在自动掩码生成器 sam2/automatic_mask_generator.py 中分别以mode="holes"与mode="islands"清理小孔洞与小岛。

这正是 INSTALL.md 所说的"后处理步骤（去除输出掩码中的小孔洞与碎块）"——它在绝大多数情况下只是轻微清理，缺失时推理结果依然可用。

常见安装问题排查

以下问题按出现场景分类，均附官方给出的解决方案。

1.ImportError: cannot import name '_C' from 'sam2'

sam2._C正是 CUDA 扩展生成的模块。该错误通常意味着：

• 尚未执行pip install -e ".[notebooks]"，或安装失败；
• 先完成安装，再对照下面的其他问题逐一排查。

部分系统上可能需要手动就地构建扩展：

python setup.py build_ext --inplace

在仓库根目录执行，生成sam2/_C*.so。

2.MissingConfigException: Cannot find primary config 'configs/sam2.1/sam2.1_hiera_l.yaml'

说明sam2不在 Python 的sys.path中，通常是没执行pip install -e .。若安装后仍然失败，可手动将仓库根目录加入PYTHONPATH：

export SAM2_REPO_ROOT=/path/to/sam2 # 本仓库路径 export PYTHONPATH="${SAM2_REPO_ROOT}:${PYTHONPATH}"

这样sam2_configs配置模块即可被找到。配置模块的初始化逻辑见 sam2/init.py，它通过 Hydra 的initialize_config_module("sam2", ...)注册内置配置；推理入口 sam2/build_sam.py 中的build_sam2_image_predictor/build_sam2_video_predictor都会按configs/sam2.1/...这类相对路径解析配置，例如 sam2/configs/sam2.1/sam2.1_hiera_l.yaml。

3. 加载新版 SAM 2.1 检查点时出现RuntimeError: Error(s) in loading state_dict for SAM2Base

多半是环境里残留着旧版仓库代码，缺少支撑 SAM 2.1 检查点的新模块。按序执行：

git pull # 拉取 main 分支最新代码 pip uninstall -y SAM-2 pip install -e ".[notebooks]"

若仍不生效，可在 Python 中确认实际加载的源码路径与内容：

from sam2.modeling import sam2_base print(sam2_base.__file__)

并检查本地 sam2/modeling/sam2_base.py 是否包含新版特征（例如no_obj_embed_spatial这一模块，它已在 sam2_base.py 作为构造参数、并在 L176-L179 初始化参数），以此判断自己是否仍在加载旧安装。

4.CUDA_HOME environment variable is not set

说明安装过程找不到包含 NVCC 编译器的 CUDA Toolkit，无法编译自定义 CUDA 内核。处理步骤：

1. 安装与 PyTorch CUDA 版本匹配的 CUDA Toolkit；
2. 若仍然报错，显式指定CUDA_HOME：

export CUDA_HOME=/usr/local/cuda # 改成你的 CUDA Toolkit 路径

3. 重跑安装命令。

可用下面命令验证 CUDA Toolkit 是否正确配置：

python -c 'import torch; from torch.utils.cpp_extension import CUDA_HOME; print(torch.cuda.is_available(), CUDA_HOME)'

预期输出(True, 一个包含 cuda 的目录)。若验证无误仍失败，可尝试给 pip 加--no-build-isolation：

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

5.undefined symbol: _ZN3c1015SmallVectorBaseIjE8grow_podEPKvmm（或类似符号错误）

这类运行时链接错误通常源于环境中存在多份版本的依赖（PyTorch 或 CUDA）：安装时编译链接到 A 版本库，运行时却链接到 B 版本库。常见成因是分别通过pip与conda安装了不同版本的 PyTorch/CUDA，删掉重复的、只保留单一版本即可。

特别地，如果当前 PyTorch 低于 2.5.1，建议先升级到 2.5.1 或更高：否则安装脚本会用pip尝试升级 PyTorch，而此前若曾用conda装过另一版本，就可能产生重复安装。仓库内部基于 PyTorch 2.5.1 构建；若问题依旧，社区反馈降级到 PyTorch 2.1.0 可能解决——可将 pyproject.toml 与 setup.py 中的torch>=2.5.1临时改为torch==2.1.0再安装。

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

说明 CUDA 内核未针对当前 GPU 的 CUDA compute capability 编译，常见于安装环境与运行环境不一致（如 slurm 集群场景）。可拉取最新代码后，手动指定编译目标：

export TORCH_CUDA_ARCH_LIST=9.0 8.0 8.6 8.9 7.0 7.2 7.5 6.0

再重新安装，使内核覆盖常见 GPU 架构。

7.RuntimeError: No available kernel. Aborting execution.（或类似错误）

通常是因为机器没有 GPU，或 PyTorch 版本与 Flash Attention 不兼容，导致F.scaled_dot_product_attention（见 sam2/modeling/sam/transformer.py）找不到可用内核。可放宽注意力内核设置，改用 Flash Attention 之外的其他内核：将 sam2/modeling/sam/transformer.py 中的

OLD_GPU, USE_FLASH_ATTN, MATH_KERNEL_ON = get_sdpa_settings()

替换为

OLD_GPU, USE_FLASH_ATTN, MATH_KERNEL_ON = True, True, True

关于内核选择的默认策略，见 sam2/utils/misc.py 的get_sdpa_settings：只有 Ampere（CUDA capability 8.0）及以上 GPU 才启用 Flash Attention，PyTorch 低于 2.2 时回退到 math 内核。

8.Error compiling objects for extension

典型日志：

unsupported Microsoft Visual Studio version! Only the versions between 2017 and 2022 (inclusive) are supported! The nvcc flag '-allow-unsupported-compiler' can be used to override this version check; however, using an unsupported host compiler may cause compilation failure or incorrect run time execution. Use at your own risk.

这通常是 CUDA 与 Visual Studio 版本不兼容所致。可给nvcc增加-allow-unsupported-compiler参数：修改 setup.py 中 get_extensions() 的compile_args["nvcc"]列表，追加该参数后形如：

def get_extensions(): srcs = ["sam2/csrc/connected_components.cu"] compile_args = { "cxx": [], "nvcc": [ "-DCUDA_HAS_FP16=1", "-D__CUDA_NO_HALF_OPERATORS__", "-D__CUDA_NO_HALF_CONVERSIONS__", "-D__CUDA_NO_HALF2_OPERATORS__", "-allow-unsupported-compiler" # 追加这个参数 ], } ext_modules = [CUDAExtension("sam2._C", srcs, extra_compile_args=compile_args)] return ext_modules

注意：使用不支持的宿主编译器可能导致编译失败或运行期行为异常，此方案需自行评估风险。

安装验证与下一步

完成安装后，可通过如下方式快速自检：

python -c "import sam2; print(sam2.__file__)" # 确认包可导入 python -c "from sam2 import _C; print(_C)" # 确认 CUDA 扩展已构建（若采用跳过模式会报错，属预期） python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

若 CUDA 扩展构建成功，上面的from sam2 import _C不会报错；若构建被跳过，则该行会抛出ImportError，属于 INSTALL.md 描述的正常降级行为，不影响推理主体。

随后即可：

• 下载检查点：运行 checkpoints/download_ckpts.sh，它会自动下载 SAM 2.1 的sam2.1_hiera_tiny.pt、sam2.1_hiera_small.pt、sam2.1_hiera_base_plus.pt、sam2.1_hiera_large.pt四个权重；
• 运行示例：按 README.md 的指引，在 notebooks/ 下体验图像预测、视频预测与自动掩码生成；
• 加载模型：通过 sam2/build_sam.py 中的build_sam2_image_predictor/build_sam2_video_predictor，配合 sam2/configs/sam2.1/ 下的 YAML 配置构建预测器。

一句话总结整个安装策略：默认安装即可覆盖绝大多数使用场景，CUDA 扩展只影响掩码后处理的精细度；只有当你需要完整的掩码清理能力、或遇到本指南列出的报错时，才需要按照严格模式重装或针对性调整编译参数。

• 人工智能
• 计算机视觉
• 基础模型
• 深度学习
• 预训练