docTR 数据集使用完全指南:内置数据集、合成数据生成器与自定义数据集接入

原创2026-10-07 18:28:111,873 阅读
文章标签:OCR计算机视觉深度学习人工智能图像处理

docTR 数据集使用完全指南:内置数据集、合成数据生成器与自定义数据集接入

docTR(Document Text Recognition)为检测、识别、OCR 与版面目标检测提供了开箱即用的数据集封装,本文基于 docs/source/using_doctr/using_datasets.rst 展开,逐一讲解内置数据集的样本规模、加载方式、合成数据生成器的用法,以及如何把私有数据格式化为 docTR 标准格式并用 DetectionDataset / RecognitionDataset / OCRDataset 加载。读完本文,你将能够直接调用 docTR 的全部内置数据集开始训练或评估,也能在不泄露敏感数据的前提下,把自有标注数据接入 docTR 的训练管线。

概述:docTR 数据体系的组成

无论是训练还是评估,预先封装好、可直接按框架习惯访问的数据集对象都能节省大量时间。docTR 的 doctr.datasets 模块将这些能力集中暴露,整体可分为四层:

  • 任务数据集:按任务(文本检测 Detection、文本识别 Recognition、端到端 OCR、目标检测 Object Detection)组织的一批公开数据集,全部支持 train=True/False 切分训练/测试子集,并支持自动下载与解压;
  • 合成数据生成器:CharacterGenerator 与 WordGenerator,用系统字体即时渲染字符/单词图像,可无限按需生成样本;
  • 自定义数据集加载器:DetectionDataset、RecognitionDataset、OCRDataset(以及文档库中一并提供的 LayoutDataset、TableStructureDataset),负责把用户自有标注解析为统一格式;
  • 数据集基础设施:抽象基类 AbstractDataset / VisionDataset(见 doctr/datasets/datasets/base.py 与 doctr/datasets/datasets/pytorch.py)统一处理下载、解压、图像读取与变换流水线。

所有数据集类都在 doctr/datasets/init.py 中统一导出,可直接 from doctr.datasets import xxx 使用。

内置数据集:文本检测(Detection)

检测数据集包含训练或验证文本检测模型所需的图像与文本框标注。下表汇总了 docTR 内置的检测数据集及其样本规模:

数据集 Train Samples Test Samples 备注
FUNSD 149 50
SROIE 626 360
CORD 800 100
IIIT5K 2000 3000
SVT 100 249
SVHN 33402 13068 Character Localization(字符定位)
SynthText 772875 85875
IC03 246 249
IC13 229 233 external resources(外部资源)
IMGUR5K 7149 796 Handwritten / external resources
WILDRECEIPT 1268 472 external resources
COCOTEXT 13880 3261 external resources / legible filtered

以 CORD(消费小票数据集)为例,加载检测数据集的写法如下:

from doctr.datasets import CORD
# 加载水平文本框(straight boxes)
train_set = CORD(train=True, download=True, detection_task=True)
# 加载旋转框(polygons,可表示倾斜文本)
train_set = CORD(train=True, download=True, use_polygons=True, detection_task=True)
img, target = train_set[0]

其中关键参数的含义:

  • train=True:使用训练子集(False 时使用测试子集);
  • download=True:若本地缓存不存在则自动下载。缓存目录默认是 ~/.cache/doctr/datasets,可通过环境变量 DOCTR_CACHE_DIR 覆盖(见 doctr/datasets/datasets/base.py);
  • use_polygons=True:把四边形四角坐标 (x1,y1),(x2,y2),(x3,y3),(x4,y4) 作为旋转框保留,否则压缩为 xmin, ymin, xmax, ymax 的水平框(对应实现见 doctr/datasets/cord.py);
  • detection_task=True:只返回 (图像, 框坐标数组),不包含文本标签。

从源码实现看(doctr/datasets/cord.py),CORD 的每个 JSON 标注被解析为 valid_line[].words[],每个 word 提供四角坐标 quad 与文本 text;检测任务下目标被整理为 np.asarray(box_targets, dtype=int),并以 float32 的 numpy 数组保存,避免后续精度损失。

内置数据集:文本识别(Recognition)

识别数据集包含训练或验证文本识别模型所需的“裁剪图像 → 字符序列”对。下表为 docTR 内置识别数据集的规模与语言说明:

数据集 Train Samples Test Samples 备注
FUNSD 21888 8707 english
SROIE 33608 19342 english / only uppercase labels(仅大写标签)
CORD 19370 2186 english
IIIT5K 2000 3000 english
SVT 257 647 english / only uppercase labels
SVHN 73257 26032 digits(数字)
SynthText ~7100000 707470 english
IC03 1156 1107 english
IC13 849 1095 english / external resources
IMGUR5K 207901 22672 english / handwritten / external resources
MJSynth 7581382 1337891 english / external resources
IIITHWS 7141797 793533 english / handwritten / external resources
WILDRECEIPT 49377 19598 english / external resources
COCOTEXT 59130 13258 english / external resources / legible filtered

加载示例(仍以 CORD 为例):

from doctr.datasets import CORD
# 直接裁剪框内区域(crop 内可能包含不规则/多余内容)
train_set = CORD(train=True, download=True, recognition_task=True)
# 按旋转框裁剪(crop 始终是规整矩形)
train_set = CORD(train=True, download=True, use_polygons=True, recognition_task=True)
img, target = train_set[0]

关键点说明:

  • recognition_task=True 时,docTR 会调用 crop_bboxes_from_image(doctr/datasets/utils.py)把每个词框从原图中裁剪出来作为训练样本;标签为词文本。若文本含空格(如 " "),CORD 会跳过该样本(见 doctr/datasets/cord.py),这与识别词表不包含空格的处理方式保持一致;
  • recognition_task 与 detection_task 不可同时为 True,同时传入会抛出 ValueError(见 doctr/datasets/cord.py)。要同时拿到框与标签,应保持两者均为 False,走下面的 OCR 加载方式。

内置数据集:端到端 OCR

OCR 模式的数据集表格与检测一致,但目标中同时携带边界框与标签信息,适合端到端训练。加载方式即上述两种模式都不开启的默认形式:

from doctr.datasets import CORD
# 加载水平框
train_set = CORD(train=True, download=True)
# 加载旋转框
train_set = CORD(train=True, download=True, use_polygons=True)
img, target = train_set[0]

此时 target 是一个字典,包含 boxes(坐标数组)与 labels(文本列表)两个键。这与抽象基类在 doctr/datasets/datasets/pytorch.py 中对 dict 类型目标的断言一致:target 必须包含 "boxes" 与 "labels" 键。此外,OCR/检测任务的目标坐标会在读取时被转换为相对坐标(convert_target_to_relative,见 doctr/datasets/utils.py),保证不同分辨率图像下的数值一致性。

内置数据集:目标检测(Object Detection)

除了文本相关任务,docTR 还内置了针对文档中非文本元素的目标检测数据集 DocArtefacts:

数据集 Train Samples Test Samples 类别
DocArtefacts 2700 300 ["background", "qr_code", "bar_code", "logo", "photo"]
from doctr.datasets import DocArtefacts
train_set = DocArtefacts(train=True, download=True)
img, target = train_set[0]

从 doctr/datasets/doc_artefacts.py 的实现可以看到,CLASSES 列表定义了 5 个类别(背景、二维码、条形码、Logo、照片),数据集在下载后按 train / val 子目录组织,并要求 labels.json 中的标注数量与 images 目录中的图像数量严格一致,否则抛出断言错误。加载时 img 为张量,target 为包含 boxes 与 labels 的字典。

合成数据集生成器

docTR 还提供了两类合成数据生成器,可用于快速扩充数据或做数据增强实验,且已集成到训练脚本中用于分类/识别模型训练。底层实现位于 doctr/datasets/generator/base.py,使用 PIL 直接渲染文本,默认以 32px 字号(DEFAULT_FONT_SIZE)绘制,并会自动校验字体能否真正渲染词表中的每个字符(无法渲染的字符会抛出带 Unicode 码点的明确报错)。

生成单个字符样本:

from doctr.datasets import CharacterGenerator
ds = CharacterGenerator(vocab='abdef', num_samples=100)
img, target = ds[0]

生成单词样本:

from doctr.datasets import WordGenerator
ds = WordGenerator(vocab='abdef', min_chars=1, max_chars=32, num_samples=100)
img, target = ds[0]

参数说明(与 doctr/datasets/generator/pytorch.py 中两个类的签名一致):

  • vocab:字符表,从中随机取字符组成样本;
  • min_chars / max_chars:单词长度范围(仅 WordGenerator);
  • num_samples:迭代数据集时产生的样本总数(__len__ 即返回该值);
  • cache_samples:是否预先渲染并缓存样本(CharacterGenerator 会按词表逐字符渲染,WordGenerator 会按 num_samples 预生成);
  • font_family:指定渲染字体(需系统已安装);可传列表,docTR 会优先为每个字符挑选能覆盖它的字体;
  • img_transforms / sample_transforms:可组合的变换,分别作用于图像与“图像+标签”样本。

合成样本的 target 语义:CharacterGenerator 返回字符在词表中的索引(整数),WordGenerator 返回生成的单词字符串。

使用自有数据集:三大约载器的标准格式

由于许多文档包含敏感/个人信息,docTR 无法公开项目中使用的全部私有数据,因此提供了标准化的自有数据格式指导,让用户能以同样的格式接入全部 docTR 工具。三种加载器统一按“图像文件夹 + JSON 标注文件”组织:

from doctr.datasets import DetectionDataset
# 加载检测数据集
train_set = DetectionDataset(img_folder="/path/to/images", label_path="/path/to/labels.json")
# 加载识别数据集
train_set = RecognitionDataset(img_folder="/path/to/images", labels_path="/path/to/labels.json")
# 加载 OCR 数据集(同时包含框与标签标注)
train_set = OCRDataset(img_folder="/path/to/images", label_file="/path/to/labels.json")
img, target = train_set[0]

检测数据集格式(DetectionDataset)

检测格式要求目录结构如下(详见 references/detection/README.md 的 "Data format" 一节):

├── images
│   ├── sample_img_01.png
│   ├── sample_img_02.png
│   └── ...
└── labels.json

labels.json 是一个字典:键为图像文件名,值为包含 img_dimensions(图像空间尺寸)、img_hash(图像文件 SHA256)、polygons(定位多边形顶点集合)三个条目的字典。多边形内顶点顺序无关紧要,坐标为绝对像素值 (x, y):

{
    "sample_img_01.png": {
        "img_dimensions": [900, 600],
        "img_hash": "theimagedumpmyhash",
        "polygons": [[[x1, y1], [x2, y2], [x3, y3], [x4, y4]], ...]
    },
    "sample_img_02.png": {
        "img_dimensions": [900, 600],
        "img_hash": "thisisahash",
        "polygons": [[[x1, y1], [x2, y2], [x3, y3], [x4, y4]], ...]
    }
}

多类别检测时,polygons 改为以类别名为键的字典,每个键对应该类别的全部多边形(references/detection/README.md 中给出了 class_name_1 / class_name_2 的完整示例)。对应源码 doctr/datasets/detection.py 中,format_polygons 对 list 与 dict 两种输入分别处理:list 形式所有框归为默认类别 CLASS_NAME,dict 形式按类别键展开;use_polygons=False 时取每个多边形的 min/max 合成水平框。类名集合通过 class_names 属性暴露,且每个样本都会暴露完整(排序后)的类别集合,保证“类别 → 通道”的映射跨样本一致——即使某张图中某类没有框,也会映射为空数组(doctr/datasets/detection.py)。若数据只做了部分标注,训练脚本可通过 --mask-empty-classes 让这些通道在损失中被忽略。

识别数据集格式(RecognitionDataset)

识别格式同样是一个图像文件夹加一个 labels.json(references/recognition/README.md):

{
    "img_1.jpg": "I",
    "img_2.jpg": "am",
    "img_3.jpg": "a",
    "img_4.jpg": "Jedi",
    "img_5.jpg": "!"
}

注意事项:

  • JSON 条目顺序无关紧要,每张图对应一个字符串标签;
  • 词表(VOCAB)不处理空格,因此标签中不要包含空格;
  • labels.json 必须使用 UTF-8 编码(doctr/datasets/recognition.py 中即显式以 encoding="utf-8" 打开)。

RecognitionDataset 还提供了 merge_dataset 方法(doctr/datasets/recognition.py),可将两个识别数据集合并为一个(内部将路径改为绝对路径后合并样本列表),便于跨数据源拼接训练。

OCR 数据集格式(OCRDataset)

OCR 格式面向同时包含框与文本的标注:labels.json 以图像文件名为键,值为包含 typed_words 列表的字典,每个 typed_words 元素含 geometry(前 4 个值为 xmin, ymin, xmax, ymax)与 value(词文本)两个字段(doctr/datasets/ocr.py):

{
    "sample_img_01.png": {
        "typed_words": [
            {"geometry": [x1, y1, x2, y2], "value": "word1"},
            {"geometry": [x1, y1, x2, y2], "value": "word2"}
        ]
    }
}

use_polygons=True 时,geometry 前 4 个值会被展开为四边形四角坐标(左上、右上、右下、左下)。若某张图 typed_words 为空,docTR 会保留该样本并生成空框 boxes=np.zeros((0, 4)) 与空标签列表(doctr/datasets/ocr.py)。

数据加载:从单个样本到批次

每个数据集都有各自加载单个样本的方式,但批次聚合与底层迭代器交由 docTR 的 DataLoader 处理。示例:

from doctr.datasets import CORD, DataLoader
train_set = CORD(train=True, download=True)
train_loader = DataLoader(train_set, batch_size=32)
train_iter = iter(train_loader)
images, targets = next(train_iter)

需要说明:doctr.datasets 模块本身不实现 DataLoader,而是与框架原生加载器对齐——仓库中的训练/评估脚本统一使用 PyTorch 的 torch.utils.data.DataLoader(例如 references/detection/train.py、references/recognition/evaluate.py),并配合 collate_fn 将单样本聚合为批次。AbstractDataset 的 collate_fn(doctr/datasets/datasets/pytorch.py)会把样本列表中的图像 torch.stack 为四维批次张量,同时收集各样本的 target;若样本带有 mask,则返回 ((images, masks), targets) 的二元组结构。因此在训练循环中,next(iter(train_loader)) 得到的 images 是形状为 (batch_size, channels, height, width) 的张量,targets 为按样本排列的标签列表。

实践要点与常见问题

  1. 首次使用记得 download=True:若本地缓存不存在且未传 download=True,_VisionDataset 会抛出 ValueError("the dataset needs to be downloaded first with download=True")(doctr/datasets/datasets/base.py)。下载后文件会校验 SHA256 并自动解压(extract_archive=True)。
  2. 缓存目录可配置:默认 ~/.cache/doctr/datasets,设置环境变量 DOCTR_CACHE_DIR 可指向更大的磁盘分区,避免重复下载。
  3. 框坐标的绝对/相对转换:检测与 OCR 任务的目标坐标在读取时会被转换为相对坐标(除以图像尺寸),训练脚本无需再手动归一化;合成生成器与识别裁剪样本则直接以裁剪后的小图 + 标签形式输出。
  4. 类别完整性问题:多类别检测数据中,训练与验证两个 split 都必须覆盖数据集中的每一个类别,且每个 split 内部类别集合一致;某类在某图中无框时写为空列表,否则脚本会因类别不一致而中止(references/detection/README.md)。
  5. 语言与字符集匹配:选择内置数据集时注意其语言/字符属性(如 SVHN 仅数字、SROIE/IIIT5K/SVT 可能仅大写),识别训练还需确保标签字符落在所选词表(VOCABS)内,docTR 支持从 latin、english 到日文、韩文、简中等大量词表,完整清单见 docs/source/modules/datasets.rst 的 "Supported Vocabs" 一节。

掌握以上内容后,无论是直接使用内置数据集、按需合成样本,还是把企业内部的敏感文档数据转化为 docTR 标准格式,都可以无缝接入 references/detection/train.py、references/recognition/train.py 等官方训练脚本,用同一套数据抽象完成检测、识别、OCR 与目标检测的训练与评估。

登录后查看全文
doctr