企业官网建设流程全解析

1. 为什么格式转换这一步，往往决定整个训练集的生死

做目标检测的同学大概都有过这种体验：模型结构照着论文抄得一字不差，超参数调了三天三夜，loss 曲线却从一开始就趴在 0 附近不动，或者 mAP 死活卡在一个匪夷所思的低值上。折腾到怀疑人生之后回头去看数据，才发现是标签本身出了问题——框的位置全偏了，或者类别 ID 全错位了，又或者某个类别的框大面积越界被裁成了零面积。这一篇要聊的，就是数据准备链条上最不起眼、但最容易被糊弄过去的一环：把 XML 标注文件转成 TXT 标注文件。

说得直白一点，这件事的本质是两套坐标记账体系的换算。一边是按图片像素给出的绝对坐标，告诉你“框的左上角在这个像素、右下角在那个像素”；另一边是归一化之后的相对坐标，告诉你“框的中心点在这张图的百分之几的位置、宽高占全图的百分之几”。两套账本各自自洽，但它们互相不说话，中间必须有一个翻译层。这个翻译层就是本篇要拆解的对象。它听起来只是几行除法，但真跑起来，边界框越界、零宽框、类别表错位、文件名对不上、图片尺寸和标注记录不一致，随便哪一个都能让你的数据集中悄悄混进一批“毒样本”，而且这些毒样本不会报错，它们只会安静地拖低指标。

这篇内容适合谁看？如果你刚开始接触目标检测，手里拿着一批 XML 标注不知道下一步该干什么，那这里有一套可以直接抄的完整脚本和目录组织方式；如果你已经能跑通训练，但总觉得自己的结果比论文差一截，那不妨对照第 5 章和第 6 章，看看自己的转换过程里是不是漏掉了某些本该做的清洗和校验。我把这套流程在自己的几个数据集上反复打磨过，也帮别人排查过不少次“训练不收敛”的现场，十次里有六七次根子上都是标注转换的问题。所以这一步值得认真对待，它不是脏活，它是地基。

2. 把两套格式摊开对照：XML 里到底有什么，TXT 里到底该写什么

2.1 一个典型 XML 文件的完整解剖

先把 XML 拆开看。一份标准的检测标注 XML，根节点叫annotation，下面几个大块：folder、filename、path描述这张图叫什么、放在哪；source记录数据来源；size里面三个子节点width、height、depth分别记图片宽度、高度和通道数；segmented表示是否做了分割；真正干活的是若干个object节点，每一个代表图上的一个目标。

一个object节点内部，name是类别名，字符串；pose大多是Unspecified，基本没信息量；truncated表示目标是否被画面边缘截断；difficult表示这个目标是不是“难以识别”的疑难样本；最后bndbox下面四个子节点xmin、ymin、xmax、ymax给出框的绝对像素坐标。

<annotation> <folder>images</folder> <filename>sample_0001.jpg</filename> <size> <width>1280</width> <height>720</height> <depth>3</depth> </size> <segmented>0</segmented> <object> <name>person</name> <pose>Unspecified</pose> <truncated>0</truncated> <difficult>0</difficult> <bndbox> <xmin>220</xmin> <ymin>150</ymin> <xmax>430</xmax> <ymax>610</ymax> </bndbox> </object> </annotation>

看清楚这个结构之后，你会发现真正对训练有用的信息只有三类：图片尺寸、类别名、框坐标。其他字段的价值在于“过滤”和“事后分析”，而不是直接喂给网络。

2.2 哪些字段必须读，哪些可以丢，哪些必须处理

我把这些字段分成三档处理。第一档是必须读取并参与计算的：width、height、name、xmin、ymin、xmax、ymax，少一个转换就没法做。第二档是可以丢的：folder、path、source、pose、segmented，这些字段对检测训练没有直接贡献，读进来也只是占内存。第三档比较特殊，是“可以不读但最好处理一下”的：truncated和difficult。

difficult这个标记很有意思。在早期的评测协议里，被标为 difficult 的目标在计算召回时是允许被忽略的。如果你打算严格复现那套评测口径，那转换时可以选择跳过这些框，或者单独记录下来，在评估阶段做剔除。但如果你的目的是训练一个能在真实场景里用的模型，我倾向于保留它们——现实场景里本来就有一堆模糊的、遮挡的目标，把它们删掉等于人为地把任务变简单，模型上线之后反而更脆。我的常规做法是：转换时保留，同时把 difficult 的统计数量打印出来，如果比例超过 20%，说明这批数据的标注质量或者采集场景有问题，需要回去复查。

truncated同理，转换阶段不必剔除，但可以统计一下，截断比例特别高的数据集，训练时对边界框回归的容忍度要放宽一些，或者直接开启 mosaic 之类的增强来模拟。

提示：不要把difficult=1的框直接删掉了事。删掉之后统计口径变了，你在论文里的指标就不可比，而且很难回溯到底是模型变差了还是数据变少了。

2.3 TXT 的六列到底怎么摆

TXT 格式极其精简，一行一个目标，五个数值加一个类别，顺序固定：

<类别ID> <x中心> <y中心> <宽> <高>

注意这里说的是“六个字段”其实是口误，标准写法是五列。第一列是整数类别 ID，必须和你在类别表里的顺序严格对应；后面四列是 0 到 1 之间的浮点数，代表归一化之后的中心点坐标和宽高。一行一个框，同一个类别的多个框就写多行。一张图有几个目标就几行，没有目标就是空文件。

这里最容易出问题的就是那个“类别 ID 和类别表严格对应”。TXT 里存的是数字，模型读的时候靠数据集配置文件里的names列表去反查含义。你转换脚本里用的映射是 A 顺序，配置文件里写的是 B 顺序，程序不会报错，它会非常愉快地把所有“人”训练成“车”，然后你看着混淆矩阵怀疑人生。我在第 4 章会把类别表的单一数据源原则单独说一遍，这是我认为整个流程里最该被强制约束的一点。

3. 坐标换算的推导：那几行除法为什么不能想当然

3.1 从两角点到一个中心点的手算过程

公式本身不复杂，但值得老老实实推一遍，因为很多人抄代码抄错了自己都不知道。设图片宽 W、高 H，框的左上角(xmin, ymin)，右下角(xmax, ymax)，单位是像素。

中心点的绝对坐标是两角点的平均值：cx = (xmin + xmax) / 2，cy = (ymin + ymax) / 2。框的绝对宽高是差值：bw = xmax - xmin，bh = ymax - ymin。然后做归一化，除以对应的图幅尺寸：x_center = cx / W，y_center = cy / H，w = bw / W，h = bh / H。

拿上面那个例子算一遍。图是 1280×720，框是 220,150 到 430,610。那么cx = (220+430)/2 = 325，cy = (150+610)/2 = 380，bw = 210，bh = 460。归一化后x_center = 325/1280 ≈ 0.2539，y_center = 380/720 ≈ 0.5278，w = 210/1280 ≈ 0.1641，h = 460/720 ≈ 0.6389。写进 TXT 就是0 0.253906 0.527778 0.164063 0.638889。

我建议你手算一两个样本，然后拿可视化工具画出来对一下。这一步花五分钟，能让你后面省掉几小时。因为如果宽度和高度写反了（把 W 和 H 用串了），在小图上误差不明显，在长宽比极端的图上框会明显变形，那时候你才去查代码就晚了。

3.2 为什么一定要归一化，而不是直接存像素

有人会问，直接存绝对坐标不行吗，反正图片尺寸也记在别处。不行，原因有两个层面。工程层面，归一化之后标签和输入分辨率解耦了。你在训练时把图片 resize 到 640×640 做数据增强，或者用多尺度训练，如果标签是像素坐标，每次尺度变化都得重新换算一遍，一旦哪里漏了就是系统性偏移。归一化坐标天然就是尺度无关的，喂给网络的框永远是对的。

数学层面更关键。做边界框回归时，网络的输出层通常会接一个 sigmoid，把预测值约束到 0 到 1 之间，这是为了让预测和标签处在同一个数值区间里。如果标签是几百上千的像素值，输出层的约束区间和标签区间对不上，loss 会直接炸掉，或者网络永远学不到东西。所以归一化不是为了好看，它是和网络结构绑定的。

3.3 精度、格式化与那个容易被忽略的 1 像素

默认的浮点格式化保留六位小数基本够用，1280 宽的图上，末位误差对应的像素精度远小于 1，可以忽略。我不建议保留太多位，文件体积白白变大，读取解析也慢。

真正值得说一句的是坐标基准问题。有些标注工具画框时角点是从 1 开始数的，也就是xmin=1表示第一列像素；另一些工具是从 0 开始数的。两种约定差了 1 个像素。对 1280 的图来说，1/1280 约等于 0.0008，肉眼完全看不出来，对指标的影响也微乎其微。但如果你的数据集里有大量极小目标，宽高只有十来个像素，1 像素的偏差就是 10% 的量级，那就不能忽视了。我的处理办法是不去纠结这个，而是在转换后抽样几十个框画回原图上看，如果框贴合得很好就算了，如果整体偏移明显，再统一做 ±1 的修正。凭经验说，绝大多数公开数据和主流标注工具产出的都是一致的，真正需要修正的情况很少。

4. 完整脚本落地：从目录结构到一键转换

4.1 先定目录，再写代码

目录结构不定好，代码写到一半就得返工。我习惯用这套布局，和主流的训练框架读取逻辑能对上：

dataset/ ├── images/ │ ├── train/ │ │ ├── sample_0001.jpg │ │ └── sample_0002.jpg │ └── val/ ├── annotations/ # 原始的 XML 全放这里 │ ├── sample_0001.xml │ └── sample_0002.xml └── labels/ ├── train/ │ ├── sample_0001.txt │ └── sample_0002.txt └── val/

关键点是labels目录和images目录结构镜像，同名的 txt 和 jpg 一一对应，只是扩展名不同。这个约定几乎所有主流检测框架都认，你后面换框架不用改数据。原始 XML 单独放一个目录，不要和 labels 混在一起，否则训练时读取目录会读到不该读的东西。

4.2 转换脚本的完整实现

下面这个脚本我用得最多，覆盖了类别过滤、difficult 跳过、越界裁剪、零面积剔除这几个必要处理。

import os import random import shutil import xml.etree.ElementTree as ET from pathlib import Path from collections import Counter # ============ 需要你改的配置 ============ CLASSES = ["person", "car", "dog"] # 顺序即类别ID，务必与 data.yaml 一致 CLASS_TO_ID = {name: i for i, name in enumerate(CLASSES)} XML_DIR = Path("dataset/annotations") IMG_DIR = Path("dataset/images") LABEL_DIR = Path("dataset/labels") SKIP_DIFFICULT = True # 是否跳过 difficult=1 的目标 CLIP_BOX = True # 是否把越界框裁剪回图内 MIN_BOX_SIZE = 1.0 # 宽或高小于该像素值的框直接丢弃 # ======================================== def box_to_yolo(w, h, box): xmin, ymin, xmax, ymax = box cx = (xmin + xmax) / 2.0 cy = (ymin + ymax) / 2.0 bw = xmax - xmin bh = ymax - ymin return cx / w, cy / h, bw / w, bh / h def convert_one(xml_path, txt_path, stats): tree = ET.parse(xml_path) root = tree.getroot() size = root.find("size") if size is None: stats["no_size"] += 1 return False w = float(size.find("width").text) h = float(size.find("height").text") if w <= 0 or h <= 0: stats["bad_size"] += 1 return False lines = [] for obj in root.findall("object"): name_node = obj.find("name") if name_node is None or name_node.text is None: stats["no_name"] += 1 continue name = name_node.text.strip() if name not in CLASS_TO_ID: stats[f"unknown:{name}"] += 1 continue diff = obj.find("difficult") if SKIP_DIFFICULT and diff is not None and diff.text is not None: if int(diff.text.strip()) == 1: stats["difficult_skipped"] += 1 continue bnd = obj.find("bndbox") if bnd is None: stats["no_bndbox"] += 1 continue try: xmin = float(bnd.find("xmin").text) ymin = float(bnd.find("ymin").text) xmax = float(bnd.find("xmax").text) ymax = float(bnd.find("ymax").text) except (AttributeError, TypeError, ValueError): stats["bad_coord"] += 1 continue # 顺序颠倒的框先纠正 if xmin > xmax: xmin, xmax = xmax, xmin if ymin > ymax: ymin, ymax = ymax, ymin # 越界裁剪 if CLIP_BOX: xmin, xmax = max(0.0, xmin), min(w, xmax) ymin, ymax = max(0.0, ymin), min(h, ymax) bw, bh = xmax - xmin, ymax - ymin if bw < MIN_BOX_SIZE or bh < MIN_BOX_SIZE: stats["degenerate_box"] += 1 continue xc, yc, nw, nh = box_to_yolo(w, h, (xmin, ymin, xmax, ymax)) # 二次保护：极少数脏数据裁剪后仍可能略微越界 xc = min(max(xc, 0.0), 1.0) yc = min(max(yc, 0.0), 1.0) nw = min(max(nw, 0.0), 1.0) nh = min(max(nh, 0.0), 1.0) cid = CLASS_TO_ID[name] lines.append(f"{cid} {xc:.6f} {yc:.6f} {nw:.6f} {nh:.6f}") stats["boxes"] += 1 stats[f"cls:{name}"] += 1 txt_path.parent.mkdir(parents=True, exist_ok=True) txt_path.write_text("\n".join(lines), encoding="utf-8") if not lines: stats["empty_label"] += 1 return True

主流程部分负责遍历、划分和汇报：

def main(): stats = Counter() xml_files = sorted(XML_DIR.glob("*.xml")) random.seed(42) random.shuffle(xml_files) n_val = int(len(xml_files) * 0.2) val_set = set(p.name for p in xml_files[:n_val]) for xml_path in xml_files: stem = xml_path.stem split = "val" if f"{stem}.xml" in val_set else "train" txt_path = LABEL_DIR / split / f"{stem}.txt" ok = convert_one(xml_path, txt_path, stats) if ok: stats[f"split:{split}"] += 1 print("=" * 44) for k, v in sorted(stats.items()): print(f"{k:>24}: {v}") print("=" * 44) if __name__ == "__main__": main()

跑完之后会打印一张统计表，里面包含每个类别的框数量、未知类别的名字、各类异常计数。这张表就是你的体检报告，别急着往下走，先看一遍。

4.3 类别表必须只有一个真源头

前面强调过，这里再落一次地。我强烈建议把CLASSES写成一个独立的classes.txt，一行一个类名，然后转换脚本、训练配置、推理脚本全部从这一个文件读。Python 侧读取就一行[l.strip() for l in open("classes.txt") if l.strip()]，配置文件里的names也用生成脚本写出去，而不是手动敲。

为什么这么较真？因为类别顺序错了，模型照样训练、照样收敛、loss 照样下降，你只是训出了一个“标签全错但内部自洽”的模型。这种错误没有任何报错提示，只有在你上线之后发现识别结果牛头不对马嘴时才会暴露。我见过一次最离谱的，两个类别顺序对调，训了两周，最后靠人眼抽查才发现，白烧了两周的卡时。从那以后我所有的项目都强制单一数据源，脚本里绝不允许出现第二份手写的类别列表。

4.4 空标签文件到底要不要留

这是个容易被忽略但影响不小的决策。某张图里没有任何目标，转换后就是一个空的 txt。留还是不留？

留着的话，训练框架会把它当成一张负样本图，告诉模型“这张图里什么都没有”，这对抑制误检是有正面作用的，尤其是你的场景里存在大量“疑似目标但实际没有”的背景图时。但前提是这些背景图是有意采集的。如果是因为漏标、标注未完成导致的空标签，那留着就是灾难，模型会被迫学会“忽略真实目标”。

我的判断标准是：如果空标签的比例在 5% 以内且确认是真实背景，保留；如果超过 10%，先停下来查清楚原因，是采集阶段混进了无关图片，还是标注队列里有没做完的任务。这个统计上面脚本已经帮你算出来了，empty_label那个数字就是。

5. 边界情况处理：真正拉开数据质量差距的地方

5.1 越界与负坐标：裁还是不裁

真实标注数据里，框超出图片边界是常态。标注员在画框的时候手一抖多拖了几十个像素，或者框的目标本身就压在画面边缘，xmin变成负数、xmax超过图宽，这都很常见。如果不处理直接归一化，x_center可能出现负值或者大于 1，某些严格的校验脚本会直接报错，某些宽松的会默默接受，然后训练时框回归的目标值落在 sigmoid 的有效区间之外，梯度异常。

处理方式有两种。一种是裁剪到图内，也就是把负的抬到 0、超出的压到图宽图高，然后重新算。另一种是整框丢弃。我默认用裁剪，因为轻微越界的框本身还是有监督价值的，裁掉之后剩下的大半截框依然贴近真实目标。但如果裁剪后面积缩水超过一半，我就倾向于丢弃了，因为这时候框已经严重偏离了原始标注意图，留着反而是噪声。

脚本里CLIP_BOX那个开关就是干这个的。上线到别的数据集时，先跑一遍看degenerate_box和异常计数的量级，再决定要不要开。

注意：裁剪一定要在“坐标顺序纠正”之后做。如果原始数据里xmin和xmax写反了，你先裁剪会把两个都压到同一个边界上，框直接变零面积，数据就白白丢了。

5.2 零宽零高与退化框：那些看起来像框其实不是框的东西

比起越界，退化框更陰险。xmin == xmax或者ymin == ymax的框，面积为零，转换成 YOLO 格式之后宽高都是 0。这种行写进去不会报错，但训练时算 IoU 会得到 0 或者 NaN，loss 里一旦混进 NaN，整个 batch 的梯度就废了，而且是随机性地、间歇性地废，你会看到 loss 曲线偶尔爆一下然后恢复，极难定位。

MIN_BOX_SIZE这个参数就是拦这个的，我一般设成 1.0，也就是宽或高不足 1 像素的直接扔。设得再大一点比如 3.0 也可以，取决于你的输入分辨率。如果你训练时把图缩到 416 或者 640，原图上 2 个像素的框缩放后连 1 个像素都不到，留着只会干扰训练。

还有一类更隐蔽的退化：宽高数值正常但面积相对全图极小，比如占全图万分之一的框。这类框不会被面积校验拦住，但它们在小分辨率训练下实际上是不可学的。处理办法是在统计阶段把框的相对面积分布打出来，看看长尾有多长，再决定要不要按面积阈值过滤。这一步不是必须的，但在做高精度小目标检测时值得做。

5.3 多类别与大小写：字符串匹配的陷阱

name字段是字符串，字符串就有大小写、空格、全半角的问题。同一个数据集里出现Person、person、person（尾部空格）三种写法，如果只按精确匹配去查字典，后两种会被当成未知类别直接丢掉，而且丢得悄无声息。

我的做法是读取之后先做一次规范化：strip()去首尾空白，然后视情况lower()。如果数据集本身约定就是小写，那就统一转小写；如果存在traffic light这种带空格的类别名，转换小写之后空格保留，那classes.txt里也必须带空格，不能写成下划线。这里没有绝对正确的答案，唯一的原则是转换脚本和类别表使用完全相同的规范化函数。我把这个函数抽出来放在公共模块里，两边 import 同一个，避免手抄出偏差。

脚本里我用了stats[f"unknown:{name}"]这个写法，就是为了把所有未知类别名都记下来。跑完看一眼，如果某个名字出现了几千次，那多半不是脏数据，而是你的类别表漏了它。

5.4 文件名对不上：转换完了才发现图找不到

XML 里的filename字段和实际图片文件名不一致，这种情况在拼接多个来源的数据时特别常见。有的 XML 记的是000001.jpg，实际文件叫000001.JPG；有的 XML 里带着子目录路径，实际文件是平铺的；还有的干脆把filename写错了。

我的策略是不信任 XML 里的 filename，一律用 XML 文件名的主干去匹配图片。也就是sample_0001.xml去找sample_0001.jpg，找不到再试.png、.jpeg、.JPG。这样处理的前提是你的 XML 命名和图片命名本来就是对应的，绝大多数标注工具导出的结果都满足这个前提。

如果确实遇到了对不上的情况，那就得单独写个核对脚本，把图片目录的文件名集合和 XML 主干集合做差集，把两者都缺的部分人工过一遍。这个活儿很枯燥，但做一次能省掉后面无数次“为什么 loss 是 NaN”的排查。

5.5 图片尺寸字段可能骗你

这一条是我踩过最深的坑之一。XML 里的width和height是标注工具读图时记下的，理论上应该和真实图片一致。但如果中间有人做过批量缩放、格式转换、裁剪，XML 没跟着更新，那记录值和真实值就对不上了。而你用它算归一化，所有框会整体性地缩放偏移，而且是按比例偏移——大图偏得多，小图偏得少，看起来不像 bug，像是模型能力不行。

防御手段很简单，转换时顺手用图片库读一下真实尺寸做比对，不一致就打日志。全量读图会慢一点，但一次转换也就几分钟的事，值得。

from PIL import Image def check_size(img_path, xml_w, xml_h): try: with Image.open(img_path) as im: real_w, real_h = im.size except Exception: return None if abs(real_w - xml_w) > 1 or abs(real_h - xml_h) > 1: return (real_w, real_h) return None

把这个函数挂到主循环里，把不一致的记录写进一个size_mismatch.log。如果这个日志很长，别犹豫，以真实图片尺寸为准重算，或者干脆把这批数据退回去重新导出标注。

6. 转换完不等于做完：三层验证把问题挡在训练之前

6.1 第一层：格式回读校验

写完的 TXT 很可能有格式问题，比如多了一列、少了一列、出现了空行、某个值是nan或者空字符串。这些都是训练时才会炸的东西，提前扫一遍最省事。

def verify_label(txt_path): problems = [] text = txt_path.read_text(encoding="utf-8") for i, line in enumerate(text.splitlines(), 1): line = line.strip() if not line: problems.append(f"line {i}: empty line") continue parts = line.split() if len(parts) != 5: problems.append(f"line {i}: {len(parts)} fields") continue try: vals = [float(p) for p in parts] except ValueError: problems.append(f"line {i}: non-numeric") continue cid = int(vals[0]) if cid < 0 or cid >= len(CLASSES): problems.append(f"line {i}: bad class id {cid}") for v in vals[1:]: if v < -1e-6 or v > 1 + 1e-6: problems.append(f"line {i}: out of range {v:.6f}") return problems

这套校验跑一遍，正常数据集应该是零告警。如果有告警，按文件名和行号能直接定位到具体的框。

6.2 第二层：把框画回图上看

数字看着都对，不代表框画得对。抽二三十张图，把 TXT 里的框还原成像素坐标画上去，人眼扫一遍。这一步没有任何技术含量，但它的检出率高得惊人，几乎所有系统性的坐标偏差、宽高对调、类别错位都能被一眼看出来。

import cv2 def draw_yolo(img_path, txt_path, out_path): img = cv2.imread(str(img_path)) h, w = img.shape[:2] if txt_path.exists(): for line in txt_path.read_text().splitlines(): if not line.strip(): continue cid, xc, yc, bw, bh = line.split() cid = int(cid) xc, yc, bw, bh = map(float, (xc, yc, bw, bh)) x1 = int((xc - bw / 2) * w) y1 = int((yc - bh / 2) * h) x2 = int((xc + bw / 2) * w) y2 = int((yc + bh / 2) * h) cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(img, CLASSES[cid], (x1, max(y1 - 5, 12)), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 1) cv2.imwrite(str(out_path), img)

抽样的原则是随机，但要覆盖不同类别、不同目标数量、不同分辨率。别只抽前二十张，因为很多数据集是分类别、分批次导出的，前面几十张可能全是同一批。

6.3 第三层：统计分布对账

最后一层是拿转换前后的统计量对账。转换前统计每个类别的 object 数量，转换后统计每个类别写进去的行数，理论上两者应该完全相等，减去被过滤掉的部分。这个对账能抓到“某几批数据整体丢失”这类问题。

对账表长这样，跑一遍填进去，差值栏必须能逐条解释清楚：

差值解释不了，就说明有逻辑没覆盖到，必须回到脚本里找。我坚持这张表必须写清楚，因为它是唯一能在你不看代码的情况下判断数据是否完整的手段。

7. 常见问题速查与几条不太写进文档的经验

7.1 问题速查表

7.2 几条踩出来的经验

第一条，转换脚本一定加统计输出。我早期写的版本是纯功能性转换，跑完打印个“done”了事。后来发现，转换过程中丢掉的每一个框都是静默的，脚本永远说 done。加上统计之后，只是多写十来行代码，换来的是每次转换完都有一份可审计的报告，出问题能立刻定位到是哪一类异常。

第二条，转换和划分要分开成两件事。我一开始图省事，在一个脚本里既做转换又做随机划分。结果有一次想调整划分比例重跑，发现问题了：划分逻辑一改，所有 txt 的位置都变了，旧的没清干净，新旧的混在一个目录里，训练时读到了两份。后来我把转换和划分彻底拆开，转换只负责生成全量标签到平铺目录，划分是另一个独立步骤，每次划分前先清空目标目录。这个习惯一直保留到现在。

第三条，源数据的备份要留一份。转换是无损的吗？理论上可以做到无损，只要修改逻辑是幂等的、可逆的。但实际中只要你做了裁剪、过滤、类别映射，就已经有损了。所以原始 XML 永远单独存一份，不要被转换脚本覆盖或者删除。我见过有人在转换脚本里顺手把处理过的 XML 删了“保持整洁”，后来发现过滤阈值设错，想回头重来，原始标注已经没了，只能重新标。

第四条，要在小样本上先跑通，再上全量。从全量里捞二三十个 XML，放到一个临时目录里，跑完转换、跑回读校验、跑可视化，三道全过之后再去处理完整数据集。全量跑一次可能要十几分钟，出错重来很浪费时间；小样本验证只要几十秒，能挡掉 90% 的低级错误。

7.3 我个人的一点体会

这套流程做下来，纯转换的核心逻辑其实只占整个代码量的三成，剩下的七成全都是校验、过滤、统计和日志。刚入行的时候我特别不理解这个比例，觉得把除法写对不就完了。做得多了才慢慢明白，数据准备这个环节的特性在于：错误不会当场暴露，它会往下游潜伏，最后以“模型效果不好”这种极其模糊的面目出现在你面前。而模型效果不好的时候，人会本能地先去怀疑网络结构、损失函数、学习率，等把那些全排查一遍，一周就过去了，最后才想起回头看数据。

所以后来我给自己定了个规矩：任何一次数据格式转换，都必须产出三样东西——转换后的标签文件、一份统计报表、一批可视化抽检图。这三样齐全了才算这一步做完。做起来也就多花一两个小时，但它换来的是后面所有实验结论的可信度。毕竟你调参调出来的每一点提升，都是建立在“标签是对的”这个前提之上的，这个前提一旦不牢，上面盖的东西再漂亮也是悬空的。后续如果要继续往下走，比如说处理类别极度不平衡，或者要给不同来源的数据做统一类别映射，那都是在这一步的基础上往上叠，地基不牢，后面每一步都在还债。