从零实践：使用aitodpycocotools精准评估小目标检测模型的APvt/APt/APs/APm

1. 为什么小目标检测需要专门的评估工具？

如果你正在做无人机航拍图像分析、卫星影像识别，或者处理任何一张图片里密密麻麻挤满了小物体的任务，那你肯定对“小目标检测”这个词不陌生。传统的目标检测模型，比如在COCO数据集上训练出来的那些，面对大尺寸的汽车、行人可能表现不错，但一遇到图片里那些只有几十甚至几个像素点的小目标，比如远处的人脸、空中的飞鸟、遥感图像里的车辆，性能往往会断崖式下跌。

这不仅仅是模型能力的问题，评估标准本身也可能“偏科”。标准的COCO评估指标（就是大家常说的AP@[.5:.95]）虽然经典，但它对所有尺寸的目标“一视同仁”。在实际计算中，一个模型可能因为抓住了几个大物体而获得不错的AP，但对大量小目标的漏检和误检却反映得不充分。这对于专门优化小目标检测的模型和研究来说，显然不够公平，也无法精准地指导我们的优化方向。

这就是为什么我们需要像aitodpycocotools这样的专用评估工具。它脱胎于我们熟悉的pycocotools，但专门为小目标检测数据集AI-TOD量身定制。它最核心的价值，就是引入了一套更细致的评估维度：APvt, APt, APs, APm。这四个指标分别对应“极小”、“小”、“中”、“大”四种目标尺寸的精度。对于AI-TOD这种目标普遍偏小的数据集，APvt和APt这两个指标的重要性，甚至可能超过整体的AP。它们能告诉你，你的模型在真正棘手的“小不点”目标上，到底表现如何。

我刚开始接触这个工具时，也以为就是简单换个import，结果在坐标转换上栽了跟头，评估结果全是0，折腾了好久。所以，这篇文章我就把自己从环境搭建、数据准备、评估执行到结果解读的全过程，以及踩过的那些坑，毫无保留地分享出来。目标就一个：让你能跟着步骤，一次性跑通整个评估流程，真正看懂你的模型在小目标上的“成绩单”。

2. 动手之前：理解核心概念与准备工作

在撸起袖子敲代码之前，我们得先搞清楚几个关键概念，这样后面遇到问题才知道去哪儿找原因。这套评估体系的核心是AP（Average Precision，平均精度），但做了非常关键的“分尺寸”细化。

1. 目标尺寸的划分标准在aitodpycocotools中，目标不是简单地分为“大”和“小”，而是依据像素面积进行了四级划分：

• APvt (Average Precision for Very Tiny objects): 评估极小目标，通常指面积在某个阈值以下（例如AI-TOD v2中可能是16像素以下）的目标。这是小目标检测中最难、也最值得关注的指标。
• APt (Average Precision for Tiny objects): 评估小目标，面积范围在vt之上，但依然属于小目标范畴（例如16到32像素）。
• APs (Average Precision for Small objects): 评估中小目标，范围更大一些（例如32到96像素）。
• APm (Average Precision for Medium objects): 评估中等目标（例如96到256像素）。在AI-TOD这类数据集中，中等目标已经算“大家伙”了。

这种划分让我们能像用“放大镜”一样，精确检验模型在不同难度层级上的表现。一个模型可能APm不错，但APvt一塌糊涂，这说明它完全没学会检测最难的那些点。

2. 关键的“-1”值是什么意思？在原始文章和你的运行结果里，可能会看到像AP @[ IoU=0.25 | area= all ] = -1.000这样的输出。别紧张，这不一定是错误。这个“-1”是一个特殊标识，通常意味着：在当前评估设置下，没有满足条件的目标用于计算。

举个例子，在标准的COCO评估中，area=large对应大目标（面积>96x96）。如果整个数据集中压根没有这么大的目标（比如AI-TOD数据集），那么这项评估就无法进行，结果就会显示为-1。同样，如果你设置了一个非常规的IoU阈值（如0.25），而评估代码的默认配置不支持或认为该阈值不合理，也可能返回-1。所以，看到-1先别慌，去检查一下你的数据集里是否存在对应尺寸的目标，或者这个评估项是否被有意忽略。在AI-TOD的评估中，关注area=verytiny, tiny, small, medium这几项就足够了。

3. 你的“作战物资”清单要完成这次实践，你需要准备好以下几样东西：

• AI-TOD数据集：主要是它的标注文件，通常是aitodv2_train.json和aitodv2_val.json或aitodv2_test.json。你需要知道它们放在你电脑上的具体路径。
• 训练好的模型预测结果：这是一个JSON文件，里面包含了你的模型在测试集/验证集上对每张图片的预测框信息。这也是我们需要重点生成和检查的文件。
• Python环境：建议使用Python 3.7或以上版本。
• 基本的深度学习环境（如PyTorch/TensorFlow），这取决于你的模型。

准备好了吗？我们接下来就从安装评估工具开始。

3. 第一步：安装与配置aitodpycocotools

安装aitodpycocotools本身非常简单，它本质上是一个修改版的COCO API。官方仓库在GitHub上，我们可以直接用pip从源码安装。

打开你的终端或命令提示符，执行以下命令：

pip install git+https://github.com/jwwangchn/cocoapi-aitod.git

这行命令会从GitHub仓库拉取代码并自动安装。如果网络环境不太顺畅，你也可以选择先克隆仓库到本地再安装：

git clone https://github.com/jwwangchn/cocoapi-aitod.git cd cocoapi-aitod/PythonAPI python setup.py build_ext --inplace python setup.py install

安装完成后，你可以在Python中尝试导入来验证是否成功：

from aitodpycocotools.coco import COCO from aitodpycocotools.cocoeval import COCOeval print("aitodpycocotools 导入成功！")

如果没有报错，说明工具已经就绪。这里有个小提示：这个工具和标准的pycocotools不能同时共存于同一个Python环境，因为它们的模块名（coco，cocoeval）是冲突的。如果你之前项目依赖标准版，可能需要使用虚拟环境（如conda或venv）来隔离。我个人的习惯是为每个需要特殊评估工具的项目创建独立的虚拟环境，避免包管理上的混乱。

安装只是第一步，真正的挑战在于准备符合格式要求的预测结果文件。很多朋友在这里出错，导致评估结果全零，问题八成出在数据格式上。

4. 第二步：生成正确格式的预测结果文件

这是整个流程中最容易出错，也最需要耐心的一步。aitodpycocotools要求预测结果文件是一个JSON格式的列表，列表中的每个元素是一个字典，代表一个预测框。这个格式和标准COCO评估完全一致。

1. 标准格式长什么样？一个合法的prediction.json文件内容大致如下：

[ { "image_id": 100000, "category_id": 1, "bbox": [258.15, 41.29, 131.45, 90.33], "score": 0.976 }, { "image_id": 100000, "category_id": 3, "bbox": [123.45, 67.89, 45.67, 32.10], "score": 0.845 }, // ... 更多预测框 ]

每个字典有四个关键字段：

• image_id：整数，对应标注文件中某张图片的id字段。必须完全匹配，否则评估时无法关联。
• category_id：整数，预测的类别ID。必须与标注文件中categories列表的id一致。
• bbox：一个包含4个浮点数的列表[x, y, width, height]。这是重中之重，也是我踩过大坑的地方。
• score：浮点数，模型预测该框的置信度分数（0到1之间），用于后续计算PR曲线和AP。

2. 坐标转换：最大的“坑”这里必须敲黑板！模型输出的边界框坐标格式，和你需要写入JSON的格式，很可能不一样。

• 模型常见输出格式：很多模型，特别是像DETR、YOLO这类，内部使用[center_x, center_y, width, height]（即cxcywh）来表示边界框。也有些框架会输出[x_min, y_min, x_max, y_max]（即xyxy）。
• JSON要求格式：必须是[x_min, y_min, width, height]（即xywh），其中x_min和y_min是边界框左上角的坐标。

如果你直接把模型输出的cxcywh当成xywh写进去，评估器会认为你的预测框位置完全错误，导致IoU计算为0，最终AP结果也是0。这就是我最初得到全零结果的原因。

3. 转换代码示例假设你的模型（以PyTorch DETR为例）对一批图像输出了结果outputs，其中包含预测框pred_boxes（格式为cxcywh，且坐标是归一化的，即值在[0, 1]之间），你可以用类似下面的代码进行转换和保存：

import json import torch # 假设 outputs 是模型输出，结构需根据你的模型调整 # pred_boxes: [batch_size, num_queries, 4] in (cx, cy, w, h) normalized # pred_scores: [batch_size, num_queries] # pred_labels: [batch_size, num_queries] def convert_cxcywh_to_xywh(bbox, img_width, img_height): """将归一化的[cx, cy, w, h]转换为绝对坐标的[x_min, y_min, width, height]""" cx, cy, w, h = bbox # 反归一化 cx = cx * img_width cy = cy * img_height w = w * img_width h = h * img_height # 计算左上角坐标 x_min = cx - w / 2.0 y_min = cy - h / 2.0 return [x_min, y_min, w, h] results = [] for batch_idx, (boxes, scores, labels) in enumerate(zip(pred_boxes, pred_scores, pred_labels)): # 假设你有一个列表image_ids，记录了这批图片对应的ID current_image_id = image_ids[batch_idx] # 假设你知道图片的原始尺寸 img_w, img_h = 800, 800 # 这里需要替换为真实的图片尺寸 for box, score, label in zip(boxes, scores, labels): if score < 0.05: # 可以设置一个置信度阈值过滤低质量预测 continue # 转换坐标 xywh_bbox = convert_cxcywh_to_xywh(box.tolist(), img_w, img_h) # 构建结果字典 result = { "image_id": int(current_image_id), "category_id": int(label.item()), "bbox": [round(coord, 2) for coord in xywh_bbox], # 保留两位小数 "score": round(score.item(), 4) } results.append(result) # 保存为JSON文件 with open('your_predictions.json', 'w') as f: json.dump(results, f) print("预测结果已保存至 your_predictions.json")

请注意：上面的代码是一个示例模板，你需要根据自己模型的实际输出结构、图片ID的获取方式以及图片原始尺寸进行修改。关键就是确保bbox字段最终是绝对的xywh格式。

5. 第三步：运行评估并解读详细结果

万事俱备，现在可以运行评估脚本了。代码结构和标准的pycocotools几乎一模一样，只是换了个导入源。

1. 评估代码模板创建一个Python脚本（比如叫做eval_ai_tod.py），内容如下：

from aitodpycocotools.coco import COCO from aitodpycocotools.cocoeval import COCOeval import numpy as np # 1. 加载真实标注 annFile = '/path/to/your/aitodv2_test.json' # 替换为你的标注文件路径 cocoGt = COCO(annFile) # 2. 加载你的预测结果 resFile = '/path/to/your/predictions.json' # 替换为你的预测文件路径 cocoDt = cocoGt.loadRes(resFile) # 3. 创建评估器，指定评估类型为‘bbox’ cocoEval = COCOeval(cocoGt, cocoDt, iouType='bbox') # 4. 执行评估 cocoEval.evaluate() cocoEval.accumulate() cocoEval.summarize() # （可选）打印更详细的分尺寸AP结果 print("\n=== 详细分尺寸AP指标 ===") stats = cocoEval.stats # 注意：stats数组的索引含义可能因版本略有不同，以下是常见顺序 # 通常 stats[1] 是 AP@0.5， stats[2] 是 AP@0.75， stats[3:7] 是 AP across scales print(f"AP@[0.5:0.95] (all): {stats[0]:.3f}") print(f"AP@0.5 (all): {stats[1]:.3f}") print(f"AP@0.75 (all): {stats[2]:.3f}") print(f"AP@[0.5:0.95] (verytiny): {stats[3]:.3f}") print(f"AP@[0.5:0.95] (tiny): {stats[4]:.3f}") print(f"AP@[0.5:0.95] (small): {stats[5]:.3f}") print(f"AP@[0.5:0.95] (medium): {stats[6]:.3f}")

运行这个脚本，你会在终端看到一长串的输出。这就是你模型的“成绩单”。

2. 如何解读输出结果？我们结合一个可能的输出来看：

Average Precision (AP) @[ IoU=0.50:0.95 | area= all | maxDets=1500 ] = 0.133 Average Precision (AP) @[ IoU=0.25 | area= all | maxDets=1500 ] = -1.000 Average Precision (AP) @[ IoU=0.50 | area= all | maxDets=1500 ] = 0.347 Average Precision (AP) @[ IoU=0.75 | area= all | maxDets=1500 ] = 0.074 Average Precision (AP) @[ IoU=0.50:0.95 | area=verytiny | maxDets=1500 ] = 0.035 Average Precision (AP) @[ IoU=0.50:0.95 | area= tiny | maxDets=1500 ] = 0.128 Average Precision (AP) @[ IoU=0.50:0.95 | area= small | maxDets=1500 ] = 0.181 Average Precision (AP) @[ IoU=0.50:0.95 | area=medium | maxDets=1500 ] = 0.242

• 第一行AP @[ IoU=0.50:0.95 | area=all ]：这是综合性能的核心指标。IoU从0.5到0.95，以0.05为步长取平均，对所有尺寸的目标进行计算。0.133这个值看起来不高，但在小目标检测任务中，尤其是AI-TOD这种高难度数据集，这是一个需要参考的基准。
• 第二行AP @[ IoU=0.25 | area=all ] = -1：如前所述，这通常是因为评估配置中未启用IoU=0.25这个宽松阈值，或者认为其无意义，可以忽略。
• 第三、四行AP@0.5和AP@0.75：这是在不同IoU阈值下的表现。AP@0.5（0.347）较高说明模型能找到很多大致位置正确的目标；AP@0.75（0.074）较低则说明模型预测框的定位精度不够准，框得不够紧。
• 第五到八行APvt, APt, APs, APm：这才是重点中的重点。我们清晰地看到：
  • APvt=0.035：模型对“极小”目标的检测能力非常弱。
  • APt=0.128：对“小”目标有一定检测能力，但仍有很大提升空间。
  • APs=0.181和APm=0.242：随着目标变大，模型性能稳步提升。 这个梯度告诉我们，模型的瓶颈就在最小的那些目标上。后续的优化策略，比如增加小尺度特征图、使用更密集的锚框、或者数据增强时侧重小目标，就有了明确的方向。

6. 实战排坑：常见问题与解决思路

即使按照步骤操作，你可能还是会遇到一些奇怪的问题。这里我总结几个自己遇到过的情况和解决办法。

问题一：评估结果全部是0，或者低得离谱（比如APvt=0.000）。

• 首要怀疑对象：坐标格式错误。99%的可能性是bbox格式不对。请务必、务必、务必确认你写入JSON的bbox是[x_min, y_min, width, height]，并且坐标是绝对像素值，不是归一化值（除非你的标注文件也是归一化的，但这很少见）。用几行代码打印出你转换前后的几个框，和标注文件里对应图片的真实框对比一下，看格式是否一致。
• 检查image_id和category_id：确保预测结果中的image_id能在标注文件中找到，category_id也是标注文件中定义的合法ID。一个ID不匹配，整个框就不会被计入评估。
• 检查置信度分数：score字段值是否在合理范围（0~1）？如果全部是1或0，可能会影响排序。

问题二：评估时报错，提示“KeyError”或“IndexError”。

• 检查JSON文件格式：你的prediction.json文件是有效的JSON吗？可以用在线JSON校验工具或者Python的json.load()测试一下。确保最外层是列表（[]），里面是字典（{}），且字段名拼写完全正确（特别是image_id,bbox）。
• 检查标注文件路径：确保aitodv2_test.json的路径正确，并且文件没有损坏。

问题三：APvt/APt等分尺寸指标为-1。

• 这通常意味着在当前数据集的该子集（如area=verytiny）中，没有足够数量的目标用于计算有意义的AP。AI-TOD数据集虽然都是小目标，但划分的阈值可能使得某个子集为空。可以检查一下标注文件，看看不同尺寸目标的数量分布。如果某个尺寸的目标数量为0，那么对应的AP输出-1是正常的。

问题四：结果波动很大，和论文里的基准模型对不上。

• 确认评估设置一致：论文里用的AI-TOD是v1还是v2版本？测试集是官方的test集还是自己划分的val集？maxDets（最大检测数量）参数设置是否一样（aitodpycocotools默认是1500）？这些都会影响最终数值。
• 检查预测框数量：你的模型是否输出了足够多的预测框？如果maxDets设得很大，但你的模型每张图只预测了10个框，那么召回率可能会受限，影响AP。

当你成功跑出评估结果，并且能看懂那一串数字背后的含义时，你就掌握了客观衡量小目标检测模型性能的关键技能。这套工具和指标能帮你摆脱“感觉模型还行”的模糊阶段，进入用数据驱动模型迭代的新阶段。记住，对于小目标检测，不要只盯着整体的AP，多看看APvt和APt，它们才是真正考验模型“眼力”的地方。