docTR 数据集使用完全指南:内置数据集、合成数据生成器与自定义数据集接入
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 为按样本排列的标签列表。
实践要点与常见问题
- 首次使用记得
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)。 - 缓存目录可配置:默认
~/.cache/doctr/datasets,设置环境变量DOCTR_CACHE_DIR可指向更大的磁盘分区,避免重复下载。 - 框坐标的绝对/相对转换:检测与 OCR 任务的目标坐标在读取时会被转换为相对坐标(除以图像尺寸),训练脚本无需再手动归一化;合成生成器与识别裁剪样本则直接以裁剪后的小图 + 标签形式输出。
- 类别完整性问题:多类别检测数据中,训练与验证两个 split 都必须覆盖数据集中的每一个类别,且每个 split 内部类别集合一致;某类在某图中无框时写为空列表,否则脚本会因类别不一致而中止(references/detection/README.md)。
- 语言与字符集匹配:选择内置数据集时注意其语言/字符属性(如 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 与目标检测的训练与评估。