1. 为什么做目标检测训练前必须先把COCO数据拆清楚做目标检测或者图像分割训练的人对COCO格式数据集应该都不陌生。标注文件里是一个庞大的JSON图片散落在不同目录训练集的划分直接决定模型的评估结果是否可信。但很多人拿到数据集后的第一反应是手动复制图片、拆JSON一旦图片上千张这么做不仅慢还容易在验证集里混进训练图片导致指标虚高。我自己最初也干过这种“人肉划分”的事结果验证集里有一张训练图没清干净模型精度愣是虚高了两个点上线之后才发现问题返工折腾的代价远比一开始花十分钟写个脚本要高。所以这篇文章就围绕“怎么用Paddle环境配合Python脚本把COCO格式的数据集正确划分为训练集、验证集和测试集”展开同时把Paddle的安装过程一并讲清楚。无论你是正准备用Paddle做检测训练还是只是想把手头数据集规范化都能在这里找到可以直接复用的方案。要特别说明一点这里说的“划分”不是简单用shutil把图片复制到不同文件夹就完事而是要把JSON里所有标注信息——包括图片信息、标注框、类别映射——按图片维度重新拆分生成三个独立的标注文件。因为PaddleDetection在训练时读取的就是标注文件而不是直接指向图片文件夹。不理解这一点后面训练时会吃大亏。1.1 COCO数据集到底长什么样COCO的标注文件是一个标准JSON核心字段包括images所有图片的元信息列表每项包含id、file_name、width、height等。annotations所有标注对象的列表每项包含image_id、category_id、bbox、area等。categories类别列表定义了所有category_id对应的类别名称。info和licenses通常是固定信息对训练没有直接影响但保留它们能让标注文件保持结构完整。这里最关键的一对关系就是annotations里的image_id会指向images里的id。图片和标注是靠这个ID关联起来的而不是靠文件名。所以划分数据集时必须先确定“哪些图片id进训练集、哪些进验证集”然后按image_id筛选标注。我用一个生活化类比来解释images就是班级花名册annotations是每个学生的成绩单成绩单上写着学号学生靠学号关联。COCO划分的意思是把某些学号的学生连同他们的成绩单一起分到A班另外一些分到B班不能只分人不分成绩单不然数据就对不上了。1.2 不划分或者划分不当会有什么后果不少初学者抱着“数据集不大直接全部丢进去训练”的心态省掉划分步骤。短期看确实省事但模型没有独立的验证集和测试集你的调参过程就完全失去了参照物。训练集是用来更新权重的验证集是用于调整超参数和观察过拟合的测试集是最终评估模型泛化能力的。三个集合互相隔离才能客观衡量模型真实水平。如果划分不当存在图片泄露问题——比如验证集里混入了和训练集相同的图片模型在验证集上的表现会虚高。实际部署时换上一批全新图片精度立刻“打回原形”。网上很多“训练时地图0.98、测试时只剩下0.72”的帖子相当一部分原因就是数据划分阶段没有严格隔离。另外不划分还会导致一个问题类别分布完全随机。某些稀有类别的图片可能全落进训练集验证集里一条都看不见。模型训练时可能学到了这个类别但验证阶段因为缺少对应样本你根本不知道模型对这个类别到底学得好不好。所以在划分脚本里最好能按类别做分层采样保证每个子集都持有每个类别的一定比例样本。1.3 训练集、验证集、测试集的比例应该怎么定最常用的比例是8:1:1和7:2:1。如果数据量非常小比如几百张可以放宽到6:2:2或者采用K折交叉验证的思路但日常场景下8:1:1足够大多数任务使用。实际操作中我一般会把测试集单独留出来训练集和验证集在训练过程中还会再切分验证。比如总共10000张图先按比例拆出1000张做测试集剩下的9000张再按8:2切成训练集和验证集。这样做的原因是测试集应该尽量少参与开发过程避免“看到过测试集”对决策产生影响。虽然严格意义上“看过测试集”不等于作弊但如果你反复用测试集调优很容易陷入过拟合测试集的尴尬境况。划分比例还要考虑一个重要约束每一类别的标注样本不能太少。假设有个类别只有30个标注框按8:1:1拆完测试集可能只分到2到3个框评估时这个类别的AP值会剧烈抖动。这种情况下建议先按类别最小编号数做比例调整比如提高整体数据量或者对稀有类别做人工补充后再划分。2. Paddle环境搭建与安装验证进入划分脚本之前先把Paddle环境准备好。严格来说写一个JSON拆分脚本并不强制依赖Paddle但既然要用Paddle做后续的目标检测训练环境迟早要装不如一步到位。装好之后还能用Paddle的算子或者paddle.io.Dataset做数据加载验证顺便排查划分后数据能不能被正常读取。2.1 先确认你的机器适合装哪个版本Paddle目前分CPU版和GPU版。CPU版安装简单依赖少适合前期做数据划分、脚本调试、小规模备份GPU版需要机器有NVIDIA显卡并且要装好CUDA和cuDNN训练时才有意义。判断方法很直接命令行里执行nvidia-smi能显示显卡信息就说明有NVIDIA GPU没有就装CPU版本。这里要提醒一个大坑Paddle的GPU版本和CUDA版本有严格对应关系。比如某个Paddle版本支持CUDA 11.8和12.x你机器上如果装的是CUDA 11.2即使强行安装也可能在运行时报“找不到libcudnn”等错误。先看你当前机器上的CUDA版本nvcc -V再到Paddle官网找到匹配的安装命令。除非你确定要更新驱动否则不要盲目装最新CUDA。2.2 CPU版安装命令与验证如果只是做数据划分CPU版完全够用# 使用Python虚拟环境避免污染全局环境 python -m venv paddle_env source paddle_env/bin/activate # Windows下激活命令不同 # 安装CPU版Paddle pip install paddlepaddle装完之后验证安装import paddle print(paddle.__version__) print(paddle.utils.run_check())如果看到PaddlePaddle is installed successfully的提示CPU环境就绪。整个验证过程通常只需要几十秒如果打印版本号时卡住半天没反应多半是网络源的问题换国内镜像源能解决。2.3 GPU版安装重点检查CUDA版本匹配GPU版的安装命令长这样以CUDA 11.8为例python -m pip install paddlepaddle-gpu2.6.1.post118 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html注意安装包的版本号后缀post118表示匹配CUDA 11.8post120表示CUDA 12.0post121表示CUDA 12.1。装错版本最常见的报错是libcudnn.so.8: cannot open shared object file遇到这个报错不用急着重装Paddle先检查ldd的依赖指向。GPU环境验证时可以加一步设备检查import paddle paddle.device.set_device(gpu:0) print(paddle.device.get_device())能正常输出gpu:0说明GPU可用。至少跑一个简单的矩阵乘法确认计算能真正落到GPU上而不是静默走CPU回退这一步在后续训练时很关键。2.4 安装过程中常见的踩坑记录我踩过的坑基本集中在三个地方。第一个是Python版本。Paddle官方目前对Python 3.12的支持还不完善建议使用3.8到3.11之间的版本。如果系统默认Python是3.12可以再装一个3.10环境。第二个是镜像源的问题。默认PyPI源在部分地区拉取Paddle这种大体积包很慢甚至超时。直接换清华源pip install paddlepaddle -i https://pypi.tuna.tsinghua.edu.cn/simple实测下载速度能提升10倍以上。第三个是环境变量问题。GPU版的Paddle有时候需要显式设置FLAGS_call_stack_level2之类的调试参数但这属于训练调优阶段的事数据划分阶段用不到知道有这回事即可。3. 划分脚本的核心设计思路先拆图片ID再拆标注划分COCO数据的核心逻辑并不复杂但很多人写出来的脚本在边界情况下会出错。我见过最典型的错误就是直接用文件名去筛标注结果两张不同目录下的同名图片互相污染。正确做法是先通过图片ID做集合运算再以ID为主键筛选标注数据。3.1 以图片ID为主键而不是文件名COCO的images列表里每张图都有一个全局唯一的id字段。这个ID可能是从0开始的递增整数也可能来自标注软件内部生成的随机数但无论如何它在整个JSON里是唯一的。划分时要做的是读取全部images列表提取所有图片id。按比例随机切分ID集合得到train_ids、val_ids、test_ids。遍历annotations根据annotation[image_id]是否属于对应的ID集合把标注归入相应子集。重新组装三个JSON文件输出到指定目录。以ID为主键的好处很明显不管图片路径怎么换、文件名怎么改只要JSON里的关联关系不出错划分就不会乱。你甚至可以先把所有图片路径存到另一个映射表里后续路径变更时只改映射表不影响已经划分好的三个JSON。3.2 随机种子让结果可复现训练过程中可能需要多次重新划分数据比如做交叉验证或者对比实验每次划分结果如果完全不一样实验结论就缺少可比性。所以脚本里必须设置随机种子import random random.seed(42)在Python的random模块设置种子之后每次运行的切分结果是一致的。这一点在团队协作时格外重要几个人同时跑同一个脚本如果种子不同每个人拿到的训练集都不一样复现实验结果时就会互相“打架”。如果想提高划分的鲁棒性可以引入分层抽样的思路。最简单的实现方式先统计每个类别在哪些图片中出现过然后保证从每个类别中抽取一定比例的图片进入验证集和测试集而不是对所有图片一视同仁地随机抽。严格的分层抽样需要按category_id对图片加权对于大多数检测任务来说实现一个“每个类别至少N张入验证集”的约束就够用了比纯随机靠谱得多。3.3 划分后的目录结构设计划分脚本输出物建议组织成以下结构dataset/ ├── images/ │ ├── train/ │ ├── val/ │ └── test/ ├── annotations/ │ ├── instances_train.json │ ├── instances_val.json │ └── instances_test.json之所以把images和annotations分开是为了和PaddleDetection的默认数据组织形式对齐。PaddleDetection里的很多配置直接指向类似dataset/annotations/instances_train.json这样的路径你用脚本生成这种结构后几乎不用改配置就能开跑。如果图片文件本身量很大复制图片很耗磁盘空间可以在生成JSON的同时保留原始路径后续用软链接方案代替物理复制。这部分我在后面第4节会展开说。3.4 不复制图片的软链接方案如果源数据集图片总量非常大比如几百GB直接在文件系统里复制三份图片会白白占用存储。更优雅的做法是脚本只负责生成三个JSON然后用os.symlink为图片建软链接os.symlink(src_img_path, dst_img_path)这样磁盘上只有一份图片实体train/val/test目录里只是引用。需要注意的是软链接在Windows上可能需要管理员权限而且如果源路径被移动软链接会失效。如果是跨平台使用更稳妥的办法是保持JSON里的file_name指向原始图片路径压根不复制图片文件。PaddleDetection训练时是读取JSON里的路径去加载图片所以路径只要存在就能正常训练。4. 划分脚本完整实现与实操演示下面给出一个可直接运行的划分脚本核心依赖只有json、os、random、shutil不需要额外安装第三方库。为了保证脚本复用性我把输入输出都用命令行参数控制。4.1 完整脚本代码将以下内容保存为split_coco.pyimport json import os import random import shutil import argparse from collections import defaultdict def load_coco_annotation(json_path): with open(json_path, r, encodingutf-8) as f: return json.load(f) def save_coco_annotation(data, output_path): os.makedirs(os.path.dirname(output_path), exist_okTrue) with open(output_path, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent4) def split_ids(all_ids, train_ratio, val_ratio): random.shuffle(all_ids) total len(all_ids) train_count int(total * train_ratio) val_count int(total * val_ratio) train_ids set(all_ids[:train_count]) val_ids set(all_ids[train_count:train_count val_count]) test_ids set(all_ids[train_count val_count:]) return train_ids, val_ids, test_ids def build_subset(images, annotations, categories, id_set, info, licenses): image_id_set id_set new_images [img for img in images if img[id] in image_id_set] new_annotations [ann for ann in annotations if ann[image_id] in image_id_set] new_categories categories # 类别映射保持不变 return { info: info, licenses: licenses, images: new_images, annotations: new_annotations, categories: new_categories, } def main(): parser argparse.ArgumentParser(descriptionSplit COCO dataset) parser.add_argument(--annotation_path, typestr, requiredTrue, helppath to the COCO annotation json file) parser.add_argument(--output_dir, typestr, default./coco_split, helpoutput directory) parser.add_argument(--train_ratio, typefloat, default0.8, helpratio for train set) parser.add_argument(--val_ratio, typefloat, default0.1, helpratio for validation set) parser.add_argument(--seed, typeint, default42, helprandom seed) parser.add_argument(--copy_images, actionstore_true, helpif set, copy images to split directories) parser.add_argument(--image_root, typestr, default, helproot directory of images) args parser.parse_args() random.seed(args.seed) print(fLoading annotation: {args.annotation_path}) coco_data load_coco_annotation(args.annotation_path) images coco_data[images] annotations coco_data[annotations] categories coco_data[categories] info coco_data.get(info, {}) licenses coco_data.get(licenses, []) all_image_ids [img[id] for img in images] print(fTotal images: {len(all_image_ids)}) train_ids, val_ids, test_ids split_ids( all_image_ids[:], args.train_ratio, args.val_ratio ) print(fTrain: {len(train_ids)}, Val: {len(val_ids)}, Test: {len(test_ids)}) subsets { train: build_subset(images, annotations, categories, train_ids, info, licenses), val: build_subset(images, annotations, categories, val_ids, info, licenses), test: build_subset(images, annotations, categories, test_ids, info, licenses), } for subset_name, subset_data in subsets.items(): out_path os.path.join(args.output_dir, annotations, finstances_{subset_name}.json) save_coco_annotation(subset_data, out_path) print(fSaved {subset_name}: {len(subset_data[images])} images, f{len(subset_data[annotations])} annotations) if args.copy_images: if not args.image_root: print(Warning: --copy_images set but --image_root is empty, skip copy) else: subset_dirs [train, val, test] for subset_name in subset_dirs: id_set {train: train_ids, val: val_ids, test: test_ids}[subset_name] dst_root os.path.join(args.output_dir, images, subset_name) os.makedirs(dst_root, exist_okTrue) for img in images: if img[id] in id_set: src os.path.join(args.image_root, img[file_name]) dst os.path.join(dst_root, os.path.basename(img[file_name])) shutil.copy2(src, dst) print(Images copied to split directories) if __name__ __main__: main()4.2 关键代码段的讲解先说split_ids函数。这里用了集合运算来取三个ID集合顺序是打乱全部ID后前train_count个进训练集接着val_count个进验证集剩下的全部进测试集。注意我每次用了all_image_ids[:]和random.shuffle()这是为了避免修改原列表影响后面可能的调试。如果你希望验证集和测试集严格按类别分布可以在洗牌前先按类别分组每组内抽样再合并这属于进阶优化脚本基础版先保证随机性即可。build_subset里保留了完整的categories字段这里特别强调一下。很多人在手工拆标注时容易把categories一起裁掉只保留子集里出现的类别这种做法会让训练时类别ID映射错乱。因为PaddleDetection的配置可能已经写死了类别数量比如你要训练80类COCO预训练模型子集里只出现20个类别训练时类别数对不上会直接报错。保留完整categories才是稳妥的做法。copy_images参数默认关闭这就是我前面说的软链接方案绝大多数场景你只需要三个JSON文件就足够训练了图片放在原地不动。只有当你明确要把子集图片归整到独立目录送去部署或者标注时才需要打开--copy_images。4.3 实际运行效果假设源标注文件位于./datasets/coco/annotations/instances_train2017.json图片在./datasets/coco/train2017执行命令python split_coco.py \ --annotation_path ./datasets/coco/annotations/instances_train2017.json \ --output_dir ./coco_split \ --train_ratio 0.8 \ --val_ratio 0.1 \ --copy_images \ --image_root ./datasets/coco/train2017终端输出类似Loading annotation: ./datasets/coco/annotations/instances_train2017.json Total images: 118287 Train: 94629, Val: 11828, Test: 11830 Saved train: 94629 images, 705123 annotations Saved val: 11828 images, 87582 annotations Saved test: 11830 images, 87451 annotations Images copied to split directories检查输出目录会发现annotations下有三个独立的JSON文件images下有对应的训练、验证、测试图片。每个JSON文件都能用官方COCO工具加载并可视化标注没有报错就说明划分成功。5. 划分结果校验确保三个子集都能被正常加载脚本跑完不代表任务结束我强烈建议做一轮校验。这一步能拦住大部分低级错误——比如图片文件和标注文件路径不一致、某张图在JSON里但实际文件不存在、类别字段为空等问题等到训练开始才暴露的话排查起来费时费力。5.1 图片与标注数量一致性检查写一个简单的统计脚本来检查import json for subset in [train, val, test]: with open(f./coco_split/annotations/instances_{subset}.json, r) as f: data json.load(f) image_ids [img[id] for img in data[images]] ann_image_ids [ann[image_id] for ann in data[annotations]] orphan_anns [ann_id for ann_id in ann_image_ids if ann_id not in set(image_ids)] print(f{subset}: images {len(image_ids)}, annotations {len(ann_image_ids)}) if orphan_anns: print(f WARNING: {len(orphan_anns)} annotations without image)这里重点检查orphan_anns也就是那些image_id在图片列表中找不到对应项的标注。一旦出现这种情况说明原始标注文件里存在脏数据或者你在划分过程中过滤掉了某张图但漏掉了它的标注。这种问题的结果是训练时某些标注框被丢弃模型学不到这部分信息但因为你没报错很难第一时间注意到。5.2 类别分布是否均衡划分后的数据集还需要检查各类别的样本分布。假设原始数据共80个类别划分后某个类别在训练集里出现1000次、验证集里只有1次、测试集里是0次这就是严重不均衡。这种情况下模型在测试集上对该类别的AP值无法计算评估结果会缺失一项指标。检查方式from collections import Counter with open(./coco_split/annotations/instances_train.json, r) as f: train_data json.load(f) category_counter Counter(ann[category_id] for ann in train_data[annotations]) print(category_counter.most_common(10))如果发现某类别在某个子集里缺失严重就需要回到划分阶段按类别做分层抽样。实操上可以给稀有类别加权重让它们在洗牌时优先进入每个子集而不是随大流被随机抽掉。5.3 用Paddle的Dataset接口做加载验证划分完的数据最终要交给Paddle训练所以最直接的验证方式就是用Paddle Dataset接口试着加载一批数据。虽然PaddleDetection有专门的数据加载模块但手动验证更快from paddle.io import Dataset import json import cv2 class SimpleCOCODataset(Dataset): def __init__(self, ann_file, img_root): with open(ann_file, r) as f: self.data json.load(f) self.img_root img_root self.images self.data[images] self.annotations self.data[annotations] self.ann_map {} for ann in self.annotations: img_id ann[image_id] if img_id not in self.ann_map: self.ann_map[img_id] [] self.ann_map[img_id].append(ann) def __getitem__(self, idx): img_info self.images[idx] img_path os.path.join(self.img_root, img_info[file_name]) img cv2.imread(img_path) anns self.ann_map.get(img_info[id], []) return img, anns def __len__(self): return len(self.images)如果遍历前几张图时发现img是None说明img_root拼接有问题如果没有标注为空可能是标注关联出错。把这些数据喂给后续的PaddleDetection配置之前先跑通这一步能节约不少排错时间。6. 常见问题与避坑指南这一节把我在实操中真正遇到过的问题整理出来都是那种报错信息不明确、在网上搜半天搜不到答案的坑。6.1 问题速查表问题现象可能原因解决方案划分后的JSON加载报KeyError: images原始标注文件不是COCO格式或者字段名不对先检查原始JSON结构如果是从某个标注工具导出的格式需要先转换成标准COCO结构训练时提示找不到图片文件JSON中file_name是相对路径但实际执行路径不对统一用绝对路径拼接或者在配置里显式指定image_root参数验证集指标异常偏高训练集和验证集图片有重合打印两边的图片ID交集如果非空说明随机种子被重置或者划分逻辑有Bug重新用脚本拆分某类别在测试集中数量为0随机划分导致稀有类别被分光改用按类别分层抽样保证每个类别在每个子集都有最低样本数输出的JSON文件大小差异巨大标注按图片ID划分时有的图片包含大量标注有的只有一两条属正常现象但如果差异超过2倍以上建议检查原始标注数据是否存在重复标注GPU版本Paddle安装后import报错CUDA版本不匹配或缺少cuDNN用ldd检查动态库依赖确认libcudnn和libcuda路径是否存在复制图片时磁盘空间不足图片总大小超过剩余磁盘改用软链接方案或者只生成JSON不复制图片修改训练配置中的路径指向6.2 我在实际操作中踩过的坑第一个坑是随机种子只对random.shuffle生效但如果脚本里有多个随机源——比如numpy.random也被用来做数据增强——那么仅设置random.seed是不够的。最好同时设置np.random.seed(seed)避免后续脚本扩展时出现不可复现。第二个坑是JSON文件中file_name的路径分隔符。Windows环境下os.path.join会生成反斜杠而COCO官方惯用正斜杠。虽然PaddleDetection在Windows上也能处理反斜杠但如果你要把JSON交给Linux服务器训练路径格式不统一会导致图片加载失败。建议在划分脚本里统一替换img[file_name] img[file_name].replace(\\, /)第三个坑是软链接方案中使用了相对路径。如果软链接指向的图片路径是相对路径切换工作目录后链接就会失效。还是建议在生成软链接时用绝对路径或者干脆不复制图片、直接让JSON里的路径指向原始图片目录。第四个坑也可能是最隐蔽的原标注文件本身可能就有重复的图片ID。有些标注工具在导出时不会严格检查ID唯一性两个不同图片共用了同一个ID划分时空集合运算没问题但训练时模型把两张图当成同一张图读取效果显然不对。所以我在脚本里加了一步预处理如果发现重复ID就自动用递增整数重新分配避免后续问题。6.3 小数据集的特殊处理方式如果整个数据集只有几百张图直接按8:1:1拆验证集可能只有几十张对模型评估的置信度很低。这种情况下可以考虑一个变通方案只拆训练集和测试集训练时再从训练集内部动态划分验证集。具体做法是训练时用paddle.io.random_split把训练集再按9:1切一次验证集每轮epoch自动变化模型见过更多不同的验证组合评估结果更稳定。但这个方法不适合模型调参因为验证集不停在换超参数对比的参照物不稳定。小数据集上更推荐的还是K折交叉验证虽然训练时间变成K倍但对模型真实水平的评估更靠谱尤其在数据量匮乏的项目里宁可多花训练时间也不能让模型“盲人摸象”。结语与个人建议从Paddle环境的安装到COCO标注文件的清洗拆分再到校验和避坑整套流程下来其实只花半小时左右但能给后续训练省下大量排查时间。我个人做数据准备时最常说的一句话就是数据没准备好之前不要急着碰模型。这句话听起来老生常谈但是每一轮因为数据问题返工的经历都在反复强化这个认知。最后再分享一个小技巧划分脚本生成结果的JSON文件后可以顺手打印一份统计报告包含各类别在三个子集中的数量存成CSV或者直接print出来。这份报告在你调参和写论文、写技术方案时会非常有用因为你能拿出具体数据说明数据集划分的合理性而不是拍脑袋说“我大概分了八成训练、一成验证”。不管是自己复盘还是向团队汇报这份统计记录都是专业度的体现。 
长河君 · 2026/10/23 1:12:46 · 阅读 1.2k Paddle环境下COCO数据集划分实战指南
1. 为什么做目标检测训练前必须先把COCO数据拆清楚做目标检测或者图像分割训练的人对COCO格式数据集应该都不陌生。标注文件里是一个庞大的JSON图片散落在不同目录训练集的划分直接决定模型的评估结果是否可信。但很多人拿到数据集后的第一反应是手动复制图片、拆JSON一旦图片上千张这么做不仅慢还容易在验证集里混进训练图片导致指标虚高。我自己最初也干过这种“人肉划分”的事结果验证集里有一张训练图没清干净模型精度愣是虚高了两个点上线之后才发现问题返工折腾的代价远比一开始花十分钟写个脚本要高。所以这篇文章就围绕“怎么用Paddle环境配合Python脚本把COCO格式的数据集正确划分为训练集、验证集和测试集”展开同时把Paddle的安装过程一并讲清楚。无论你是正准备用Paddle做检测训练还是只是想把手头数据集规范化都能在这里找到可以直接复用的方案。要特别说明一点这里说的“划分”不是简单用shutil把图片复制到不同文件夹就完事而是要把JSON里所有标注信息——包括图片信息、标注框、类别映射——按图片维度重新拆分生成三个独立的标注文件。因为PaddleDetection在训练时读取的就是标注文件而不是直接指向图片文件夹。不理解这一点后面训练时会吃大亏。1.1 COCO数据集到底长什么样COCO的标注文件是一个标准JSON核心字段包括images所有图片的元信息列表每项包含id、file_name、width、height等。annotations所有标注对象的列表每项包含image_id、category_id、bbox、area等。categories类别列表定义了所有category_id对应的类别名称。info和licenses通常是固定信息对训练没有直接影响但保留它们能让标注文件保持结构完整。这里最关键的一对关系就是annotations里的image_id会指向images里的id。图片和标注是靠这个ID关联起来的而不是靠文件名。所以划分数据集时必须先确定“哪些图片id进训练集、哪些进验证集”然后按image_id筛选标注。我用一个生活化类比来解释images就是班级花名册annotations是每个学生的成绩单成绩单上写着学号学生靠学号关联。COCO划分的意思是把某些学号的学生连同他们的成绩单一起分到A班另外一些分到B班不能只分人不分成绩单不然数据就对不上了。1.2 不划分或者划分不当会有什么后果不少初学者抱着“数据集不大直接全部丢进去训练”的心态省掉划分步骤。短期看确实省事但模型没有独立的验证集和测试集你的调参过程就完全失去了参照物。训练集是用来更新权重的验证集是用于调整超参数和观察过拟合的测试集是最终评估模型泛化能力的。三个集合互相隔离才能客观衡量模型真实水平。如果划分不当存在图片泄露问题——比如验证集里混入了和训练集相同的图片模型在验证集上的表现会虚高。实际部署时换上一批全新图片精度立刻“打回原形”。网上很多“训练时地图0.98、测试时只剩下0.72”的帖子相当一部分原因就是数据划分阶段没有严格隔离。另外不划分还会导致一个问题类别分布完全随机。某些稀有类别的图片可能全落进训练集验证集里一条都看不见。模型训练时可能学到了这个类别但验证阶段因为缺少对应样本你根本不知道模型对这个类别到底学得好不好。所以在划分脚本里最好能按类别做分层采样保证每个子集都持有每个类别的一定比例样本。1.3 训练集、验证集、测试集的比例应该怎么定最常用的比例是8:1:1和7:2:1。如果数据量非常小比如几百张可以放宽到6:2:2或者采用K折交叉验证的思路但日常场景下8:1:1足够大多数任务使用。实际操作中我一般会把测试集单独留出来训练集和验证集在训练过程中还会再切分验证。比如总共10000张图先按比例拆出1000张做测试集剩下的9000张再按8:2切成训练集和验证集。这样做的原因是测试集应该尽量少参与开发过程避免“看到过测试集”对决策产生影响。虽然严格意义上“看过测试集”不等于作弊但如果你反复用测试集调优很容易陷入过拟合测试集的尴尬境况。划分比例还要考虑一个重要约束每一类别的标注样本不能太少。假设有个类别只有30个标注框按8:1:1拆完测试集可能只分到2到3个框评估时这个类别的AP值会剧烈抖动。这种情况下建议先按类别最小编号数做比例调整比如提高整体数据量或者对稀有类别做人工补充后再划分。2. Paddle环境搭建与安装验证进入划分脚本之前先把Paddle环境准备好。严格来说写一个JSON拆分脚本并不强制依赖Paddle但既然要用Paddle做后续的目标检测训练环境迟早要装不如一步到位。装好之后还能用Paddle的算子或者paddle.io.Dataset做数据加载验证顺便排查划分后数据能不能被正常读取。2.1 先确认你的机器适合装哪个版本Paddle目前分CPU版和GPU版。CPU版安装简单依赖少适合前期做数据划分、脚本调试、小规模备份GPU版需要机器有NVIDIA显卡并且要装好CUDA和cuDNN训练时才有意义。判断方法很直接命令行里执行nvidia-smi能显示显卡信息就说明有NVIDIA GPU没有就装CPU版本。这里要提醒一个大坑Paddle的GPU版本和CUDA版本有严格对应关系。比如某个Paddle版本支持CUDA 11.8和12.x你机器上如果装的是CUDA 11.2即使强行安装也可能在运行时报“找不到libcudnn”等错误。先看你当前机器上的CUDA版本nvcc -V再到Paddle官网找到匹配的安装命令。除非你确定要更新驱动否则不要盲目装最新CUDA。2.2 CPU版安装命令与验证如果只是做数据划分CPU版完全够用# 使用Python虚拟环境避免污染全局环境 python -m venv paddle_env source paddle_env/bin/activate # Windows下激活命令不同 # 安装CPU版Paddle pip install paddlepaddle装完之后验证安装import paddle print(paddle.__version__) print(paddle.utils.run_check())如果看到PaddlePaddle is installed successfully的提示CPU环境就绪。整个验证过程通常只需要几十秒如果打印版本号时卡住半天没反应多半是网络源的问题换国内镜像源能解决。2.3 GPU版安装重点检查CUDA版本匹配GPU版的安装命令长这样以CUDA 11.8为例python -m pip install paddlepaddle-gpu2.6.1.post118 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html注意安装包的版本号后缀post118表示匹配CUDA 11.8post120表示CUDA 12.0post121表示CUDA 12.1。装错版本最常见的报错是libcudnn.so.8: cannot open shared object file遇到这个报错不用急着重装Paddle先检查ldd的依赖指向。GPU环境验证时可以加一步设备检查import paddle paddle.device.set_device(gpu:0) print(paddle.device.get_device())能正常输出gpu:0说明GPU可用。至少跑一个简单的矩阵乘法确认计算能真正落到GPU上而不是静默走CPU回退这一步在后续训练时很关键。2.4 安装过程中常见的踩坑记录我踩过的坑基本集中在三个地方。第一个是Python版本。Paddle官方目前对Python 3.12的支持还不完善建议使用3.8到3.11之间的版本。如果系统默认Python是3.12可以再装一个3.10环境。第二个是镜像源的问题。默认PyPI源在部分地区拉取Paddle这种大体积包很慢甚至超时。直接换清华源pip install paddlepaddle -i https://pypi.tuna.tsinghua.edu.cn/simple实测下载速度能提升10倍以上。第三个是环境变量问题。GPU版的Paddle有时候需要显式设置FLAGS_call_stack_level2之类的调试参数但这属于训练调优阶段的事数据划分阶段用不到知道有这回事即可。3. 划分脚本的核心设计思路先拆图片ID再拆标注划分COCO数据的核心逻辑并不复杂但很多人写出来的脚本在边界情况下会出错。我见过最典型的错误就是直接用文件名去筛标注结果两张不同目录下的同名图片互相污染。正确做法是先通过图片ID做集合运算再以ID为主键筛选标注数据。3.1 以图片ID为主键而不是文件名COCO的images列表里每张图都有一个全局唯一的id字段。这个ID可能是从0开始的递增整数也可能来自标注软件内部生成的随机数但无论如何它在整个JSON里是唯一的。划分时要做的是读取全部images列表提取所有图片id。按比例随机切分ID集合得到train_ids、val_ids、test_ids。遍历annotations根据annotation[image_id]是否属于对应的ID集合把标注归入相应子集。重新组装三个JSON文件输出到指定目录。以ID为主键的好处很明显不管图片路径怎么换、文件名怎么改只要JSON里的关联关系不出错划分就不会乱。你甚至可以先把所有图片路径存到另一个映射表里后续路径变更时只改映射表不影响已经划分好的三个JSON。3.2 随机种子让结果可复现训练过程中可能需要多次重新划分数据比如做交叉验证或者对比实验每次划分结果如果完全不一样实验结论就缺少可比性。所以脚本里必须设置随机种子import random random.seed(42)在Python的random模块设置种子之后每次运行的切分结果是一致的。这一点在团队协作时格外重要几个人同时跑同一个脚本如果种子不同每个人拿到的训练集都不一样复现实验结果时就会互相“打架”。如果想提高划分的鲁棒性可以引入分层抽样的思路。最简单的实现方式先统计每个类别在哪些图片中出现过然后保证从每个类别中抽取一定比例的图片进入验证集和测试集而不是对所有图片一视同仁地随机抽。严格的分层抽样需要按category_id对图片加权对于大多数检测任务来说实现一个“每个类别至少N张入验证集”的约束就够用了比纯随机靠谱得多。3.3 划分后的目录结构设计划分脚本输出物建议组织成以下结构dataset/ ├── images/ │ ├── train/ │ ├── val/ │ └── test/ ├── annotations/ │ ├── instances_train.json │ ├── instances_val.json │ └── instances_test.json之所以把images和annotations分开是为了和PaddleDetection的默认数据组织形式对齐。PaddleDetection里的很多配置直接指向类似dataset/annotations/instances_train.json这样的路径你用脚本生成这种结构后几乎不用改配置就能开跑。如果图片文件本身量很大复制图片很耗磁盘空间可以在生成JSON的同时保留原始路径后续用软链接方案代替物理复制。这部分我在后面第4节会展开说。3.4 不复制图片的软链接方案如果源数据集图片总量非常大比如几百GB直接在文件系统里复制三份图片会白白占用存储。更优雅的做法是脚本只负责生成三个JSON然后用os.symlink为图片建软链接os.symlink(src_img_path, dst_img_path)这样磁盘上只有一份图片实体train/val/test目录里只是引用。需要注意的是软链接在Windows上可能需要管理员权限而且如果源路径被移动软链接会失效。如果是跨平台使用更稳妥的办法是保持JSON里的file_name指向原始图片路径压根不复制图片文件。PaddleDetection训练时是读取JSON里的路径去加载图片所以路径只要存在就能正常训练。4. 划分脚本完整实现与实操演示下面给出一个可直接运行的划分脚本核心依赖只有json、os、random、shutil不需要额外安装第三方库。为了保证脚本复用性我把输入输出都用命令行参数控制。4.1 完整脚本代码将以下内容保存为split_coco.pyimport json import os import random import shutil import argparse from collections import defaultdict def load_coco_annotation(json_path): with open(json_path, r, encodingutf-8) as f: return json.load(f) def save_coco_annotation(data, output_path): os.makedirs(os.path.dirname(output_path), exist_okTrue) with open(output_path, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent4) def split_ids(all_ids, train_ratio, val_ratio): random.shuffle(all_ids) total len(all_ids) train_count int(total * train_ratio) val_count int(total * val_ratio) train_ids set(all_ids[:train_count]) val_ids set(all_ids[train_count:train_count val_count]) test_ids set(all_ids[train_count val_count:]) return train_ids, val_ids, test_ids def build_subset(images, annotations, categories, id_set, info, licenses): image_id_set id_set new_images [img for img in images if img[id] in image_id_set] new_annotations [ann for ann in annotations if ann[image_id] in image_id_set] new_categories categories # 类别映射保持不变 return { info: info, licenses: licenses, images: new_images, annotations: new_annotations, categories: new_categories, } def main(): parser argparse.ArgumentParser(descriptionSplit COCO dataset) parser.add_argument(--annotation_path, typestr, requiredTrue, helppath to the COCO annotation json file) parser.add_argument(--output_dir, typestr, default./coco_split, helpoutput directory) parser.add_argument(--train_ratio, typefloat, default0.8, helpratio for train set) parser.add_argument(--val_ratio, typefloat, default0.1, helpratio for validation set) parser.add_argument(--seed, typeint, default42, helprandom seed) parser.add_argument(--copy_images, actionstore_true, helpif set, copy images to split directories) parser.add_argument(--image_root, typestr, default, helproot directory of images) args parser.parse_args() random.seed(args.seed) print(fLoading annotation: {args.annotation_path}) coco_data load_coco_annotation(args.annotation_path) images coco_data[images] annotations coco_data[annotations] categories coco_data[categories] info coco_data.get(info, {}) licenses coco_data.get(licenses, []) all_image_ids [img[id] for img in images] print(fTotal images: {len(all_image_ids)}) train_ids, val_ids, test_ids split_ids( all_image_ids[:], args.train_ratio, args.val_ratio ) print(fTrain: {len(train_ids)}, Val: {len(val_ids)}, Test: {len(test_ids)}) subsets { train: build_subset(images, annotations, categories, train_ids, info, licenses), val: build_subset(images, annotations, categories, val_ids, info, licenses), test: build_subset(images, annotations, categories, test_ids, info, licenses), } for subset_name, subset_data in subsets.items(): out_path os.path.join(args.output_dir, annotations, finstances_{subset_name}.json) save_coco_annotation(subset_data, out_path) print(fSaved {subset_name}: {len(subset_data[images])} images, f{len(subset_data[annotations])} annotations) if args.copy_images: if not args.image_root: print(Warning: --copy_images set but --image_root is empty, skip copy) else: subset_dirs [train, val, test] for subset_name in subset_dirs: id_set {train: train_ids, val: val_ids, test: test_ids}[subset_name] dst_root os.path.join(args.output_dir, images, subset_name) os.makedirs(dst_root, exist_okTrue) for img in images: if img[id] in id_set: src os.path.join(args.image_root, img[file_name]) dst os.path.join(dst_root, os.path.basename(img[file_name])) shutil.copy2(src, dst) print(Images copied to split directories) if __name__ __main__: main()4.2 关键代码段的讲解先说split_ids函数。这里用了集合运算来取三个ID集合顺序是打乱全部ID后前train_count个进训练集接着val_count个进验证集剩下的全部进测试集。注意我每次用了all_image_ids[:]和random.shuffle()这是为了避免修改原列表影响后面可能的调试。如果你希望验证集和测试集严格按类别分布可以在洗牌前先按类别分组每组内抽样再合并这属于进阶优化脚本基础版先保证随机性即可。build_subset里保留了完整的categories字段这里特别强调一下。很多人在手工拆标注时容易把categories一起裁掉只保留子集里出现的类别这种做法会让训练时类别ID映射错乱。因为PaddleDetection的配置可能已经写死了类别数量比如你要训练80类COCO预训练模型子集里只出现20个类别训练时类别数对不上会直接报错。保留完整categories才是稳妥的做法。copy_images参数默认关闭这就是我前面说的软链接方案绝大多数场景你只需要三个JSON文件就足够训练了图片放在原地不动。只有当你明确要把子集图片归整到独立目录送去部署或者标注时才需要打开--copy_images。4.3 实际运行效果假设源标注文件位于./datasets/coco/annotations/instances_train2017.json图片在./datasets/coco/train2017执行命令python split_coco.py \ --annotation_path ./datasets/coco/annotations/instances_train2017.json \ --output_dir ./coco_split \ --train_ratio 0.8 \ --val_ratio 0.1 \ --copy_images \ --image_root ./datasets/coco/train2017终端输出类似Loading annotation: ./datasets/coco/annotations/instances_train2017.json Total images: 118287 Train: 94629, Val: 11828, Test: 11830 Saved train: 94629 images, 705123 annotations Saved val: 11828 images, 87582 annotations Saved test: 11830 images, 87451 annotations Images copied to split directories检查输出目录会发现annotations下有三个独立的JSON文件images下有对应的训练、验证、测试图片。每个JSON文件都能用官方COCO工具加载并可视化标注没有报错就说明划分成功。5. 划分结果校验确保三个子集都能被正常加载脚本跑完不代表任务结束我强烈建议做一轮校验。这一步能拦住大部分低级错误——比如图片文件和标注文件路径不一致、某张图在JSON里但实际文件不存在、类别字段为空等问题等到训练开始才暴露的话排查起来费时费力。5.1 图片与标注数量一致性检查写一个简单的统计脚本来检查import json for subset in [train, val, test]: with open(f./coco_split/annotations/instances_{subset}.json, r) as f: data json.load(f) image_ids [img[id] for img in data[images]] ann_image_ids [ann[image_id] for ann in data[annotations]] orphan_anns [ann_id for ann_id in ann_image_ids if ann_id not in set(image_ids)] print(f{subset}: images {len(image_ids)}, annotations {len(ann_image_ids)}) if orphan_anns: print(f WARNING: {len(orphan_anns)} annotations without image)这里重点检查orphan_anns也就是那些image_id在图片列表中找不到对应项的标注。一旦出现这种情况说明原始标注文件里存在脏数据或者你在划分过程中过滤掉了某张图但漏掉了它的标注。这种问题的结果是训练时某些标注框被丢弃模型学不到这部分信息但因为你没报错很难第一时间注意到。5.2 类别分布是否均衡划分后的数据集还需要检查各类别的样本分布。假设原始数据共80个类别划分后某个类别在训练集里出现1000次、验证集里只有1次、测试集里是0次这就是严重不均衡。这种情况下模型在测试集上对该类别的AP值无法计算评估结果会缺失一项指标。检查方式from collections import Counter with open(./coco_split/annotations/instances_train.json, r) as f: train_data json.load(f) category_counter Counter(ann[category_id] for ann in train_data[annotations]) print(category_counter.most_common(10))如果发现某类别在某个子集里缺失严重就需要回到划分阶段按类别做分层抽样。实操上可以给稀有类别加权重让它们在洗牌时优先进入每个子集而不是随大流被随机抽掉。5.3 用Paddle的Dataset接口做加载验证划分完的数据最终要交给Paddle训练所以最直接的验证方式就是用Paddle Dataset接口试着加载一批数据。虽然PaddleDetection有专门的数据加载模块但手动验证更快from paddle.io import Dataset import json import cv2 class SimpleCOCODataset(Dataset): def __init__(self, ann_file, img_root): with open(ann_file, r) as f: self.data json.load(f) self.img_root img_root self.images self.data[images] self.annotations self.data[annotations] self.ann_map {} for ann in self.annotations: img_id ann[image_id] if img_id not in self.ann_map: self.ann_map[img_id] [] self.ann_map[img_id].append(ann) def __getitem__(self, idx): img_info self.images[idx] img_path os.path.join(self.img_root, img_info[file_name]) img cv2.imread(img_path) anns self.ann_map.get(img_info[id], []) return img, anns def __len__(self): return len(self.images)如果遍历前几张图时发现img是None说明img_root拼接有问题如果没有标注为空可能是标注关联出错。把这些数据喂给后续的PaddleDetection配置之前先跑通这一步能节约不少排错时间。6. 常见问题与避坑指南这一节把我在实操中真正遇到过的问题整理出来都是那种报错信息不明确、在网上搜半天搜不到答案的坑。6.1 问题速查表问题现象可能原因解决方案划分后的JSON加载报KeyError: images原始标注文件不是COCO格式或者字段名不对先检查原始JSON结构如果是从某个标注工具导出的格式需要先转换成标准COCO结构训练时提示找不到图片文件JSON中file_name是相对路径但实际执行路径不对统一用绝对路径拼接或者在配置里显式指定image_root参数验证集指标异常偏高训练集和验证集图片有重合打印两边的图片ID交集如果非空说明随机种子被重置或者划分逻辑有Bug重新用脚本拆分某类别在测试集中数量为0随机划分导致稀有类别被分光改用按类别分层抽样保证每个类别在每个子集都有最低样本数输出的JSON文件大小差异巨大标注按图片ID划分时有的图片包含大量标注有的只有一两条属正常现象但如果差异超过2倍以上建议检查原始标注数据是否存在重复标注GPU版本Paddle安装后import报错CUDA版本不匹配或缺少cuDNN用ldd检查动态库依赖确认libcudnn和libcuda路径是否存在复制图片时磁盘空间不足图片总大小超过剩余磁盘改用软链接方案或者只生成JSON不复制图片修改训练配置中的路径指向6.2 我在实际操作中踩过的坑第一个坑是随机种子只对random.shuffle生效但如果脚本里有多个随机源——比如numpy.random也被用来做数据增强——那么仅设置random.seed是不够的。最好同时设置np.random.seed(seed)避免后续脚本扩展时出现不可复现。第二个坑是JSON文件中file_name的路径分隔符。Windows环境下os.path.join会生成反斜杠而COCO官方惯用正斜杠。虽然PaddleDetection在Windows上也能处理反斜杠但如果你要把JSON交给Linux服务器训练路径格式不统一会导致图片加载失败。建议在划分脚本里统一替换img[file_name] img[file_name].replace(\\, /)第三个坑是软链接方案中使用了相对路径。如果软链接指向的图片路径是相对路径切换工作目录后链接就会失效。还是建议在生成软链接时用绝对路径或者干脆不复制图片、直接让JSON里的路径指向原始图片目录。第四个坑也可能是最隐蔽的原标注文件本身可能就有重复的图片ID。有些标注工具在导出时不会严格检查ID唯一性两个不同图片共用了同一个ID划分时空集合运算没问题但训练时模型把两张图当成同一张图读取效果显然不对。所以我在脚本里加了一步预处理如果发现重复ID就自动用递增整数重新分配避免后续问题。6.3 小数据集的特殊处理方式如果整个数据集只有几百张图直接按8:1:1拆验证集可能只有几十张对模型评估的置信度很低。这种情况下可以考虑一个变通方案只拆训练集和测试集训练时再从训练集内部动态划分验证集。具体做法是训练时用paddle.io.random_split把训练集再按9:1切一次验证集每轮epoch自动变化模型见过更多不同的验证组合评估结果更稳定。但这个方法不适合模型调参因为验证集不停在换超参数对比的参照物不稳定。小数据集上更推荐的还是K折交叉验证虽然训练时间变成K倍但对模型真实水平的评估更靠谱尤其在数据量匮乏的项目里宁可多花训练时间也不能让模型“盲人摸象”。结语与个人建议从Paddle环境的安装到COCO标注文件的清洗拆分再到校验和避坑整套流程下来其实只花半小时左右但能给后续训练省下大量排查时间。我个人做数据准备时最常说的一句话就是数据没准备好之前不要急着碰模型。这句话听起来老生常谈但是每一轮因为数据问题返工的经历都在反复强化这个认知。最后再分享一个小技巧划分脚本生成结果的JSON文件后可以顺手打印一份统计报告包含各类别在三个子集中的数量存成CSV或者直接print出来。这份报告在你调参和写论文、写技术方案时会非常有用因为你能拿出具体数据说明数据集划分的合理性而不是拍脑袋说“我大概分了八成训练、一成验证”。不管是自己复盘还是向团队汇报这份统计记录都是专业度的体现。