betum_tool 中的 SAM 3 零样本 PCS 消融实验日志：从实验设计到后处理调优

• 人工智能
• 深度学习
• NLP
• 计算机视觉
• 强化学习

导读

本文围绕betum_tool仓库中 SAM 3（Segment Anything Model 3）模块的消融实验记录文档 ablations.md 展开，系统讲解 Promptable Concept Segmentation（PCS）零样本推理实验的完整设计与记录规范：包括实验跟踪表、文本提示词工程、置信度阈值扫描与 mask→bbox 后处理调优。读者将掌握如何在 Cashew / Coffee 农业数据集上运行 SAM 3 零样本分割实验、如何用统一 COCOEval 计算 AP@50，以及如何把每一次实验系统地沉淀为可复现、可对比的消融日志。

一、实验日志的定位：为什么需要一张"一行一跑"的消融表

在 betum_tool 的统一评测框架下，四支学生团队分别用 OWL-ViT、YOLO26、SAM 3、DiffusionDet 完成同一个农业检测任务，最终全部换算成 COCOEval 的AP@50单一指标进行对比。SAM 3 组的目标是：用文本提示驱动分割基础模型输出稠密实例分割掩码，再通过掩码转边界框（mask→bbox）管道对齐到目标检测的评价口径。

正因如此，ablations.md 被设计为 SAM 3 组的实验台账——"Track all experiments here. One row per run."（在这里跟踪所有实验，每次运行一行）。它承担三个核心职能：

1. 实验可复现：记录 Mode、Dataset、Prompts/Config、Confidence Threshold 等关键变量，后续可完整复现任一行实验；
2. 对比可追溯：AP@50 指标与提示词、阈值一一对应，便于横评提示词工程与后处理策略的收益；
3. 汇报可依赖：作为小组展示与跨模型对比的原始依据，直接支撑 TECHNICAL_BRIEFING.md 中 SAM 3 消融结论的沉淀。

仓库约定：每个模型组只能在各自的models/<name>/目录内工作，实验结果统一记录在models/<name>/results/ablations.md，这与本文档的目录位置（betum_tool/models/sam3/results/ablations.md）完全对应。

二、实验跟踪表：零样本 PCS 的四种基线运行

文档的核心是 Results 表，当前已登记的 4 次运行为 SAM 3 组划定了零样本实验的起点：

这张表揭示了 SAM 3 组消融实验的两个关键设计维度：

• 数据集维度：Cashew 与 Coffee 两个数据集在类别构成上差异显著。class_map.json 显示，Cashew 有 6 类（tree、flower、premature、unripe、ripe、spoilt），Coffee 有 5 类（unripe、ripening、ripe、spoilt、coffee_tree）。因此在同一提示词策略下分别验证两个数据集，可以区分"提示词质量问题"与"数据集固有难度"。
• 提示词维度：Run 1/2 使用 baseline prompts（如"cashew tree"、"cashew flower"、"premature cashew nut"等类别直译提示），Run 3/4 使用 simple prompts（如"tree"、"flower"、"premature"等更短、更泛化的提示）。两组实验保持相同的置信度阈值（0.05），从而隔离出提示词措辞对 AP@50 的独立影响。

从 template_inference.ipynb 的配置节可以看出，提示词列表与 COCO JSON 的category_id顺序严格对应（"Order matches category_ids 0, 1, 2, ..."）：

TEXT_QUERIES = { "cashew": [ "cashew tree", "cashew flower", "premature cashew nut", "unripe cashew nut", "ripe cashew nut", "spoilt cashew nut", ], "coffee": [ "unripe coffee berry", "ripening coffee berry", "ripe coffee berry", "spoilt coffee berry", "coffee tree", ], }

这意味着 Run 1 在 Cashew 上实际会逐类执行 6 次 PCS 推理，每次推理产出的实例掩码被转换为 bbox 后统一汇入预测 JSON，再与cashew_val.json比对计算 AP@50。填表时 Notes 列建议补充每类的表现差异，例如 TECHNICAL_BRIEFING.md 中记录的微类（micro-class）案例：标准提示"cashew flower"的 AP@50 仅为 0.0001，而判别性提示下同一类提升约 100 倍——这类洞察正是 Notes 列应当沉淀的内容。

三、提示词工程：零样本 PCS 收益最大的杠杆

文档的第二张表专门用于记录"试过哪些文本提示及其对 PCS 分割质量与 bbox 推导的影响"：

3.1 三类提示词策略的设计意图

• baseline（基线）：用类别名直译，是最自然的出发点，便于建立零样本性能下限；
• simple（简单）：去掉类别前缀（如"cashew"），测试模型对单一名词的响应能力。从实践中看，这种提示往往因为概念过于泛化（如"tree"可能命中背景中的其他树木）而表现不稳，因此必须逐一记录其 AP@50 影响；
• domain-specific（领域特定）：引入作物学高保真术语（如"cashew inflorescence"花序、"immature cashew nut"未成熟坚果），目标是缩小基础模型预训练分布与无人机俯拍农业图像之间的语义鸿沟。

3.2 提示词工程的标准实验协议

template_inference.ipynb 的"Prompt Engineering Experiments"一节给出了明确的实验纪律：至少评估 3 种不同的提示词配置，并把结果记录到results/ablations.md。建议的消融方向包括：

1. 简单类别名：tree、flower、unripe等；
2. 上下文短语：a photo of a unripe coffee berry、dense cashew tree leaves等；
3. 领域特定描述：采用数据集论文或类别映射中的高保真术语。

仓库已有的实证结果（见 TECHNICAL_BRIEFING.md）充分说明提示词对 PCS 微类性能的放大效应：

• Standard Prompt（"cashew flower"）：AP@50 =0.0001
• Discriminant Prompt（"an isolated cluster of tiny pale cashew flower blossoms"）：AP@50 =0.0177

需要注意的是：判别性提示对特定微类带来约 100 倍的相对提升，但绝对分数依然很低，说明零样本性能瓶颈更多来自领域根本性差距而非提示措辞——这正是一张规范的提示词消融表能帮助团队得出"是否值得继续投入提示词工程"结论的原因。

四、后处理与推理参数调优：阈值、最小面积与 NMS

文档第三张表记录后处理/推理阶段的调参实验：

4.1 confidence_threshold：从低起点出发并做扫描

零样本模型输出的置信度普遍偏低，因此仓库默认CONFIDENCE_THRESHOLD = 0.05，并在推理时先用更低的threshold=0.01采集候选，再在评估阶段统一扫描：

SCORE_THRESHOLDS_TO_SWEEP = [0.01, 0.05, 0.1, 0.15, 0.2]

template_inference.ipynb 中的阈值扫描节对每个阈值调用统一评估包装器并汇总成表：

for thresh in SCORE_THRESHOLDS_TO_SWEEP: res = run_coco_eval(COCO_VAL_JSON, all_predictions, score_threshold=thresh) sweep_results[thresh] = res["AP@50"]

阈值过滤的实际逻辑位于 evaluate.py 的evaluate_coco：

if score_threshold is not None: pred_list = [p for p in pred_list if p.get("score", 1.0) >= score_threshold]

仓库基线数据（TECHNICAL_BRIEFING.md）显示：SAM 3 在标准阈值 0.25 下 Aggregate AP@50 = 0.03，在超宽松阈值 0.01 下为 0.04，提升极其有限——这印证了文档中"从低阈值开始，之后逐步调优"的策略，同时也提示：当阈值扫描收益极小时，问题大概率出在模型/提示词端而非过滤设置端。

4.2 min_mask_area_pixels：用最小面积过滤噪点掩码

PCS 的低阈值推理会产出大量碎小掩码（如背景噪点、重复分割片段）。min_mask_area_pixels用于在 mask→bbox 转换前过滤面积过小的掩码。从 masks_to_bboxes.py 的实现看，mask_to_bbox对空掩码返回None并跳过：

rows = np.any(mask, axis=1) cols = np.any(mask, axis=0) if not rows.any(): return None # Empty mask

这说明"面积为 0"的掩码已被天然过滤；而面积较小的非空掩码仍会生成 bbox。实践中建议将min_mask_area_pixels与 COCO 的 area 定义对齐——evaluate.py 中明确指出 COCOEval 的 area 划分为small（< 32² 像素）、medium（32²–96²）、large（> 96²）——在无人机俯拍场景中，小于 32×32 像素的实例通常既难以辨认也无实际产量统计价值。

4.3 nms_iou_threshold：对派生 bbox 做去重

同一概念在相邻区域可能产出多个高重叠掩码（例如一朵花被分割成多个碎片），转换为 bbox 后会出现大量重复框。此时需要在 bbox 层面执行 NMS（非极大值抑制），nms_iou_threshold控制"多大重叠算重复"。从 README.md 的"Key Parameters to Explore"清单看，NMS 被明确列为 SAM 3 组建议探索的后处理项之一。需要注意的是：SAM 3 原生推理（run_sam3_native_pcs）会返回 processor 后处理得到的boxes（xyxy 格式）与scores，而仓库的统一评测入口evaluate_coco本身不包含 NMS，因此若需 NMS 去重，应在生成 COCO 预测 JSON 之前完成。

4.4 记录规范：一次实验 = 一组参数 + 一个 AP@50

文档的表格采用"Parameter | Default | Tried | Effect"四列结构，这正是可复现实验的最小记录单元：默认值定义基线，Tried记录尝试值，Effect记录对 AP@50（或视觉质量）的影响。填表时应把Tried列与 Results 表中的 Run 号交叉引用，形成"参数 → 运行 → 指标"的完整链条。

五、从实验到结论：mask→bbox 与统一评测如何支撑消融结果

消融日志的价值最终要落到 AP@50 这一个数字上，而该数字的正确性依赖两条已由源码与测试锁定的链路。

5.1 掩码 → bbox 转换的正确性

masks_to_bboxes.py 提供两个函数：

• mask_to_bbox(mask)：输入二值掩码(H, W)，通过np.any分别在行、列方向投影，取首末非零下标，输出 COCO 格式[x_min, y_min, width, height]，空掩码返回None；
• pcs_output_to_coco_predictions(masks, scores, image_id, category_id)：把一个概念的多实例掩码批量转换为 COCO 预测字典（含image_id、category_id、bbox、score），空掩码自动跳过。

其正确性由 masks_to_bboxes_test.py 的四个用例验证：空掩码返回None、单像素掩码[5, 4, 1, 1]、矩形掩码[3, 2, 4, 3]，以及多实例掩码批量转换后 bbox 与 score 的完整对应。这意味着你在消融表中填写的每个 AP@50，其底层的 bbox 几何都是经过单元测试保障的。

5.2 统一评估口径

所有预测最终统一走 common/evaluate.py 的evaluate_coco：

results = evaluate_coco(gt_json="path/to/gt.json", predictions=pred_list, score_threshold=0.05)

该函数内部通过COCOeval(coco_gt, coco_dt, "bbox")执行标准 bbox 评估，返回AP（IoU 0.50:0.95）、AP@50、AP@75以及per_class_ap50字典。它同时对预测做两层保障：阈值过滤（见 4.1）与空预测兜底（返回全零指标并告警），保证任何一次实验都能得到结构化、可比对的指标输出——这正是消融表"一行一跑、AP@50 可横比"的制度基础。

六、完整的 SAM 3 消融实验工作流

结合 template_inference.ipynb 与本文档的表格体系，一次规范的消融实验按以下流程执行：

1. 准备数据：安装依赖（transformers、torch、pycocotools等），下载 Coffee & Cashew 数据集，用 flatten_coffee.py 展平 Coffee 批次，用 yolo_to_coco.py 将 YOLO 标注转换为 COCO JSON（--split_ratio 0.8划分验证集）；
2. 鉴权加载模型：facebook/sam3为门控仓库，需先通过 Hugging Face 认证，再以Sam3Processor/Sam3Model加载，并自动选择 CUDA / MPS / CPU 设备；
3. 配置实验变量：设置NUM_EXAMPLES（建议 4 张做冒烟测试，全量置None）、DATASET、CONFIDENCE_THRESHOLD、SCORE_THRESHOLDS_TO_SWEEP与TEXT_QUERIES；
4. 推理与转换：对每张图、每个概念提示执行 PCS（processor.post_process_instance_segmentation，阈值 0.01、mask 阈值 0.0），将返回的掩码/xyxy bbox 统一转为 COCO[x_min, y_min, width, height]预测；
5. 评估与扫描：调用evaluate_coco计算 AP@50，并对阈值列表逐一扫描，输出阈值—AP@50 汇总表；
6. 可视化与落盘：以较高阈值（如 0.15）绘制预测 vs 真值对照图，预测 JSON 保存到results/目录供跨模型对比；
7. 回填日志：把 Run 号、Mode、Dataset、Prompts/Config、阈值、AP@50 填入 Results 表，把提示词变体填入提示词表，把参数尝试填入后处理表。

完成至少 3 种提示词配置的消融后，即可基于日志在小组展示中横向对比 SAM 3（零样本分割）与 OWL-ViT（开放词汇检测）、YOLO26（有监督检测）在稠密微农业场景下的定位能力差异——这正是 TECHNICAL_BRIEFING.md 中跨模型结论（"边界框架构在稠密微农业场景中仍保有明显优势"）的实验来源。

七、实践建议：让消融日志发挥最大价值

最后，基于仓库的整体设计与已有消融结果，为 SAM 3 组的日志维护给出几点建议：

1. 保持"一行一跑"纪律：任何参数变更（哪怕只是改了一个词）都单独开一行，严禁覆盖式更新，否则跨模型对比将失去可信度；
2. Notes 列记录定性观察：如"树标签经常把花簇圈进 bbox""spoilt 类与果实黑斑强相关"等定性发现（参见 TECHNICAL_BRIEFING.md 对标注噪声的分析），能帮助解释数值异常；
3. 阈值扫描结果并入日志：将 4.1 中的扫描表粘贴到 Results 表附近，注明每个阈值对应的 AP@50，避免"阈值选择不可复现"；
4. 区分"提示词问题"与"领域问题"：当判别性提示只能带来 100 倍相对提升而绝对值仍低（0.0001 → 0.0177）时，应把调优重心转移到微调 mask decoder（冻结编码器 vs 全量微调，见 README.md）而非继续堆提示词；
5. 与统一评测接口强绑定：任何新实验的 AP@50 都必须经 evaluate.py 输出，禁止自行实现评估逻辑，以保障四组横评口径一致。

通过这样一份严谨的消融日志，SAM 3 组不仅能回答"零样本 PCS 在农业稠密场景下能达到什么水平"，还能为后续的提示词工程、后处理调优与模型微调提供可直接引用的实验证据。

• 人工智能
• 深度学习
• NLP
• 计算机视觉
• 强化学习