XML转TXT标签转换：YOLO训练前的归一化与校验避坑指南

1. 为什么xml转txt是YOLO训练链条上最容易翻车的一环

做目标检测的人都有个共识：模型不收敛的时候，八成时间浪费在怀疑学习率、怀疑数据增强、怀疑网络结构，最后发现是标签文件里的坐标压根儿就不对。xml转txt这个操作听起来简单到不值一提——不就是把几个数字拿出来除一下嘛，一个脚本二十行代码搞定。但我见过的实际项目里，恰恰是这个"二十行代码"的环节，让不少人白白跑了两三天训练，最后mAP一直是0.00。

先把场景说清楚。xml文件通常来自LabelImg、Labelme一类标注工具，采用PASCAL VOC的格式组织，一个图片对应一个xml，文件内部用<object>节点罗列每个目标，每个目标包含类别名<name>和边界框<bndbox>，框内是xmin、ymin、xmax、ymax四个以像素为单位的整数坐标，原点是图片左上角。而YOLO系列要的txt文件，每行代表一个目标，格式是类别索引 中心点x 中心点y 宽 高，后面四个数值全部要归一化到0到1之间，且以图片实际的宽高为分母。所以转换的本质是三件事：坐标原点从左上角挪到中心、绝对像素变相对比例、类别名变数字索引。这三件事里任何一件做偏了，训练都不会报错，只会静静地给你一个废掉的模型。

很多人第一次写转换脚本时，只盯着"除以宽高"这个动作，却忽略了归一化的分母必须是每张图片自己的尺寸，而不是数据集统一的输入尺寸。我见过有人图省事，直接把所有坐标除以640，理由是他打算用640的输入分辨率训练。这个做法在图片本身尺寸一致时勉强能跑，一旦数据来源混杂——比如一部分是手机拍的4000×3000，一部分是网络抓的800×600——标签就会大面积越界，出现坐标大于1的情况，训练时被框架悄悄裁掉或者直接算错损失。

注意：YOLO的txt里出现任何大于1或小于0的数值，都不应该"容忍"。正常转换出来的标签，四个数值理论上都在(0,1)开区间内，越界就是错的信号。

还有一个隐蔽的坑：VOC的xmax、ymax到底是闭区间还是开区间。标注工具画框时，xmax通常指的是框最右侧那个像素的坐标，如果直接按(xmax-xmin)/width算宽度，会得到比实际少一个像素的结果。对于大目标这点误差可以忽略，但对于密集小目标检测，这种半像素级的系统性偏移累积起来会影响召回。严谨的写法是用xmax - xmin作为宽度像素值，不做加一处理，同时保证宽度不为0，因为当目标只有一个像素宽时xmax == xmin，归一化后宽度为0，这一行标签在训练时会变成无效样本。

这篇内容适合两类人看：刚跑通YOLO官方Demo、正准备换自己数据集的新手，以及手上有历史VOC格式数据、需要批量迁移到YOLO训练流程的老手。前者需要一套能直接抄的完整脚本和边界情况清单，后者更关心批量处理时的鲁棒性、类别映射的一致性和转换后的校验手段。下面的内容会按"先想清楚再动手"的顺序展开，把每一步的选择理由都讲透，而不是甩一段代码让你自己猜。

2. 转换之前必须先把数据集的全貌摸清楚

2.1 三个必须提前确认的数据集事实

动手写脚本之前，先花十分钟做三件核实工作，能省掉后面几小时的调试。

第一件是类别清单是否统一。VOC格式的xml里，类别是以字符串形式写在<name>标签里的，大小写、空格、下划线都可能不一致。同一批数据里同时出现person和Person，或者traffic_light和traffic light，在转换后会被映射成两个不同的索引，模型会学到两个语义完全相同的类别，直接稀释每个类别的有效样本量。我建议第一遍不要急着转换，先扫一遍所有xml，把所有出现过的<name>文本收集起来去重打印，人眼过一遍。这个动作只需要几秒钟，但能暴露很多标注规范不严的问题。

第二件是图片尺寸的分布。转换脚本需要读图片的宽高，所以必须确认图片文件真实存在且能正常打开。有些数据集在整理过程中被打包、重命名、压缩过，xml里记录的<size>节点和实际图片尺寸对不上。这种情况在公开数据集上少见，在自采数据上很常见——比如标注完之后用工具批量压缩了图片，xml没同步改。所以我的习惯是不信xml里的<size>，一律从图片文件本身读宽高，用PIL或者OpenCV都行。这也顺带解决了另一个问题：有些标注工具压根不写<size>节点。

第三件是文件名与图片名的对应关系。VOC的组织方式是Annotations/放xml，JPEGImages/放图片，两个目录下的文件名主干应该一一对应。但实际交付的数据里经常出现图片是IMG_0001.JPG、xml里对应的<filename>写的是IMG_0001.jpg，扩展名大小写不一致；或者图片被重命名成001.jpg而xml还叫IMG_0001.xml。转换脚本如果按xml里的<filename>去找图片，就会大面积找不到。稳妥策略是以xml文件名的主干为唯一键，去图片目录里匹配同名图片，而不是依赖xml内部的<filename>字段。

2.2 一次快速摸底脚本

下面这段脚本不做转换，只做体检。跑一遍拿到类别清单、缺失图片列表、尺寸异常列表，心里有底了再进入下一步。

import os import xml.etree.ElementTree as ET from collections import Counter from PIL import Image xml_dir = "dataset/Annotations" img_dir = "dataset/JPEGImages" classes = Counter() missing = [] size_conflict = [] img_index = {} for name in os.listdir(img_dir): stem, _ = os.path.splitext(name) img_index[stem] = os.path.join(img_dir, name) for fname in os.listdir(xml_dir): if not fname.endswith(".xml"): continue stem = os.path.splitext(fname)[0] tree = ET.parse(os.path.join(xml_dir, fname)) root = tree.getroot() for obj in root.findall("object"): classes[obj.find("name").text.strip()] += 1 if stem not in img_index: missing.append(fname) continue with Image.open(img_index[stem]) as im: w, h = im.size sz = root.find("size") if sz is not None: xw = int(float(sz.find("width").text)) xh = int(float(sz.find("height").text)) if (xw, xh) != (w, h): size_conflict.append((fname, (xw, xh), (w, h))) print("类别统计:", classes.most_common()) print("缺失图片数:", len(missing)) print("尺寸不一致数:", len(size_conflict)) print("前10个尺寸冲突:", size_conflict[:10])

这份体检报告里，类别统计的计数分布本身也很有信息量。如果某个类别的样本数只有个位数，就要考虑是标注遗漏还是这个类本来就稀有，后续划分训练验证集时得做分层抽样，否则验证集里可能一个正样本都没有，mAP评估会失真。尺寸冲突那部分尤其要看，如果冲突数量很多，说明整个数据集在某个环节被动过，这时候用xml里的size去归一化必然出错，必须坚持从图片读尺寸。

2.3 类别索引的分配与固化

YOLO的类别索引是个整数，从0开始。索引本身没有语义，但训练和推理时必须完全一致。这就是为什么我强烈建议把类别映射写成一个独立的、显式声明的有序列表，存成文件，而不是在脚本里用set()或者字典遍历顺序临时生成。Python 3.7之后字典保序，但用set做中间容器时顺序是不稳定的，同一批数据跑两次可能得到两套索引，然后你训练完的权重在推理时把所有类别都标错。

我的做法是建一个classes.txt，一行一个类别名，行的顺序就是索引顺序。转换脚本读这个文件构造{name: idx}的字典。这样有个额外好处：标注时如果用了LabelImg，它本身也支持生成classes.txt，两边可以直接对齐，减少人工出错。同时这个文件将来部署时也要跟着权重一起走，属于模型的一部分资产。

with open("classes.txt", "r", encoding="utf-8") as f: class_names = [line.strip() for line in f if line.strip()] name_to_id = {n: i for i, n in enumerate(class_names)}

对于xml里出现了、但不在classes.txt中的类别，千万不能静默跳过。跳过会导致某些目标凭空消失，而且不会报错。正确做法是记录下来并让转换脚本以非零状态退出，逼着人去处理：要么是标注时打错了字，要么是classes.txt漏了类，两种情况都必须人工确认。

3. 坐标转换的数学细节与逐行拆解

3.1 从左上角绝对坐标到中心点归一化坐标

把这件事讲透，只需要一张纸一支笔。设图片宽W、高H，框的左上角(xmin, ymin)、右下角(xmax, ymax)，全部是像素值，坐标系原点在图片左上角，x向右，y向下。

第一步求框的像素宽高：bw = xmax - xmin，bh = ymax - ymin。 第二步求框中心点像素坐标：cx = xmin + bw / 2，cy = ymin + bh / 2。注意这里用的是xmin + bw/2而不是(xmin+xmax)/2，两者在数学上等价，但用前者能保证cx严格落在框内，浮点运算时更稳。 第三步归一化：cx /= W，cy /= H，bw /= W，bh /= H。

写成代码就是：

def voc_to_yolo(xmin, ymin, xmax, ymax, W, H): bw = xmax - xmin bh = ymax - ymin cx = xmin + bw / 2.0 cy = ymin + bh / 2.0 return cx / W, cy / H, bw / W, bh / H

为什么YOLO要用中心点加宽高，而不是直接沿用角点？这跟它的预测机制有关。YOLO把图像切成网格，每个网格单元负责预测中心点落在该单元内的目标，网络输出的是相对于网格单元的偏移量。用中心点表示，目标的"归属网格"是唯一的、明确的；如果用角点，一个跨网格的大目标会牵扯到多个单元的归属判定，逻辑会变得复杂。而且中心点加宽高的表示方式在做数据增强（比如随机缩放、裁剪）时变换更直观，缩放因子直接乘到宽高上即可，不用重新推导角点。

归一化的意义也值得说一句。如果标签存的是绝对像素，那么训练时一旦改变输入分辨率（比如从416换到640），所有标签都要重新算一遍，数据集就无法在不同输入尺寸间复用。归一化之后，标签描述的是"目标占图片多大比例、位于图片什么相对位置"，与分辨率解耦，同一份数据集可以在任意输入尺寸下训练。这是YOLO能灵活支持多尺度训练的基础之一。

3.2 四个必须写进脚本的数值保护

纯数学公式没问题，但真实数据总能给你惊喜。下面四类保护逻辑，缺一个都可能让训练悄悄出问题。

保护一：宽高为零。当xmax == xmin或者ymax == ymin时，框退化成一条线，归一化后宽或高为0。这种样本对检测训练毫无价值，还会在计算IoU时产生除零。处理方式是直接丢弃该目标并计数告警，同时在日志里打印是哪个xml，方便回头查标注。

保护二：坐标越界。理论上xmax <= W，但标注工具允许鼠标拖到图片边缘外，或者坐标是浮点数被截断产生偏差。转换前把xmin/ymin钳制到不小于0，xmax/ymax钳制到不大于W-1和H-1。钳制之后如果框的面积小到不可用（比如宽或高小于2像素），同样丢弃。

保护三：坐标反了。极少见但确实存在，xmin > xmax。这通常是标注时从右下往左上拖，某些工具没做归一化处理。检测到就交换两者，并记录日志。

保护四：坐标为负或超出范围。有些标注工具在图片被旋转或者做了EXIF方向修正后，坐标会出现负数。必须钳制，不能直接除。

def safe_box(xmin, ymin, xmax, ymax, W, H, min_px=2): if xmin > xmax: xmin, xmax = xmax, xmin if ymin > ymax: ymin, ymax = ymax, ymin xmin = max(0.0, min(float(xmin), W - 1)) xmax = max(0.0, min(float(xmax), W - 1)) ymin = max(0.0, min(float(ymin), H - 1)) ymax = max(0.0, min(float(ymax), H - 1)) if (xmax - xmin) < min_px or (ymax - ymin) < min_px: return None return xmin, ymin, xmax, ymax

那个min_px阈值设成多少合适？我的经验是2。低于2像素的目标，在主流检测网络的感受野和特征图分辨率下基本学不出来，留着只会污染损失函数。如果你的任务确实是极小目标检测（比如遥感图像里的车辆），那策略要整体重做，包括输入分辨率、特征金字塔层级和切图推理，不是靠保留1像素标签能解决的。

3.3 数值精度：保留几位小数才够

txt里写几位小数？有人写6位，有人写2位。位数的选择影响两件事：文件体积和坐标精度。

精度方面，归一化坐标的量级在0.001到1之间。假设一张1920宽的图，1个像素对应归一化值约0.00052。要能区分相邻像素，至少需要4位小数。所以6位小数是安全且常见的做法，%.6f格式。2位小数意味着大约2个像素的量化误差，对于大目标无所谓，对小目标就是灾难——一个20像素宽的目标，误差可能占到10%。

文件体积方面，6位小数每行大约60到70个字符。十万个目标也就6MB到7MB，对现代存储完全不是问题。所以没必要为了省空间牺牲精度。我统一用6位，格式化成{cls} {cx:.6f} {cy:.6f} {bw:.6f} {bh:.6f}。

3.4 一个完整的转换脚本

把前面的逻辑拼起来，得到下面这份可以直接用的脚本。它做了几件额外的事：三类异常分别计数、生成一个可直接阅读的转换报告、保留图片与txt同名对应关系。

import os import xml.etree.ElementTree as ET from PIL import Image XML_DIR = "dataset/Annotations" IMG_DIR = "dataset/JPEGImages" OUT_DIR = "dataset/labels" CLASSES_FILE = "classes.txt" MIN_PX = 2 os.makedirs(OUT_DIR, exist_ok=True) with open(CLASSES_FILE, "r", encoding="utf-8") as f: class_names = [l.strip() for l in f if l.strip()] name_to_id = {n: i for i, n in enumerate(class_names)} img_index = {} for n in os.listdir(IMG_DIR): stem, _ = os.path.splitext(n) img_index[stem] = os.path.join(IMG_DIR, n) stat = {"ok": 0, "no_img": 0, "degenerate": 0, "unknown_cls": 0, "clamped": 0, "empty_file": 0} for fname in sorted(os.listdir(XML_DIR)): if not fname.endswith(".xml"): continue stem = os.path.splitext(fname)[0] if stem not in img_index: stat["no_img"] += 1 continue with Image.open(img_index[stem]) as im: W, H = im.size root = ET.parse(os.path.join(XML_DIR, fname)).getroot() lines, bad = [], 0 for obj in root.findall("object"): cname = (obj.find("name").text or "").strip() if cname not in name_to_id: stat["unknown_cls"] += 1 bad += 1 continue bb = obj.find("bndbox") try: xmin = float(bb.find("xmin").text) ymin = float(bb.find("ymin").text) xmax = float(bb.find("xmax").text) ymax = float(bb.find("ymax").text) except (AttributeError, ValueError): stat["degenerate"] += 1 continue if xmin > xmax: xmin, xmax = xmax, xmin if ymin > ymax: ymin, ymax = ymax, ymin if xmin < 0 or ymin < 0 or xmax > W - 1 or ymax > H - 1: stat["clamped"] += 1 xmin = max(0.0, min(xmin, W - 1)) xmax = max(0.0, min(xmax, W - 1)) ymin = max(0.0, min(ymin, H - 1)) ymax = max(0.0, min(ymax, H - 1)) bw, bh = xmax - xmin, ymax - ymin if bw < MIN_PX or bh < MIN_PX: stat["degenerate"] += 1 continue cid = name_to_id[cname] cx = (xmin + bw / 2.0) / W cy = (ymin + bh / 2.0) / H lines.append(f"{cid} {cx:.6f} {cy:.6f} {bw/W:.6f} {bh/H:.6f}") if not lines: stat["empty_file"] += 1 # 仍写出空文件，保证后续对齐时有占位，避免训练器把图片当无标签样本 open(os.path.join(OUT_DIR, stem + ".txt"), "w").close() continue with open(os.path.join(OUT_DIR, stem + ".txt"), "w", encoding="utf-8") as f: f.write("\n".join(lines) + "\n") stat["ok"] += 1 for k, v in stat.items(): print(f"{k}: {v}")

关于"空txt文件要不要写"这个细节，值得单独说一下。YOLO的训练逻辑里，一张图片如果找不到对应的txt标签文件，有的实现会当它不存在而跳过，有的实现会当它是一张纯背景图（负样本）参与训练。这两种行为差异很大。如果你的数据集里确实存在一部分只有背景没有目标的图片，那就是有意为之的负样本，应该写空文件；如果本来应该有目标但因为转换失败变成空文件，那就必须报警而不是默默写出去。

提示：负样本图片对抑制误检是有价值的，但比例要控制。我一般把纯背景图控制在总图片数的5%以内，全程混在全量数据里，不做单独加权。

4. 转换完之后怎么验证标签真的对

4.1 可视化回画：最直接也最容易被跳过的一步

脚本跑完没报错，不代表标签是对的。中间任何一个逻辑写错，输出依然是合法的六位小数，训练依然能启动，直到你发现模型什么都检测不出来。所以转换后必须做回画验证：把txt里的归一化坐标还原成像素坐标，画到原图上，人眼看框是否贴合目标。

还原公式是转换的逆运算：cx*W得中心点像素x，bw*W得像素宽，左上角就是cx*W - bw*W/2。用OpenCV或者PIL画矩形加类别文字，抽20到30张覆盖不同场景、不同目标密度的图片看看。我习惯抽那些目标特别多和特别少的样本，前者能暴露坐标串行问题，后者能暴露归一化分母问题。

import cv2 def draw_check(img_path, txt_path, class_names): img = cv2.imread(img_path) H, W = img.shape[:2] if not os.path.exists(txt_path): return img with open(txt_path) as f: for line in f: parts = line.strip().split() if len(parts) != 5: continue cid = int(parts[0]); cx, cy, bw, bh = map(float, parts[1:]) x1 = int((cx - bw / 2) * W) y1 = int((cy - bh / 2) * H) x2 = int((cx + bw / 2) * W) y2 = int((cy + bh / 2) * H) cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(img, class_names[cid], (x1, max(y1 - 5, 12)), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2) return img

回画时重点看三件事：框是不是整体偏移了（说明中心点算错）、框是不是整体缩放不对（说明分母用错）、框之间的相对位置是否错乱（说明读取object节点的顺序有问题）。如果框看起来"差半个框"或者"缩在左上角"，基本就是中心点和宽高搞混了，把cx当成了xmin直接用。

4.2 用一个可复现的自检清单过一遍

可视化肉眼过完之后，再跑几个自动化检查，把主观判断变成客观数字。下面这几条我每次都会过一遍：

第二项特别值得强调。转换脚本里如果用了continue跳过异常目标，最终行数会少于原始目标数。这个差值必须能对上degenerate加unknown_cls的计数，对不上就说明有地方吃了目标没记账。我在实际项目里就遇到过一次，某批xml里有几个<object>节点缺少<bndbox>子节点，代码里bb.find("xmin").text直接抛AttributeError被外层吞掉，整张图的标签都没写出去，而统计里没记录，直到对比行数才发现差了几十个目标。

4.3 和训练框架的label缓存对齐

到这一步标签文件本身是对的，但还有一层要确认：训练器读到的标签和你写在磁盘上的标签是同一份。Ultralytics系列的实现会在首次训练时扫描标签、生成缓存文件（.cache），之后启动训练直接读缓存。这意味着如果你在训练启动之后又改了txt，缓存不会自动失效，训练用的还是旧标签。表现出来就是"我明明改了标签怎么模型还是那样"。

所以流程上必须守住一条：任何标签修改都要在训练启动之前完成，或者修改后手动删掉缓存文件。缓存文件通常和标签在同一层目录或者图片目录下，名字带.cache后缀。我在调整标签格式时踩过这个坑，改了十几分钟后发现验证集指标纹丝不动，删了缓存重训才对上。这不是玄学，是缓存机制的正常表现，知道了就不会浪费时间。

另外，YOLO体系里的data.yaml要指向正确的路径，并且names字段的顺序必须和classes.txt完全一致。有人图省事在两个地方各写一份类别列表，改了一处忘了另一处，最后训练出来的类别名张冠李戴——数字索引是对的，显示的名字全错。我的做法是data.yaml里的names直接从classes.txt生成，脚本里一次性写出来，杜绝两份数据源。

5. 规模化转换时的脚本工程化处理

5.1 十万级样本下的性能与内存考量

单个xml转换用ET.parse完全没问题，但数据量上到十万级时，有些写法会明显拖慢速度。最典型的是在循环里反复ET.parse同一个文件、或者在循环里重复os.listdir。前者不常见，后者很多人会写——在遍历xml的循环里每次都调os.listdir(IMG_DIR)去拼图片路径，等于把目录扫描做了N次。正确做法是循环外建一次索引字典，就是前面脚本里img_index的做法。

第二个性能点是图片尺寸读取。Image.open是惰性的，只读文件头就能拿到尺寸，不加载像素数据，所以速度很快。但如果图片在网络上或者磁盘很慢，这一步会成为瓶颈。可以考虑把图片尺寸预先缓存成一个stem -> (W,H)的json或者csv，转换时直接查表。对于十万级数据集，这一步能把转换时间从几分钟压到几十秒。缓存本身也有风险——图片被替换过而缓存没更新，所以我一般在缓存文件里带上图片的修改时间和文件大小，读取时校验一下，不匹配就重新读。

内存方面，逐文件处理、逐文件写出是最省内存的，不要把所有结果攒在内存里最后统一写。上面那份脚本就是逐文件写，内存占用基本恒定在几百KB级别。如果为了多进程并行，把任务切成若干块分给不同worker，每个worker处理一部分xml，各自写各自的结果目录，最后合并。用multiprocessing.Pool大概能提速3到5倍，具体取决于磁盘IO和CPU核数。不过对于一般规模的数据集，单进程跑几分钟就完了，没必要提前上并行，增加调试复杂度。

5.2 训练集验证集划分的时机

有个顺序问题很多人会搞混：应该先划分数据集再转换，还是先转换再划分？

我的答案是按图片划分，转换前后都行，但划分必须在转换之前定好随机种子和名单，而且划分要以图片为单位而不是以标签行为单位。原因是同一张图的所有目标必须整体进入训练集或验证集，不能拆开。如果先转换再划分，且划分逻辑是按txt文件随机抽样，那其实也是按图片粒度的，问题不大。但如果你在划分时按"目标行"抽样，同一张图的目标就会散落到两边，验证集里出现训练时见过的图像内容，评估指标虚高。

实际做法是：所有图片名列表打乱，按8:1:1或者7:2:1切分，把文件名写进train.txt、val.txt、test.txt三个清单文件。转换脚本独立于划分运行，全量转换，然后靠清单文件在训练时决定读哪些。这样好处是转换只需要做一次，后续调整划分比例不用重转。清单文件放在数据集根目录，data.yaml里分别指向它们。划分时记得做分层抽样，尤其类别不均衡的时候，保证每个类在训练集和验证集里都有足够样本，否则某个类在验证集里只有三五个实例，算出来的AP波动会非常大，你会误以为模型不稳定。

5.3 一个常见的路径陷阱

YOLO训练器读标签时的默认规则是：把图片路径里的images替换成labels，扩展名换成txt。比如datasets/mydata/images/train/001.jpg对应的标签路径是datasets/mydata/labels/train/001.txt。如果你的目录结构不是这个约定，要么改结构，要么在data.yaml里显式写标签路径。我见过有人把标签放在Annotations_yolo/下，然后怎么都读不到，报错信息也不明显。花五分钟把目录对齐到官方约定，比调试半天路径映射划算得多。

推荐的目录长这样：

mydata/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ ├── classes.txt └── data.yaml

注意images/train和labels/train必须是平级的，层级结构完全镜像。转换脚本里OUT_DIR也要按划分分别写，或者先全量转换到labels/all/再按清单拆分复制。后一种更稳妥，因为原始xml只有一份，全量转换后再镜像拆分不会出错。

6. 那些只有动手之后才会遇到的问题

6.1 中文路径与编码问题

Windows上最常踩的坑就是中文路径。cv2.imread在路径含中文时会返回None，PIL.Image.open一般没问题。数据集目录只要有中文，cv2回画验证那一步就全军覆没，而且报错是NoneType相关的，看不出根因。解决办法有两个：一是把整个数据集路径改成纯英文，这是最省事的；二是用numpy.fromfile加cv2.imdecode绕过路径编码问题。我倾向第一种，项目从建目录开始就用英文加下划线，避免后续一系列麻烦。

xml文件本身的编码也要留意。标准VOC的xml开头会声明encoding="utf-8"，但有些老工具导出的是gb2312或者没声明。ET.parse在遇到非utf-8编码的中文类别名时会抛ParseError。稳妥写法是先用open(path, "rb")读字节，检测编码后再ET.fromstring。如果类别名是中文，那classes.txt也要用同一种编码保存，并且在训练时确保框架能正确读中文类名——有些评估脚本在做类别名匹配时只支持ASCII。

6.2 标注工具的格式变体

不同标注工具导出的xml虽然大体遵循VOC，细节差异不小。有的工具把<bndbox>里的坐标写成浮点数123.456，有的写成整数，float()转换都能处理，但浮点坐标意味着标注时进行了缩放映射，可能引入亚像素偏移，一般可接受。有的工具在<object>里额外加了<difficult>和<truncated>字段，YOLO训练通常不用这两个字段，可以选择忽略，但如果你的任务对遮挡特别敏感，可以把difficult=1的目标过滤掉，或者反过来单独统计。还有的工具会导出<segmented>和分割多边形点，转换时只看bndbox即可。

还有一个变体值得注意：部分工具导出的<name>里带前后空格，或者大小写混杂。前面体检脚本里用了.strip()，但没统一大小写。如果实际数据里确实存在person和Person并存的情况，需要在体检阶段就统一成小写或者按classes.txt做大小写敏感匹配，不要指望转换脚本自动修复。

6.3 转换后损失函数异常高的诊断路径

训练启动后box_loss一直居高不下，或者从第一轮就异常高（比如几十），基本可以断定标签有问题。按下面的顺序排查，能快速定位：

第一步，看loss的初始值。正常情况YOLO的box_loss起始在1到2左右，如果一开始就是十几二十，标签坐标大概率有系统性错误。第二步，随机抽几张训练图，用前面回画的脚本画框，重点看框是不是都在左上角一小片区域——如果都在左上角，说明中心点的相对位置没算对，比如把cx写成了xmin。第三步，确认归一化分母是每张图自己的尺寸而不是固定值。第四步，检查txt的行数和图片里实际目标数是否一致，差得多就是过滤太激进或者object节点读取不全。

我遇到过一个特别隐蔽的case：代码里for obj in root.findall("object")写得没问题，但xml里有一条<object>节点的<bndbox>下面多嵌套了一层<bndbox>（标注工具bug导致），find("xmin")返回None，float(None.text)抛异常，被外层except吞掉，结果整张图被当成无目标处理。这种结构异常，光看统计数字发现不了，必须在异常处理里打印出问题文件的路径，我后来所有转换脚本的except分支都强制print路径，宁可日志多一点。

6.4 保持转换脚本可复现的两条纪律

第一，转换脚本进版本管理，和数据集版本号绑定。每次数据集内容变化，脚本和classes.txt一起提交，注释里写清楚这次变了什么——是新增了类别、修正了某些标注、还是调整了过滤阈值。半年后回头复现某个实验，能准确知道当时用的是哪个版本的标签，这对写报告和复现结果极其重要。

第二，转换过程必须留日志。上面脚本里的stat字典只是雏形，正式用的时候把每个异常文件、每条被丢弃的目标都写进一个log文件，格式是"文件名 目标序号 异常类型 原始坐标"。这样即使几个月后发现某个类别效果异常，也能追溯到是不是转换阶段就丢了样本。日志文件通常不大，加起来几十MB，留着不心疼。

标签是检测模型的天花板。再好的网络结构、再精细的超参调优，都建立在标签正确的前提下。xml转txt这活儿的价值不在于脚本写得多漂亮，而在于你对数据本身有多少掌控：知道有几类、每类多少、尺寸怎么分布、哪些异常被处理、处理掉了多少。把这些数字捏在手里，后面训练出任何异常指标，第一反应才不会是怀疑模型，而是先去核对标签。我个人习惯是每次拿到新数据集，花半天时间做体检、转换、回画验证、统计核对，这半天投入通常能省掉后面整整两天的盲目调试。