接手过真实数据项目的朋友应该都有这种感觉数据标注格式真是个老大难。同一个数据集里树形结构的 XML 标注、键值对清晰的 JSON 标注、还有那种一行一个对象的 TXT 标注经常轮着出现。格式不统一的代价就是每次做训练之前都要先花大半天去写转换脚本。这篇是 OpenClaw 超级 AI 实战专栏数据与数据集系列的第八篇我把 XML、JSON、TXT 三种标注格式互转的完整思路和可复现代码整理了出来包括我一开始踩过的坑和最终沉淀下来的实现方案。这套方案已经在我手头的几个项目里反复用过适合标注工具迁移、数据集合并、训练框架格式对齐三类场景。不管你是刚接触标注数据的新手还是已经写过不少脚本的熟手都可以直接拿去对照着改。1. 三种标注格式的来龙去脉与选型逻辑1.1 XML 标注格式老牌数据集的默认结构XML 标注格式的典型长相连没见过的人也能猜出七八分最外层是一个 annotation 根节点下面挂着 filename、size 这类图片元信息object 节点则一层层嵌套出目标的类别名和包围盒坐标。这种树形设计天然适合表达“一张图片包含多个目标每个目标又有若干属性”的层次关系所以很多老牌数据集的默认发布格式就是它。说几个实际用下来的感受。XML 的优点首先是结构严谨有固定的节点层级外部系统可以用 DTD 或 Schema 做校验。其次是信息表达能力强一个目标框除了坐标还能带截断、遮挡、难例标志等附加属性这在某些细分场景下非常有用。但缺点同样明显同样的标注信息用 XML 写出来体积比 JSON 大不少标签名反复出现读起来也累。还有一个不太起眼但很坑的地方XML 允许带命名空间一旦根节点上出现 xmlns 定义解析路径就全变了这个问题我会在后面的坑位清单里具体展开。总而言之XML 很适合归档和跨系统交换但如果你只是想快速把标注喂给训练脚本它并不算最顺手的选择。1.2 JSON 标注格式现代工具链的事实标准JSON 标注格式的长相比 XML 直观得多一个字典对象里放着 filename、width、height 和 objects 列表每个目标是一个包含 label 和 bbox 的子对象。这种结构几乎和编程语言里的“字典”“数组”一一对应Python 里一个 json.load() 就能拿到原生字典JS 里 JSON.parse() 之后也能直接点属性访问。正因为这个原因现在市面上的标注工具、数据管理平台、开源可视化组件半数以上的接口都默认输出或接收 JSON。程序处理、内置到 Web 界面、做数据预览都很方便。文件体积比 XML 小比 TXT 大属于中间档。但 JSON 也不是没有坑它没有明确的字段规范。同样是“边界框”有的工具输出 bbox 是一个四元数组有的输出 box 这样一个对象还有的写 x、y、width、height 这种独立字段同样是类别名有的叫 label有的叫 name有的叫 category。所以处理 JSON 标注时最费劲的往往不是解析本身而是字段映射和类型容错。这一点在后文的解析器实现里会专门处理。1.3 TXT 标注格式给训练管线看的极简表达TXT 标注格式就极简到了骨头里每行一个目标一行的内容是五个数字分别是类别 ID、中心点横坐标、中心点纵坐标、框宽、框高。这里所有坐标都是相对图片宽高的归一化值取值范围在 0 到 1 之间。这种格式的优点非常突出文件极小、读取极快训练数据加载阶段几乎不消耗 IO 资源很多目标检测框架的训练输入格式都长这样。但它的缺点也藏得很深TXT 本身不包含图片尺寸也不包含类别名字。同样是“0.5 0.5 0.2 0.2”它到底代表一个多大的框完全取决于配套的图片宽高第一列的那个 0 到底是猫还是狗取决于训练配置文件里的类别表顺序。所以 TXT 往往不是孤立存在的它必须搭配一个图片目录和一份类别表才能完整解释。这也是它在格式转换中特殊性的根源你没办法仅凭一个 TXT 文件就还原出完整的标注上下文。1.4 选型逻辑不是你喜欢什么而是下游要什么把三种格式放在一起对比看得更清楚格式结构特点优势短板典型使用场景XML树形节点层级严谨、可校验标签冗余、文件偏大老数据集、归档、复杂元信息交换JSON键值 数组读写效率高、通用性好字段名不统一现代标注工具、API、二次开发TXT每行一组数字体积小、加载快依赖外部尺寸和类别表训练数据加载、边缘设备推理我的选型经验很简单别凭喜好选格式去看下游要什么。训练框架的输入接口要求 TXT那就转 TXT数据展示平台要 JSON那就给 JSON老数据集需要保留完整元信息XML 永远是安全的归档格式。所谓互转本质上就是服务于不同链路之间的数据对接。你手里握着什么、目标链路需要什么决定了这一趟转换的方向。2. 互转的整体设计先解析、再序列化2.1 一个直觉方案为什么不可取很多人第一次写格式转换会本能地按照“从哪来到哪去”去命名函数写一个 xml_to_json()再写一个 json_to_txt()然后反过来又需要 txt_to_json()、json_to_xml()……当格式只有两种时这个方案还能凑合。一旦格式变成三种需要维护的转换函数就是 3 × 2 个以后再加一种就变成 4 × 3 个。组合数量随格式种类平方级增长每个函数里都塞着一套独立的字段映射逻辑改一个字段定义要牵连所有相关函数。更糟糕的是这种写法把“解析”和“序列化”两件事耦合在一起代码重复严重排查问题也很痛苦。这个方案的问题不在代码量而在结构上转换逻辑被写死了格式之间并没有一个统一的“交流语言”。2.2 中间表示层把转换组合变成两层函数正确的打开方式是引入一个统一的中间表示层。每个格式只需要写两个函数一个解析器把这种格式读成“标准结构”一个序列化器把“标准结构”写回这种格式。转换的时候永远先解析到标准结构再从标准结构序列化出去。这样一来三种格式互转只需要 3 个解析器加 3 个序列化器共 6 个函数。以后新增一种格式也只需要给新格式写一个解析器和一个序列化器旧代码一行都不用动。在标注场景里我习惯把标准结构定义为下面这副模样annotation { filename: 000001.jpg, width: 1920, height: 1080, depth: 3, objects: [ {label: cat, bbox: [100, 120, 320, 410]}, {label: dog, bbox: [500, 300, 780, 650]} ] }几个关键设计决策解释一下。bbox 统一用绝对像素坐标的 [xmin, ymin, xmax, ymax]而不是中心点加宽高因为后者在裁剪、绘制、做 IoU 计算时都要多一步换算。label 统一用字符串而不是类别 ID因为 ID 的映射关系在不同工程里千差万别字符串可比对、可调试、可排序。filename 默认只存文件名具体路径拼接由下游环节负责避免中间结构里混入一次性的本地路径信息。2.3 为什么坐标体系要统一成绝对像素值XML 和 JSON 格式里坐标通常以绝对像素存在TXT 格式里坐标一律是相对图片宽高的归一化值。中间表示层必须选一个统一的坐标体系那为什么挑绝对像素而不是归一化像素理由是信息完整性。归一化值丢了图片尺寸就寸步难行而绝对像素值即使没有原图也可以被直观理解成“大约在图片的哪个位置”。从绝对像素转换成 TXT 只需要做一次除法从 TXT 转换成绝对像素同样只需要乘一次图片尺寸。绝对值在视觉验证时可以直接对比原图的像素位置归一化值则必须换算回像素才能肉眼判断对错。另一个细节是数值类型。标注坐标在实际数据里绝大多数是整数像素但有些工具会把坐标写成浮点字符串比如 XML 里出现 “123.0”。所以我统一在解析阶段做一轮 to_int 容错把“浮点字符串转整数”这类脏活在入口处就处理干净。中间结构里的 bbox 全是整数序列化出去时也稳定不容易出现“有的字段是 int 有的是 float”的混乱状态。3. 实操环节XML、JSON、TXT 互转的完整代码实现3.1 环境准备和目录约定这篇文章里的全部代码都基于 Python 3.8用到的是标准库 xml.etree.ElementTree、json、os、glob不需要安装第三方依赖。只有批量转换时需要从图片读取尺寸才会用到 Pillow那个场景我会单独标明。我习惯把数据集先收拾成下面这种目录结构再开工data/ images/ 000001.jpg 000002.jpg annotations_xml/ 000001.xml annotations_txt/ classes.txtclasses.txt 是一行一个类别名的纯文本行号从 0 开始恰好对应 TXT 格式里的类别 ID。这份文件是 TXT 转换绕不开的映射表最好和转换脚本放在一起纳入版本管理。3.2 先准备两个公共小函数代码实现的第一步先写两个小工具一个把各种形态的字符串/数字安全转成整数一个读取类别表。import os import json import glob import xml.etree.ElementTree as ET def to_int(value, default0): 把字符串、浮点、None 统一转成整数避免直接 int() 抛异常 if value is None: return default try: return int(float(value)) except (ValueError, TypeError): return default def load_classes(classes_path): 读取类别表一行一个类别名行号即类别 ID with open(classes_path, r, encodingutf-8) as f: return [line.strip() for line in f if line.strip()]to_int 里的 int(float(value)) 是关键。很多 XML 里的坐标值是 “123.0” 这种带小数点的字符串直接用 int(123.0) 会直接抛异常先转一次 float 再转 int 就完全稳了。3.3 XML 解析器实现XML 解析器用标准库 ElementTree 就够了。注意这里刻意选择了 findtext 而不是先 find 再取 .text因为 findtext 在节点缺失时返回 None而 find 之后再取 .text 会抛 AttributeError出错排查成本完全不同。def parse_xml(xml_path): tree ET.parse(xml_path) root tree.getroot() ann { filename: root.findtext(filename, ).strip(), width: to_int(root.findtext(size/width)), height: to_int(root.findtext(size/height)), depth: to_int(root.findtext(size/depth), 3), objects: [] } for obj_el in root.findall(object): label obj_el.findtext(name, ).strip() bbox_el obj_el.find(bndbox) if bbox_el is None: continue bbox [ to_int(bbox_el.findtext(xmin)), to_int(bbox_el.findtext(ymin)), to_int(bbox_el.findtext(xmax)), to_int(bbox_el.findtext(ymax)) ] if bbox[2] bbox[0] or bbox[3] bbox[1]: continue ann[objects].append({label: label, bbox: bbox}) return ann最后那个“bbox 合法性过滤”是我后加上的。真实数据里偶尔会出现 xmax 小于 xmin、ymax 小于 ymin 的脏标注这种框要么是标注软件 bug要么是人工拖动时手滑了。与其让它在后续环节引发莫名其妙的错误不如在转换入口就清掉。当然如果你希望保留所有原始信息再做过滤也可以把这一步挪到校验环节我倾向于做转换时顺手过滤因为绝大多数训练框架都不接受非法框。3.4 JSON 解析器实现附带字段容错JSON 解析器最需要防的就是字段不一致。我在开头说过了不同工具产出的 JSON 字段名五花八门所以解析函数里刻意做了兼容label 和 name 都认bbox 和 box 都认bbox 可能是数组也可能是字典字典形态可能是中心点加宽高也可能是左上角加宽高。def parse_json(json_path): with open(json_path, r, encodingutf-8-sig) as f: data json.load(f) objects [] for obj in data.get(objects, []): label obj.get(label) or obj.get(name) or bbox obj.get(bbox) or obj.get(box) or [0, 0, 0, 0] if isinstance(bbox, dict): # 兼容 xyxy / xywh / cxcywh 三种常见表达 if xmin in bbox: bbox [ to_int(bbox.get(xmin)), to_int(bbox.get(ymin)), to_int(bbox.get(xmax)), to_int(bbox.get(ymax)) ] else: x to_int(bbox.get(x) or bbox.get(left)) y to_int(bbox.get(y) or bbox.get(top)) w to_int(bbox.get(width)) h to_int(bbox.get(height)) bbox [x, y, x w, y h] else: bbox [to_int(v) for v in bbox] if bbox[2] bbox[0] or bbox[3] bbox[1]: continue objects.append({label: label, bbox: bbox}) return { filename: data.get(filename, os.path.basename(json_path)), width: to_int(data.get(width)), height: to_int(data.get(height)), depth: to_int(data.get(depth), 3), objects: objects, }开头用 utf-8-sig 读取而不是 utf-8是为了兼容 Windows 记事本在文件开头写入的 BOM 标记。标注文件很多是标注人员在 Windows 机器上手工整理的这个问题出现频率远比想象中高。如果有一天你在 Linux 上解析某种 JSON 突然报错先看一眼文件开头是不是多了三个不可见字符八成就是 BOM 的问题。3.5 TXT 解析器实现TXT 解析器的难点在前面反复提过文件本身不含图片尺寸和类别名必须由调用方传进来。所以这个函数的签名是 parse_txt(txt_path, img_width, img_height, class_names)缺一个都没办法正确还原。def parse_txt(txt_path, img_width, img_height, class_names): base os.path.basename(txt_path).rsplit(., 1)[0] ann { filename: base .jpg, width: int(img_width), height: int(img_height), depth: 3, objects: [] } with open(txt_path, r, encodingutf-8-sig) as f: for line in f: line line.strip() if not line: continue parts line.split() if len(parts) 5: continue cls_id to_int(parts[0]) x_center, y_center, box_w, box_h map(float, parts[1:5]) if cls_id 0 or cls_id len(class_names): print(f跳过越界类别 ID {cls_id}: {txt_path}) continue xmin round((x_center - box_w / 2) * img_width) ymin round((y_center - box_h / 2) * img_height) xmax round((x_center box_w / 2) * img_width) ymax round((y_center box_h / 2) * img_height) xmin max(0, min(xmin, img_width)) ymin max(0, min(ymin, img_height)) xmax max(0, min(xmax, img_width)) ymax max(0, min(ymax, img_height)) if xmax xmin or ymax ymin: continue ann[objects].append({ label: class_names[cls_id], bbox: [xmin, ymin, xmax, ymax] }) return ann这里有个细节值得展开归一化坐标乘以图片宽高后可能会因为浮点精度产生 1 像素左右的越界。比如归一化 xmax 明明算出来是 1919.9999四舍五入后变成 1920刚好超出图片宽度。所以我干脆在计算之后统一做一次 clamp把坐标限制在合法区间内。3.6 三个序列化器解析器负责把各种格式“读进来”序列化器则负责把标准结构“写出去”。三个序列化器分别看一下。save_xml 的关键在于子节点的创建顺序。XML 节点不像 dict 那样无序子节点顺序在语义上有影响所以创建子节点时务必按照目标工具能接受的习惯顺序来先 filename再 size最后 object 列表。def save_xml(ann, out_path): root ET.Element(annotation) ET.SubElement(root, filename).text ann[filename] size ET.SubElement(root, size) ET.SubElement(size, width).text str(ann[width]) ET.SubElement(size, height).text str(ann[height]) ET.SubElement(size, depth).text str(ann[depth]) for obj in ann[objects]: obj_el ET.SubElement(root, object) ET.SubElement(obj_el, name).text obj[label] bbox_el ET.SubElement(obj_el, bndbox) xmin, ymin, xmax, ymax obj[bbox] ET.SubElement(bbox_el, xmin).text str(xmin) ET.SubElement(bbox_el, ymin).text str(ymin) ET.SubElement(bbox_el, xmax).text str(xmax) ET.SubElement(bbox_el, ymax).text str(ymax) if hasattr(ET, indent): ET.indent(root, space ) tree ET.ElementTree(root) tree.write(out_path, encodingutf-8, xml_declarationTrue)ET.indent 是 Python 3.9 才加入的功能用来给 XML 子节点加缩进纯属美化不缩进也不影响任何解析器。hasattr 的写法是为了兼容老版本直接忽略缩进也不会有问题。save_json 就简单得多def save_json(ann, out_path): with open(out_path, w, encodingutf-8) as f: json.dump(ann, f, ensure_asciiFalse, indent2)注意两个参数。ensure_asciiFalse 必须写否则中文类别名会被转成 \uXXXX 的转义序列文件能读但人眼无法直接查看内容。indent2 是为了可读性不是性能追求标注文件的数量级一般不大多一些换行字符完全可以接受。save_txt 是序列化器里最容易出错的一个因为需要反向计算归一化坐标def save_txt(ann, out_path, class_names): with open(out_path, w, encodingutf-8) as f: for obj in ann[objects]: label obj[label] if label not in class_names: raise ValueError(f类别 {label} 不在 class_names 中) cls_id class_names.index(label) xmin, ymin, xmax, ymax obj[bbox] img_w max(ann[width], 1) img_h max(ann[height], 1) x_center ((xmin xmax) / 2) / img_w y_center ((ymin ymax) / 2) / img_h box_w (xmax - xmin) / img_w box_h (ymax - ymin) / img_h x_center min(max(x_center, 0.0), 1.0) y_center min(max(y_center, 0.0), 1.0) box_w min(max(box_w, 0.0), 1.0) box_h min(max(box_h, 0.0), 1.0) f.write(f{cls_id} {x_center:.6f} {y_center:.6f} {box_w:.6f} {box_h:.6f}\n)浮点格式用了 :.6f也就是保留 6 位小数。对归一化坐标来说6 位小数已经可以把像素误差压到几乎不可见的级别。如果你做的项目对坐标精度极度敏感比如小目标检测可以改成 :.8f文件体积差别不大但精度会更宽松。3.7 批量转换调度单文件转换函数写好了批量转换就只是套一层外层循环的事。这里我习惯用 glob 精确匹配对应后缀的源文件而不是遍历整个目录这样不容易把图片或者类别表也误当成标注文件处理。def get_image_size(img_path): from PIL import Image with Image.open(img_path) as im: w, h im.size return w, h def convert_dir(src_dir, src_fmt, dst_fmt, out_dir, img_dirNone, classes_pathNone): class_names load_classes(classes_path) if classes_path else [] os.makedirs(out_dir, exist_okTrue) pattern {xml: *.xml, json: *.json, txt: *.txt}[src_fmt] for src_path in sorted(glob.glob(os.path.join(src_dir, pattern))): ann None if src_fmt xml: ann parse_xml(src_path) elif src_fmt json: ann parse_json(src_path) elif src_fmt txt: img_name os.path.splitext(os.path.basename(src_path))[0] .jpg img_path os.path.join(img_dir, img_name) if not os.path.exists(img_path): print(f找不到对应图片: {img_path}) continue w, h get_image_size(img_path) ann parse_txt(src_path, w, h, class_names) if ann is None: continue out_name os.path.splitext(os.path.basename(src_path))[0] . dst_fmt out_path os.path.join(out_dir, out_name) if dst_fmt xml: save_xml(ann, out_path) elif dst_fmt json: save_json(ann, out_path) elif dst_fmt txt: save_txt(ann, out_path, class_names) print(f已转换: {src_path} - {out_path})TXT 转其他格式时get_image_size 用 Pillow 读图片尺寸这是最省心的方案。如果目标环境实在装不了 Pillow也可以退而求其次读图片文件二进制头的宽高字段但维护成本不低我基本不会主动建议这么做。4. 实战踩坑清单转格式时容易忽略的细节4.1 编码问题BOM、GBK、Windows 换行符我接过的标注数据里编码问题的出现频率高到值得单独立项。最常见的是 BOM。Windows 记事本保存文本文件时会默认在文件头加上 UTF-8 BOM即三个不可见字节。如果你用普通 utf-8 编码去读这类文件早期版本的解析器可能会报错更麻烦的是某些解析库读出来的第一个字段名会带着看不见的 \ufeff 前缀导致字段匹配失败、数据被整体跳过。解决办法就是我前面代码里写的读取文本时统一用 encodingutf-8-sig这个编码模式会自动把文件头部的 BOM 剥离掉兼容带不带 BOM 两种情况。第二个常见问题是 GBK 编码的 XML 标注。不用惊讶国内早期标注工具确实产出过大量 GBK 编码的 XML而且根节点声明的编码可能本身就不准确。遇到这种情况建议先做一次编码探测识别成 GBK 后转换成 UTF-8 再进入后续流程。直接硬解析 XML 大概率会在中文标签名上翻车。换行符反而是最小的坑。Windows 的 CRLF 换行在 Python 的文本模式下会被自动转换配合 line.strip() 之后坐标解析基本不会受受影响。4.2 XML 命名空间导致的解析路径失效XML 的命名空间问题是那种“不遇到一次就不会想起来”的坑。有些标注工具导出的 XML 会在根节点带上 xmlns 定义比如 xmlnshttp://some-schema这样一来所有子节点在解析时就不再叫 filename而叫 {http://some-schema}filename。你在代码里写 root.findtext(filename) 返回的永远是 None解析出来的全是空字段标注对象一个都读不出来。排查方法很简单解析之前先把根节点的 tag 打印出来看一眼如果 tag 是类似 {http://...}annotation 这样的带花括号前缀的形式就说明存在默认命名空间。处理方式是写一个函数把花括号里的部分剥掉或者把命名空间写死在路径表达式里。剥前缀的方式更通用我通常这么干def strip_ns(tag): return tag.split(}, 1)[1] if tag.startswith({) else tag把 strip_ns 应用在节点 tag 上做判断或者用递归遍历替代固定路径都能绕开命名空间这个坑。我的最终建议是在新接一个标注工具时先用命令行把样例 XML 完整打印出来确认有没有命名空间再决定解析策略。4.3 字段名不统一JSON 解析必须做一层容错JSON 字段不统一的问题我在 1.2 节已经提过这里补充一个真实场景同一份数据标注工具 A 导出的是 objects 列表每项的 bbox 数组后来换到标注工具 B导出的是 annotations 列表每项的 box 是一个 dict键名是 x、y、width、height。表面看都是 JSON实际结构完全对不上。要是没做字段容错接手新工具的数据就得改代码、改字段映射、重新转换来回折腾。我的做法固定成JSON 解析器永远只认一组保守的字段别名label/name 都认bbox/box 都认dict 形态兼容 xyxy 和 xywh。新来一种字段形态就加强 parse_json 里的兼容分支而不是为每一种新工具单独写一个解析函数。这样长期维护下来解析器只会越来越健壮不会越来越臃肿。4.4 类别 ID 与类别映射最容易出错但最容易被忽略TXT 格式的第一列是数字 ID不是类别名。这就带来一个致命问题同一份 TXT 标注不同项目的类别表顺序可能完全不同。A 项目里 0 号是猫B 项目里 0 号可能是狗直接拿 A 项目的 classes.txt 去解析 B 项目的 TXT结果是每一行的类别都错位。这个问题的麻烦在于它不会报错。解析器不会告诉你“这个类别 ID 是对不上的”它只会按你给的类别表翻译成一个“看起来合理”的字符串。等训练结束、评估结果出来才发现整个类别的语义全乱了那时候返工代价就很大了。我的建议是任何涉及 TXT 的转换都要把类别表当成转换参数显式传入并在转换完成后打印一份“类别 ID 与名称对照表”人工核对一眼。classes.txt 应该纳入版本管理任何改动都要有记录否则团队协作时会变成一个暗坑。4.5 边界值和野值处理标注数据里的野值比想象中多。坐标越界、类别 ID 越界、空标签、空标注文件都是高频现象。坐标越界最常见的场景是人工标注时目标贴边标注框超出图片边缘几个像素。这在 XML 或 JSON 里还能保存下来转 TXT 归一化后某些训练框架会忽略超界目标导致模型少学一个样本。我采用的做法是转换时把坐标 clamp 到图片合法区间尽量保留信息而不是直接丢弃。类别 ID 越界在解析 TXT 时是硬伤说明 TXT 文件和类别表根本不是同一套来源直接 print 警告并把该行跳过。空标注文件在 TXT 里就是 0 字节文件某些训练框架遇到空文件会报错需要在转换配置里提前和下游确认是否需要生成一个默认背景框或者直接跳过。4.6 转换后的数据校验回读一次成本很低收益很高格式转换不是写完脚本就完事数据校验才是最后一道闸门。最实用的校验方法是“回读”把转换结果再按目标格式解析一次回到中间结构和转换前解析出的原始中间结构做逐字段对比。def diff_annotations(ann1, ann2, tol1): if ann1[filename] ! ann2[filename]: return False if len(ann1[objects]) ! len(ann2[objects]): return False for o1, o2 in zip(ann1[objects], ann2[objects]): if o1[label] ! o2[label]: return False for a, b in zip(o1[bbox], o2[bbox]): if abs(a - b) tol: return False return True这个函数里的 tolerance 参数很关键。TXT 转 XML 再转回 TXT六位小数的归一化坐标来回换算可能有 1 像素以内的误差完全相等不现实。允许 1 像素的误差就能覆盖浮点精度损失同时不会放过真正的大偏差。批量校验时我对每张图都执行一次“原始格式解析 → 目标格式写出 → 目标格式解析 → diff”任何一张失败就把文件路径和差异打印出来。这套流程虽然多跑一次 IO但对于动辄上万张的标注集它能提前拦截掉九成以上的低级错误值得写入任何正式的转换流程里。5. 场景化扩展从单文件到自动化工作流5.1 做成命令行工具解析、序列化、批量转换的代码都有了最后一步是把它们封装成团队可用的命令行工具。这样组里的同学拿到新数据时不用打开编辑器改 Python 脚本一条命令就能完成转换。import argparse def main(): parser argparse.ArgumentParser(description标注格式转换工具) parser.add_argument(--src_dir, requiredTrue, help源标注目录) parser.add_argument(--src_fmt, requiredTrue, choices[xml, json, txt]) parser.add_argument(--dst_fmt, requiredTrue, choices[xml, json, txt]) parser.add_argument(--out_dir, requiredTrue, help输出目录) parser.add_argument(--img_dir, help图片目录TXT 源格式时必填) parser.add_argument(--classes, help类别表TXT 相关转换时建议提供) args parser.parse_args() convert_dir( src_dirargs.src_dir, src_fmtargs.src_fmt, dst_fmtargs.dst_fmt, out_dirargs.out_dir, img_dirargs.img_dir, classes_pathargs.classes, ) if __name__ __main__: main()用法示例python convert_annotations.py \ --src_dir annotations/xml \ --src_fmt xml \ --dst_fmt txt \ --img_dir data/images \ --classes data/classes.txt \ --out annotations_txt做成命令行工具之后我会顺手加一个 --check 参数转换完成后自动执行回读校验。这一步几乎零成本但能让整个流程的可信度上一个台阶。5.2 和训练框架对接时还要检查什么格式转换成功不等于训练就能跑通对接训练管线时还有几个额外的检查点。第一文件名对应关系。TXT 标注的文件名通常不带后缀或者直接是“图片名.txt”而训练框架配置文件里写的往往是“图片名.jpg”。转换脚本里我已经默认把 TXT 对应的图片名补成 .jpg如果你的图片是 .png 或者其他后缀需要自行调整。第二类别顺序一致性。训练框架的类别配置必须和 classes.txt 保持一致。这句话说了很多遍但在真实项目里它依然是翻车率最高的地方因为类别顺序一旦变化所有 TXT 的 ID 都跟着失效。第三空文件策略。如果一个标注文件里没有任何对象TXT 落地就是 0 字节。有些训练框架对空文件会直接跳过有些会报错。你需要提前确认下游的行为并在转换阶段决定是保留空文件、跳过它还是额外生成一个默认背景框。5.3 再往前一步把转换纳入数据管线格式转换这件事本身不大但它往往是整个数据管线里的第一道工序。我更推荐的做法是把转换脚本嵌进数据处理流程的第一步让所有上游产出的标注统一先落成 JSON 中间格式后续的清洗、抽样、统计、可视化全部基于中间格式操作最后针对特定训练框架再做一次定向导出。这个模式的好处很明显清洗和统计只需要写一套基于标准结构的代码不管上游工具换来换去都只用改第一层解析器训练框架升级、输入格式变化时也只需要调整最后一步的序列化器中间结构完全不用动。我在自己的项目里就是这样实践的一旦这个流程稳定下来后面每次接入新数据集的时间成本会肉眼可见地下降。格式转换听起来像程序员最不起眼的杂活但实际做起来你能从中发现不少数据集质量问题的线索。某个 XML 里出现了 height 为 0 的框某张图在 TXT 里的类别 ID 越界某批 JSON 的文件名后缀写错了这些都是脏数据的早期信号。我现在处理任何数据集第一步永远是先把标注格式收敛成统一的 JSON 中间结构再做统计和清洗最后才考虑投给什么训练框架。这套“解析—中间表示—序列化”的通用结构帮我省下来的时间远比最初写脚本花掉的时间多得多。如果你也在做数据集相关工作强烈建议搭一套自己的转换工具后面一定会用得上。
接手过真实数据项目的朋友应该都有这种感觉数据标注格式真是个老大难。同一个数据集里树形结构的 XML 标注、键值对清晰的 JSON 标注、还有那种一行一个对象的 TXT 标注经常轮着出现。格式不统一的代价就是每次做训练之前都要先花大半天去写转换脚本。这篇是 OpenClaw 超级 AI 实战专栏数据与数据集系列的第八篇我把 XML、JSON、TXT 三种标注格式互转的完整思路和可复现代码整理了出来包括我一开始踩过的坑和最终沉淀下来的实现方案。这套方案已经在我手头的几个项目里反复用过适合标注工具迁移、数据集合并、训练框架格式对齐三类场景。不管你是刚接触标注数据的新手还是已经写过不少脚本的熟手都可以直接拿去对照着改。1. 三种标注格式的来龙去脉与选型逻辑1.1 XML 标注格式老牌数据集的默认结构XML 标注格式的典型长相连没见过的人也能猜出七八分最外层是一个 annotation 根节点下面挂着 filename、size 这类图片元信息object 节点则一层层嵌套出目标的类别名和包围盒坐标。这种树形设计天然适合表达“一张图片包含多个目标每个目标又有若干属性”的层次关系所以很多老牌数据集的默认发布格式就是它。说几个实际用下来的感受。XML 的优点首先是结构严谨有固定的节点层级外部系统可以用 DTD 或 Schema 做校验。其次是信息表达能力强一个目标框除了坐标还能带截断、遮挡、难例标志等附加属性这在某些细分场景下非常有用。但缺点同样明显同样的标注信息用 XML 写出来体积比 JSON 大不少标签名反复出现读起来也累。还有一个不太起眼但很坑的地方XML 允许带命名空间一旦根节点上出现 xmlns 定义解析路径就全变了这个问题我会在后面的坑位清单里具体展开。总而言之XML 很适合归档和跨系统交换但如果你只是想快速把标注喂给训练脚本它并不算最顺手的选择。1.2 JSON 标注格式现代工具链的事实标准JSON 标注格式的长相比 XML 直观得多一个字典对象里放着 filename、width、height 和 objects 列表每个目标是一个包含 label 和 bbox 的子对象。这种结构几乎和编程语言里的“字典”“数组”一一对应Python 里一个 json.load() 就能拿到原生字典JS 里 JSON.parse() 之后也能直接点属性访问。正因为这个原因现在市面上的标注工具、数据管理平台、开源可视化组件半数以上的接口都默认输出或接收 JSON。程序处理、内置到 Web 界面、做数据预览都很方便。文件体积比 XML 小比 TXT 大属于中间档。但 JSON 也不是没有坑它没有明确的字段规范。同样是“边界框”有的工具输出 bbox 是一个四元数组有的输出 box 这样一个对象还有的写 x、y、width、height 这种独立字段同样是类别名有的叫 label有的叫 name有的叫 category。所以处理 JSON 标注时最费劲的往往不是解析本身而是字段映射和类型容错。这一点在后文的解析器实现里会专门处理。1.3 TXT 标注格式给训练管线看的极简表达TXT 标注格式就极简到了骨头里每行一个目标一行的内容是五个数字分别是类别 ID、中心点横坐标、中心点纵坐标、框宽、框高。这里所有坐标都是相对图片宽高的归一化值取值范围在 0 到 1 之间。这种格式的优点非常突出文件极小、读取极快训练数据加载阶段几乎不消耗 IO 资源很多目标检测框架的训练输入格式都长这样。但它的缺点也藏得很深TXT 本身不包含图片尺寸也不包含类别名字。同样是“0.5 0.5 0.2 0.2”它到底代表一个多大的框完全取决于配套的图片宽高第一列的那个 0 到底是猫还是狗取决于训练配置文件里的类别表顺序。所以 TXT 往往不是孤立存在的它必须搭配一个图片目录和一份类别表才能完整解释。这也是它在格式转换中特殊性的根源你没办法仅凭一个 TXT 文件就还原出完整的标注上下文。1.4 选型逻辑不是你喜欢什么而是下游要什么把三种格式放在一起对比看得更清楚格式结构特点优势短板典型使用场景XML树形节点层级严谨、可校验标签冗余、文件偏大老数据集、归档、复杂元信息交换JSON键值 数组读写效率高、通用性好字段名不统一现代标注工具、API、二次开发TXT每行一组数字体积小、加载快依赖外部尺寸和类别表训练数据加载、边缘设备推理我的选型经验很简单别凭喜好选格式去看下游要什么。训练框架的输入接口要求 TXT那就转 TXT数据展示平台要 JSON那就给 JSON老数据集需要保留完整元信息XML 永远是安全的归档格式。所谓互转本质上就是服务于不同链路之间的数据对接。你手里握着什么、目标链路需要什么决定了这一趟转换的方向。2. 互转的整体设计先解析、再序列化2.1 一个直觉方案为什么不可取很多人第一次写格式转换会本能地按照“从哪来到哪去”去命名函数写一个 xml_to_json()再写一个 json_to_txt()然后反过来又需要 txt_to_json()、json_to_xml()……当格式只有两种时这个方案还能凑合。一旦格式变成三种需要维护的转换函数就是 3 × 2 个以后再加一种就变成 4 × 3 个。组合数量随格式种类平方级增长每个函数里都塞着一套独立的字段映射逻辑改一个字段定义要牵连所有相关函数。更糟糕的是这种写法把“解析”和“序列化”两件事耦合在一起代码重复严重排查问题也很痛苦。这个方案的问题不在代码量而在结构上转换逻辑被写死了格式之间并没有一个统一的“交流语言”。2.2 中间表示层把转换组合变成两层函数正确的打开方式是引入一个统一的中间表示层。每个格式只需要写两个函数一个解析器把这种格式读成“标准结构”一个序列化器把“标准结构”写回这种格式。转换的时候永远先解析到标准结构再从标准结构序列化出去。这样一来三种格式互转只需要 3 个解析器加 3 个序列化器共 6 个函数。以后新增一种格式也只需要给新格式写一个解析器和一个序列化器旧代码一行都不用动。在标注场景里我习惯把标准结构定义为下面这副模样annotation { filename: 000001.jpg, width: 1920, height: 1080, depth: 3, objects: [ {label: cat, bbox: [100, 120, 320, 410]}, {label: dog, bbox: [500, 300, 780, 650]} ] }几个关键设计决策解释一下。bbox 统一用绝对像素坐标的 [xmin, ymin, xmax, ymax]而不是中心点加宽高因为后者在裁剪、绘制、做 IoU 计算时都要多一步换算。label 统一用字符串而不是类别 ID因为 ID 的映射关系在不同工程里千差万别字符串可比对、可调试、可排序。filename 默认只存文件名具体路径拼接由下游环节负责避免中间结构里混入一次性的本地路径信息。2.3 为什么坐标体系要统一成绝对像素值XML 和 JSON 格式里坐标通常以绝对像素存在TXT 格式里坐标一律是相对图片宽高的归一化值。中间表示层必须选一个统一的坐标体系那为什么挑绝对像素而不是归一化像素理由是信息完整性。归一化值丢了图片尺寸就寸步难行而绝对像素值即使没有原图也可以被直观理解成“大约在图片的哪个位置”。从绝对像素转换成 TXT 只需要做一次除法从 TXT 转换成绝对像素同样只需要乘一次图片尺寸。绝对值在视觉验证时可以直接对比原图的像素位置归一化值则必须换算回像素才能肉眼判断对错。另一个细节是数值类型。标注坐标在实际数据里绝大多数是整数像素但有些工具会把坐标写成浮点字符串比如 XML 里出现 “123.0”。所以我统一在解析阶段做一轮 to_int 容错把“浮点字符串转整数”这类脏活在入口处就处理干净。中间结构里的 bbox 全是整数序列化出去时也稳定不容易出现“有的字段是 int 有的是 float”的混乱状态。3. 实操环节XML、JSON、TXT 互转的完整代码实现3.1 环境准备和目录约定这篇文章里的全部代码都基于 Python 3.8用到的是标准库 xml.etree.ElementTree、json、os、glob不需要安装第三方依赖。只有批量转换时需要从图片读取尺寸才会用到 Pillow那个场景我会单独标明。我习惯把数据集先收拾成下面这种目录结构再开工data/ images/ 000001.jpg 000002.jpg annotations_xml/ 000001.xml annotations_txt/ classes.txtclasses.txt 是一行一个类别名的纯文本行号从 0 开始恰好对应 TXT 格式里的类别 ID。这份文件是 TXT 转换绕不开的映射表最好和转换脚本放在一起纳入版本管理。3.2 先准备两个公共小函数代码实现的第一步先写两个小工具一个把各种形态的字符串/数字安全转成整数一个读取类别表。import os import json import glob import xml.etree.ElementTree as ET def to_int(value, default0): 把字符串、浮点、None 统一转成整数避免直接 int() 抛异常 if value is None: return default try: return int(float(value)) except (ValueError, TypeError): return default def load_classes(classes_path): 读取类别表一行一个类别名行号即类别 ID with open(classes_path, r, encodingutf-8) as f: return [line.strip() for line in f if line.strip()]to_int 里的 int(float(value)) 是关键。很多 XML 里的坐标值是 “123.0” 这种带小数点的字符串直接用 int(123.0) 会直接抛异常先转一次 float 再转 int 就完全稳了。3.3 XML 解析器实现XML 解析器用标准库 ElementTree 就够了。注意这里刻意选择了 findtext 而不是先 find 再取 .text因为 findtext 在节点缺失时返回 None而 find 之后再取 .text 会抛 AttributeError出错排查成本完全不同。def parse_xml(xml_path): tree ET.parse(xml_path) root tree.getroot() ann { filename: root.findtext(filename, ).strip(), width: to_int(root.findtext(size/width)), height: to_int(root.findtext(size/height)), depth: to_int(root.findtext(size/depth), 3), objects: [] } for obj_el in root.findall(object): label obj_el.findtext(name, ).strip() bbox_el obj_el.find(bndbox) if bbox_el is None: continue bbox [ to_int(bbox_el.findtext(xmin)), to_int(bbox_el.findtext(ymin)), to_int(bbox_el.findtext(xmax)), to_int(bbox_el.findtext(ymax)) ] if bbox[2] bbox[0] or bbox[3] bbox[1]: continue ann[objects].append({label: label, bbox: bbox}) return ann最后那个“bbox 合法性过滤”是我后加上的。真实数据里偶尔会出现 xmax 小于 xmin、ymax 小于 ymin 的脏标注这种框要么是标注软件 bug要么是人工拖动时手滑了。与其让它在后续环节引发莫名其妙的错误不如在转换入口就清掉。当然如果你希望保留所有原始信息再做过滤也可以把这一步挪到校验环节我倾向于做转换时顺手过滤因为绝大多数训练框架都不接受非法框。3.4 JSON 解析器实现附带字段容错JSON 解析器最需要防的就是字段不一致。我在开头说过了不同工具产出的 JSON 字段名五花八门所以解析函数里刻意做了兼容label 和 name 都认bbox 和 box 都认bbox 可能是数组也可能是字典字典形态可能是中心点加宽高也可能是左上角加宽高。def parse_json(json_path): with open(json_path, r, encodingutf-8-sig) as f: data json.load(f) objects [] for obj in data.get(objects, []): label obj.get(label) or obj.get(name) or bbox obj.get(bbox) or obj.get(box) or [0, 0, 0, 0] if isinstance(bbox, dict): # 兼容 xyxy / xywh / cxcywh 三种常见表达 if xmin in bbox: bbox [ to_int(bbox.get(xmin)), to_int(bbox.get(ymin)), to_int(bbox.get(xmax)), to_int(bbox.get(ymax)) ] else: x to_int(bbox.get(x) or bbox.get(left)) y to_int(bbox.get(y) or bbox.get(top)) w to_int(bbox.get(width)) h to_int(bbox.get(height)) bbox [x, y, x w, y h] else: bbox [to_int(v) for v in bbox] if bbox[2] bbox[0] or bbox[3] bbox[1]: continue objects.append({label: label, bbox: bbox}) return { filename: data.get(filename, os.path.basename(json_path)), width: to_int(data.get(width)), height: to_int(data.get(height)), depth: to_int(data.get(depth), 3), objects: objects, }开头用 utf-8-sig 读取而不是 utf-8是为了兼容 Windows 记事本在文件开头写入的 BOM 标记。标注文件很多是标注人员在 Windows 机器上手工整理的这个问题出现频率远比想象中高。如果有一天你在 Linux 上解析某种 JSON 突然报错先看一眼文件开头是不是多了三个不可见字符八成就是 BOM 的问题。3.5 TXT 解析器实现TXT 解析器的难点在前面反复提过文件本身不含图片尺寸和类别名必须由调用方传进来。所以这个函数的签名是 parse_txt(txt_path, img_width, img_height, class_names)缺一个都没办法正确还原。def parse_txt(txt_path, img_width, img_height, class_names): base os.path.basename(txt_path).rsplit(., 1)[0] ann { filename: base .jpg, width: int(img_width), height: int(img_height), depth: 3, objects: [] } with open(txt_path, r, encodingutf-8-sig) as f: for line in f: line line.strip() if not line: continue parts line.split() if len(parts) 5: continue cls_id to_int(parts[0]) x_center, y_center, box_w, box_h map(float, parts[1:5]) if cls_id 0 or cls_id len(class_names): print(f跳过越界类别 ID {cls_id}: {txt_path}) continue xmin round((x_center - box_w / 2) * img_width) ymin round((y_center - box_h / 2) * img_height) xmax round((x_center box_w / 2) * img_width) ymax round((y_center box_h / 2) * img_height) xmin max(0, min(xmin, img_width)) ymin max(0, min(ymin, img_height)) xmax max(0, min(xmax, img_width)) ymax max(0, min(ymax, img_height)) if xmax xmin or ymax ymin: continue ann[objects].append({ label: class_names[cls_id], bbox: [xmin, ymin, xmax, ymax] }) return ann这里有个细节值得展开归一化坐标乘以图片宽高后可能会因为浮点精度产生 1 像素左右的越界。比如归一化 xmax 明明算出来是 1919.9999四舍五入后变成 1920刚好超出图片宽度。所以我干脆在计算之后统一做一次 clamp把坐标限制在合法区间内。3.6 三个序列化器解析器负责把各种格式“读进来”序列化器则负责把标准结构“写出去”。三个序列化器分别看一下。save_xml 的关键在于子节点的创建顺序。XML 节点不像 dict 那样无序子节点顺序在语义上有影响所以创建子节点时务必按照目标工具能接受的习惯顺序来先 filename再 size最后 object 列表。def save_xml(ann, out_path): root ET.Element(annotation) ET.SubElement(root, filename).text ann[filename] size ET.SubElement(root, size) ET.SubElement(size, width).text str(ann[width]) ET.SubElement(size, height).text str(ann[height]) ET.SubElement(size, depth).text str(ann[depth]) for obj in ann[objects]: obj_el ET.SubElement(root, object) ET.SubElement(obj_el, name).text obj[label] bbox_el ET.SubElement(obj_el, bndbox) xmin, ymin, xmax, ymax obj[bbox] ET.SubElement(bbox_el, xmin).text str(xmin) ET.SubElement(bbox_el, ymin).text str(ymin) ET.SubElement(bbox_el, xmax).text str(xmax) ET.SubElement(bbox_el, ymax).text str(ymax) if hasattr(ET, indent): ET.indent(root, space ) tree ET.ElementTree(root) tree.write(out_path, encodingutf-8, xml_declarationTrue)ET.indent 是 Python 3.9 才加入的功能用来给 XML 子节点加缩进纯属美化不缩进也不影响任何解析器。hasattr 的写法是为了兼容老版本直接忽略缩进也不会有问题。save_json 就简单得多def save_json(ann, out_path): with open(out_path, w, encodingutf-8) as f: json.dump(ann, f, ensure_asciiFalse, indent2)注意两个参数。ensure_asciiFalse 必须写否则中文类别名会被转成 \uXXXX 的转义序列文件能读但人眼无法直接查看内容。indent2 是为了可读性不是性能追求标注文件的数量级一般不大多一些换行字符完全可以接受。save_txt 是序列化器里最容易出错的一个因为需要反向计算归一化坐标def save_txt(ann, out_path, class_names): with open(out_path, w, encodingutf-8) as f: for obj in ann[objects]: label obj[label] if label not in class_names: raise ValueError(f类别 {label} 不在 class_names 中) cls_id class_names.index(label) xmin, ymin, xmax, ymax obj[bbox] img_w max(ann[width], 1) img_h max(ann[height], 1) x_center ((xmin xmax) / 2) / img_w y_center ((ymin ymax) / 2) / img_h box_w (xmax - xmin) / img_w box_h (ymax - ymin) / img_h x_center min(max(x_center, 0.0), 1.0) y_center min(max(y_center, 0.0), 1.0) box_w min(max(box_w, 0.0), 1.0) box_h min(max(box_h, 0.0), 1.0) f.write(f{cls_id} {x_center:.6f} {y_center:.6f} {box_w:.6f} {box_h:.6f}\n)浮点格式用了 :.6f也就是保留 6 位小数。对归一化坐标来说6 位小数已经可以把像素误差压到几乎不可见的级别。如果你做的项目对坐标精度极度敏感比如小目标检测可以改成 :.8f文件体积差别不大但精度会更宽松。3.7 批量转换调度单文件转换函数写好了批量转换就只是套一层外层循环的事。这里我习惯用 glob 精确匹配对应后缀的源文件而不是遍历整个目录这样不容易把图片或者类别表也误当成标注文件处理。def get_image_size(img_path): from PIL import Image with Image.open(img_path) as im: w, h im.size return w, h def convert_dir(src_dir, src_fmt, dst_fmt, out_dir, img_dirNone, classes_pathNone): class_names load_classes(classes_path) if classes_path else [] os.makedirs(out_dir, exist_okTrue) pattern {xml: *.xml, json: *.json, txt: *.txt}[src_fmt] for src_path in sorted(glob.glob(os.path.join(src_dir, pattern))): ann None if src_fmt xml: ann parse_xml(src_path) elif src_fmt json: ann parse_json(src_path) elif src_fmt txt: img_name os.path.splitext(os.path.basename(src_path))[0] .jpg img_path os.path.join(img_dir, img_name) if not os.path.exists(img_path): print(f找不到对应图片: {img_path}) continue w, h get_image_size(img_path) ann parse_txt(src_path, w, h, class_names) if ann is None: continue out_name os.path.splitext(os.path.basename(src_path))[0] . dst_fmt out_path os.path.join(out_dir, out_name) if dst_fmt xml: save_xml(ann, out_path) elif dst_fmt json: save_json(ann, out_path) elif dst_fmt txt: save_txt(ann, out_path, class_names) print(f已转换: {src_path} - {out_path})TXT 转其他格式时get_image_size 用 Pillow 读图片尺寸这是最省心的方案。如果目标环境实在装不了 Pillow也可以退而求其次读图片文件二进制头的宽高字段但维护成本不低我基本不会主动建议这么做。4. 实战踩坑清单转格式时容易忽略的细节4.1 编码问题BOM、GBK、Windows 换行符我接过的标注数据里编码问题的出现频率高到值得单独立项。最常见的是 BOM。Windows 记事本保存文本文件时会默认在文件头加上 UTF-8 BOM即三个不可见字节。如果你用普通 utf-8 编码去读这类文件早期版本的解析器可能会报错更麻烦的是某些解析库读出来的第一个字段名会带着看不见的 \ufeff 前缀导致字段匹配失败、数据被整体跳过。解决办法就是我前面代码里写的读取文本时统一用 encodingutf-8-sig这个编码模式会自动把文件头部的 BOM 剥离掉兼容带不带 BOM 两种情况。第二个常见问题是 GBK 编码的 XML 标注。不用惊讶国内早期标注工具确实产出过大量 GBK 编码的 XML而且根节点声明的编码可能本身就不准确。遇到这种情况建议先做一次编码探测识别成 GBK 后转换成 UTF-8 再进入后续流程。直接硬解析 XML 大概率会在中文标签名上翻车。换行符反而是最小的坑。Windows 的 CRLF 换行在 Python 的文本模式下会被自动转换配合 line.strip() 之后坐标解析基本不会受受影响。4.2 XML 命名空间导致的解析路径失效XML 的命名空间问题是那种“不遇到一次就不会想起来”的坑。有些标注工具导出的 XML 会在根节点带上 xmlns 定义比如 xmlnshttp://some-schema这样一来所有子节点在解析时就不再叫 filename而叫 {http://some-schema}filename。你在代码里写 root.findtext(filename) 返回的永远是 None解析出来的全是空字段标注对象一个都读不出来。排查方法很简单解析之前先把根节点的 tag 打印出来看一眼如果 tag 是类似 {http://...}annotation 这样的带花括号前缀的形式就说明存在默认命名空间。处理方式是写一个函数把花括号里的部分剥掉或者把命名空间写死在路径表达式里。剥前缀的方式更通用我通常这么干def strip_ns(tag): return tag.split(}, 1)[1] if tag.startswith({) else tag把 strip_ns 应用在节点 tag 上做判断或者用递归遍历替代固定路径都能绕开命名空间这个坑。我的最终建议是在新接一个标注工具时先用命令行把样例 XML 完整打印出来确认有没有命名空间再决定解析策略。4.3 字段名不统一JSON 解析必须做一层容错JSON 字段不统一的问题我在 1.2 节已经提过这里补充一个真实场景同一份数据标注工具 A 导出的是 objects 列表每项的 bbox 数组后来换到标注工具 B导出的是 annotations 列表每项的 box 是一个 dict键名是 x、y、width、height。表面看都是 JSON实际结构完全对不上。要是没做字段容错接手新工具的数据就得改代码、改字段映射、重新转换来回折腾。我的做法固定成JSON 解析器永远只认一组保守的字段别名label/name 都认bbox/box 都认dict 形态兼容 xyxy 和 xywh。新来一种字段形态就加强 parse_json 里的兼容分支而不是为每一种新工具单独写一个解析函数。这样长期维护下来解析器只会越来越健壮不会越来越臃肿。4.4 类别 ID 与类别映射最容易出错但最容易被忽略TXT 格式的第一列是数字 ID不是类别名。这就带来一个致命问题同一份 TXT 标注不同项目的类别表顺序可能完全不同。A 项目里 0 号是猫B 项目里 0 号可能是狗直接拿 A 项目的 classes.txt 去解析 B 项目的 TXT结果是每一行的类别都错位。这个问题的麻烦在于它不会报错。解析器不会告诉你“这个类别 ID 是对不上的”它只会按你给的类别表翻译成一个“看起来合理”的字符串。等训练结束、评估结果出来才发现整个类别的语义全乱了那时候返工代价就很大了。我的建议是任何涉及 TXT 的转换都要把类别表当成转换参数显式传入并在转换完成后打印一份“类别 ID 与名称对照表”人工核对一眼。classes.txt 应该纳入版本管理任何改动都要有记录否则团队协作时会变成一个暗坑。4.5 边界值和野值处理标注数据里的野值比想象中多。坐标越界、类别 ID 越界、空标签、空标注文件都是高频现象。坐标越界最常见的场景是人工标注时目标贴边标注框超出图片边缘几个像素。这在 XML 或 JSON 里还能保存下来转 TXT 归一化后某些训练框架会忽略超界目标导致模型少学一个样本。我采用的做法是转换时把坐标 clamp 到图片合法区间尽量保留信息而不是直接丢弃。类别 ID 越界在解析 TXT 时是硬伤说明 TXT 文件和类别表根本不是同一套来源直接 print 警告并把该行跳过。空标注文件在 TXT 里就是 0 字节文件某些训练框架遇到空文件会报错需要在转换配置里提前和下游确认是否需要生成一个默认背景框或者直接跳过。4.6 转换后的数据校验回读一次成本很低收益很高格式转换不是写完脚本就完事数据校验才是最后一道闸门。最实用的校验方法是“回读”把转换结果再按目标格式解析一次回到中间结构和转换前解析出的原始中间结构做逐字段对比。def diff_annotations(ann1, ann2, tol1): if ann1[filename] ! ann2[filename]: return False if len(ann1[objects]) ! len(ann2[objects]): return False for o1, o2 in zip(ann1[objects], ann2[objects]): if o1[label] ! o2[label]: return False for a, b in zip(o1[bbox], o2[bbox]): if abs(a - b) tol: return False return True这个函数里的 tolerance 参数很关键。TXT 转 XML 再转回 TXT六位小数的归一化坐标来回换算可能有 1 像素以内的误差完全相等不现实。允许 1 像素的误差就能覆盖浮点精度损失同时不会放过真正的大偏差。批量校验时我对每张图都执行一次“原始格式解析 → 目标格式写出 → 目标格式解析 → diff”任何一张失败就把文件路径和差异打印出来。这套流程虽然多跑一次 IO但对于动辄上万张的标注集它能提前拦截掉九成以上的低级错误值得写入任何正式的转换流程里。5. 场景化扩展从单文件到自动化工作流5.1 做成命令行工具解析、序列化、批量转换的代码都有了最后一步是把它们封装成团队可用的命令行工具。这样组里的同学拿到新数据时不用打开编辑器改 Python 脚本一条命令就能完成转换。import argparse def main(): parser argparse.ArgumentParser(description标注格式转换工具) parser.add_argument(--src_dir, requiredTrue, help源标注目录) parser.add_argument(--src_fmt, requiredTrue, choices[xml, json, txt]) parser.add_argument(--dst_fmt, requiredTrue, choices[xml, json, txt]) parser.add_argument(--out_dir, requiredTrue, help输出目录) parser.add_argument(--img_dir, help图片目录TXT 源格式时必填) parser.add_argument(--classes, help类别表TXT 相关转换时建议提供) args parser.parse_args() convert_dir( src_dirargs.src_dir, src_fmtargs.src_fmt, dst_fmtargs.dst_fmt, out_dirargs.out_dir, img_dirargs.img_dir, classes_pathargs.classes, ) if __name__ __main__: main()用法示例python convert_annotations.py \ --src_dir annotations/xml \ --src_fmt xml \ --dst_fmt txt \ --img_dir data/images \ --classes data/classes.txt \ --out annotations_txt做成命令行工具之后我会顺手加一个 --check 参数转换完成后自动执行回读校验。这一步几乎零成本但能让整个流程的可信度上一个台阶。5.2 和训练框架对接时还要检查什么格式转换成功不等于训练就能跑通对接训练管线时还有几个额外的检查点。第一文件名对应关系。TXT 标注的文件名通常不带后缀或者直接是“图片名.txt”而训练框架配置文件里写的往往是“图片名.jpg”。转换脚本里我已经默认把 TXT 对应的图片名补成 .jpg如果你的图片是 .png 或者其他后缀需要自行调整。第二类别顺序一致性。训练框架的类别配置必须和 classes.txt 保持一致。这句话说了很多遍但在真实项目里它依然是翻车率最高的地方因为类别顺序一旦变化所有 TXT 的 ID 都跟着失效。第三空文件策略。如果一个标注文件里没有任何对象TXT 落地就是 0 字节。有些训练框架对空文件会直接跳过有些会报错。你需要提前确认下游的行为并在转换阶段决定是保留空文件、跳过它还是额外生成一个默认背景框。5.3 再往前一步把转换纳入数据管线格式转换这件事本身不大但它往往是整个数据管线里的第一道工序。我更推荐的做法是把转换脚本嵌进数据处理流程的第一步让所有上游产出的标注统一先落成 JSON 中间格式后续的清洗、抽样、统计、可视化全部基于中间格式操作最后针对特定训练框架再做一次定向导出。这个模式的好处很明显清洗和统计只需要写一套基于标准结构的代码不管上游工具换来换去都只用改第一层解析器训练框架升级、输入格式变化时也只需要调整最后一步的序列化器中间结构完全不用动。我在自己的项目里就是这样实践的一旦这个流程稳定下来后面每次接入新数据集的时间成本会肉眼可见地下降。格式转换听起来像程序员最不起眼的杂活但实际做起来你能从中发现不少数据集质量问题的线索。某个 XML 里出现了 height 为 0 的框某张图在 TXT 里的类别 ID 越界某批 JSON 的文件名后缀写错了这些都是脏数据的早期信号。我现在处理任何数据集第一步永远是先把标注格式收敛成统一的 JSON 中间结构再做统计和清洗最后才考虑投给什么训练框架。这套“解析—中间表示—序列化”的通用结构帮我省下来的时间远比最初写脚本花掉的时间多得多。如果你也在做数据集相关工作强烈建议搭一套自己的转换工具后面一定会用得上。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
