gatilin/WeDetect-Ref-2B-Base

WeDetect Verify · 指代表达目标检测（Referring Expression Detection）本地验证工程

本工程在 macOS（Apple Silicon, MPS 后端）上对 WeDetect 两阶段检测体系进行端到端本地验证：

1. WeDetect-Base-Uni（YOLO-World 风格，ConvNeXt-Base + CSPRepBiFPAN）— 负责生成 100 个类别无关的 object proposals；
2. WeDetect-Ref-2B（基于 Qwen3-VL 2B 的 Grounding 模型，Qwen3VLGroundingForConditionalGeneration）— 将每个 proposal 映射为一个 <object> token，在单次前向传播中对全部 proposal 按指代查询（referring query）打分，取 top-1（或按阈值过滤）作为最终检测框。

该「proposal 生成 → VLM 重打分」的范式兼具传统检测器的定位密度与多模态大模型的语言理解能力。

---

目录结构

wedetect_verify/
├── assets/
│   └── demo.jpeg                     # 验证用示例图（卧室场景, 1280×720）
├── models/
│   ├── wedetect-base-uni/
│   │   └── wedetect_base_uni.pth     # Proposal 生成器权重（414 MB）
│   └── wedetect-ref-2b/              # Ref-2B 权重（5.0 GB, safetensors ×2 分片）
│       ├── config.json               # model_type: qwen3_vl, bf16
│       ├── model-0000{1,2}-of-00002.safetensors
│       └── tokenizer / preprocessor / chat_template 等
├── scripts/
│   ├── generate_proposal.py          # SimpleYOLOWorldDetector 完整实现（ConvNeXt + Neck + Head）
│   ├── wedetect_ref/                 # Qwen3VL Grounding 模型适配代码
│   ├── run_ref.py                    # 单查询端到端推理（官方 infer 脚本的 macOS 适配版）
│   ├── verify.py                     # 多查询批量验证 + 彩色面板可视化
│   ├── verify_uni.py                 # Uni proposal 生成器独立验证
│   ├── vis.py / smoke_test.py        # 可视化工具 / 冒烟测试
├── outputs/                          # 推理输出（可视化 + JSON/TXT 结果）
├── download.sh                       # 模型权重下载脚本（hf-mirror，支持断点续传）
└── resume_shard{1,2}.sh / resume_ref.sh  # 大文件续传脚本

模型说明

模型	角色	架构	权重规模
WeDetect-Base-Uni	Proposal 生成（class-agnostic）	YOLO-World 风格：ConvNeXt-Base backbone + CSPRepBiFPAN neck + 解耦回归/对比分类头（reg_max=16）	414 MB (.pth)
WeDetect-Ref-2B	指代查询重打分（grounding）	Qwen3-VL 2B：vision encoder（24 层, hidden 1024, patch 16）+ LLM（28 层, hidden 2048, GQA 16/8, mrope），bf16	5.0 GB (safetensors)

下载（含断点续传，已配置 hf-mirror）：

bash download.sh

推理管线

输入图像
  │
  ├─ ① WeDetect-Base-Uni ──► 100 proposals (xyxy, 原图坐标) ──► proposals.png
  │
  └─ ② WeDetect-Ref-2B
        prompt:  Please detect the "<query>" in the image
        answer:  <object> × 100          # 每个 proposal 对应一个 <object> token
        ──► 单次 forward，对每个 <object> 位置输出 sigmoid 分数
        ──► top-1 / score_thre 过滤
        ──► results_*.png（标注面板）+ results_*.json

关键实现点（scripts/run_ref.py / verify.py）：

• 权重键重映射（remap_uni_keys）：官方 .pth 的 backbone.image_model.model.*、bbox_head.head_module.* 命名与本地简化实现不一致，加载前做 key 重命名。
• <object> token 对齐：object_token_index = tokenizer.convert_tokens_to_ids("<object>")，推理后将 logits 在 <object> 位置上取出并 sigmoid，即得到每个 proposal 的匹配分数。
• 设备自适应：--device auto 时优先 MPS（bf16），否则 CPU（fp32）；attn_implementation="sdpa"。

快速开始

环境依赖：torch（含 MPS 支持）、transformers>=4.57、safetensors、torchvision、Pillow。

cd scripts

# ① 端到端单查询推理
python run_ref.py \
  --image ../assets/demo.jpeg \
  --query "the round alarm clock" \
  --score_thre -1.0          # -1 表示 top-1；>=0 时按阈值保留多框

# ② 多查询批量验证（生成彩色标注面板）
python verify.py \
  --queries "yellow pillows on the bed" "the round alarm clock" \
            "paintings on the wall" "the arc floor lamp" "flowers in the vase"

# ③ 单独验证 proposal 生成器
python verify_uni.py

验证结果（MPS · bf16 · 1280×720 示例图）

Proposal 生成（WeDetect-Base-Uni，100 框）

100 个类别无关 proposal 完整覆盖图中主要物体（床、枕头、落地灯、挂画、闹钟、花瓶、窗、书架、高跟鞋等）。Top-10 proposal 分数区间为 0.49–0.78，完整排序见 outputs/uni_proposals.txt。

指代查询定位（WeDetect-Ref-2B）

#	查询	得分	耗时（forward）
Q1	yellow pillows on the bed	0.39	4.0 s（首次含预热）
Q2	the round alarm clock	0.57	1.6 s
Q3	paintings on the wall	0.82	1.6 s
Q4	the arc floor lamp	0.73	1.8 s
Q5	flowers in the vase	0.28	1.6 s

5 条查询全部正确定位：闹钟、挂画、落地灯框选精准；flowers in the vase 得分偏低（0.28）但位置正确，符合小目标在稀疏 proposal 下的预期表现。稳态单次前向约 1.6 s（MPS / bf16 / 100 proposals）。结构化结果见 outputs/results_demo.json。

输出文件说明

文件	内容
outputs/proposals.png	全部 100 个 proposal 的青色框叠加图
outputs/uni_proposals.png	同上图（verify_uni.py 独立运行产物）
outputs/uni_proposals.txt	100 个 proposal 的 xyxy 坐标 + 分数 + 面积（按分数降序）
outputs/results_demo.png	多查询彩色标注面板（每查询一色，框上标注 query 与 score）
outputs/results_demo.json	每条查询的 box / score / forward 耗时、设备与 dtype 信息

备注

• 权重下载若中断，直接重跑 download.sh 或使用 resume_shard{1,2}.sh 断点续传（-C -）。
• Ref-2B 为 bf16 权重，在 CPU 上运行需 fp32，显存/内存占用约 10 GB，建议 MPS 或 CUDA。
• 本工程为验证用途：SimpleYOLOWorldDetector 是对官方实现的精简复刻，已验证与官方权重 strict=False 加载兼容（missing/unexpected 键为 0 或仅无关项）。