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