SAM3 这波热度大家应该都看到了官方 Demo 里随手点几个点就能把物体干净地抠出来确实惊艳。但真正到了你自己电脑上来跑很多朋友会在第一步卡住Hugging Face 权重下载不动、环境依赖互相打架、demo 脚本里的路径不对最后只能对着报错干瞪眼。这篇文章就是我踩完坑之后的完整记录主旨很明确用国内镜像 ModelScope 权重把 SAM3 Demo 从安装到启动的每一步掰开揉碎讲清楚照着抄就能跑通。不管你是想本地验证效果、做二次微调还是打算接到 ComfyUI、Gradio 之类的项目里这套流程都适用。1. SAM3到底是什么动手指之前先搞清楚模型结构1.1 SAM3和之前版本最关键的区别SAM3 的全称是 Segment Anything Model 3核心思路和 SAM、SAM2 一脉相承给你一张图你再给一个点、一个框或者一段涂鸦它就能把对应物体完整分割出来。但 SAM3 最大的变化不是换了个更大的 backbone而是把“自动分割一切”和“可交互微调”这两件事更好地揉在了一起。它沿用了经典的三大件架构图像编码器负责把图片变成特征向量提示编码器接收点、框这些用户输入掩码解码器负责输出最终的分割掩码。SAM3 在社区里被讨论最多的是它对 Adapter 的支持。“sam3 adapter”这个说法你如果搜过应该不陌生它其实是一组小型的可训练模块插在图像编码器后面让你微调时不需要动整个几十亿参数的大模型只训练 adapter 里的低秩参数即可。这样做有一个非常实际的好处显存占用低、训练速度快个人机器也能跑微调。另外很多开源 SAM3 实现里会把注意力机制玩出花来比如在 adapter 内部引入通道注意力和空间注意力模块去决定到底应该把网络容量分配给哪些特征通道、哪些空间位置。如果你下载的权重文件描述里写着 CBAM不用觉得奇怪它就是一种经典的通道、空间权重分配结构。理解这一点你在跑 Demo 时看到“adapter checkpoint not found”这类报错就会知道该去找哪个文件补上。1.2 Demo 跑不起来的常见原因我在各种群里看到最多的求助不是模型效果差而是根本跑不起来总结下来无非三类第一类权重下载问题。官方 Demo 默认从 Hugging Face 拉权重但实际下载时经常是速度极慢、中断、checkpoint 文件损坏。很多人卡在“Downloading model.safetensors…”这行字上大半天进度条纹丝不动。第二类环境依赖冲突。SAM3 涉及 PyTorch、torchvision、opencv、gradio 等一堆包版本稍微一不对就会在 import 阶段报错或者明明装了 GPU 版 torch 却提示 CUDA not available。第三类路径不对。权重文件明明是下载好了但是 demo 脚本里写死了一个 checkpoint 路径你丢到别的目录跑自然 FileNotFoundError。这中间最气人的是第一类因为你网络快慢不归你控制但下载方案完全可以换。所以这篇文章会把权重下载作为重点中的重点先把源搞定再谈环境。2. 国内镜像到底怎么用选对方案才不白折腾2.1 Hugging Face 镜像和 ModelScope 怎么选先说结论如果你的目标只是下载 SAM3 权重优先用 ModelScope。它的服务部署在国内下载速度快、稳定而且支持命令行和 Python API 两种方式。Hugging Face 国内镜像也很好用适合你还需要拉其他 HF 仓库官方依赖的场景。我自己实际测试下来Hugging Face 在部分网络环境下会频繁断流设置镜像后速度能稳定在几 MB/s 到十几 MB/s但对一些大型 safetensors 文件仍然可能出现校验失败。ModelScope 则稳很多尤其是一个仓库里多个文件需要连续下载时它的断点续传和缓存策略做得比较省心。方案适合场景常见痛点推荐度Hugging Face 国内镜像需要兼容 HF 生态的代码个别文件需重试高ModelScope只下载模型权重部分仓库是社区搬运需要核对文件名非常高如果你是跑 SAM3 的官方 demo代码里大概率用了from_pretrained或者checkpointxxx这种方式官方默认还是会去 HF 找。这时候你可以先设置HF_ENDPOINT环境变量让所有 huggingface_hub 的请求都走国内镜像比如export HF_ENDPOINThttps://hf-mirror.com这一行写在终端里再启动 Python或者写进.bashrc就能让 huggingface_hub 不走默认源。如果你在 Windows 上可以在系统环境变量里加一个HF_ENDPOINThttps://hf-mirror.com效果一样。2.2 环境变量和 pip 镜像一次配好除了 Hugging Face 镜像Python 包下载源也建议一起换成国内镜像。否则你 pip install 的时候光一个 torch 就能卡到怀疑人生。建议先做一次全局配置pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn这条命令会把 pip 默认源改成清华源后续安装依赖的体验会好很多。如果用 conda 建环境也可以顺手把 conda 的 channel 换成国内镜像conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --set show_channel_urls yes如果你打算用 Docker 跑 Demo那还得看一下 Docker 的国内镜像源配置。daemon.json里加一段registry-mirrors这样拉基础镜像不会卡在层下载上。这一步不是必需但能减少很多“看起来是代码问题、实际是镜像拉不下来”的假报错。2.3 下载权重的三种方式下载 SAM3 权重常见的有三种姿势直接用git lfs clone适合下载小仓库但对大文件支持一般而且 Git LFS 在国内某些网络下表现不稳定。用huggingface_hub的snapshot_download配合HF_ENDPOINT使用适合代码里想按需下载的场景。用 ModelScope 的modelscope download命令这是我最推荐的方式尤其适合一次性拉大文件多文件。下面一节会单独讲 ModelScope 的实操这里先提一句不要在一个权重还没下载完的时候反复 CtrlC很多断点续传实现得并不好重头再来时间更亏。多等几分钟或者用带断点续传的hf命令比如hf download加--resume能省很多事情。3. ModelScope 权重下载实操照着抄就行3.1 安装 modelscope 并配置缓存目录ModelScope 的安装很简单一行命令pip install modelscope装完之后我建议先设一个缓存目录避免模型文件散落在 home 目录下不好找export MODELSCOPE_CACHE/data/modelscope_cache这样所有通过 ModelScope 下载的模型都会集中在同一个目录后续清理、备份、复用都比较方便。Windows 下就在系统环境变量里加MODELSCOPE_CACHE路径指向一个空间足够的盘。3.2 用一条命令把 SAM3 全套权重拉回来ModelScope 最方便的是支持命令行直接下载。一般格式是这样modelscope download --model 模型命名空间/模型仓库名 --local_dir ./weights/sam3比如你看到社区里有人用comfy-org/z_image这个仓库来跑相关任务那命令就是modelscope download --model comfy-org/z_image --local_dir ./models/z_image如果是 SAM3 的官方权重仓库把模型命名空间/模型仓库名替换成实际仓库 id 就行。我建议先登录 ModelScope 网页搜索 “SAM3”看权重文件列表确认需要的文件名再下载。因为社区搬运仓库有时候命名比较随意有的是sam3_h.pt有的是sam3_h.pth还有的是pytorch_model.bin。先看一眼要什么省得下完发现文件名对不上。如果你需要在自己写的 Python 脚本里自动下载可以改用 APIfrom modelscope import snapshot_download model_dir snapshot_download( namespace/sam3, local_dir./weights/sam3 ) print(model_dir)这个 API 的好处是会把仓库里的文件全部同步下来并且本地已经存在且校验通过的文件不会重复下载。跑过一次之后日常调试不重下非常实用。3.3 下载完成后的目录检查与哈希校验权重下完之后别急着跑先看一眼目录结构和文件大小ls -lh ./weights/sam3 du -sh ./weights/sam3SAM3 的权重文件一般不小vit_h级别的 checkpoint 动辄 2GB 以上如果你看到只有几十 KB那八成只是 dl 脚本不是真正的模型权重。看文件大小是最快的“防呆”手段。如果模型仓库页面上给了 SHA256你还可以做一次校验sha256sum ./weights/sam3/sam3_h.pt我在实际下载连续中断了几次之后就吃过哈希不对的亏。模型加载的时候没有立刻报错但是推理出来的掩码全是乱的排查了很久才发现是权重文件下载不完整。所以这一步千万别省特别是从大文件断点续传之后的场景。4. 从零跑通 Demo依赖安装、脚本改动、界面启动4.1 用 conda 隔离环境并安装 PyTorch环境问题大部分都是因为全局环境太乱。我的习惯是每个模型单独建一个 conda 环境SAM3 也不例外conda create -n sam3 python3.10 -y conda activate sam3Python 版本建议选 3.10兼容性最好。接下来安装 PyTorch。如果你有 N 卡先确认自己 CUDA 版本再选择对应命令。以 CUDA 12.1 为例pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121如果你没有 GPU就装 CPU 版pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpuCPU 版也能跑 Demo只是推理会慢不少但至少能把流程走通。装完 torch 之后再装 SAM3 相关依赖。不同仓库包名不一样我习惯用的最小依赖集是这样的pip install opencv-python pillow scipy gradioSAM3 的推理代码可能封装成segment-anything风格也可能在sam3包里具体以你下载的仓库 README 为准。关键是先把基础库装好后面缺什么补什么。4.2 修改 Demo 脚本里的权重路径很多 Demo 跑不起来就是权重路径写死。我自己的习惯是把权重统一放到项目下的weights/sam3目录然后在脚本开头用绝对路径或者基于项目根目录的路径。比如CHECKPOINT_PATH ./weights/sam3/sam3_h.pt不要直接复制官方脚本里的/root/.cache/huggingface/...这种你机器上根本不存在的路径。改完之后先做一个最简单的加载测试import torch from segment_anything import sam_model_registry device cuda if torch.cuda.is_available() else cpu sam sam_model_registry[vit_h](checkpoint./weights/sam3/sam3_h.pt).to(device) print(SAM3 loaded successfully)如果这一步不报错就说明权重文件至少能正常读入接下来再深入其他逻辑。4.3 跑一个基础的 SAM3 分割脚本下面这个脚本是我用来快速验证 SAM3 是否可用的模板你只需要准备一张图然后把一个点的坐标传进去SAM3 就会输出 maskimport cv2 import numpy as np import torch from segment_anything import SamPredictor, sam_model_registry device cuda if torch.cuda.is_available() else cpu sam sam_model_registry[vit_h](checkpoint./weights/sam3/sam3_h.pt).to(device) predictor SamPredictor(sam) image cv2.imread(demo.jpg) image cv2.cvtColor(image, cv2.COLOR_BGR2RGB) predictor.set_image(image) input_point np.array([[250, 250]]) input_label np.array([1]) masks, scores, logits predictor.predict( point_coordsinput_point, point_labelsinput_label, multimask_outputTrue, ) best_idx np.argmax(scores) mask masks[best_idx] print(mask shape:, mask.shape, score:, scores[best_idx])这段代码的关键在于predictor.set_image会先算一次图像特征后面的交互预测就可以很快返回。如果你用 SAM3 的 adapter 版本这段逻辑基本不变只是模型加载的地方会多传一个 adapter 权重路径。4.4 改成 Gradio 交互 Demo官方 Demo 那种可以点来点去的界面其实就是用 Gradio 包的壳。要快速变成交互界面可以写一个简单的函数接收图片和点坐标返回掩码叠加结果import gradio as gr import cv2 import numpy as np import torch from segment_anything import SamPredictor, sam_model_registry device cuda if torch.cuda.is_available() else cpu sam sam_model_registry[vit_h](checkpoint./weights/sam3/sam3_h.pt).to(device) predictor SamPredictor(sam) def segment_image(image, x, y): image_rgb cv2.cvtColor(image, cv2.COLOR_BGR2RGB) predictor.set_image(image_rgb) input_point np.array([[int(x), int(y)]]) input_label np.array([1]) masks, scores, _ predictor.predict( point_coordsinput_point, point_labelsinput_label, multimask_outputTrue, ) mask masks[np.argmax(scores)] overlay image.copy() overlay[mask 0] (0, 255, 0) return overlay gr.Interface( fnsegment_image, inputs[gr.Image(), gr.Number(labelx), gr.Number(labely)], outputsgr.Image(), ).launch(server_name0.0.0.0, server_port7860)启动后浏览器打开http://localhost:7860上传一张图填两个坐标就能看到分割结果。想要更像官方 Demo可以再加画点组件但核心原理不变set_image 一次然后不断预测。5. 常见问题与排查技巧实录5.1 权重文件不完整、加载报错症状模型加载时提示unexpected key in checkpoint或者size mismatch甚至直接CUDA out of memory后程序崩掉。这种大概率是权重文件没下完。先用文件大小和哈希校验确认。如果确实不完整重新下载时建议用local_dir指定到一个固定目录避免重复下载半截文件。另外很多仓库会同时提供.pt和.safetensors两种格式如果.pt加载报错换成.safetensors加载往往能绕过 pickle 序列化兼容问题。5.2 显存不足或推理太慢SAM3 的大模型版本吃显存比较厉害。如果是 6GB 显存以下建议换vit_b轻量版本或者直接把输入图片缩小到 1024 内。predictor.set_image之前先做一次 resize速度和显存占用都会好很多。如果是在 CPU 上跑不要用vit_h不然一张图等几十秒是常事。可以考虑先用vit_b验证流程等需要生产环境了再换大模型。5.3 Adapter 权重没生效分割结果不理想如果你用的 SAM3 仓库包含 adapter 机制但跑出来的结果和官方效果差很多先检查 adapter 权重有没有真正加载。有些 demo 脚本只加载了主模型 checkpointadapter 路径还是注释掉的。去代码里搜一下adapter关键字确认类似load_adapter(weights/sam3/adapter.bin)的调用存在。更隐蔽的问题是某些实现里 adapter 和主模型的 device 不一致导致推理结果错乱。保险做法是把主模型和 adapter 都.to(device)保持统一。5.4 Gradio 页面打不开或白屏Gradio 启动后如果页面白屏常见原因有三个端口被占用、浏览器代理问题、服务器监听地址不对。端口占用就换一个lsof -i:7860如果远程服务器上部署一定要server_name0.0.0.0。如果本地访问正常但远程打开不了检查防火墙和云平台安全组。6. ComfyUI 里快速接入 SAM3 的补充方案6.1 修改 ComfyUI 的模型加载源很多人用 SAM3 不是直接在 Python 里写脚本而是想在 ComfyUI 里拖节点玩。问题是 ComfyUI 有些自定义节点默认会去 Hugging Face 下载权重这时可以沿用前面说的HF_ENDPOINT环境变量方案。在启动 ComfyUI 之前终端里执行export HF_ENDPOINThttps://hf-mirror.com然后启动python main.py这样 ComfyUI 里所有依赖 huggingface_hub 的节点都会优先走国内镜像省去很多等待。6.2 用 ModelScope 下载 ComfyUI SAM3 相关权重ComfyUI 的自定义节点通常需要把权重放到指定目录可以先用 ModelScope 命令行拉到本地再手动移动。比如modelscope download --model comfy-org/z_image --local_dir ./models/z_image然后根据节点要求把这个目录下的文件放到ComfyUI/models/checkpoints/或ComfyUI/models/sam/。具体放哪个目录看节点的 README通常写得很明确。重要的一点是不要在一个节点报错说找不到模型文件时才想起来去下载。我一般先看节点代码里的folder_paths相关逻辑确认它到底去哪个目录找再动手放文件。6.3 自定义节点路径与验证把权重放到 ComfyUI 后重启一次 ComfyUI然后在模型加载节点里刷新列表。如果还是没看到 SAM3 权重大概率是路径不对。最简单的验证方法是在 ComfyUI 工作流里加一个显示路径的节点或者直接去 Python shell 里打印folder_paths.get_filename_list(checkpoints)。实测下来ComfyUI 接入 SAM3 的坑往往不是权重本身而是自定义节点和 ComfyUI 版本之间的兼容性。遇到ModuleNotFoundError就补装对应依赖遇到节点报错就看看自定义节点是否有requirements.txt先把它装上再说。7. 最后再分享几个实操细节写到这里其实整个流程已经通了。最后再分享几个我在实际使用中总结的小细节。SAM3 权重动辄几个 GB我强烈建议把MODELSCOPE_CACHE和HF_HOME都指向一个大盘目录而不是默认的 home 目录。否则跑几次之后磁盘空间悄悄被占满你会看到各种莫名其妙的写文件报错。另外跑 Demo 之前先确认 CUDA 和 PyTorch 是否匹配。不要装了 CPU 版 torch 却在 N 卡机器上等半天也不要 GPU 版 torch 配了太老的 CUDA 驱动。用torch.cuda.is_available()测一下最快。还有网上不少“安装教程”会推荐直接 pip install 官方最新包但 SAM3 这种迭代快的模型我建议优先用 stable tag 或者 Release 版本避免跟踪 master 分支时接口突然变化。我第一次就是锁了最新 commit 去装结果第二天接口就变了整个脚本报废。如果你是打算做 SAM3 微调尤其要注意 adapter 权重文件的位置。很多微调脚本会把 adapter 单独输出一个目录你需要记住它因为推理阶段还要单独加载。踩过几次坑之后我的习惯是把主模型、adapter、配置文件放在同一个权重目录下命名里带上版本号和日期说起来还是那句权重目录整理清楚能帮你省下至少两小时的排查时间。SAM3 这个模型本身确实很强但再强的模型第一步没跑通也白搭。希望这份“避开大坑”的手册能让你少走弯路把力气花在调效果上而不是和权重文件、镜像源死磕。