企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 预训练

PaddleLabel 是飞桨（PaddlePaddle）生态提供的配套数据标注工具，覆盖图像分类、目标检测、语义/实例分割等常见计算机视觉任务的标注与数据集导出。本文聚焦于关联文档所讲解的 PaddleLabel 数据集“通用基础功能”——即几乎所有非 COCO 项目都支持的labels.txt与xx_list.txt两个核心文件的格式规范、导入导出行为与最佳实践，并结合仓库源码与 PaddleSeg 的自定义数据集读取逻辑，帮助读者正确组织数据集、避免导入失败，并能将 PaddleLabel 导出的数据无缝衔接进 PaddleSeg 等下游训练流程。

一、无标注数据集的导入

如果您的数据集不包含任何标注，那么无需准备任何标签文件：只需将所有图像文件放在一个文件夹下，并将该文件夹路径填入创建项目时的“数据集路径”即可。

PaddleLabel 在导入时会遍历数据集文件夹（以及所有子文件夹）中的所有文件，并按照文件扩展名判断文件类型，导入全部图像文件。所有隐藏文件（文件名以.开头的文件，如.DS_Store）将被忽略，不会进入数据集。

这一设计的直接好处是：即使手头只有一批散落的图片、尚未进行任何标注，也可以立即创建项目开始标注；标注完成后再通过“划分数据集”与“导出数据集”功能生成完整的标注数据集（详见后文）。

二、labels.txt：项目标签清单

2.1 基本用法

所有不使用 COCO 格式保存标注的项目（即分类、检测的 PASCAL VOC 格式、语义/实例分割等）都支持labels.txt。PaddleLabel 在导入过程中会在数据集路径下寻找labels.txt文件，您可以在该文件中列出项目的全部标签，每行一个。例如：

# labels.txt Monkey Mouse

• 标签命名约束：PaddleLabel 的标签名称支持任意字符串，但由于标签名称可能被用作导出数据集的文件夹名，应避免使用任何操作系统不支持的字符串（如\ / : * ? " < > |等）。此外，Paddle 生态中的其他工具对标签名可能有进一步限制，例如 PaddleX 的分类任务不支持中文字符作为标签名称，这一点在跨套件使用前需要特别留意。
• 标签编号规则：导入过程中，PaddleLabel 会首先创建labels.txt中指定的标签，因此该文件中标签的编号将从0开始并依次递增。在导出过程中，PaddleLabel 也会生成此文件。

2.2 扩展格式：颜色、编号与注释

在导入时，labels.txt每一行可以包含标签名以外的信息。目前支持 4 种长度格式（其中|表示分隔符，默认为空格）：

其他规则：

• //：//之后的字符串将被视为标签注释，导入时忽略；
• -：如果需要指定标签颜色但不想指定标签编号，可以在标签编号位置写-，由 PaddleLabel 自动分配编号。

综合示例：

dog monkey 4 mouse - #0000ff // mouse's id will be 5 cat 10 yellow zibra 11 blue // some common colors are supported snake 12 255 0 0 // rgb color

上例的含义分别是：

• dog：仅标签名，自动分配编号；
• monkey 4：标签monkey，显式编号 4；
• mouse - #0000ff：标签mouse，自动分配编号（上一条已用 4，故为 5），颜色为十六进制#0000ff（蓝色），//后为注释；
• cat 10 yellow：标签cat，编号 10，颜色使用常用颜色名称yellow；
• zibra 11 blue：标签zibra，编号 11，颜色名称blue；
• snake 12 255 0 0：标签snake，编号 12，颜色以 RGB 三元组255 0 0（红色）表示。

PaddleLabel 支持的颜色名称可以在其后端的 paddlelabel/task/util/color.py（仓库中对应 color.py 的实现）中查到完整列表。

提示：分割任务（尤其是伪彩色掩膜）对标签颜色有强依赖，语义分割项目要求labels.txt中为每个标签指定颜色，且第一个标签固定被视为背景类并赋予编号 0；详见 PaddleLabel 文档数据集文件结构说明中的“语义分割”小节。

三、xx_list.txt：数据集划分与匹配关系

3.1 文件组成与位置

xx_list.txt是train_list.txt、val_list.txt、test_list.txt三个文件的统称，同样由所有不使用 COCO 格式保存标注的项目支持。这三个文件需要放在数据集文件夹的根目录中，与labels.txt同级。

它们承担两个职责：

1. 指定数据集的划分（哪些数据用于训练、验证、测试）；
2. 描述标签/标注文件与图像文件之间的匹配关系（例如在 VOC 格式下，每一行是“图像文件路径 + 标签文件路径”）。

3.2 行内容结构

三个文件的内容结构完全相同：每一行都以一条数据的路径开始，该路径是相对数据集根目录的相对路径，后面跟着表示类别的整数/字符串，或者标签文件的路径。

格式一：图像路径 + 类别（单标签 / 多标签）

# train_list.txt image/9911.jpg 0 3 image/9932.jpg 4 image/9928.jpg Cat

其中image/9911.jpg 0 3表示图像image/9911.jpg同时属于编号 0 和编号 3 两个类别（适用于图像多分类等一条数据多个类别的场景）；image/9928.jpg Cat则直接用标签名字符串Cat表示类别。

格式二：图像路径 + 标签文件路径（VOC 检测 / 分割掩膜等）

# train_list.txt JPEGImages/1.jpeg Annotations/1.xml JPEGImages/2.jpeg Annotations/2.xml JPEGImages/3.jpeg Annotations/3.xml

这一格式常见于 PASCAL VOC 目标检测（图像对应 xml 标注文件）与语义分割（图像对应 png 掩膜）。

3.3 类别解析规则

• 整数类别：如果标签类别为整数，PaddleLabel 将在labels.txt中查找对应标签，标签 id 从0开始。请确保整数与labels.txt中的编号一一对应，否则可能产生错误匹配。
• 数字作为标签名：如果希望直接用数字作为标签名称，可以把数字写进labels.txt，并在xx_list.txt中提供标签 id；或者给数字标签加一个前缀以避免歧义，例如将10表示为n10。
• 划分信息优先：需要特别注意的是，大多数项目只会用到xx_list.txt中的数据集划分信息（例如单分类项目以文件夹名作为类别，此时xx_list.txt中的类别字段将被忽略）。

3.4 导出行为

• 这三个文件都会在导出过程中生成，即使其中某些文件是空的（例如未划分测试集时，test_list.txt仍会生成空文件）。
• 为了确保文件可以被 Paddle 生态系统中的其他工具读取，没有标注的数据不会包含在xx_list.txt中——这一约定保证了下游工具读到的每一行都对应一条有效标注数据。

四、与下游工具衔接：PaddleSeg 如何读取这些文件

PaddleLabel 导出的xx_list.txt与labels.txt之所以采用“相对路径 + 空格分隔”的结构，正是为了与飞桨各套件的自定义数据集接口对齐。以本仓库 PaddleSeg 为例，其自定义数据集类 dataset.py 的读取逻辑与上述规范完全对应：

• 训练/验证/测试阶段分别要求传入train_path/val_path/test_path，即 PaddleLabel 导出的三个xx_list.txt路径；
• 每个文件的每一行按分隔符（默认空格）拆分为两项：image_path与label_path，并分别以dataset_root为基准拼接出绝对路径（dataset.py）；
• 如果一行只有图像路径而没有标签路径（len(items) != 2），在训练/验证模式下会直接抛出格式错误（dataset.py），这也解释了为什么 PaddleLabel 约定“没有标注的数据不会写入xx_list.txt”。

因此，一个从 PaddleLabel 导出、可直接被 PaddleSeg 消费的自定义分割数据集，其标准目录结构为：

dog_seg_dataset ├── Annotations # 标签掩膜（png） ├── JPEGImages # 原始图像 ├── labels.txt # 标签清单（第一行为背景类） ├── train_list.txt # 每行: 图像相对路径 + 标签相对路径 ├── val_list.txt └── test_list.txt

对应的 PaddleSeg 训练配置中，train_dataset与val_dataset的dataset_root指向数据集根目录、train_path/val_path指向相应 list 文件即可（可参考文档从 PaddleLabel 到 PaddleSeg 的训练流程中的完整mynet.yml示例）。更完整的 PaddleSeg 自定义数据集使用说明见 PaddleSeg 数据准备文档。

五、使用注意事项与最佳实践

1. 导入前备份：PaddleLabel 在“导入更多数据”时，会把新的数据文件移动到该项目的数据集文件夹中（目的是避免复制数据集、节省磁盘空间）。虽然 PaddleLabel 不会删除磁盘上的任何内容，但导入操作会改变数据集文件夹的目录结构，建议在导入之前复制数据集作为备份。
2. 留意paddlelabel.warning文件：使用过程中，PaddleLabel 会在数据集根文件夹下创建一个名为paddlelabel.warning的文件，请避免更改数据集文件夹下的任何文件以防出现问题。
3. 同名校验：在语义分割等按文件名配对图像与标签的场景中，PaddleLabel 会去掉所有文件扩展名进行匹配，因此应避免出现多张图像对应同一个标签名（例如image.png与image.webp同时对应image.png标签）的情况，否则导入会失败。
4. 标签编号连续性：labels.txt中标签编号从 0 开始递增，分割项目第一个标签为背景类；若需要自定义编号与颜色，请使用 2/3/5 字段格式显式声明，避免与自动编号冲突。
5. 与 COCO 格式的关系：所有使用 COCO 格式保存标注的项目（如 COCO 格式的检测与实例分割）不支持labels.txt与xx_list.txt，其数据划分与类别信息统一由train.json/val.json/test.json三个文件承载。若项目采用了 COCO 格式，请勿混入上述两个文件。
6. 样例参考：PaddleLabel 为每种支持的标注项目都内置了样例数据集，可在欢迎页面点击“样例项目”按钮创建；样例数据会被解压到~/.paddlelabel/sample文件夹，是核对上述文件格式最直接的可运行参考。

六、小结

labels.txt与xx_list.txt是 PaddleLabel 所有非 COCO 项目共用的数据集“通用基础功能”：前者定义标签清单（支持编号、颜色、注释的扩展格式），后者定义数据集划分与“图像—标签”匹配关系。正确理解二者的字段规则、编号约定与导出行为，是保证 PaddleLabel 数据能被 PaddleSeg 等下游套件无缝读取的关键。结合 dataset.py 的读取实现可以看到，PaddleLabel 的导出格式与 PaddleSeg 自定义数据集接口是天然对齐的：保持labels.txt与三个 list 文件与数据集目录结构的规范，即可从“标注”一路顺畅走到“训练”。

• 人工智能
• 计算机视觉
• 预训练