一个面向 COCO2017 的多粒度视觉-语言（Vision-Language）目标检测与聚类实验项目。核心思路是：将 CLIP 视觉特征与「粗粒度（名词）」+「细粒度（整句自然语言描述）」的多粒度文本特征对齐，通过可学习的跨模态适配器与聚类头，提升开放世界的目标检测与聚类能力。
项目名 MAGIC 取「Multi-granularity Aligned Grounded Image Clustering」之意。
- 多粒度语义对齐：粗粒度特征（框内名词 Top-K 加权聚合）与细粒度特征（整句自然语言描述）两种粒度的文本表征，分别与视觉特征对齐。
- 跨模态适配器（Adapter）：固定压缩率适配器与**动态瓶颈（Dynamic Bottleneck）**两种模式。动态瓶颈通过熵门控，对高不确定性的框保留更多信息、对低不确定性的框进行更激进的压缩。
- 聚类头（Cluster Head）：双分支设计——图像分支与「文本-图像注意力」分支，配合一致性矩阵，实现可训练的开放世界聚类。
- 多粒度联合损失：实例级对比蒸馏损失（双向 InfoNCE）+ 聚类损失（类内紧凑 / 类间可分）+ 聚类头监督，统一训练适配器与聚类头。
- 框级与图像级双视角：既支持整图作为样本的图像级聚类（
train_joint.py），也支持每个检测框作为样本的框级聚类评估（box_cluster_eval.py）。 - 完整的检测 → 描述 → 特征 → 对齐 → 聚类 数据流水线，并内置内存库（Memory Bank）用于增量学习防遗忘。
┌────────────────────────────────────────────────────────────────────────┐
│ 数据预处理流水线 │
│ │
│ COCO 标注 ──► generate_coco_descriptions_from_labels.py ──► 整图描述 │
│ └──► text.py（CLIP 编码）──────────────► 整图文本特征 │
│ │
│ box_captioning.py（Qwen2.5-VL 生成框级描述）──► 框级描述 │
│ box_coarse_extractor.py（名词提取 + Top-K 加权）──► 框级粗粒度特征 │
│ semantic_encoder.generate_fine_embeddings（CLIP 编码）──► 框级细粒度特征│
└────────────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ 模型模块 │
│ │
│ DetectionBackbone（DETR）──► 检测框 [B,100,4] + 视觉特征 [B,100,512] │
│ SemanticEncoder ──► 对齐的文本特征 [B,N,512] │
│ BoxAligner ──► 检测框与语义特征索引对齐（IoU / ID / 顺序） │
│ AdapterModule（固定 / 动态瓶颈）──► 跨模态特征适配 │
│ ClusterHead ──► 聚类 logits + 判别 embedding │
│ MultiGranularityLoss ──► 多粒度联合损失 │
│ MemoryBank ──► 增量学习历史样本回放 │
└────────────────────────────────────────────────────────────────────────┘
│
▼
训练（train_joint.py）/ 评估（box_cluster_eval.py）
MAGIC-Master/
├── detection_backbone.py # 检测骨干（DETR → 框 + 视觉特征）
├── semantic_encoder.py # 语义编码器（统一文本特征接口）
├── box_aligner.py # 框索引对齐器 + 端到端集成测试
├── models.py # AdapterModule / ClusterHead / 跨模态注意力
├── dynamic_bottleneck.py # 动态瓶颈（熵门控压缩）
├── loss_utils.py # 多粒度损失
├── memory_bank.py # 增量学习内存库
├── prompt_generator.py # 跨任务 Prompt 生成器
│
├── box_captioning.py # 框级描述生成（Qwen2.5-VL / 固定描述）
├── box_coarse_extractor.py # 框级粗粒度名词特征提取
├── generate_coco_descriptions_from_labels.py # 从标签生成整图描述
├── text.py # 整图描述 CLIP 编码
│
├── train_joint.py # 图像级聚类联合训练（主入口）
├── box_cluster_eval.py # 框级多粒度特征聚类评估
├── test_adapter.py # 适配器消融实验
├── test_backbone.py # 检测骨干接口测试
├── eval_utils.py # 聚类指标（ACC/NMI/ARI，匈牙利对齐）
│
├── environment.yml # conda 环境
├── INTERFACE.md # 团队模块接口说明书
├── COCO2017/ # 数据与预提取特征（.gitignore 已排除）
├── test_data/ # 小型测试数据
├── checkpoints/ # 训练权重（magic_last.pt）
└── box_cluster_eval_report.txt # 框级聚类评估报告
本项目基于 conda 环境 myproject（Python 3.9），主要依赖：
| 依赖 | 用途 |
|---|---|
| PyTorch 2.8.0 + CUDA 12.8 | 深度学习框架 |
| openai-clip | CLIP 视觉/文本编码（ViT-B/32） |
| transformers 4.57 + timm | DETR 检测骨干、Qwen2.5-VL |
| pycocotools | COCO 标注解析 |
| scikit-learn | KMeans / 聚类指标 |
| scipy | 匈牙利匹配（框对齐） |
# 1. 创建环境（基于 environment.yml 一键安装）
conda env create -f environment.yml
conda activate myproject
# 2. environment.yml 未覆盖的额外依赖，需手动安装：
pip install git+https://github.com/openai/CLIP.git # openai-clip
pip install spacy && python -m spacy download en_core_web_sm # 名词提取
pip install munkres # 匈牙利算法（评估）
pip install qwen-vl-utils # 仅框级描述用（可选）镜像提示：代码中已通过
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'使用 HuggingFace 镜像，方便国内下载模型。
数据集采用 COCO2017（本项目默认使用 val2017 子集做实验）。数据与预提取特征默认放在 ./COCO2017/ 目录（已被 .gitignore 排除）：
COCO2017/
├── annotations/instances_val2017.json # 标注
├── val2017/ # 图片（需自行下载）
├── coco_descriptions_val.txt # 整图描述（脚本生成）
├── coco_clip_fine_embedding_val.npy # 整图 CLIP 文本特征（脚本生成）
├── box_descriptions_val.txt # 框级描述（脚本生成）
├── box_coarse_embeddings.npy # 框级粗粒度特征（脚本生成）
├── box_fine_embeddings.npy # 框级细粒度特征（脚本生成）
└── box_metadata.pkl # 框索引元数据（脚本生成）
完整数据流水线按如下顺序运行：
# ① 从标签生成整图描述 → coco_descriptions_val.txt
python generate_coco_descriptions_from_labels.py
# ② 编码整图描述 → coco_clip_fine_embedding_val.npy
python text.py
# ③ 生成框级描述 → box_descriptions_val.txt
# （USE_FIXED_DESCRIPTION=True 用固定描述快速跑通；False 则需本地 Qwen2.5-VL-3B）
python box_captioning.py
# ④ 提取框级粗粒度特征 → box_coarse_embeddings.npy + box_metadata.pkl
python box_coarse_extractor.py
# ⑤ 生成框级细粒度特征 → box_fine_embeddings.npy
# （可调用 semantic_encoder.generate_fine_embeddings，见文件底部注释）若只是复现评估/训练，且
COCO2017/已含上述.npy/.txt文件，可跳过步骤 ①–⑤。
python train_joint.py关键参数：
| 参数 | 默认 | 说明 |
|---|---|---|
--limit |
None |
只用前 N 张图（None=全部 5000 张） |
--epochs |
30 |
训练轮数 |
--batch-size |
32 |
批次大小 |
--dynamic |
False |
是否启用动态瓶颈适配器 |
--ce-weight |
1.0 |
聚类头交叉熵权重 |
--eval-every |
5 |
每 N 轮阶段性评估 |
训练完成后权重保存至 ./checkpoints/magic_last.pt。
python box_cluster_eval.py该脚本在每个检测框粒度和粗/细/融合特征上做：CLIP 零样本分类、KMeans 聚类、线性探测与可学习融合（linear / proj_concat / gate_vec）。
| 参数 | 说明 |
|---|---|
--skip-clip |
跳过 CLIP 零样本基线 |
--skip-kmeans |
跳过 KMeans 聚类 |
--skip-probe |
跳过线性探测/可学习融合 |
--save-fused |
保存 gate_vec 融合特征 |
--report |
指定报告输出文件（默认 box_cluster_eval_report.txt） |
python test_adapter.py # 对比 无适配器 / 固定压缩 / 动态瓶颈 / 熵引导瓶颈python test_backbone.py # 验证 DETR 输出 [B,100,4] 与 [B,100,512]python box_aligner.py # 端到端验证 图像 → 检测 → 对齐 → 适配 全链路框级聚类评估（box_cluster_eval_report.txt，共 36,781 个框，80 类）：
CLIP 零样本分类（无训练）
| 特征 | ACC |
|---|---|
| coarse（粗粒度名词） | 42.22% |
| fine（细粒度描述） | 53.26% |
| mean | 53.01% |
| concat | 53.01% |
线性探测（少量标注微调，测试集）
| 方法 | ACC% | 框级 mAP | 图像级 mAP |
|---|---|---|---|
| linear | 30.58 | 40.08 | 32.04 |
| proj_concat | 48.76 | 59.32 | 54.40 |
| gate_vec | 31.60 | 41.55 | 33.52 |
结论：可学习的
proj_concat融合（1024→512 投影）显著优于单一粒度与gate_vec门控，说明粗+细粒度特征存在互补信息，显式投影融合最有效。
本项目采用模块化分工，各模块接口约定详见 INTERFACE.md。核心接口约定：
- 检测骨干（
detection_backbone.py）：输出[B,100,4]检测框 +[B,100,512]视觉特征 - 文本编码器：
get_semantic_features(boxes, pixel_values) -> text_feat [B,100,512] - 适配器：
adapter(vis_feat [B,100,512], txt_feat [B,100,512]) -> (adapted_vis, adapted_txt) - 语义编码器（
semantic_encoder.py）：get_text_features(img_ids, box_indices) -> text_feat [B,N,512]
- 训练脚本默认冻结 CLIP 编码器，仅训练适配器、聚类头与线性探测分类器。
- 文本特征顺序必须与
sorted(img_id)一致，训练脚本已内置对齐与自愈逻辑。 - 框级粗粒度特征依赖 spaCy 名词提取；细粒度描述依赖 Qwen2.5-VL（可选，可用固定描述替代）。
本项目仅用于学术研究。