如何在自定义数据集上微调 SAM 3：从跑通到落地的完整指南

【免费下载链接】sam3The repository provides code for running inference and finetuning with the Meta Segment Anything Model 3 (SAM 3), links for downloading the trained model checkpoints, and example notebooks that show how to use the model.项目地址: https://gitcode.com/gh_mirrors/sam/sam3

跟着走一遍，你手里会多出一个适配自己业务的分割模型：输入一张图加一句"卡车"或一个框，它就把图里所有目标实例整块抠出来。这是典型的 SAM 3 finetuning 场景，预训练模型在通用概念上已经够用，但在你自己的品类、领域图上召回和边界常常掉档，微调就是为了把这段差距补上。下面按"先跑通、再调优"的顺序过一遍，全程只用仓库自带的 Hydra 配置，不碰模型代码。

先把环境跑通，5 分钟的事

🔧 前置条件只有一条：Python 3.12+、PyTorch 2.7+、带 CUDA 12.6+ 的 GPU，训练是实打实吃显存的。克隆仓库并装训练依赖，一条命令搞定：

git clone https://gitcode.com/gh_mirrors/sam/sam3 cd sam3 pip install -e ".[train]"

装完还差一步：微调用的是官方预训练权重，得先在 Hugging Face 上申请 checkpoint 访问权限，然后hf auth login登录，训练时才拉得下来。这步最容易漏，漏了会在加载模型阶段报 401。

数据流视角：它为什么能"看懂"一句话

把 SAM 3 当成一条流水线看更清楚。一句"a penguin"先进文本编码器，和当前帧一起喂给检测器（Detector），负责在这一帧里找出所有匹配实例；同一帧的图像特征还会进图像编码器，和上一帧传来的掩码一起交给跟踪器（Tracker），把已有目标顺延到当前帧。检测器发现的新目标，再和跟踪器传过来的旧目标合并，得到当前帧的完整输出。

这里有两个关键设计解释了"它为什么行"。一是 presence token：它专门负责判断"这个文本提示到底对不对得上"，所以"红衣球员"和"白衣球员"这种近似提示不会互相串味，这是微调后文本区分度能不能拉开的根基。二是检测器和跟踪器解耦：一帧内负责"发现"，跨帧负责"跟上"，两者不抢参数，数据能上量而任务不互相拖累。视频场景下，历史帧信息存在 Memory Bank 里供 Tracker 复用，这就是它能做视频跟踪的来路。

数据长什么样，配置里就怎么写

💾 数据格式和配置字段是绑在一起的，最好一起看。SAM 3 走 COCO 格式：训练目录里放图像，配一份_annotations.coco.json，里面存图像路径、XYWH 边界框、RLE 掩码和类别标签。推荐按train/、valid/、test/三个子目录组织，每个子目录一份标注。

配置就在 sam3/train/configs/ 下，基于现有模板改paths和trainer.data两块即可。数据"长什么样"，对应配置里的这些 key：

paths: roboflow_vl_100_root: /path/to/your/dataset experiment_log_dir: /path/to/logs bpe_path: sam3/assets/bpe_simple_vocab_16e6.txt.gz trainer: data: train: dataset: img_folder: ${paths.roboflow_vl_100_root}/train/ ann_file: ${paths.roboflow_vl_100_root}/train/_annotations.coco.json load_segmentation: ${scratch.enable_segmentation}

其中img_folder指向图像目录，ann_file指向对应的 COCO 标注；load_segmentation和trainer.model.enable_segmentation要一起置true，否则掩码分支不生效，只学框不学 mask。其余transforms、loss 权重、归一化参数保持默认即可，它们默认值就是全参微调的推荐设置。

单卡先跑通，再上多卡和集群

🚀 先让它在一张卡上转起来，确认数据能读、loss 能降，再谈规模。单卡启动：

python sam3/train/train.py \ -c configs/roboflow_v100/roboflow_v100_full_ft_100_images.yaml \ --use-cluster 0 --num-gpus 1

多卡只需把--num-gpus调大，脚本内部走 NCCL 起多进程：

python sam3/train/train.py -c configs/...yaml --use-cluster 0 --num-gpus 4

上 SLURM 集群时改--use-cluster 1，再带--partition、--account、--num-nodes，机制和本地一致，不再展开。

跑起来之后再动这三个最高频参数，别贪多：

• scratch.resolution（默认 1008）：输入分辨率，是显存和精度的主旋钮，显存紧就先降它。
• scratch.train_batch_size配合scratch.gradient_accumulation_steps：前者默认 1，显存不够时用后者把有效 batch 攒大。
• scratch.lr_scale（默认 0.1）：整体缩放各参数组学习率，全参微调别用原始大学习率，容易被自己的小数据集带过拟合。

怎么判断效果达标，怎么接进现有流程

✅ 判断标准很简单：把同一份配置里trainer.mode从train改成val，跑一遍验证：

python sam3/train/train.py -c configs/...yaml trainer.mode=val

看 COCO 风格的 IoU、AP（含边界框精度和掩码质量）。训练侧用 TensorBoard 盯总 loss、分类 loss、分割 loss 和学习率：

tensorboard --logdir /path/to/experiment_log_dir/tensorboard

判断达标的方式，是对比微调前后在验证集上的 AP 提升幅度，以及人工抽查几张边界和召回是否明显改善，而不是死盯某个绝对值。落地接入也不复杂：微调产物是标准 checkpoint，直接交给 sam3/ 里的Sam3Processor或 video predictor 推理，接口和原版一致，等于把权重换掉、流程不动，能直接塞进你现有的检测或分割管线。

实战高频踩的坑

显存直接爆：现象是刚开训或第一个 val 就 OOM，原因多为resolution1008 偏高叠加enable_segmentation开了掩码分支，解法是先把scratch.resolution降到 640、用gradient_accumulation_steps顶 batch，再视情况开 bfloat16（配置里optim.amp默认已开）。

只学框不学 mask：现象是输出只有边界框没有掩码，原因是只开了load_segmentation没同步开trainer.model.enable_segmentation，解法是两处一起置true，并确保 loss 里的 Masks 项没被注释掉。

文本近似提示互相串味：现象是"红衣/白衣球员"召回一塌糊涂，原因是没用好 presence token 对应的 presence loss，解法是确认 loss 配置中use_presence: True且presence_loss权重保持 20 量级。

checkpoint 拉不下来：现象是加载阶段报 401/403，原因是没在 Hugging Face 申请过 SAM 3 权重访问权限或未登录，解法是申请通过后执行hf auth login再启动训练。

接下来可以往哪走

微调只是起点，方向看你的瓶颈：

• 推理加速：装flash-attn-3等可选依赖能显著提速，适合要把微调模型推到线上、对延迟敏感的场景。
• 视频跟踪迁移：同一套权重能直接跑视频跟踪（见 examples/ 里的 video predictor 示例），图像微调收益会顺带传导到跟踪任务。
• 多任务与小样本扩展：配置里的 job array 支持一次在多个数据集上批量微调，适合你有一堆细分类目、想低成本铺开专属模型的场合。

选一条往下推，先拿一个小数据集把"微调→验证→接入"这条闭环走通，再谈规模和精度，比一上来就调参稳得多。

【免费下载链接】sam3The repository provides code for running inference and finetuning with the Meta Segment Anything Model 3 (SAM 3), links for downloading the trained model checkpoints, and example notebooks that show how to use the model.项目地址: https://gitcode.com/gh_mirrors/sam/sam3