企业官网建设流程全解析

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 是 Meta 的开放词汇分割基础模型：给一句短语，它就能在图像或视频里找出该概念的全部实例并分割、跟踪。但零样本效果在私有领域图像上往往不够用。本文讲解如何用你自己的 COCO 标注数据对 SAM 3 微调，读完你能完整走通"数据准备 → 改配置 → 训练 → 评估"全流程。

为什么要微调：通用模型不认识你的货架

SAM 3 微调的业务起点：模型要在货架、产线这类私有场景里工作

以超市盘点为例：你想让模型把货架上某个牌子的果汁纸箱全部框出来。SAM 3 在通用域数据上训练，从没见过这种包装——零样本时它分不清同形状不同规格的纸箱，提示词写再长也不稳定。问题不在提示词，而在数据分布。SAM 3 官方仓库自带微调入口 sam3/train/train.py，配合几百分张私有标注图，就能训出专属于你领域的模型。

环境准备：版本、克隆与依赖安装

官方要求比较新的运行环境，先对照清单：

• Python ≥ 3.12
• PyTorch ≥ 2.7（README 中给出的示例安装是 2.10.0）
• CUDA ≥ 12.6，NVIDIA GPU
• 磁盘空间留足：模型权重和训练日志都不小

建好 conda 环境后，把 PyTorch、仓库和训练依赖一次装齐，执行完你就能import sam3并运行训练脚本：

conda create -n sam3 python=3.12 && conda activate sam3 pip install torch==2.10.0 torchvision --index-url https://download.pytorch.org/whl/cu128 git clone https://gitcode.com/gh_mirrors/sam/sam3 cd sam3 && pip install -e ".[train]"

另外注意：模型权重托管在官方 Hugging Face 仓库，需要先申请访问权限并登录认证后才能下载，训练前把 checkpoint 准备好。

🧩 它是怎么工作的：SAM 3 在训练中的分工

SAM 3 微调的模型架构：文本与视觉编码、检测、跟踪各管一段

训练时你实际上是在"喂"这几块组件：

• 图像编码器：把输入图压缩成视觉特征。微调时它接收梯度更新，学会你领域图像的视觉风格。
• 文本编码器：把 "orange juice carton" 这类短语编码成概念特征，与图像特征融合——这是开放词汇能力（用文字而非固定类别查目标）的来源。
• 检测器 + 解码器：输出框和掩码。默认模板的损失只含框回归（bbox/GIoU）和分类（含 presence 头）两项，掩码损失默认关闭，对应配置里的enable_segmentation: False。
• 训练框架：Hydra 管理配置、submitit 负责本地或集群调度，命令行只决定"在哪跑"。

🗂️ 数据准备：COCO 标注格式与目录布局

加载器（sam3/train/data/coco_json_loaders.py）要求标注文件是 COCO 风格 JSON，关键点如下：

• 标注文件名为_annotations.coco.json，放在train/、test/子目录内
• 每条标注至少含：category_id、bbox（xywh 绝对坐标）、segmentation（多边形或 RLE 均可）、iscrowd
• 类别名就是文本查询本身——模型逐类别拿名字当短语去搜图，所以名字要写成短概念短语
• 图像与标注同目录，文件名在images里一一对应

按官方 README_TRAIN.md 的布局组织数据，占位符<YOUR_DATASET_DIR>对应你的数据根目录：

/path/to/your_dataset/ your_super_category/ train/ 00001.jpg _annotations.coco.json valid/ test/ 00001.jpg _annotations.coco.json

标注 JSON 的最小结构长这样（示例仅说明字段，数值需换成你的真实标注）：

{ "images": [ {"id": 1, "file_name": "00001.jpg", "width": 1920, "height": 1080} ], "annotations": [ {"id": 1, "image_id": 1, "category_id": 1, "iscrowd": 0, "bbox": [412, 305, 260, 180], "segmentation": [[412, 305], [672, 305], [672, 485], [412, 485]]} ], "categories": [ {"id": 1, "name": "orange juice carton"} ] }

SA-CO 数据集样例：SAM 3 训练数据里标注与文本概念是这样组织的

配置定制：实际只需改四组参数

官方模板配置很多，但 90% 不用动。复制一份 sam3/train/configs/ 里的模板（如roboflow_v100/roboflow_v100_full_ft_100_images.yaml），先替换路径段：

paths: roboflow_vl_100_root: /path/to/your_dataset experiment_log_dir: /path/to/experiments bpe_path: sam3/assets/bpe_simple_vocab_16e6.txt.gz

bpe_path指向文本编码器的分词表，仓库内已附带，用相对路径即可。其余最常改的参数，以及"改它会发生什么"：

• scratch.train_batch_size（默认 1）：调大批次收敛更稳但显存上升，显存不够时配合gradient_accumulation_steps用梯度累积兜底
• scratch.lr_scale（默认 0.1）：统一缩放三组学习率（transformer 8e-4、视觉 2.5e-4、文本 5e-5）；调大收敛快，小数据容易发散
• scratch.wd（权重衰减，默认 0.1）：调大相当于加强正则，小数据集抗过拟合就靠它
• scratch.resolution（默认 1008）：输入分辨率，调大对密集小目标更友好，显存和时间同步上涨
• trainer.max_epochs（默认 20）与val_epoch_freq（默认 10）：小数据往往几个 epoch 就收敛，验证频率可同步调小
• scratch.max_ann_per_img（默认 200）：单图最大标注数，密集场景可以下压
• freeze_text_tower/freeze_image_tower（ODinW 模板中为False/NoFreeze，即全不冻结）：小数据时冻结编码器只训头部更稳，改之前先查源码确认合法取值

🚀 启动训练：单卡、多卡、集群三档

三档命令只差调度参数，执行后日志都会落到配置的experiment_log_dir下：

单卡——先验证数据管线和配置能跑通，出第一个 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改成你的卡数：

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

SLURM 集群——partition、account、qos换成你集群的真实取值，跨节点训练加--num-nodes：

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

想快速调试配置时，把配置里的num_images设成小数值（模板默认 100，含义是只取前 100 张训练图），置null则用全量数据。

📊 日志与验收：看哪些指标，怎么评估

训练目录是固定的，方便你直接ls检查：

experiment_log_dir/ ├── config.yaml # 原始配置 ├── config_resolved.yaml # 变量全部展开后的实际配置 ├── checkpoints/ # skip_saving_ckpts=false 时才有 ├── tensorboard/ └── logs/

监控训练健康的命令：

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

判断训练是否正常，盯三件事：

• loss 曲线：稳步下降；突然飙升或直接 NaN 就是发散的信号
• 验证指标：每val_epoch_freq个 epoch 在验证集跑 COCO 框检测评估（AP 系指标），和零样本基线比涨跌
• checkpoint：模板默认skip_saving_ckpts: true不存权重，要留模型就设false，save_freq: 0表示只存最后一个

训练结束后，把配置里trainer.mode改成val再用同一脚本评估你的数据；官方也提供了现成的评估配置可直接跑：

python sam3/train/train.py -c configs/roboflow_v100/roboflow_v100_eval.yaml

验收时除了看 AP，建议抽几张验证集图像人工检查：同类不同规格的对象是否还能区分，这是微调真正要解决的问题。

SA-CO 黄金标注样例：微调后你可以拿模型输出与这类 gold 标注逐张对比

🧯 避坑清单：现象、原因与解法

• 显存爆了（CUDA OOM）：原因通常是resolution偏高、category_chunk_size偏大或批次数了。依次降scratch.resolution、保持train_batch_size: 1、确认配置里use_act_checkpoint_*激活检查点开关都是开的，混合精度默认已是 bfloat16 无需再动。
• loss 发散到 NaN：官方文档明确说"少量 job 训练中可能发散"，届时取发散前最后一个 checkpoint 的结果即可。诱因多为学习率相对数据量太大，把lr_scale降一档重跑。
• GPU 利用率低、像在等数据：多为 worker 不足，调大scratch.num_train_workers（模板默认 10），再确认标注文件不是慢速网络盘。
• 验证集掉点、训练验证差距拉大：典型过拟合，按"加大wd→ 冻结编码器 → 减少max_epochs"的顺序处理。
• 报 checkpoint/权重相关错误：权重需要 Hugging Face 访问权限，先确认已认证且下载完整，再启动训练。

可以继续做的事

1. 打开掩码损失：模板里Masks损失和enable_segmentation都以注释形式给出，需要像素级分割时按注释启用，验收指标也换成 mask 维度。
2. 用 job array 批量扫数据集：submitit.job_array可以一次提交多个数据集的训练任务，适合横向对比多个类别。
3. 复现官方少样本结果：ODinW13 配置里的train_file指定了 seed 化的 few-shot 划分，可以当作"小数据能调成什么样"的参照线。
4. 往视频方向延伸：仓库自带视频推理入口（examples/下的 predictor notebook）和视频数据加载器（sam3/train/data/sam3_video_dataset.py），图像微调跑通后值得评估一下迁移收益。

微调不是一次性的工程，而是"数据 → 配置 → 训练 → 评估"的循环。把第一轮跑通之后，剩下的就是把私有数据持续喂给这个循环。

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