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

本文带你把 Meta 的 Segment Anything Model 3（SAM 3）放到自定义数据集上完成一次微调，训出一个懂你领域的专属图像分割模型。从一条最简训练命令讲起，再到 COCO 数据准备、Hydra 配置精调、单机到集群的三种训练规模，最后给出判断训练健康的监控指标与常见毛病的排查思路。

先看成果：微调完你能拿到什么 🎯

跑完下面的流程，你拿到的不只是几个 checkpoint：给模型一句文本提示，它就能在你的目标类别上画出像素级掩码。仓库里的 SA-CO 标注图展示了这种效果——同一场景下不同标注者的分割结果叠在一起，轮廓贴合度一目了然。你的精调模型要追的就是这个水平。

三分钟上手：一条命令先跑通训练 ⚡

先把环境装好。要求 Python 3.8+、PyTorch 1.10+，有 NVIDIA GPU 且 CUDA 11.3+ 体验最好。

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

装完你会看到 pip 顺带装好 hydra-core、submitit、tensorboard 这批训练依赖，sam3包以可编辑模式挂进当前 Python 环境。

然后准备一份最小配置，你只需要改paths这一段：

paths: dataset_root: /path/to/your/custom_dataset experiment_log_dir: ./experiments/custom_training bpe_path: assets/bpe_simple_vocab_16e6.txt.gz

三个字段各管一事：dataset_root指向你的图像与标注根目录；experiment_log_dir是日志与权重的落点；bpe_path指向仓库自带的分词词表，文本提示靠它编码。启动后experiment_log_dir下会生成config.yaml与config_resolved.yaml，这份 paths 是两者里最先被展开的部分。

接着在单卡上拉起训练：

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

跑起来后终端会先打印解析完的 Hydra 配置，随后进入 step 级日志；experiment_log_dir下自动生成checkpoints/、tensorboard/、logs/等子目录，权重与曲线分别落在里面。

原理速览：这套架构为什么值得精调

SAM 3 的核心是"视觉语言融合"：文本编码器把自然语言描述变成向量，图像编码器负责抽视觉特征，检测器在两者交汇处找出目标并吐出掩码，跟踪器把这套能力延伸到视频帧序列，内存银行（memory bank）则保存先前帧的信息供后续帧复用。

对微调而言，这个设计的好处是"两头都热"：你既能靠文本侧学新领域的词汇与描述习惯，又能靠视觉侧吸收新场景的纹理与光照。编码器和解码器默认都不冻结，小数据集也能端到端受益——当然，这也意味着后面要盯紧过拟合。

数据准备：COCO 标注与目录结构一次摆对

SAM 3 读的是 COCO 风格标注：每个 JSON 文件里，每张图给出路径与尺寸，每个目标给出 XYWH 边界框、RLE 或多边形形式的分割掩码，外加类别名与文本描述——文本描述会被文本编码器直接消费，写得具体点没坏处。图像用 JPG 或 PNG 即可。

目录按训练、验证、测试切三份，标注 JSON 与图像文件夹一一对应：

custom_dataset/ ├── images/ │ ├── train/ │ ├── val/ │ └── test/ └── annotations/ ├── train.json ├── val.json └── test.json

按这个结构摆好后，加载数据集时每个ann_file都能在自己的img_folder里找到对应图像，缺图会直接报错。仓库里的 SA-CO 示例数据场景多样、标注密集，很适合当你自己数据集的参照物：

配置精调：只碰这 4 组参数

全部训练参数由 Hydra 配置系统管理，现成模板都在 sam3/train/configs/ 里，roboflow_v100、odinw13 等子目录可直接参考。你真正会动的就四处：paths（上节讲过）、model、training、data。

模型部分决定"从哪开始、冻不冻"：

model: type: sam3_image checkpoint_path: /path/to/pretrained_model.pth freeze_encoder: false freeze_decoder: false

checkpoint_path留空会从 Hugging Face 自动下载；两个 freeze 都为 false，即编码器与解码器一起更新。加载完你会看到日志打印各参数组的学习率，确认没有模块被误冻结。

训练超参管"学多快、学多久"：

training: batch_size: 4 learning_rate: 1e-5 num_epochs: 50 warmup_steps: 1000 weight_decay: 1e-4

batch_size看显存，learning_rate用 1e-5 量级适合小数据集精调，warmup_steps让前 1000 步学习率爬坡，weight_decay控正则强度。改完重启，前 1000 步的损失应平稳下滑而不是起步就抖。

数据加载部分把上节的目录接进训练：

data: train_dataset: type: Sam3ImageDataset img_folder: ${paths.dataset_root}/images/train ann_file: ${paths.dataset_root}/annotations/train.json load_segmentation: true

load_segmentation设为 true 才会真正解析掩码而非只算框；val_dataset 照抄一份换成 val 路径即可。启动后若数据没问题，第一个 step 就会正常出损失值。

其余字段（优化器细节、变换管线、日志配置）保持默认即可，各任务模板里都有现成写法。

训练与看结果：三种规模命令 + 训练健康检查

规模升级只改命令行。单卡换多卡，就是把--num-gpus调大：

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

4 卡跑起来后，每步耗时约压到单卡的 1/4，整体吞吐线性提升。

上 SLURM 集群则把--use-cluster翻成 1，补上分区与账号：

python sam3/train/train.py -c configs/your_custom_config.yaml \ --use-cluster 1 \ --partition gpu_partition \ --account your_account \ --num-gpus 8 --num-nodes 2

提交后作业日志落到experiment_log_dir/submitit_logs/，集群控制台能查到 2 节点 16 卡的任务状态。更完整的命令行参数（--qos等）见 README_TRAIN.md。

训练期间开 TensorBoard 盯曲线：

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

浏览器打开后你会看到损失、学习率、验证指标几条主线。判断训练是否健康看四点：总损失与分类、分割分项损失同步下降；验证集 mIoU、AP 稳步抬升而非锯齿；学习率按 warmup 走不突变；吞吐不随时间衰减。

训完跑评估，同一个训练入口切到验证模式即可：

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

跑完日志会给出 IoU、AP、边界框精度与掩码质量四类指标，对照验证集就能确认这次精调有没有让模型更懂你的领域。

调优实战：过拟合、跑得慢、显存不够的排查路径 🩺

掩码越训越"糙"、验证指标掉头，这是过拟合的典型症状。原因多是数据量撑不起全量更新：先给transforms加随机翻转、缩放抖动这类增强，再设early_stopping.patience让指标停滞时自动刹车；想更保守的话，把weight_decay调大，或直接打开freeze_encoder只让解码器学习。

明明有卡却慢得像单卡，多半是数据管线在排队。处方按性价比排序：把data.num_workers拉到 CPU 核心数附近，让取数与计算重叠；确认training.mixed_precision=true走半精度；batch_size压到能塞下的下限，单步变快，整体吞吐反而上来。

训练中途 OOM 直接崩，通常是显存被高分辨率图像和大标注量挤爆。降法有三个：把data.transforms.resize的输入分辨率调小，这是最立竿见影的；把max_ann_per_img压一压，单图标注太多时中间张量会膨胀；或者开training.gradient_accumulation_steps，用多步小 batch 模拟大 batch，显存不涨而等效 batch 不缩水。

写在最后

到这里，从 clone 仓库、摆好 COCO 数据，到改 4 组配置、按规模起训练、用指标判断健康度，你已经完整走了一遍 SAM 3 在自定义数据集上的精调闭环。接下来想走得更远，有三个方向很自然：把文本描述打磨得更贴近你的领域话术，往往比加数据见效更快；对收敛后的大模型做蒸馏，换一个小得多的权重上产线；或者把精调后的模型接到推理 notebook 上，用 examples/ 里的交互式样例直接验收效果。

【免费下载链接】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