bqewutq5565/sam3-concept-bank

SAM3 Concept Bank v3 (3D part names)

一个 287 KB 的文本嵌入偏移库，让冻结的 SAM3 更擅长在无纹理的灰模渲染图上按部件名分割 3D 资产（head / armrest / axle / …）。

SAM3 权重完全没有改动。学到的东西只有两个张量：

	形状	作用
E_0	[256]	共享偏移，适配"灰模渲染 + 部件名"这个域
E	[280, 256]	280 个高频部件名各自的偏移

推理时 pooler_output += E_0 + E[name]（对每个文本 token 广播），然后跑冻结的检测器。方法基于 M2C（arXiv 2606.26711），改成"共享 + 逐名字"的两级库。

文件

文件	内容
bank.pt	部署用。{E_0, E, names, template, base, meta}，meta 里存了全部训练参数
bank_epoch1/2/3.pt	逐 epoch 快照（收益几乎都在 epoch 1）
split.json	1800 训练 / 200 留出物体，复现同一划分
log.jsonl	每 50 step 的 loss，每 epoch 的完整留出集指标
text_cache.pt	2.8 MB，全部名字的 256 维文本向量（已加偏移）。给下游 SegviGen 的图例 token 用，单独用概念库时不需要

结果

留出集 200 个物体 / 1068 个提示词。epoch 0 = 裸 SAM3 基线，v3 = 本库：

分数阈值	mIoU	灰像素（未绑定部件像素，越低越好）	难负例误检（越低越好）
0.4	0.309 → 0.397	0.607 → 0.321	0.229 → 0.254
0.5	0.288 → 0.368	0.654 → 0.381	0.186 → 0.188
0.6	0.259 → 0.333	0.685 → 0.501	0.142 → 0.121

主收益是召回：阈值 0.5 上没被任何名字绑定的部件像素从 65% 降到 38%，而误检率基本不动（0.186 → 0.188），阈值 0.6 上还更低。这说明提升不是靠整体放宽阈值换来的。

建议部署阈值 0.4。阈值 0.3 上难负例误检会从 0.289 涨到 0.324，不要用。

mIoU 绝对值不高（0.37）是正常的：它是"名字级并集"的 2D IoU，GT 用 PartVerse 的部件划分，很多名字本身有歧义（body 到哪算完）。只作相对比较。

用法

import torch

d = torch.load("bank.pt", map_location="cpu")
E_0, E, names = d["E_0"], d["E"], d["names"]
idx = {n: i for i, n in enumerate(names)}

def offset(name):                       # 词表外的名字只吃 E_0
    o = E_0.clone()
    if name in idx:
        o = o + E[idx[name]]
    return o

# 在冻结的 SAM3 上：
#   text_out = model.get_text_features(input_ids=..., attention_mask=...)
#   text_out.pooler_output = text_out.pooler_output + offset(name).view(1, 1, -1)
#   out = model(vision_embeds=..., text_embeds=text_out, attention_mask=...)

完整实现见 finetune/sam3_bank.py 的 ConceptBank 与 run_prompts。

训练

数据：bqewutq5565/segvigen-pv-2view。

python finetune/concept_bank.py --dataset_root /data/pv --out /data/concept_bank_v4 \
  --template name --epochs 3 --neg_mode mixed --negatives 3 --neg_weight 0.5 \
  --lr_e0 5e-4 --holdout_file /data/pv_holdout_v3.txt --azimuths 0,135 \
  --min_count 8 --max_prompts 12 --eval_thresholds 0.4,0.5,0.6

3 epoch × 3600 step，单卡 70 min、峰值 15.3 GB 显存。损失 = 正例 BCE+Dice + 0.5 × 负例 BCE + 0.5 × presence BCE。

facebook/sam3 是 gated 仓库，需要先 huggingface-cli login 并申请访问。

局限

• 只在 az0 / az135 两个方位的 512×512 灰模渲染图上训练，别的视角/带纹理的图没验证过。
• 词表 280 个名字覆盖训练集约 82% 的部件实例；长尾和词表外的名字只吃 E_0，没有专属向量。
• 名字是 LLM 生成后人工审阅的，仍有噪声；names_meta.json 的 uncertain 部件在训练时被排除。
• 只监督"名字 → 像素并集"，同名多实例不会被分开。

相关

代码与完整报告：GzaIcebreak/sam3seggen —— finetune/DATA_concept_bank.md（数据格式与云端训练）、finetune/REPORT_overview.md（含下游 3D 分割对比）。