简介这是一套基于Pytorch实现的OW-DETR开放世界目标检测算法项目面向已有深度学习与目标检测基础、希望掌握Transformer系列检测框架的开发者。OW-DETR不依赖固定类别标签可对未知类别进行推理适合自动驾驶、智能监控等类别多样且不断变化的应用场景也适合作为开放世界检测方向的研究起点。资源包含算法完整工程、训练与评估脚本、多数据集处理模块和配套流程教程能够帮助读者从环境准备、数据组织到模型训练、开放世界评估逐步走通整个项目。压缩包共74个文件以38个py源码脚本、18个txt配置说明、9个sh启动脚本及2个md说明文档为主另有少量C/CUDA扩展文件整体约1.51MB结构清晰、便于按模块复现。目前已有408人学习下载适合需要参考高质量开源实现、快速二次开发或复现实验的研究者与学生。1. OW-DETR是什么从固定类别到开放世界目标检测自动驾驶的视觉系统最怕遇到没见过的物体废纸箱、工程路障、散落的零件传统目标检测网络会把这一切直接压成背景。OW-DETR就是为解决这类问题而生的开放世界Transformer目标检测算法它基于Pytorch实现在Deformable DETR骨架上加了未知类感知分支让模型在训练阶段就能对没见过的东西产生响应而不是等到推理时翻车。下面从算法拆解讲到复现把项目源码里的数据脚本、训练配置和踩坑点一次捋清楚。适合已经在做目标检测、想把手上的检测器从固定类别扩展到开放场景的开发者Pytorch和Transformer基础越扎实读起来越顺手。2. OW-DETR的模型设计四个关键模块拆开看2.1 从DETR到OW-DETR多出来的那一层在干什么普通DETR把目标检测当成集合预测问题Transformer解码器输出300个query的预测结果用匈牙利匹配算法把预测框和真实框一一配对再用set-level的损失训练。这套设计能自然规避NMS但有一个根本前提它假设所有需要检测的目标都有确定的已知类别标签。一张图里如果出现一个训练时没见过的类物体DETR的匈牙利匹配会把这个query硬分给某个已知类要么给一个接近背景的低置信度要么产生错误的高置信度预测。OW-DETR的改动很直接它给每个query增加一个独立的二分类输出分支。这个分支不回答“这是什么”只回答“这里有没有物体”。当已知类分类头给出的分数都不高但unknown分支的前景分数很高时模型就输出一个未知物体框。代码结构上models/deformable_detr.py里的模型forward会同时返回已知类logits、未知类前景logits和回归框三组输出engine.py里再把这三种输出合并进总损失。# 简化自 models/deformable_detr.py 的输出头设计 class OWDeformableDetr(nn.Module): def __init__(self, num_known_classes, hidden_dim256, num_queries300): super().__init__() # 编码器-解码器主体负责多尺度特征提取和 query 迭代 self.transformer DeformableTransformer() # 已知类分类头输出 num_known_classes 个类别分数 self.class_embed nn.Linear(hidden_dim, num_known_classes) # 未知类分支只输出 1 个分数用 sigmoid 解释成前景概率 self.unknown_embed nn.Linear(hidden_dim, 1) # 回归头cx, cy, w, h均归一化到 [0,1] self.bbox_embed MLP(hidden_dim, hidden_dim, 4) def forward(self, features, queries): hs, memory self.transformer(features, queries) outputs_classes self.class_embed(hs) # [B, N, C] outputs_unknown self.unknown_embed(hs) # [B, N, 1] outputs_boxes self.bbox_embed(hs).sigmoid() return outputs_classes, outputs_unknown, outputs_boxesclass_embed的参数数量取决于已知类个数unknown_embed固定输出1维bbox_embed负责四个归一化的坐标值。实际源码里这些层分布在deformable_detr.py和deformable_transformer.py两个文件中DeformableTransformer实现多尺度编码器和解码器class_embed与unknown_embed挂在解码器每一层输出上。训练时匈牙利匹配只看已知类与对应GT框unknown分支则单独计算损失推理时一个query的known logits最高分低于known_threshold、同时unknown概率高于unknown_threshold就标成未知物体。这里有个细节值得注意unknown分支不输出具体类别它只能回答“这里有个东西不在已知类里”。在自动驾驶、安防这类“宁可多报不可漏报”的场景里这种设计是实用的在需要精确分类的质检场景里未知框还需要二级分类器二次确认。2.2 伪标签与对比聚类没有标注怎么让模型认识“未知”开放世界检测最大的训练难点是数据里没有未知类的标注。如果直接用COCO这类固定类别数据集训练模型永远看不到“一个未标注的物体应该被检测出来”的正样本。OW-DETR的做法分两步第一步用区域提议网络跑出候选区域选出与所有已知类GT重合度低于阈值的候选框当作“可能是未知物体”的伪标签第二步用对比聚类约束让已知类物体在embedding空间里按类别聚集未知物体落不进任何已知类簇时就会被unknown分支捕获。伪标签质量直接决定未知类检测的上限。伪标签太少unknown分支学不到东西伪标签太脏会把大量背景误检成未知物体。项目里datasets目录下的create_imagenets_t1.py到create_imagenets_t4.py以及coco2voc.py做的就是这类数据准备活——把COCO原始标注按增量学习的多个阶段切分。# 按增量学习阶段切分 COCO 标注 python datasets/create_imagenets_t1.py --coco_path /data/coco --output_dir /data/owdetr/t1 python datasets/create_imagenets_t2.py --coco_path /data/coco --output_dir /data/owdetr/t2 python datasets/create_imagenets_t3.py --coco_path /data/coco --output_dir /data/owdetr/t3 python datasets/create_imagenets_t4.py --coco_path /data/coco --output_dir /data/owdetr/t4--coco_path指向COCO数据集根目录--output_dir指定这个task的标注JSON输出位置。T1阶段模型只知道第一批类别T2阶段加入第二批T3、T4依次扩展每轮训练都用当前task的已知类集合过滤GT模拟真实世界里类别逐步开放的过程。coco2voc.py把COCO格式的JSON标注转成VOC XML方便在已有检测流程里复用。2.3 能量函数把“吃不准的样本”从主损失里摘出去第三个关键模块是能量加权损失。伪标签覆盖的未知区域其实处于已知类边界附近模型会倾向于把这些区域往已知类上推产生误检。OW-DETR用能量函数量化这个风险把每个query的已知类logits做LogSumExp聚合得到一个标量EE越大表示这个query越容易被分到某个已知类。对于未知区域E越大越危险训练时就应该削弱它的梯度。# engine.py 中能量加权损失的核心计算 def energy_aware_loss(outputs_known, outputs_unknown, targets, temperature2.0): # 用 LogSumExp 把已知类 logits 聚合成能量分数 logits outputs_known energy torch.logsumexp(logits, dim-1) # energy 越大说明模型越容易把该区域判成已知类权重压低 weight torch.exp(-energy / temperature) # 未知类分支的 BCE 损失按权重缩放 loss_unknown F.binary_cross_entropy_with_logits( outputs_unknown.squeeze(-1), targets.unknown_mask) return (weight * loss_unknown).mean(), energytemperature决定权重曲线陡峭程度temperature越小高能量样本被压得越狠设得太大权重趋近均匀能量加权就失去意义。我习惯先用temperature2.0跑一个短epoch观察能量分数分布如果unknown分支损失长期不下降说明温度太低把有效信号也压没了。这个trick比直接调学习率更有效。能量函数还有一个额外价值训练结束后它能当置信度用。推理时能量值接近0说明logits里某个类占绝对优势模型对分类很有把握能量值很大说明模型在多个已知类之间犹豫这类框要么标成未知要么直接丢弃。第6章再细讲怎么利用这个性质。3. Pytorch环境与项目结构conda、CUDA对齐与三个启动脚本3.1 Pytorch环境搭建GPU版本、conda和CUDA对齐拿到项目第一步不是看模型代码而是把Pytorch基础框架搭对。这个项目依赖可变形注意力的CUDA扩展对Pytorch版本和CUDA版本非常敏感。我的习惯是用conda先建一个干净环境再装GPU版Pytorch。conda create -n owdetr python3.8 -y conda activate owdetr # 先查本机驱动支持的 CUDA 最高版本11.8 只是示例 nvidia-smi # 安装与本地环境匹配的 Pytorch pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu118 cd OW-DETR pip install -r requirements.txtnvidia-smi输出里Driver Version对应的CUDA Version是驱动支持的最高版本不是当前环境的运行时版本。Pytorch的cu118指运行时CUDA 11.8驱动版本高于运行库要求即可不需要严格相等。requirements.txt里一般包含pycocotools、scipy、opencv-python这些和数据处理、评估相关的依赖建议在装完Pytorch后再装避免pip自动把torch版本改掉。装完跑一下python -c import torch; print(torch.cuda.is_available())输出True再进下一步。很多人卡在这一步最典型的场景是conda base环境里已经有了一个CPU版Pytorchactivate新环境后import torch加载到了旧路径。用python -c import torch; print(torch.__file__)确认当前环境实际加载的是哪个路径能少踩一个坑。3.2 项目目录拆解configs、data、models、tools各管什么这个项目的目录结构本身就是一份很好的学习材料。从根目录往下main_open_world.py是训练入口engine.py是训练和验证循环configs/下面是训练与评估的shell配置tools/里是分布式启动和benchmark工具models/是模型定义data/是COCO数据加载和评测逻辑datasets/是数据划分与转换脚本exps/用来放实验输出和checkpoint。OW-DETR/ ├── main_open_world.py # 训练/评估统一入口 ├── engine.py # 训练循环、验证循环、损失计算 ├── configs/ # 训练与评估的 shell 配置 ├── tools/ # 分布式启动、benchmark ├── models/ # DETR/Transformer/Backbone/Matcher ├── data/ # COCO 加载、coco_eval、open_world_eval ├── datasets/ # COCO→OWDETR task 转化脚本 ├── exps/ # 实验输出目录 └── requirements.txtmodels/backbone.py提供ResNet主干models/deformable_transformer.py实现多尺度编码器和解码器models/matcher.py实现匈牙利匹配models/position_encoding.py提供空间位置编码。data/open_world_eval.py是开放世界评测逻辑单独计算已知类和未知类的指标data/coco_eval.py则复用标准COCO的mAP逻辑models/deformable_detr.py把以上几个模块串成完整网络。我看这个项目的顺序和看其他检测项目源码一样先看configs再看models。configs里的参数会告诉你作者训练时用了什么batch、什么轮数、什么损失权重带着这些数字去看models里的类名和forward逻辑整个架构立刻清晰。3.3 训练启动run.sh、run_slurm.sh、run_dist_launch.sh到底用哪个项目里同时放了三个启动脚本很多第一次接触的人不知道选哪个。单机单卡优先看run.sh或configs/OWOD_our_proposed_split.sh多机多卡用tools/run_dist_launch.sh在SLURM集群上跑才用run_slurm.sh和run_dist_slurm.sh。# 本地单机训练直接指向项目内的训练配置 bash configs/OWOD_our_proposed_split.sh # 多机多卡用 torch.distributed 封装启动 python tools/launch.py --nproc_per_node 8 --master_port 29500 \ main_open_world.py --config configs/OWOD_our_proposed_split.shrun_slurm.sh是给SLURM调度器用的里面通常有--partition、--gresgpu:8这类资源申请参数本机没有集群环境直接跑会报sbatch命令找不到。tools/launch.py是torch.distributed.launch的轻量封装--nproc_per_node指定每机的GPU数--master_port指定多机通信端口端口冲突时改成29501这类高位端口即可。到这里环境就绪、结构也清楚了。数据准备带来的坑比环境更多下一章专门处理COCO到OWDETR的task划分和配置调参。4. 数据准备与配置调参四个task划分脚本和一组关键参数4.1 COCO数据集准备下载、摆放和处理脚本OW-DETR训练基于COCO2017目标检测数据集的原始结构是annotations/instances_train2017.json和images/train2017目录。下载后摆放成固定结构并且路径里不要带中文和空格。/data/coco/ ├── annotations/ │ ├── instances_train2017.json │ └── instances_val2017.json └── images/ ├── train2017/ └── val2017/目录准备好后执行第2章里的create_imagenets_t1.py到t4.py生成按阶段划分的标注子集。这一步常被跳过直接拿完整COCO标注去训练导致已知类集合和基准划分不一致结果没有任何可比性。train2017压缩包接近20GB解压后建议随机抽几张图用OpenCV读一遍确认图片没有损坏再进训练流程。4.2 训练配置拆解这些数字分别控制什么打开configs/OWOD_our_proposed_split.sh里面定义了一组训练核心参数。这类shell配置一般用变量名直接赋值我挑几个最关键的说配置项作用建议DATA_PATHCOCO根目录用绝对路径避免相对路径在不同终端失效output_dir实验输出目录每次实验单独建目录方便对比BATCH_SIZE单卡batch大小显存不够优先减batch不要减输入分辨率LR学习率主干换预训练权重时保持默认UNKNOWN_LOSS_WEIGHT未知类分支占总损失的比例未知类漏检时调大误检多时调小ENERGY_TEMPERATURE能量权重曲线陡峭程度先固定2.0看能量分布再调# configs/OWOD_our_proposed_split.sh 关键参数段示意 DATA_PATH/data/coco OUTPUT_DIRexps/owdetr_t1 EPOCHS50 BATCH_SIZE2 LR2e-4 UNKNOWN_LOSS_WEIGHT0.25 ENERGY_TEMPERATURE2.0BATCH_SIZE2是参考值输入尺寸800左右时单卡12GB显存能跑再大容易OOM。UNKNOWN_LOSS_WEIGHT控制unknown分支的贡献太大会让模型把所有低置信度区域都判成未知太弱则unknown分支学不到有效特征。先按0.25跑一个阶段观察验证集上known类mAP不掉、unknown类Recall在涨说明这个权重是健康的。4.3 benchmark.py和open_world_eval.py训练完怎么验收训练结束后先用tools/benchmark.py测标准指标再用main_open_world.py配合OWOD_our_proposed_split_eval.sh看开放世界指标。# 评估已知类 mAP python tools/benchmark.py --config configs/OWOD_our_proposed_split.sh \ --resume exps/owdetr_t1/checkpoint.pth # 评估开放世界指标已知类 mAP 未知类 Recall python main_open_world.py --eval --config configs/OWOD_our_proposed_split_eval.sh \ --resume exps/owdetr_t1/checkpoint.pthdata/open_world_eval.py计算两类Recall已知类Recall和未知类Recall。已知类Recall高但未知类Recall低说明网络被已知类垄断了需要增强伪标签和unknown损失两个都低大概率是训练本身没收敛。这个区分比只看mAP有用得多mAP会掩盖未知类问题。5. 避坑排查环境、数据与训练中的五个常见问题5.1 环境安装坑conda不识别与扩展编译失败坑一conda activate之后报“无法将conda项识别为命令”。现象是Windows PowerShell里输入conda activate owdetr直接报错。原因大多是conda没有被加入PATH或者PowerShell没有初始化conda hook。解决方法是先执行conda init powershell再重开终端临时办法是直接到conda安装目录的Scripts文件夹下执行conda.exe绕过PATH问题。坑二import模型时报错提示找不到MultiScaleDeformableAttention相关符号。现象是第一次跑训练脚本模型初始化就失败。原因是没有编译可变形注意力的C/CUDA扩展或者Pytorch版本和源码里的编译接口不匹配。解决方法是回到requirements.txt锁定的Pytorch版本重新编译# 重新编译前设置目标显卡算力8.6 对应 RTX 3090/3080 export TORCH_CUDA_ARCH_LIST8.6 pip install -e .如果不用export直接编译在较老显卡上可能编出通用版本性能不够在较新显卡上则可能编不出来。这一步是环境里最多的坑编译日志里看到“gcc: error”基本就是CUDA_TOOLKIT_ROOT_DIR没指对。5.2 数据与训练坑误判未知与显存OOM坑三训练loss正常下降但验证时未知类Recall极高几乎所有框都标成未知。现象是模型把背景、建筑边缘、树冠全部当作未知物体。原因大多是task划分脚本没有正确覆盖已知类GT模型在用一个过滤错误的数据集训练。解决方法是训练前把数据加载逻辑单独跑一遍打印首批图像的GT标签和框数量# 训练前打印首批样本的已知类标签确认 task 划分生效 for batch in data_loader: known_ids batch[gt_labels].unique() print(known class ids:, known_ids) break正常情况应看到少量类别ID比如0到19之间如果看到类别ID包含了80类全集说明task过滤没有生效回去检查create_imagenets脚本的类别划分列表。坑四batch size只有2还爆显存。现象是单卡12GB显存训练到第二个step直接OOM。原因多是输入分辨率过大或backbone没有冻结时梯度占用显存多也可能是评估阶段同时加载了训练和验证两个数据流。解决方法是先把输入尺寸调到800再不行把batch降到1确认整条链路能跑通再逐步加回来。12GB跑这个项目比较紧24GB才宽裕。5.3 分布式坑多卡端口冲突与卡死坑五分布式训练进行到一半进程卡死或直接报address already in use。现象是启动日志停在“waiting for all processes to join”然后卡住不动。原因是master_port默认29500和别的任务撞了。解决方法是换高位端口# 换高位端口启动避免和已有训练任务冲突 python tools/launch.py --nproc_per_node 8 --master_port 29501 \ main_open_world.py --config configs/OWOD_our_proposed_split.sh同时确认每台机器的GPU数目和--nproc_per_node参数一致多机时还要检查node list里的IP地址是否互通。端口冲突的另一个隐藏来源是同时开了多个launch.py进程检查一下后台是否有残留的python进程没杀掉。6. 进阶验证用能量分数和可视化把OW-DETR调到可用6.1 可视化预测框与能量分布判断模型是不是真学到东西训练完先别急着看数字把预测结果画出来看一遍。engine.py的验证循环里会输出每个query的预测框、已知类logits和unknown分数我一般会在验证循环里额外把能量分数也打印出来直接输出成一张带框的图。util/plot_utils.py提供了可视化辅助函数可以把known框和unknown框画在同一张图上known框用实线unknown框用虚线一眼就能看出漏检和误检在哪。# 推理时同时取出能量分数和未知类分数用于后续调阈值 outputs_classes, outputs_unknown, outputs_boxes model(images) logits outputs_classes # [B, N, C] energy torch.logsumexp(logits, dim-1) # [B, N] unknown_prob torch.sigmoid(outputs_unknown).squeeze(-1) # [B, N] # 未知类判定unknown 概率高且能量低于阈值 unknown_mask (unknown_prob 0.5) (energy energy_thresh)看可视化结果时重点观察unknown框是否落在真实物体上还是贴在纹理丰富的背景上。如果unknown框大量出现在建筑物边缘、树木纹理上说明伪标签太脏或者UNKNOWN_LOSS_WEIGHT设得过高。这时候先调低损失权重再检查伪标签生成的置信度阈值不要直接改学习率。6.2 小数据验证流程先跑通再上全量换到遥感影像、工业质检这类新场景时我的习惯是先用小数据验证流程。拿2000张图按OWDETR的task划分方式生成T1和T2两个子集跑50个epoch然后单独画能量分布直方图。能量分布会呈现两个峰已知类样本的能量集中在低位未知/背景样本的能量分散在高位。根据两个峰之间的谷底选一个能量阈值作为unknown分支的置信度下限比单纯看sigmoid分数稳定得多。从那以后我每次换数据集都强制走一遍这个流程先打印GT标签确认task划分再跑小规模训练确认收敛最后画能量分布再上全量训练。这套流程帮我挡掉过至少三次数据路径配错的翻车现场也让“开放世界”这个听起来很玄学的概念变成了可以量化的指标。希望帮到你。本文还有配套的精品资源点击获取 OW-DETR开放世界目标检测：模型解析与Pytorch复现实践
简介这是一套基于Pytorch实现的OW-DETR开放世界目标检测算法项目面向已有深度学习与目标检测基础、希望掌握Transformer系列检测框架的开发者。OW-DETR不依赖固定类别标签可对未知类别进行推理适合自动驾驶、智能监控等类别多样且不断变化的应用场景也适合作为开放世界检测方向的研究起点。资源包含算法完整工程、训练与评估脚本、多数据集处理模块和配套流程教程能够帮助读者从环境准备、数据组织到模型训练、开放世界评估逐步走通整个项目。压缩包共74个文件以38个py源码脚本、18个txt配置说明、9个sh启动脚本及2个md说明文档为主另有少量C/CUDA扩展文件整体约1.51MB结构清晰、便于按模块复现。目前已有408人学习下载适合需要参考高质量开源实现、快速二次开发或复现实验的研究者与学生。1. OW-DETR是什么从固定类别到开放世界目标检测自动驾驶的视觉系统最怕遇到没见过的物体废纸箱、工程路障、散落的零件传统目标检测网络会把这一切直接压成背景。OW-DETR就是为解决这类问题而生的开放世界Transformer目标检测算法它基于Pytorch实现在Deformable DETR骨架上加了未知类感知分支让模型在训练阶段就能对没见过的东西产生响应而不是等到推理时翻车。下面从算法拆解讲到复现把项目源码里的数据脚本、训练配置和踩坑点一次捋清楚。适合已经在做目标检测、想把手上的检测器从固定类别扩展到开放场景的开发者Pytorch和Transformer基础越扎实读起来越顺手。2. OW-DETR的模型设计四个关键模块拆开看2.1 从DETR到OW-DETR多出来的那一层在干什么普通DETR把目标检测当成集合预测问题Transformer解码器输出300个query的预测结果用匈牙利匹配算法把预测框和真实框一一配对再用set-level的损失训练。这套设计能自然规避NMS但有一个根本前提它假设所有需要检测的目标都有确定的已知类别标签。一张图里如果出现一个训练时没见过的类物体DETR的匈牙利匹配会把这个query硬分给某个已知类要么给一个接近背景的低置信度要么产生错误的高置信度预测。OW-DETR的改动很直接它给每个query增加一个独立的二分类输出分支。这个分支不回答“这是什么”只回答“这里有没有物体”。当已知类分类头给出的分数都不高但unknown分支的前景分数很高时模型就输出一个未知物体框。代码结构上models/deformable_detr.py里的模型forward会同时返回已知类logits、未知类前景logits和回归框三组输出engine.py里再把这三种输出合并进总损失。# 简化自 models/deformable_detr.py 的输出头设计 class OWDeformableDetr(nn.Module): def __init__(self, num_known_classes, hidden_dim256, num_queries300): super().__init__() # 编码器-解码器主体负责多尺度特征提取和 query 迭代 self.transformer DeformableTransformer() # 已知类分类头输出 num_known_classes 个类别分数 self.class_embed nn.Linear(hidden_dim, num_known_classes) # 未知类分支只输出 1 个分数用 sigmoid 解释成前景概率 self.unknown_embed nn.Linear(hidden_dim, 1) # 回归头cx, cy, w, h均归一化到 [0,1] self.bbox_embed MLP(hidden_dim, hidden_dim, 4) def forward(self, features, queries): hs, memory self.transformer(features, queries) outputs_classes self.class_embed(hs) # [B, N, C] outputs_unknown self.unknown_embed(hs) # [B, N, 1] outputs_boxes self.bbox_embed(hs).sigmoid() return outputs_classes, outputs_unknown, outputs_boxesclass_embed的参数数量取决于已知类个数unknown_embed固定输出1维bbox_embed负责四个归一化的坐标值。实际源码里这些层分布在deformable_detr.py和deformable_transformer.py两个文件中DeformableTransformer实现多尺度编码器和解码器class_embed与unknown_embed挂在解码器每一层输出上。训练时匈牙利匹配只看已知类与对应GT框unknown分支则单独计算损失推理时一个query的known logits最高分低于known_threshold、同时unknown概率高于unknown_threshold就标成未知物体。这里有个细节值得注意unknown分支不输出具体类别它只能回答“这里有个东西不在已知类里”。在自动驾驶、安防这类“宁可多报不可漏报”的场景里这种设计是实用的在需要精确分类的质检场景里未知框还需要二级分类器二次确认。2.2 伪标签与对比聚类没有标注怎么让模型认识“未知”开放世界检测最大的训练难点是数据里没有未知类的标注。如果直接用COCO这类固定类别数据集训练模型永远看不到“一个未标注的物体应该被检测出来”的正样本。OW-DETR的做法分两步第一步用区域提议网络跑出候选区域选出与所有已知类GT重合度低于阈值的候选框当作“可能是未知物体”的伪标签第二步用对比聚类约束让已知类物体在embedding空间里按类别聚集未知物体落不进任何已知类簇时就会被unknown分支捕获。伪标签质量直接决定未知类检测的上限。伪标签太少unknown分支学不到东西伪标签太脏会把大量背景误检成未知物体。项目里datasets目录下的create_imagenets_t1.py到create_imagenets_t4.py以及coco2voc.py做的就是这类数据准备活——把COCO原始标注按增量学习的多个阶段切分。# 按增量学习阶段切分 COCO 标注 python datasets/create_imagenets_t1.py --coco_path /data/coco --output_dir /data/owdetr/t1 python datasets/create_imagenets_t2.py --coco_path /data/coco --output_dir /data/owdetr/t2 python datasets/create_imagenets_t3.py --coco_path /data/coco --output_dir /data/owdetr/t3 python datasets/create_imagenets_t4.py --coco_path /data/coco --output_dir /data/owdetr/t4--coco_path指向COCO数据集根目录--output_dir指定这个task的标注JSON输出位置。T1阶段模型只知道第一批类别T2阶段加入第二批T3、T4依次扩展每轮训练都用当前task的已知类集合过滤GT模拟真实世界里类别逐步开放的过程。coco2voc.py把COCO格式的JSON标注转成VOC XML方便在已有检测流程里复用。2.3 能量函数把“吃不准的样本”从主损失里摘出去第三个关键模块是能量加权损失。伪标签覆盖的未知区域其实处于已知类边界附近模型会倾向于把这些区域往已知类上推产生误检。OW-DETR用能量函数量化这个风险把每个query的已知类logits做LogSumExp聚合得到一个标量EE越大表示这个query越容易被分到某个已知类。对于未知区域E越大越危险训练时就应该削弱它的梯度。# engine.py 中能量加权损失的核心计算 def energy_aware_loss(outputs_known, outputs_unknown, targets, temperature2.0): # 用 LogSumExp 把已知类 logits 聚合成能量分数 logits outputs_known energy torch.logsumexp(logits, dim-1) # energy 越大说明模型越容易把该区域判成已知类权重压低 weight torch.exp(-energy / temperature) # 未知类分支的 BCE 损失按权重缩放 loss_unknown F.binary_cross_entropy_with_logits( outputs_unknown.squeeze(-1), targets.unknown_mask) return (weight * loss_unknown).mean(), energytemperature决定权重曲线陡峭程度temperature越小高能量样本被压得越狠设得太大权重趋近均匀能量加权就失去意义。我习惯先用temperature2.0跑一个短epoch观察能量分数分布如果unknown分支损失长期不下降说明温度太低把有效信号也压没了。这个trick比直接调学习率更有效。能量函数还有一个额外价值训练结束后它能当置信度用。推理时能量值接近0说明logits里某个类占绝对优势模型对分类很有把握能量值很大说明模型在多个已知类之间犹豫这类框要么标成未知要么直接丢弃。第6章再细讲怎么利用这个性质。3. Pytorch环境与项目结构conda、CUDA对齐与三个启动脚本3.1 Pytorch环境搭建GPU版本、conda和CUDA对齐拿到项目第一步不是看模型代码而是把Pytorch基础框架搭对。这个项目依赖可变形注意力的CUDA扩展对Pytorch版本和CUDA版本非常敏感。我的习惯是用conda先建一个干净环境再装GPU版Pytorch。conda create -n owdetr python3.8 -y conda activate owdetr # 先查本机驱动支持的 CUDA 最高版本11.8 只是示例 nvidia-smi # 安装与本地环境匹配的 Pytorch pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu118 cd OW-DETR pip install -r requirements.txtnvidia-smi输出里Driver Version对应的CUDA Version是驱动支持的最高版本不是当前环境的运行时版本。Pytorch的cu118指运行时CUDA 11.8驱动版本高于运行库要求即可不需要严格相等。requirements.txt里一般包含pycocotools、scipy、opencv-python这些和数据处理、评估相关的依赖建议在装完Pytorch后再装避免pip自动把torch版本改掉。装完跑一下python -c import torch; print(torch.cuda.is_available())输出True再进下一步。很多人卡在这一步最典型的场景是conda base环境里已经有了一个CPU版Pytorchactivate新环境后import torch加载到了旧路径。用python -c import torch; print(torch.__file__)确认当前环境实际加载的是哪个路径能少踩一个坑。3.2 项目目录拆解configs、data、models、tools各管什么这个项目的目录结构本身就是一份很好的学习材料。从根目录往下main_open_world.py是训练入口engine.py是训练和验证循环configs/下面是训练与评估的shell配置tools/里是分布式启动和benchmark工具models/是模型定义data/是COCO数据加载和评测逻辑datasets/是数据划分与转换脚本exps/用来放实验输出和checkpoint。OW-DETR/ ├── main_open_world.py # 训练/评估统一入口 ├── engine.py # 训练循环、验证循环、损失计算 ├── configs/ # 训练与评估的 shell 配置 ├── tools/ # 分布式启动、benchmark ├── models/ # DETR/Transformer/Backbone/Matcher ├── data/ # COCO 加载、coco_eval、open_world_eval ├── datasets/ # COCO→OWDETR task 转化脚本 ├── exps/ # 实验输出目录 └── requirements.txtmodels/backbone.py提供ResNet主干models/deformable_transformer.py实现多尺度编码器和解码器models/matcher.py实现匈牙利匹配models/position_encoding.py提供空间位置编码。data/open_world_eval.py是开放世界评测逻辑单独计算已知类和未知类的指标data/coco_eval.py则复用标准COCO的mAP逻辑models/deformable_detr.py把以上几个模块串成完整网络。我看这个项目的顺序和看其他检测项目源码一样先看configs再看models。configs里的参数会告诉你作者训练时用了什么batch、什么轮数、什么损失权重带着这些数字去看models里的类名和forward逻辑整个架构立刻清晰。3.3 训练启动run.sh、run_slurm.sh、run_dist_launch.sh到底用哪个项目里同时放了三个启动脚本很多第一次接触的人不知道选哪个。单机单卡优先看run.sh或configs/OWOD_our_proposed_split.sh多机多卡用tools/run_dist_launch.sh在SLURM集群上跑才用run_slurm.sh和run_dist_slurm.sh。# 本地单机训练直接指向项目内的训练配置 bash configs/OWOD_our_proposed_split.sh # 多机多卡用 torch.distributed 封装启动 python tools/launch.py --nproc_per_node 8 --master_port 29500 \ main_open_world.py --config configs/OWOD_our_proposed_split.shrun_slurm.sh是给SLURM调度器用的里面通常有--partition、--gresgpu:8这类资源申请参数本机没有集群环境直接跑会报sbatch命令找不到。tools/launch.py是torch.distributed.launch的轻量封装--nproc_per_node指定每机的GPU数--master_port指定多机通信端口端口冲突时改成29501这类高位端口即可。到这里环境就绪、结构也清楚了。数据准备带来的坑比环境更多下一章专门处理COCO到OWDETR的task划分和配置调参。4. 数据准备与配置调参四个task划分脚本和一组关键参数4.1 COCO数据集准备下载、摆放和处理脚本OW-DETR训练基于COCO2017目标检测数据集的原始结构是annotations/instances_train2017.json和images/train2017目录。下载后摆放成固定结构并且路径里不要带中文和空格。/data/coco/ ├── annotations/ │ ├── instances_train2017.json │ └── instances_val2017.json └── images/ ├── train2017/ └── val2017/目录准备好后执行第2章里的create_imagenets_t1.py到t4.py生成按阶段划分的标注子集。这一步常被跳过直接拿完整COCO标注去训练导致已知类集合和基准划分不一致结果没有任何可比性。train2017压缩包接近20GB解压后建议随机抽几张图用OpenCV读一遍确认图片没有损坏再进训练流程。4.2 训练配置拆解这些数字分别控制什么打开configs/OWOD_our_proposed_split.sh里面定义了一组训练核心参数。这类shell配置一般用变量名直接赋值我挑几个最关键的说配置项作用建议DATA_PATHCOCO根目录用绝对路径避免相对路径在不同终端失效output_dir实验输出目录每次实验单独建目录方便对比BATCH_SIZE单卡batch大小显存不够优先减batch不要减输入分辨率LR学习率主干换预训练权重时保持默认UNKNOWN_LOSS_WEIGHT未知类分支占总损失的比例未知类漏检时调大误检多时调小ENERGY_TEMPERATURE能量权重曲线陡峭程度先固定2.0看能量分布再调# configs/OWOD_our_proposed_split.sh 关键参数段示意 DATA_PATH/data/coco OUTPUT_DIRexps/owdetr_t1 EPOCHS50 BATCH_SIZE2 LR2e-4 UNKNOWN_LOSS_WEIGHT0.25 ENERGY_TEMPERATURE2.0BATCH_SIZE2是参考值输入尺寸800左右时单卡12GB显存能跑再大容易OOM。UNKNOWN_LOSS_WEIGHT控制unknown分支的贡献太大会让模型把所有低置信度区域都判成未知太弱则unknown分支学不到有效特征。先按0.25跑一个阶段观察验证集上known类mAP不掉、unknown类Recall在涨说明这个权重是健康的。4.3 benchmark.py和open_world_eval.py训练完怎么验收训练结束后先用tools/benchmark.py测标准指标再用main_open_world.py配合OWOD_our_proposed_split_eval.sh看开放世界指标。# 评估已知类 mAP python tools/benchmark.py --config configs/OWOD_our_proposed_split.sh \ --resume exps/owdetr_t1/checkpoint.pth # 评估开放世界指标已知类 mAP 未知类 Recall python main_open_world.py --eval --config configs/OWOD_our_proposed_split_eval.sh \ --resume exps/owdetr_t1/checkpoint.pthdata/open_world_eval.py计算两类Recall已知类Recall和未知类Recall。已知类Recall高但未知类Recall低说明网络被已知类垄断了需要增强伪标签和unknown损失两个都低大概率是训练本身没收敛。这个区分比只看mAP有用得多mAP会掩盖未知类问题。5. 避坑排查环境、数据与训练中的五个常见问题5.1 环境安装坑conda不识别与扩展编译失败坑一conda activate之后报“无法将conda项识别为命令”。现象是Windows PowerShell里输入conda activate owdetr直接报错。原因大多是conda没有被加入PATH或者PowerShell没有初始化conda hook。解决方法是先执行conda init powershell再重开终端临时办法是直接到conda安装目录的Scripts文件夹下执行conda.exe绕过PATH问题。坑二import模型时报错提示找不到MultiScaleDeformableAttention相关符号。现象是第一次跑训练脚本模型初始化就失败。原因是没有编译可变形注意力的C/CUDA扩展或者Pytorch版本和源码里的编译接口不匹配。解决方法是回到requirements.txt锁定的Pytorch版本重新编译# 重新编译前设置目标显卡算力8.6 对应 RTX 3090/3080 export TORCH_CUDA_ARCH_LIST8.6 pip install -e .如果不用export直接编译在较老显卡上可能编出通用版本性能不够在较新显卡上则可能编不出来。这一步是环境里最多的坑编译日志里看到“gcc: error”基本就是CUDA_TOOLKIT_ROOT_DIR没指对。5.2 数据与训练坑误判未知与显存OOM坑三训练loss正常下降但验证时未知类Recall极高几乎所有框都标成未知。现象是模型把背景、建筑边缘、树冠全部当作未知物体。原因大多是task划分脚本没有正确覆盖已知类GT模型在用一个过滤错误的数据集训练。解决方法是训练前把数据加载逻辑单独跑一遍打印首批图像的GT标签和框数量# 训练前打印首批样本的已知类标签确认 task 划分生效 for batch in data_loader: known_ids batch[gt_labels].unique() print(known class ids:, known_ids) break正常情况应看到少量类别ID比如0到19之间如果看到类别ID包含了80类全集说明task过滤没有生效回去检查create_imagenets脚本的类别划分列表。坑四batch size只有2还爆显存。现象是单卡12GB显存训练到第二个step直接OOM。原因多是输入分辨率过大或backbone没有冻结时梯度占用显存多也可能是评估阶段同时加载了训练和验证两个数据流。解决方法是先把输入尺寸调到800再不行把batch降到1确认整条链路能跑通再逐步加回来。12GB跑这个项目比较紧24GB才宽裕。5.3 分布式坑多卡端口冲突与卡死坑五分布式训练进行到一半进程卡死或直接报address already in use。现象是启动日志停在“waiting for all processes to join”然后卡住不动。原因是master_port默认29500和别的任务撞了。解决方法是换高位端口# 换高位端口启动避免和已有训练任务冲突 python tools/launch.py --nproc_per_node 8 --master_port 29501 \ main_open_world.py --config configs/OWOD_our_proposed_split.sh同时确认每台机器的GPU数目和--nproc_per_node参数一致多机时还要检查node list里的IP地址是否互通。端口冲突的另一个隐藏来源是同时开了多个launch.py进程检查一下后台是否有残留的python进程没杀掉。6. 进阶验证用能量分数和可视化把OW-DETR调到可用6.1 可视化预测框与能量分布判断模型是不是真学到东西训练完先别急着看数字把预测结果画出来看一遍。engine.py的验证循环里会输出每个query的预测框、已知类logits和unknown分数我一般会在验证循环里额外把能量分数也打印出来直接输出成一张带框的图。util/plot_utils.py提供了可视化辅助函数可以把known框和unknown框画在同一张图上known框用实线unknown框用虚线一眼就能看出漏检和误检在哪。# 推理时同时取出能量分数和未知类分数用于后续调阈值 outputs_classes, outputs_unknown, outputs_boxes model(images) logits outputs_classes # [B, N, C] energy torch.logsumexp(logits, dim-1) # [B, N] unknown_prob torch.sigmoid(outputs_unknown).squeeze(-1) # [B, N] # 未知类判定unknown 概率高且能量低于阈值 unknown_mask (unknown_prob 0.5) (energy energy_thresh)看可视化结果时重点观察unknown框是否落在真实物体上还是贴在纹理丰富的背景上。如果unknown框大量出现在建筑物边缘、树木纹理上说明伪标签太脏或者UNKNOWN_LOSS_WEIGHT设得过高。这时候先调低损失权重再检查伪标签生成的置信度阈值不要直接改学习率。6.2 小数据验证流程先跑通再上全量换到遥感影像、工业质检这类新场景时我的习惯是先用小数据验证流程。拿2000张图按OWDETR的task划分方式生成T1和T2两个子集跑50个epoch然后单独画能量分布直方图。能量分布会呈现两个峰已知类样本的能量集中在低位未知/背景样本的能量分散在高位。根据两个峰之间的谷底选一个能量阈值作为unknown分支的置信度下限比单纯看sigmoid分数稳定得多。从那以后我每次换数据集都强制走一遍这个流程先打印GT标签确认task划分再跑小规模训练确认收敛最后画能量分布再上全量训练。这套流程帮我挡掉过至少三次数据路径配错的翻车现场也让“开放世界”这个听起来很玄学的概念变成了可以量化的指标。希望帮到你。本文还有配套的精品资源点击获取