人车预标注Python算法：从画框到改框的完整落地指南

先说个结论：人车预标注这件事，本质上不是要做一套“特别聪明的识别器”，而是要建一条把“人工画框”变成“人工改框”的生产线。跑数据标注项目的人应该都有体会，行人、车辆这两个类目看起来最简单，标注量却常常最吓人。这篇把我在实际项目里落地过的一套人车预标注Python算法模型完整拆开，从选型思路、核心代码、使用说明到踩坑记录都写出来，给正在做智慧城市、安防监控、道路数据集预处理的朋友一个可以直接照搬的参考。

这套方案的基本玩法是：用已有的检测模型对一批图片自动打上候选框，输出成常见标注工具能直接打开的格式，标注人员只需要对机器生成的框做确认、微调、补漏，而不需要从零开始画框。适合手里攒了一大堆待标注图片、想压缩工时和预算的个人开发者或小团队。下面按我实际推进这个项目的顺序来讲，先聊为什么值得做，再讲模型怎么选，然后放代码，最后补使用说明和踩坑经验。

1. 人车预标注解决的核心矛盾：从“画框”到“改框”

1.1 一个看起来不起眼但很现实的人工标注账本

先算一笔账。做过目标检测数据集的人都知道，标注一张普通街道图片，如果只有三五个目标，熟练标注员的实际耗时在15到25秒之间，这个时间已经把拖框、选类别、确认保存、翻下一张全都算进去了。假设一个项目有1万张图，按平均20秒一张算，就是5.5万秒，差不多15个小时。如果图片内容复杂一点，比如商圈、停车场、十字路口，每张图有七八个甚至十几个目标，单张耗时经常拉到40秒以上，总工时直奔80个小时。

这只是纯画框的时间。画完之后还有质检、返工、坐标修正，实际投入比估算还要高。如果外包给标注公司，按复杂度和质量要求折算，这笔费用非常可观。更麻烦的是，人工画框的速度瓶颈和模型迭代速度是“剪刀差”：模型一周训一版，每训一版可能需要新增或重新标注几千张图，标注永远是项目里最拖后腿的环节。

那预标注为什么能解决问题？因为检测模型输出的候选框，在绝大多数正常场景下已经比较接近真实位置，差的只是边缘几个像素的微调、少数漏检目标以及类别误判。人工从零画框是把每个目标从头拖一遍，而改框只需要在已有矩形框上拉动边缘，动作幅度小、决策时间短。实际测试下来，一张原本20秒的图，在预标注草稿的基础上修改，普遍能压到5到8秒。这种提升不是靠眼睛快，而是把“定位成本”转移给了模型，人类只负责判断和修正。

1.2 预标注的边界：机器给草稿，人来定稿

需要先明确一个认知：预标注产出的不是最终标注，而是伪标签草稿。它存在的目的不是为了省掉人工质检，而是把标注人员的注意力集中到模型不确定的地方。我在项目启动时就跟团队强调，任何自动生成的框都默认“不可信任”，必须逐张人工复核后才算有效数据。

这么做主要是为了避免“自动化偏见”：标注员看到机器已经画好框，容易下意识地直接保存，结果模型漏掉的目标也被跟着漏掉了，误检的框也被照单全收，最后训练出来的模型会继承甚至放大这些错误。所以我在流程里规定，预标注的XML导出后必须用标注工具逐张打开，漏检目标要补框，明显错误的要删框，框边缘不准的要手动贴边。用人机协同的态度对待预标注，而不是幻想“一键完成数据集”，整个Pipeline才能真正跑得稳。

2. 模型选型与推理框架权衡：检测模型、ONNX部署和权重闭环

2.1 为什么是人车检测模型，而不是分割模型

预标注的产出最终要喂给目标检测项目使用，所以输出格式绝大多数情况是矩形框，也就是VOC格式的bndbox或者COCO格式的bbox。检测模型天然输出矩形框，这是最直接的匹配。有人会问，用实例分割模型比如Mask R-CNN或更细粒度的分割模型输出多边形再取外接矩形，不是能获得更准的框吗？

理论上没问题，但实操上不推荐。分割模型的推理成本远高于检测模型，一张图可能要多花几倍甚至十几倍的时间，而多边形的边缘在转成矩形框的过程中，外接矩形通常还带着一小圈背景，未必比原生检测框更贴合目标。预标注的本质是“先画一个八九不离十的框让人去改”，矩形框本身就是最好的中间表达，没必要让模型去做更重的工作再退化成矩形。唯一值得用分割模型的场景是项目交付格式本身要求多边形，这时候才值得牺牲速度换精细度。

2.2 推理引擎的选择：为什么我最后选ONNX Runtime

模型结构我用了常见的YOLO系列检测模型，具体是哪个版本其实不是最关键的，关键是推理环节怎么落地。我推荐把训练好的模型导出成ONNX格式，然后用ONNX Runtime加载推理，而不是在预标注脚本里依赖完整的深度学习训练框架。

原因很实在。第一，ONNX Runtime不绑定训练框架，训练环境用的PyTorch版本和预标注服务器用的Python环境可以完全分开，互不污染。第二，ONNX Runtime对CPU的优化足够好，很多场景根本没有独立显卡，用CPU也能跑出可接受的吞吐量，单人标注团队完全负担得起。第三，后续如果要换推理硬件，比如从CPU换到带CUDA的GPU，ONNX Runtime只需要换一个Execution Provider配置，代码不用动。

我在实际部署时用的是这样一套环境：预处理用OpenCV，推理用ONNX Runtime，输出解析用Numpy，后处理NMS直接用OpenCV的cv2.dnn.NMSBoxes。整个脚本的第三方依赖非常轻，部署到任何一台内网机器上都很方便。

2.3 权重从哪里来：预训练基线到场景微调的闭环

权重策略是预标注质量的分水岭。第一次跑预标注，不要指望一上来就有一个完美的模型，直接用成熟的预训练权重作为基线就行。这套基线跑出来的框对正常光照、常规视角下的行人车辆已经相当可用，足以让标注员在此基础上工作。

真正的效率提升来自“预标注→人工校对→增量训练→再预标注”的闭环。我在实际操作中，第一轮预标注会特意把置信度阈值调低，多放一些候选框进来，宁可让标注员多删，也别让模型漏掉目标。校对过程中会顺手记录高频漏检的典型场景，比如夜间低照度、远距离小目标、大面积遮挡、雨天反光等等。攒够几百到一千张困难样本之后，用这批数据微调一个专用版本，再用新模型跑第二轮预标注。这时候的漏检率会明显下降，人工需要补框的量大幅减少。

这个飞轮转起来之后，标注成本会一版比一版低。如果项目是持续进数据的长期任务，第二版微调模型的收益通常是最明显的；如果是临时凑一批数据，用预训练权重也能满足基本的预标注需求，看时间和预算取舍。

3. 核心代码实现：从图片输入到伪标签导出的完整链路

3.1 Pipeline的整体结构与配置入口

整个预标注脚本我拆成了四个部分：配置加载、模型推理、结果解析、XML导出。结构上保持单一Python文件加一个YAML配置文件，好处是复制到任何新项目都能独立跑，不依赖复杂的代码工程。

配置文件的骨架长这样：

# config/prelabel.yaml model_path: "models/best.onnx" # 导出的ONNX模型路径 input_size: 640 # 推理输入尺寸，边长按比例等比放缩后填充 conf_thres: 0.35 # 置信度阈值，低于该值的框直接丢弃 iou_thres: 0.45 # NMS的IoU阈值 class_names: ["person", "car"] # 模型输出类别顺序，按模型训练时的顺序填 input_dir: "data/images" # 待预标注图片目录 output_dir: "data/annotations" # 输出XML目录 save_scores: true # 是否把置信度写入XML的score字段 workers: 4 # 并行处理进程数

YAML里的每个字段都有明确的用途，其中最容易忽略的是class_names。这一步会把模型输出的类别索引和项目需要的类别名对齐，如果模型是COCO权重导出的，这里要填成COCO的80类顺序，再在解析阶段按需求过滤出人车；如果模型是自己训练的，就按训练时的类别顺序填。顺序错了，输出的框类别会全部张冠李戴。

3.2 模型加载、图片预处理与letterbox坐标还原

模型加载部分很简单，ONNX Runtime几句话就够了。预处理环节要重点提一下letterbox操作。真实图片的宽高比五花八门，不能直接拉伸成正方形喂给模型，否则人会被压扁、车会被拉长，检测效果明显变差。letterbox的做法是把图片等比缩放到合适尺寸，然后在两侧填充灰色边，补齐到目标尺寸。

import cv2 import numpy as np import onnxruntime as ort def letterbox(img, new_shape=(640, 640), color=(114, 114, 114)): shape = img.shape[:2] # 原始H, W r = min(new_shape[0] / shape[0], new_shape[1] / shape[1]) new_unpad = (int(round(shape[1] * r)), int(round(shape[0] * r))) dw = (new_shape[1] - new_unpad[0]) / 2 dh = (new_shape[0] - new_unpad[1]) / 2 if shape[::-1] != new_unpad: img = cv2.resize(img, new_unpad, interpolation=cv2.INTER_LINEAR) top, bottom = int(round(dh - 0.1)), int(round(dh + 0.1)) left, right = int(round(dw - 0.1)), int(round(dw + 0.1)) img = cv2.copyMakeBorder(img, top, bottom, left, right, cv2.BORDER_CONSTANT, value=color) return img, r, (dw, dh) class PrelabelEngine: def __init__(self, cfg): self.session = ort.InferenceSession(cfg["model_path"], providers=["CUDAExecutionProvider", "CPUExecutionProvider"]) self.input_name = self.session.get_inputs()[0].name self.output_name = self.session.get_outputs()[0].name self.img_size = cfg["input_size"] self.conf_thres = cfg["conf_thres"] self.iou_thres = cfg["iou_thres"] self.class_names = cfg["class_names"]

推理函数需要注意两点：一是OpenCV读入的是BGR顺序，喂给模型前要转成RGB并调整维度顺序；二是模型输出坐标是相对于letterbox后的输入图的，必须记录r和(dw, dh)，在解析阶段把坐标还原回原始图片尺寸。这个还原步骤非常关键，我见过直接把模型输出的框存下来的，结果所有框都贴着图中心聚集，就是因为忘了减padding。

def predict(self, image_bgr): h, w = image_bgr.shape[:2] img, ratio, (dw, dh) = letterbox(image_bgr, (self.img_size, self.img_size)) img = img[:, :, ::-1].transpose(2, 0, 1).astype(np.float32) / 255.0 img = np.expand_dims(img, axis=0) pred = self.session.run([self.output_name], {self.input_name: img})[0] pred = pred[0].transpose(1, 0) # 从[num_anchors, 4+nc]转为逐anchor的行 return self._parse_output(pred, ratio, (dw, dh), (w, h))

3.3 后处理：坐标还原、NMS与类别过滤

YOLO系列新版检测头的输出格式一般是[1, 4 + nc, num_anchors]，转置后每一行是[cx, cy, bw, bh, cls1, cls2, ...]。解析时先按行取置信度最高的类别和分数，过滤低分框，然后把中心点宽高格式的坐标换算成左上右下坐标，再减去letterbox的padding并除以缩放比例，还原到原图坐标。

def _parse_output(self, pred, ratio, pad, orig_size): # pred: [num_anchors, 4 + nc] cls_conf = pred[:, 4:] class_ids = np.argmax(cls_conf, axis=1) scores = cls_conf[np.arange(len(class_ids)), class_ids] keep = scores >= self.conf_thres boxes = pred[keep][:, :4].copy() class_ids = class_ids[keep] scores = scores[keep] if len(boxes) == 0: return [], [], [] # xywh -> xyxy boxes[:, 0] = boxes[:, 0] - boxes[:, 2] / 2 boxes[:, 1] = boxes[:, 1] - boxes[:, 3] / 2 boxes[:, 2] = boxes[:, 0] + boxes[:, 2] boxes[:, 3] = boxes[:, 1] + boxes[:, 3] # 还原letterbox偏移 dw, dh = pad boxes[:, [0, 2]] = (boxes[:, [0, 2]] - dw) / ratio boxes[:, [1, 3]] = (boxes[:, [1, 3]] - dh) / ratio # 裁剪到原始图像边界 orig_w, orig_h = orig_size boxes[:, [0, 2]] = np.clip(boxes[:, [0, 2]], 0, orig_w) boxes[:, [1, 3]] = np.clip(boxes[:, [1, 3]], 0, orig_h) # NMS，cv2.dnn.NMSBoxes用的是[x, y, w, h]格式 boxes_wh = boxes.copy() boxes_wh[:, 2] -= boxes_wh[:, 0] boxes_wh[:, 3] -= boxes_wh[:, 1] indices = cv2.dnn.NMSBoxes(boxes_wh.tolist(), scores.tolist(), self.conf_thres, self.iou_thres) if isinstance(indices, tuple): indices = indices[0] if len(indices) == 0: return [], [], [] indices = np.array(indices).flatten() return boxes[indices], class_ids[indices], scores[indices]

这里有一个容易踩的细节：cv2.dnn.NMSBoxes返回的格式在不同OpenCV版本里不一样，有的是二维数组，有的已经压平了，所以我统一np.array(indices).flatten()处理。NMS之后，我只保留配置里需要的类别，过滤掉其他类别。如果class_names填的是完整COCO列表，那过滤逻辑就是在解析后按class_ids是否属于目标集合来筛。

3.4 批量导出VOC XML标签文件

输出格式我选择了VOC XML，因为这个格式是标注工具兼容性最好的，后续转YOLO TXT或者COCO JSON都有现成转换脚本。XML的生成用Python标准库里的xml.etree.ElementTree，不需要额外引第三方库。

import xml.etree.ElementTree as ET import os def save_voc_xml(self, image_path, boxes, class_ids, scores, out_path): root = ET.Element("annotation") folder = ET.SubElement(root, "folder") folder.text = os.path.basename(os.path.dirname(image_path)) filename = ET.SubElement(root, "filename") filename.text = os.path.basename(image_path) img = cv2.imread(image_path) h, w = img.shape[:2] size = ET.SubElement(root, "size") width = ET.SubElement(size, "width"); width.text = str(w) height = ET.SubElement(size, "height"); height.text = str(h) depth = ET.SubElement(size, "depth"); depth.text = "3" for box, cls_id, score in zip(boxes, class_ids, scores): obj = ET.SubElement(root, "object") name = ET.SubElement(obj, "name") name.text = self.class_names[cls_id] bndbox = ET.SubElement(obj, "bndbox") xmin = ET.SubElement(bndbox, "xmin"); xmin.text = str(int(box[0])) ymin = ET.SubElement(bndbox, "ymin"); ymin.text = str(int(box[1])) xmax = ET.SubElement(bndbox, "xmax"); xmax.text = str(int(box[2])) ymax = ET.SubElement(bndbox, "ymax"); ymax.text = str(int(box[3])) tree = ET.ElementTree(root) tree.write(out_path, encoding="utf-8", xml_declaration=True)

XML的filename节点必须与图片文件名完全一致，标注工具靠这个字段关联图片和标注文件。保存时我建议显式指定encoding="utf-8"和xml_declaration=True，否则有些老旧标注工具读中文路径或特殊字符时会出现解析问题。

3.5 批量处理、进度管理与异常保护

主流程就是遍历图片目录，逐张调用推理和保存。由于预标注过程往往要连续跑几小时，异常处理必须做扎实。我习惯把单张图片的处理包在try...except里，遇到坏图、非图片文件直接跳过并记录到error.txt，而不是让整个任务中断。

from concurrent.futures import ProcessPoolExecutor from tqdm import tqdm import glob def process_one(args): engine_cfg, image_path, out_dir = args # 每一进程单独创建engine，避免多线程共享onnxruntime会话 engine = PrelabelEngine(engine_cfg) try: img = cv2.imread(image_path) if img is None: return ("error", image_path, "imread failed") boxes, class_ids, scores = engine.predict(img) base = os.path.splitext(os.path.basename(image_path))[0] out_path = os.path.join(out_dir, base + ".xml") engine.save_voc_xml(image_path, boxes, class_ids, scores, out_path) return ("ok", image_path, len(boxes)) except Exception as e: return ("error", image_path, str(e))

并行处理时有一个重要注意点：每个子进程都要重新创建一次ONNX会话，不要跨进程共享同一个InferenceSession对象，否则轻则报错，重则静默崩溃。进程数不用太多，CPU推理的话设为本机物理核心数减一即可；GPU推理时进程数建议保持在1到2个，因为GPU显存是稀缺资源，多进程同时压显存反而会降低吞吐。

4. 使用说明详解：环境依赖、目录结构与参数配置

4.1 环境依赖与安装

这套工具的依赖非常少，全部写在requirements.txt里：

onnxruntime-gpu==1.17.1 opencv-python>=4.8.0 numpy>=1.24.0 PyYAML>=6.0 tqdm>=4.64.0

没有CUDA显卡的环境可以把onnxruntime-gpu换成onnxruntime，CPU模式也能跑，只是吞吐量低一些。安装时建议用独立的虚拟环境，别直接装到系统Python里。如果遇到ONNX Runtime和OpenCV版本冲突，优先固定版本号再装，这两个库的大版本更新偶尔会引入依赖冲突。

4.2 项目目录与文件约定

建议的目录结构长这样：

prelabel/ ├── config/ │ └── prelabel.yaml ├── models/ │ └── best.onnx ├── data/ │ ├── images/ # 放待标注原图 │ ├── annotations/ # 输出的XML会写到这里 │ └── error.txt # 异常图片记录 ├── prelabel.py └── requirements.txt

图片文件命名我是强烈建议统一改好的，比如000001.jpg这样的纯数字编号，不要带中文、空格和特殊字符。虽然现在的标注工具大多能处理中文文件名，但后续转COCO、转TFRecord等环节经常在文件名上翻车，源头规范省去很多麻烦。

4.3 命令行与参数配置对照

脚本的启动方式很简单：

python prelabel.py --config config/prelabel.yaml

也可以不依赖配置文件，直接用命令行参数覆盖关键项：

python prelabel.py --input data/images --output data/annotations --conf 0.35 --model models/best.onnx

几个核心参数的经验取值我列个表参考：

input_size值得一提，它对小目标影响最明显。监控摄像头截取的画面里，远端的行人在原始图上可能只有二三十个像素高，用640推理很容易漏。我实际测试过，同一批图片从640升到1024，小目标召回能提升5到10个点，代价是单张推理时间增加了约1.5倍。如果项目对漏检容忍度低，建议直接上1024，预标注本来就是离线任务，时间多一点完全能接受。

4.4 输出格式与标注工具的衔接

脚本生成的VOC XML可以直接用常见标注工具打开。在标注工具里打开图片时，它会自动读取同目录下的同名XML文件，预标注的框会直接叠加显示。标注员要做的就是把框修正、补漏、删除误检，然后重新保存。

这里有个衔接上的细节：有的标注工具保存时会重写整个XML，如果原XML里存在它不认识的字段，可能会导致保存失败。所以我在XML里只保留最基础的结构，不写太多自定义字段，save_scores默认也只在调试时开。宁可让标注工具没有任何兼容性问题，也不为了一个置信度字段引入不必要的风险。

5. 实测效果与踩坑记录：从阈值调优到工具链衔接

5.1 置信度阈值是预标注体验的分水岭

我踩过的第一个坑就是阈值设置。第一次跑预标注时，我把conf_thres设成了0.1，想着反正人工要复核，多给点框总比漏检好。结果高密度人群场景里，一张图从模型里吐出来上百个框，大部分是很低置信度的误检，标注员改框没改多少，光删框就删得耐心归零。

后来我把阈值策略改成两档处理。第一轮预标注用0.25，保证召回，但明确要求标注员先删后改、漏检必须补；第二轮用微调后的高置信度模型配0.5的阈值，这时候误检已经很少，标注员的注意力基本都在细节框位上。经验是：宁可让模型漏检几个目标，也不能让误检铺满全屏，因为删框的决策负担比补框还要重，人的大脑处理“这个框要不要”比处理“这里缺个框”更累。

5.2 小目标、遮挡与极端角度的实战处理

监控场景里最头疼的不是正常大小的车，而是远处的行人和被遮挡的骑行者。远距离行人属于典型的小目标问题，解决路径有两个，一个是前面提到的提高推理input_size到768或1024；另一个是给模型喂困难样本做针对性训练。遮挡问题更依赖数据，纯靠推理参数调不出来，只能在微调阶段多准备局部遮挡样本。

我在微调训练里有一个固定动作：把人工校对阶段标记为“漏检”的图片单独建一个文件夹，不混入正常样本，每轮训练前按一定比例和普通样本混合。这样模型在每次迭代中都能反复看到自己犯过的错，比盲目的数据增强更对症。大概跑三轮增量训练之后，夜间和远距离场景的预标注质量会有质的提升，标注员补框的频率肉眼可见地下降。

5.3 格式兼容与工具链衔接的坑

格式兼容的坑集中在三个地方。第一个是OpenCV版本导致NMS返回格式不一致，早版本返回的是元组套二维数组，新版本直接返回一维数组，不兼容处理的话轻则报错重则全部框被丢弃。第二个是XML里<filename>和实际图片名不一致，标注工具加载时找不到关联图片，会把XML当作无效文件。第三个别忽略的是图片和XML的存放位置，有的标注工具要求XML必须和图片在同一目录，有的工具允许分开，建议统一放在同级目录里，省得来回调路径。

还有一个我一开始没注意到的坑：推理时如果图片读取用的是OpenCV，jpg的EXIF旋转信息会被忽略，手机拍的竖图会被直接读成横图。虽然监控截图和相机采集的素材基本没有EXIF问题，但如果图片来源很杂，我建议批量处理前先统一做一次方向矫正，否则预标注框和肉眼看到的画面会对不上。

5.4 人效对比：预标注到底能省多少时间

最后放一组我这边实际跑过的数据，给还没入坑的朋友一个心理预期。某批监控场景截图约2万张，目标密度平均每张3.5个。纯人工标注阶段，团队平均每张耗时约18秒，算下来总工时约100小时。接入预标注后，第一轮用预训练权重加0.25阈值，标注员平均每张耗时降到7秒左右；整理困难样本微调模型后，第二轮预标注的平均耗时进一步降到5秒以内。

换算下来，预标注加微调模型这个组合，整体节省了六到七成的人工标注时间。更大的隐性收益是质量一致性：模型画的框天然稳定，标注员只做小幅修正，最终交付的框贴合程度反而比纯人工时更均匀。当然，这些数字依赖场景复杂度和标注员熟练度，但即便是最保守的估计，预标注把人从重复劳动里解放出来这件事，是实实在在成立的。

我自己跑了这么多轮之后，最大的体会是：预标注模型的初始精度没那么重要，重要的是整个校准流程能不能快速迭代起来。第一次跑出来的框哪怕歪歪扭扭，只要人工修正的产物能迅速变成下一版模型的训练数据，第二轮、第三轮的体验就会明显好转。如果你正准备给一批人车图片做标注，不要花太多时间纠结用哪个预训练权重，先把这套Pipeline跑通，把“改框”的节奏顺起来，后续优化都是水到渠成的事。