人工智能计算机视觉基础模型深度学习预训练【免费下载链接】sam2The repository provides code for running inference with the Meta Segment Anything Model 2 (SAM 2), links for downloading the trained model checkpoints, and example notebooks that show how to use the model.项目地址https://gitcode.com/gh_mirrors/sa/sam2点击查看免费下载本文以 Meta Segment Anything Model 2SAM 2官方安装文档INSTALL.md为核心结合仓库内 setup.py、pyproject.toml 等源码细节系统讲解 SAM 2 在 Linux / WSL 环境下的完整安装流程。读者将掌握如何满足 Python、PyTorch、CUDA 的环境要求如何通过pip install -e完成可编辑安装如何在构建 CUDA 扩展失败时依旧正常使用 SAM 2 的图像与视频推理以及如何强制构建扩展以启用掩码后处理并逐一解决安装与运行阶段的高频报错。环境要求Requirements官方推荐的运行环境组合如下这是确保所有特性尤其是torch.compile可用的前提组件要求说明操作系统Linux若使用 Windows强烈建议安装 Windows Subsystem for LinuxWSL UbuntuPython≥ 3.10setup.py 中通过python_requires3.10.0硬性约束PyTorch≥ 2.5.1与 torchvision 一起在 https://pytorch.org 安装保证两者版本匹配torchvision与 PyTorch 匹配的版本必须与 PyTorch 一同安装避免版本错位CUDA Toolkit与 PyTorch 的 CUDA 版本匹配默认安装命令下通常对应 CUDA 12.1几点补充说明更老版本的 Python 或 PyTorch 也可能正常工作但上述版本是官方强烈推荐组合只有满足它们才能使用全部特性如torch.compile与 Flash Attention v2 相关的注意路径。源码层面pyproject.toml 的构建依赖与 setup.py 的REQUIRED_PACKAGES都声明了torch2.5.1。PyTorch 的 CUDA 版本与系统 CUDA Toolkit 版本必须匹配安装时 SAM 2 需要用 NVCC 编译自定义 CUDA 内核运行时则依赖 PyTorch 链接的 CUDA 运行时。安装 CUDA Toolkit 后可用nvcc --version检查其版本。标准安装步骤在仓库根目录执行pip install -e .[notebooks]该命令做了两件事可编辑安装-e以开发模式将sam2包链接进当前 Python 环境后续from sam2 import ...即可直接导入同时将仓库根目录含sam2_configs配置模块纳入sys.path。安装 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_CUDA0 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_argscompile_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 -vverbose 模式下才会显示。判断扩展是否构建失败如果在安装日志中看到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_ERRORS0 pip install -v -e .[notebooks]要点pip uninstall -y SAM-2包名是SAM-2见 setup.py必须完整卸载旧安装rm -f ./sam2/*.so清理旧的扩展编译产物若残留旧.so可能导致加载到旧二进制SAM2_BUILD_ALLOW_ERRORS0一旦 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 中分别以modeholes与modeislands清理小孔洞与小岛。这正是 INSTALL.md 所说的后处理步骤去除输出掩码中的小孔洞与碎块——它在绝大多数情况下只是轻微清理缺失时推理结果依然可用。常见安装问题排查以下问题按出现场景分类均附官方给出的解决方案。1.ImportError: cannot import name _C from sam2sam2._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 .。若安装后仍然失败可手动将仓库根目录加入PYTHONPATHexport 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 内核。处理步骤安装与 PyTorch CUDA 版本匹配的 CUDA Toolkit若仍然报错显式指定CUDA_HOMEexport CUDA_HOME/usr/local/cuda # 改成你的 CUDA Toolkit 路径重跑安装命令。可用下面命令验证 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-isolationpip 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 中的torch2.5.1临时改为torch2.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_LIST9.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只有 AmpereCUDA capability 8.0及以上 GPU 才启用 Flash AttentionPyTorch 低于 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_FP161, -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_argscompile_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 扩展只影响掩码后处理的精细度只有当你需要完整的掩码清理能力、或遇到本指南列出的报错时才需要按照严格模式重装或针对性调整编译参数。赞分享人工智能计算机视觉基础模型深度学习预训练【免费下载链接】sam2The repository provides code for running inference with the Meta Segment Anything Model 2 (SAM 2), links for downloading the trained model checkpoints, and example notebooks that show how to use the model.项目地址https://gitcode.com/gh_mirrors/sa/sam2点击查看免费下载相关推荐PHPExcel 入门指南环境要求、安装部署与常见问题排查PHPExcel 入门指南环境要求、安装部署与常见问题排查 本篇技术指南以 PHPExcel 官方开发者文档《Getting Started》为骨架结合仓库后端数据处理Apache Thrift 全平台安装与源码构建指南环境要求、构建流程与常见问题Apache Thrift 全平台安装与源码构建指南环境要求、构建流程与常见问题 Apache Thrift 是一套跨语言的 RPC 与序列化框架其代码仓库后端微服务API设计Detectron2 安装完全指南环境要求、源码编译、常见错误排查与 Docker/Colab 部署Detectron2 安装完全指南环境要求、源码编译、常见错误排查与 Docker/Colab 部署 导读 本指南以仓库根目录的 INSTALL.md htt人工智能计算机视觉深度学习机器学习上一篇DeepChat部署3条命令多模型AI助手直接能用下一篇xiaomusic 极空间ZSpaceNAS 部署完整教程镜像拉取、容器配置与设备绑定排错创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考