# 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
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`。

```bash
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 框）

![proposals](outputs/proposals.png)

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

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

![results](outputs/results_demo.png)

| # | 查询 | 得分 | 耗时（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/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 或仅无关项）。