SAM3 智能工业plc 技术 之机器视频上手实战演示
00怎么用这份教程
SAM 前两代解决的问题是"你点哪里、我切哪里"(PVS,可提示视觉分割);SAM3 往前跨了一大步:你说"找出所有划痕",它就能把图里每一条划痕都连掩码带编号交给你(PCS,可提示概念分割)。它同时还能做点/框提示和视频跟踪——一个模型,三种用法。
这份教程刻意把顺序反过来:先跑通、再玩熟、做出一个像样的质检项目,最后才讲理论。每一章都配了动画演示(基于合成工业数据制作,方便你一眼看清流程),所有代码都可以直接复制到你自己的机器上运行,换成你自己的图片即可得到真实结果。
你需要准备什么
| 项目 | 最低要求 | 说明 |
|---|---|---|
| 硬件 | CUDA GPU(建议 16GB+ 显存) | 848M 参数模型,CPU 跑不动;没有 GPU 可看第 6 章的托管 API 方案 |
| 软件 | Python 3.12+ / PyTorch 2.7+ / CUDA 12.6+ | 官方仓库的硬性要求 |
| 账号 | Hugging Face | 权重是受限开放的,需要先在模型页点"申请访问",一般很快通过 |
| 基础 | 会跑 Python 脚本 | 不需要懂 Transformer,不需要读过 SAM 论文 |
0130 分钟跑通 SAM3
目标只有一个:在你的机器上,用一句 "scratch" 把一张图里所有划痕分割出来。跑通这一步,后面都是顺水推舟。
1.1 安装(官方流程)
# 1) 创建环境(要求 Python ≥ 3.12)
conda create -n sam3 python=3.12 -y
conda activate sam3
# 2) 安装 PyTorch(要求 ≥ 2.7,CUDA ≥ 12.6)
pip install torch==2.10.0 torchvision --index-url https://download.pytorch.org/whl/cu128
# 3) 拉取并安装 SAM3
git clone https://github.com/facebookresearch/sam3.git
cd sam3
pip install -e "."
# 想跑官方示例 notebook 的话:
pip install -e ".[notebooks]"
# 4) 登录 Hugging Face(先去 facebook/sam3 模型页申请权重访问权限)
hf auth login
facebook/sam3 模型页面,点"Request access"即可。另外 SAM 3.1(2026-03 发布,多目标跟踪大幅提速)使用新权重时需要把仓库 git pull 到最新并重装。1.2 第一次分割:一句"scratch"找出所有划痕
把任意一张工业照片命名为 part.jpg,运行下面 12 行核心代码:
from PIL import Image
from sam3.model_builder import build_sam3_image_model
from sam3.model.sam3_image_processor import Sam3Processor
# 加载模型(首次运行自动下载权重)
model = build_sam3_image_model()
processor = Sam3Processor(model)
image = Image.open("part.jpg")
state = processor.set_image(image) # 图像只编码一次,之后可反复提问
# 核心一句:用文本提示"划痕"
output = processor.set_text_prompt(state=state, prompt="scratch")
masks, boxes, scores = output["masks"], output["boxes"], output["scores"]
print(f"发现 {len(scores)} 个实例,置信度:{scores}")
"defect" 的输出:三个缺陷实例(划痕、连锡、铜渣)被同时分割并给出置信度。注意——一次提问,返回的是该类概念的"全部"实例,这是 SAM3 与前两代最直观的区别。1.3 输出到底是什么?
| 字段 | 形状 / 类型 | 含义与用法 |
|---|---|---|
| masks | [N, H, W] 布尔/0-1 | N 个实例的像素级掩码,True 的像素属于该实例。质检里用它算缺陷面积、长度、形状 |
| boxes | [N, 4] | 每个实例的外接框,用来在图上画框、贴标签 |
| scores | [N] | 每个实例的置信度(0~1)。工业场景一定要用它做阈值过滤,见第 3.4 节 |
把掩码叠加到原图上看效果,10 行搞定:
import numpy as np, matplotlib.pyplot as plt
img = np.array(image).astype(float)
for m, s in zip(masks, scores):
m = np.asarray(m)[..., None]
img = img*(1-0.5*m) + np.array([233,37,37])*0.5*m
plt.imsave("result.png", img.astype(np.uint8))
动手做
- 跑通安装,确认
torch.cuda.is_available()返回 True - 用
"scratch"、"dent"、"stain"分别提问你的图,观察哪个词最准 - 把
scores打印出来,看看实例数量与置信度的关系
02四种提示方式:把 SAM3 用熟
SAM3 把"提示"这件事扩展成了四种武器:文本概念、图像示例、点/框几何、视频文本。质检现场 90% 的需求,用前两种就能覆盖;后两种用于精细修正和产线视频。
2.1 文本概念提示(PCS)——主力武器
输入一个简短英文名词短语,模型返回图中所有匹配实例的掩码、框和置信度。这是 SAM3 新引入的能力(Promptable Concept Segmentation),也是工业质检最顺手的入口:缺陷是什么,就直接写什么——"scratch"、"dent"、"solder bridge"、"missing screw"。
state = processor.set_image(image)
output = processor.set_text_prompt(state=state, prompt="surface scratch")
# 同一句话可以连续追问多个概念:
output2 = processor.set_text_prompt(state=state, prompt="dent")
"red apple" 而不是 "find all red apples");② 粒度决定成败——太泛("defect")可能误检,太细可能漏检,多试几个粒度;③ 词有歧义时(比如 "mouse"),改用 2.2 的示例提示消歧。2.2 图像示例提示——圈一个样品,找出所有同款
文字说不清的时候(新型缺陷、外观特殊的专有零件),直接给模型"看例子":框一个正样本告诉它"就要这样的",再框一个负样本告诉它"这种不是"。模型会据此找出全图所有相似实例。官方实验显示,3 轮示例修正后指标可提升 18.6 cgF1——这是质检"人机协同复核"的理论基础。
# 框格式:归一化 [中心x, 中心y, 宽, 高],label=True 为正样本
processor.add_geometric_prompt(box=[0.42, 0.30, 0.35, 0.28], label=True, state=state)
# 负样本:label=False,压制误检
output = processor.add_geometric_prompt(box=[0.82, 0.75, 0.15, 0.15], label=False, state=state)
masks, boxes, scores = output["masks"], output["boxes"], output["scores"]
提示:正负样本框可以叠加多个,也可以与文本提示混用(文本定大类、示例消歧义)。具体参数形态以仓库 examples/sam3_image_predictor_example.ipynb 为准。
2.3 点 / 框几何提示(PVS)——老 SAM 的手艺还在
需要"就切这一个"的时候(比如标注员修掩码、复检时人工指定某个可疑点),用点或框提示。正点纳入、负点剔除,掩码在几轮点击中逐步收敛——这是 SAM 1/2 的经典交互,SAM3 完整保留并可与概念提示混合使用。
2.4 视频分割跟踪——产线的连续画面
视频模式同样接受文本提示:第 0 帧说一句 "defect" 或 "connector",模型会在后续所有帧里检测、分割并保持每个目标的 ID 不变(遮挡后重现也能对上号)。跟踪器继承自 SAM 2 的记忆架构;2026 年 3 月发布的 SAM 3.1(Object Multiplex)用共享记忆做多目标联合跟踪,速度最高提升约 7 倍且精度不降。
from sam3.model_builder import build_sam3_video_predictor
predictor = build_sam3_video_predictor()
resp = predictor.handle_request(request=dict(
type="start_session", resource_path="line.mp4")) # 也支持 JPEG 帧目录
sid = resp["session_id"]
resp = predictor.handle_request(request=dict(
type="add_prompt", session_id=sid,
frame_index=0, text="defect")) # 在任意帧给提示
outputs = resp["outputs"] # 逐帧的掩码与实例 ID
2.5 四种方式怎么选
| 提示方式 | 一句话原理 | 质检中的典型场景 |
|---|---|---|
| 文本概念 | 说一句名词短语,找出所有同类实例 | 常规缺陷类型:划痕、凹坑、缺件、连锡 |
| 图像示例 | 给正/负样品框,找"长得像的" | 新型缺陷、说不清名称的专有结构、消歧 |
| 点 / 框 | 指哪切哪,点击逐步修正 | 人工复检补刀、数据集精细标注 |
| 视频文本 | 一帧给提示,全程跟踪同一批目标 | 传送带连续检测、缺陷件追溯定位 |
03工业质检实战:表面缺陷检测系统
把前面四件武器组装成一条真正能跑的流水线:采图 → SAM3 推理 → 后处理过滤 → OK/NG 判定 → 报表/报警。我们以"金属结构件表面缺陷"为例,你换成 PCB、注塑件、焊缝都一样。
3.1 总体流程
3.2 核心代码:批量检测 + 过滤 + 报表
import glob, csv
import numpy as np
from PIL import Image
from sam3.model_builder import build_sam3_image_model
from sam3.model.sam3_image_processor import Sam3Processor
model = build_sam3_image_model()
processor = Sam3Processor(model)
CONF_THRES = 0.5 # 置信度阈值(3.4 节教你怎么科学地定)
MIN_AREA = 200 # 最小缺陷面积(像素):过滤噪点与伪缺陷
def inspect(image_path, prompt="surface defect"):
image = Image.open(image_path).convert("RGB")
state = processor.set_image(image)
out = processor.set_text_prompt(state=state, prompt=prompt)
defects = []
for m, b, s in zip(out["masks"], out["boxes"], out["scores"]):
m, s = np.asarray(m), float(s)
area = int(m.sum())
if s < CONF_THRES or area < MIN_AREA: # 双闸门过滤
continue
defects.append({"score": round(s, 3), "area_px": area,
"bbox": [round(float(v), 1) for v in b]})
return {"file": image_path,
"verdict": "NG" if defects else "OK",
"defects": defects}
# 批量跑整个文件夹,输出 CSV 报表
rows = []
for p in sorted(glob.glob("line_images/*.jpg")):
r = inspect(p)
rows.append([r["file"], r["verdict"], len(r["defects"]),
max([d["score"] for d in r["defects"]], default=0)])
with open("report.csv", "w", newline="") as f:
csv.writer(f).writerows(
[["file","verdict","n_defects","max_score"], *rows])
set_image 只需一次,换提示词不用重复编码图像——同一工位要查多种缺陷时很省时;② MIN_AREA 按你的相机分辨率与工艺公差换算(如 0.1mm² 对应多少像素);③ 多张实例掩码可继续做形态学分析(长度、长宽比),把"划痕"与"污点"分开判。3.3 分割效果长什么样
3.4 阈值怎么定:别拍脑袋,画曲线
置信度阈值 τ 是质检系统的"松紧螺丝":拧紧了(τ 高)漏检率上升,拧松了(τ 低)误报泛滥。正确做法是拿一小批人工标注过的图,扫描 τ 从 0.05 到 0.95,画出精确率 P、召回率 R、F1 三条曲线,取 F1 最大处为工作点;如果工艺要求"宁错杀不放过",就在召回率 ≥ 目标值的前提下选最高 τ。
for tau in np.arange(0.05, 0.95, 0.05):
tp = fp = fn = 0
for img_path, gt in labeled_set: # 你人工标注的小数据集
out = inspect(img_path) # 用 3.2 的函数
pred = [d for d in out["defects"] if d["score"] >= tau]
# 按掩码 IoU ≥ 0.5 判定命中,累计 tp / fp / fn
...
P, R = tp/(tp+fp+1e-9), tp/(tp+fn+1e-9)
print(tau, P, R, 2*P*R/(P+R+1e-9))
3.5 上产线:从单张图到视频流
- 节拍评估:官方数据是 H200 上约 30ms/图(含 100+ 实例),约合 33 FPS;普通工作站显卡会更慢,先实测你的硬件。
- 多目标视频:换用
build_sam3_video_predictor,提示词在第 0 帧给一次即可全程跟踪;多目标场景优先升级 SAM 3.1(Object Multiplex),联合跟踪最高提速约 7 倍。 - 速度还不够:用 SAM3 自动标注几万张产线图 → 训练 YOLO / RF-DETR 等小模型上线,SAM3 退居"标注引擎 + 抽检复核"(第 6 章详述)。
- 成像先行:现场 80% 的误检来自光照而非模型——先把打光、焦距、曝光做稳定,再谈模型。
04评估指标怎么看
质检系统上线前,老板只会问一个问题:"准不准?"这一节给你回答这个问题需要的全部词汇。
4.1 IoU:分割准不准的基石
4.2 一张表记住所有指标
| 指标 | 公式 / 定义 | 质检里的含义 |
|---|---|---|
| IoU | 交集面积 ÷ 并集面积 | 单个缺陷掩码贴不贴合 |
| 精确率 P | TP ÷ (TP+FP) | 报出来的缺陷里,有多少是真的(误报率反面) |
| 召回率 R | TP ÷ (TP+FN) | 真实缺陷里,有多少被抓到(漏检率反面) |
| F1 | 2PR ÷ (P+R) | P 与 R 的调和平均,定阈值时看它 |
| AP / mAP | PR 曲线下面积(按类平均) | 学术榜单通用分;越高越好 |
| cgF1 | 按概念分组的 F1 平均 | SAM3 论文主指标:防止"常见概念刷分",长尾缺陷也算数 |
| pHOTA | 检测 × 关联 的综合分 | 视频跟踪质量:ID 有没有跟丢 |
4.3 SAM3 官方成绩单(论文 / 官方仓库口径)
| 基准 | SAM3 | 对比对象 | 怎么读 |
|---|---|---|---|
| SA-Co/Gold 检测 cgF1 | 55.7 | OWLv2 24.5 · DINO-X 22.5 · Gemini 2.5 14.4 | 开放词汇检测,领先第二名一倍以上 |
| LVIS 零样本掩码 AP | 47.0 | 此前最佳 38.5 | 零样本实例分割提升约 22% |
| SA-Co 人类水平对比 | 约 75–80% | 人类 = 100% | 开放概念分割已接近人类标注员的八成 |
| 3 轮示例修正增益 | +18.6 cgF1 | 零修正基线 | 人机协同复核的收益上限 |
| 推理速度(H200) | ≈30 ms/图 | 100+ 实例 | 约合 33 FPS 的检测节拍 |
| 视频基准 | SAM3 成绩 | 指标 |
|---|---|---|
| SA-V test | 30.3 cgF1 / 58.0 pHOTA | 概念视频分割 |
| YT-Temporal-1B test | 50.8 cgF1 / 69.9 pHOTA | 长视频概念跟踪 |
| LVVIS / BURST | 36.3 mAP / 44.5 HOTA | 长尾实例视频分割 |
| MOSEv2(VOS) | 60.1 J&F | 较 SAM 2.1 提升 25.5% |
数据来源:SAM3 官方仓库 README、Meta 研究博客与 Ultralytics 文档(链接见第 7 章)。数字随版本更新,以官方页面为准。
05回头懂理论:SAM3 为什么能做到
有了前面的手感,现在看架构图会有完全不同的体验——每个模块你都"用过"。SAM3 = 一个共享的视觉编码器,拖着两条生产线:DETR 式概念检测器(负责图像)和记忆跟踪器(负责视频)。
5.1 一张图看懂数据怎么流
5.2 三个关键设计(用你已有的手感来理解)
① DETR 式检测器 + 检测查询:为什么"一句话能找全所有实例"
SAM 1/2 是"一个提示出一个掩码"的解码器结构;SAM3 换成了 DETR 范式——一组可学习的"检测查询"像 N 个探测针,同时扎向图像特征,每根针若撞上提示所描述的概念就长出一个框和掩码。你在 2.1 看到的"一次提问返回所有划痕",机制上就是这组并行查询的功劳。
② Presence Token:先判断"有没有",再找"在哪里"
开放词汇最容易翻车的地方是相似概念互相污染("白衣球员" vs "红衣球员")。SAM3 在检测查询里加了一个 Presence Token,专门回答"这个概念在图里存在吗",把识别与定位解耦:图里没有的概念直接整体拒答,而不是硬找一个出来。工程含义:负提示(图中不存在的缺陷词)返回空结果是正常且可靠的行为,配合置信度阈值即可放心接入自动判定。
③ 检测器与跟踪器解耦:各练各的,互不拖累
跟踪器直接继承 SAM 2 的 Transformer 记忆架构——把历史帧的掩码特征存进"记忆库",每来一帧就 cross-attention 检索一遍,所以遮挡后重现仍能对上 ID。检测与跟踪解耦意味着两者可以独立加数据、独立迭代(SAM 3.1 的 Object Multiplex 就是只改跟踪器的一次升级)。
5.3 三代 SAM 对比
| SAM 1(2023) | SAM 2(2024) | SAM 3(2025-11) | |
|---|---|---|---|
| 提示方式 | 点 / 框 / 掩码 | + 视频记忆跟踪 | + 文本短语 / 图像示例 |
| 单次提示产出 | 1 个掩码 | 1 个目标的跨帧掩码 | 概念的全部实例(+视频 ID) |
| 语义理解 | 无(类无关) | 无(类无关) | 开放词汇(270K+ 概念评测) |
| 典型定位 | 交互标注工具 | 视频对象分割 | 开放概念检测分割跟踪 · 质检 · 自动标注 |
5.4 能力的来源:SA-Co 数据引擎
SAM3 的"见多识广"来自 Meta 配套构建的 SA-Co 数据引擎:自动标注了超过 400 万个独特概念,评测基准含 27 万个独特概念(约为此前开放词汇基准的 50 倍),并且专门挖掘"看着像但语义不同"的硬负样本。这解释了你实践中的两个观察:① 常见缺陷词零样本就很准;② 碰上特别冷门的专有概念时,给几个示例框(或微调)立刻改善——因为模型"学过怎么学概念",缺的只是你这一类概念的数据。
06进阶与避坑
6.1 什么时候需要微调
判断标准很简单:零样本 + 示例修正仍达不到你的召回率目标,再微调。微调有两种路线:
| 路线 | 做法 | 适合谁 |
|---|---|---|
| 官方训练脚本 | pip install -e ".[train]" 后运行 python sam3/train/train.py -c configs/...yaml --use-cluster 0 --num-gpus 1 |
有 GPU、有标注数据、想完全掌控的团队;配置用 Hydra 管理,支持单机多卡与集群 |
| Roboflow 托管 | 上传数据集 → 版本化(预处理缩放到 1008×1008)→ 一键 Custom Train 选 SAM3 → 云端 / 本地 Inference 部署 | 不想管训练基建、愿意为托管付费的团队;标注阶段可白嫖其 SAM3 Label Assist |
6.2 部署的现实账本
- 速度:H200 约 30ms/图 ≈ 33FPS;你的卡大概率没这么快,先实测。要求 50–100+ FPS 的产线,SAM3 直跑不现实。
- 蒸馏路线(推荐):SAM3 零样本自动标注数万张产线图 → 训练 YOLO-seg / RF-DETR Seg 等小模型上线跑实时;SAM3 留作"新缺陷应急 + 抽检复核 + 持续标注"。这是当前性价比最高的落地范式。
- 无 GPU 团队:可用 Roboflow Inference 等托管 API 按调用计费,先验证业务价值再买卡。
- 显存:848M 参数模型 + 高分辨率工业图,建议 16GB 起步;批量推理用官方
sam3_image_batched_inference.ipynb的批处理写法。
6.3 避坑清单
| 坑 | 症状 | 解法 |
|---|---|---|
| 权重未授权 | 加载模型报 401 / gated repo | HF 模型页申请访问 + hf auth login |
| 提示词写中文或长句 | 结果稀少或不稳 | 改用简短英文名词短语:"scratch" 而非 "找出所有划痕" |
| 提示词太泛 | 正常纹理也被误检 | 加粒度:"deep scratch";或负样本框压制 |
| 不设阈值直接用 | 低置信度噪声实例混入 | scores ≥ τ(第 3.4 节方法定 τ)+ 最小面积过滤 |
| 光照不稳定 | 同一件产品早晚结果不同 | 先修成像(打光/曝光/焦距),再调模型 |
| 视频跟丢 ID | 遮挡后编号错乱 | 升级 SAM 3.1;关键帧重新给提示 |
| 3.1 权重配旧代码 | 加载报错或精度异常 | git pull 最新代码并重装 |
07资源与练习
官方与权威资源
- 代码与权重:github.com/facebookresearch/sam3(安装、示例 notebook、SA-Co 评测)
- 论文与博客:SAM 3: Segment Anything with Concepts · Meta 官方发布博客
- 权重申请:Hugging Face 搜索 facebook/sam3(含 SAM 3.1 新权重与 RELEASE 说明)
- 快速体验:Ultralytics SAM3 集成文档(SAM3SemanticPredictor 几行代码跑文本/示例提示)
- 工业落地参考:Roboflow 制造业缺陷检测算法对比 · SAM3 微调实战
课后练习(按顺序做)
- 用你自己的产品图跑通 2.1 文本提示,试 5 个不同的英文短语并记录效果
- 挑一个"文字说不清"的目标,用 2.2 的正/负示例框消歧,对比修正前后
- 把 3.2 的脚本跑在一个文件夹上,生成你第一张 OK/NG 报表
- 标注 30 张图,按 3.4 画出你的第一条阈值扫描曲线,确定 τ*
- 找一段产线视频,用视频 predictor 全程跟踪,观察遮挡后的 ID 表现
- (进阶)用 3.1 权重重新跑一遍,对比多目标场景的帧率变化
浙公网安备 33010602011771号