简介

Donut 🍩，即 Document understanding transformer，是一种全新的文档理解方法，它采用无 OCR 的端到端 Transformer 模型。Donut 无需现成的 OCR 引擎或 API，却在多种视觉文档理解任务上表现出最先进的性能，例如视觉文档分类或信息提取（即文档解析）。此外，我们还提出了 SynthDoG 🐶，即 Synthetic Document Generator，它可以帮助模型在多种语言和领域上进行灵活的预训练。

我们的学术论文详细描述了该方法，并提供了完整的实验结果与分析，可在此处找到：

无 OCR 文档理解 Transformer。
Geewook Kim (https://geewook.kim), Teakgyu Hong (https://dblp.org/pid/183/0952.html), Moonbin Yim (https://github.com/moonbings), JeongYeon Nam (https://github.com/long8v), Jinyoung Park (https://github.com/jyp1111), Jinyeong Yim (https://jinyeong.github.io), Wonseok Hwang (https://scholar.google.com/citations?user=M13_WdcAAAAJ), Sangdoo Yun (https://sangdooyun.github.io), Dongyoon Han (https://dongyoonhan.github.io), Seunghyun Park (https://scholar.google.com/citations?user=iowjmTwAAAAJ)。发表于 ECCV 2022。

预训练模型与网页演示

Gradio 网页演示现已上线！

• 您可以使用 ./app.py 文件运行演示。
• 示例图片可在 ./misc 中找到，更多收据图片则可在 CORD 数据集链接 获取。
• 网页演示可通过下表中的链接访问。
• 注意：我们已于 2023 年 6 月 15 日更新了 Google Colab 演示，以确保其正常运行。

任务	每张图片耗时	分数	训练模型	演示
CORD（文档解析）	0.7 / 0.7 / 1.2	91.3 / 91.1 / 90.9	donut-base-finetuned-cord-v2 (1280) / donut-base-finetuned-cord-v1 (1280) / donut-base-finetuned-cord-v1-2560	gradio space 网页演示, google colab 演示（23.06.15 更新）
火车票（文档解析）	0.6	98.7	donut-base-finetuned-zhtrainticket	google colab 演示（23.06.15 更新）
RVL-CDIP（文档分类）	0.75	95.3	donut-base-finetuned-rvlcdip	gradio space 网页演示, google colab 演示（23.06.15 更新）
DocVQA Task1（文档 VQA）	0.78	67.5	donut-base-finetuned-docvqa	gradio space 网页演示, google colab 演示（23.06.15 更新）

预训练骨干模型的链接如下：

• donut-base：由 64 块 A100 GPU 训练而成（约 2.5 天），层数为（编码器：{2,2,14,2}, 解码器：4），输入尺寸为 2560×1920，Swin 窗口大小为 10，数据来源为 IIT-CDIP（1100 万张）和 SynthDoG（英语、中文、日语、韩语，每种 50 万张）。
• donut-proto：（初步模型）由 8 块 V100 GPU 训练而成（约 5 天），层数为（编码器：{2,2,18,2}, 解码器：4），输入尺寸为 2048×1536，Swin 窗口大小为 8，数据来源为 SynthDoG（英语、日语、韩语，每种 40 万张）。

更多详情请参阅我们的论文（见“如何引用”部分）。

SynthDoG 数据集

SynthDoG 生成的数据集链接如下：

• synthdog-en：英语，50 万张。
• synthdog-zh：中文，50 万张。
• synthdog-ja：日语，50 万张。
• synthdog-ko：韩语，50 万张。

如需使用我们的 SynthDoG 生成合成数据集，请参阅 ./synthdog/README.md 及我们的论文（见“如何引用”部分）获取详细信息。

更新

2023-06-15 我们已更新所有 Google Colab 演示，以确保其正常运行。
2022-11-14 新版本 1.0.9 已发布（pip install donut-python --upgrade）。请参阅 1.0.9 发行说明。
2022-08-12 Donut 🍩 也已在 huggingface/transformers 🤗 上提供（由 @NielsRogge 贡献）。donut-python 会从模型仓库的 official 分支加载预训练权重。请参阅 1.0.5 发行说明。
2022-08-05 关于 donut 🍩 的一篇操作性很强的教程已在 Towards Data Science 上发表（作者为 @estaudere）。
2022-07-20 首次提交，我们发布了代码、模型权重、合成数据及生成器。

软件安装

pip install donut-python

或者克隆此仓库并安装依赖项：

git clone https://github.com/clovaai/donut.git
cd donut/
conda create -n donut_official python=3.7
conda activate donut_official
pip install .

我们使用以下版本测试了 donut-python == 1.0.1：

• torch == 1.11.0+cu113
• torchvision == 0.12.0+cu113
• pytorch-lightning == 1.6.4
• transformers == 4.11.3
• timm == 0.5.4

注意：根据多起反馈的问题，我们注意到由于关键依赖库的近期更新，配置 donut-python 的测试环境变得愈发困难。虽然我们正在积极寻找解决方案，但我们已于 2023 年 6 月 15 日更新了 Google Colab 演示，以确保其正常运行。如需帮助，请参考以下演示链接：CORD Colab 演示、火车票 Colab 演示、RVL-CDIP Colab 演示、DocVQA Colab 演示。

入门指南

数据

本仓库假定数据集具有如下结构：

> tree dataset_name
dataset_name
├── test
│   ├── metadata.jsonl
│   ├── {image_path0}
│   ├── {image_path1}
│             .
│             .
├── train
│   ├── metadata.jsonl
│   ├── {image_path0}
│   ├── {image_path1}
│             .
│             .
└── validation
    ├── metadata.jsonl
    ├── {image_path0}
    ├── {image_path1}
              .
              .

> cat dataset_name/test/metadata.jsonl
{"file_name": {image_path0}, "ground_truth": "{\"gt_parse\": {ground_truth_parse}, ... {other_metadata_not_used} ... }"}
{"file_name": {image_path1}, "ground_truth": "{\"gt_parse\": {ground_truth_parse}, ... {other_metadata_not_used} ... }"}
     .
     .

• metadata.jsonl 文件的结构采用 JSON Lines 文本格式，即 .jsonl。每行包含：
  • file_name：图像文件的相对路径。
  • ground_truth：字符串格式（JSON 序列化），字典中包含 gt_parse 或 gt_parses。其他字段（元数据）可以添加到字典中，但不会被使用。
• donut 将所有任务视为 JSON 预测问题。因此，所有 donut 模型的训练都遵循相同的流程。在训练和推理时，唯一需要做的就是按照下文所述的格式准备任务所需的 gt_parse 或 gt_parses。

对于文档分类

gt_parse 的格式为 {"class" : {class_name}}，例如 {"class" : "scientific_report"} 或 {"class" : "presentation"}。

• Google Colab 演示可在 这里 查看。
• Gradio 网页演示可在 这里 查看。

对于文档信息抽取

gt_parse 是一个包含文档图像全部信息的 JSON 对象，例如，一张收据的 JSON 对象可能看起来是 {"menu" : [{"nm": "ICE BLACKCOFFEE", "cnt": "2", ...}, ...], ...}。

• 更多示例可在 CORD 数据集 中找到。
• Google Colab 演示可在 这里 查看。
• Gradio 网页演示可在 这里 查看。

对于文档视觉问答

gt_parses 的格式为 [{"question" : {question_sentence}, "answer" : {answer_candidate_1}}, {"question" : {question_sentence}, "answer" : {answer_candidate_2}}, ...]，例如 [{"question" : "模型名称是什么？", "answer" : "donut"}, {"question" : "模型名称是什么？", "answer" : "文档理解 Transformer"}]。

• DocVQA Task1 有多重答案，因此 gt_parses 应该是一个包含问题与答案对的字典列表。
• Google Colab 演示可在 这里 查看。
• Gradio 网页演示可在 这里 查看。

对于（伪）文本阅读任务

gt_parse 的格式为 {"text_sequence" : "word1 word2 word3 ... "}

• 该任务同时也是 Donut 模型的预训练任务。
• 您可以使用我们的 SynthDoG 🐶 生成适合文本阅读任务的合成图像，并附带正确的 gt_parse。详情请参阅 ./synthdog/README.md。

训练

这是我们实验中使用的、在 CORD 数据集上训练 Donut 模型的配置。我们使用单块 NVIDIA A100 GPU 运行了该训练。

python train.py --config config/train_cord.yaml \
                --pretrained_model_name_or_path "naver-clova-ix/donut-base" \
                --dataset_name_or_paths '["naver-clova-ix/cord-v2"]' \
                --exp_version "test_experiment"    
  .
  .                                                                                                                                                                                                                                         
预测: <s_menu><s_nm>柠檬茶 (L)</s_nm><s_cnt>1</s_cnt><s_price>25.000</s_price></s_menu><s_total><s_total_price>25.000</s_total_price><s_cashprice>30.000</s_cashprice><s_changeprice>5.000</s_changeprice></s_total>
答案: <s_menu><s_nm>柠檬茶 (L)</s_nm><s_cnt>1</s_cnt><s_price>25.000</s_price></s_menu><s_total><s_total_price>25.000</s_total_price><s_cashprice>30.000</s_cashprice><s_changeprice>5.000</s_changeprice></s_total>
归一化编辑距离: 0.0
预测: <s_menu><s_nm>浩克顶配套餐</s_nm><s_cnt>1</s_cnt><s_price>100.000</s_price></s_menu><s_total><s_total_price>100.000</s_total_price><s_cashprice>100.000</s_cashprice><s_changeprice>0</s_changeprice></s_total>
答案: <s_menu><s_nm>浩克顶配套餐</s_nm><s_cnt>1</s_cnt><s_price>100.000</s_price></s_menu><s_total><s_total_price>100.000</s_total_price><s_cashprice>100.000</s_cashprice><s_changeprice>0</s_changeprice></s_total>
归一化编辑距离: 0.0
预测: <s_menu><s_nm>巨型乌贼</s_nm><s_cnt>x 1</s_cnt><s_price>Rp. 39.000</s_price><s_sub><s_nm>C.精加工 - 切割</s_nm><s_price>Rp. 0</s_price><sep/><s_nm>B.辣度 - 极辣 Rp. 0</s_price></s_sub><sep/><s_nm>A.口味 - 盐椒</s_nm><s_price>Rp. 0</s_price></s_sub></s_menu><s_sub_total><s_subtotal_price>Rp. 39.000</s_subtotal_price></s_sub_total><s_total><s_total_price>Rp. 39.000</s_total_price><s_cashprice>Rp. 50.000</s_cashprice><s_changeprice>Rp. 11.000</s_changeprice></s_total>
答案: <s_menu><s_nm>巨型乌贼</s_nm><s_cnt>x1</s_cnt><s_price>Rp. 39.000</s_price><s_sub><s_nm>C.精加工 - 切割</s_nm><s_price>Rp. 0</s_price><sep/><s_nm>B.辣度 - 极辣</s_nm><s_price>Rp. 0</s_price><sep/><s_nm>A.口味 - 盐椒</s_nm><s_price>Rp. 0</s_price></s_sub></s_menu><s_sub_total><s_subtotal_price>Rp. 39.000</s_subtotal_price></s_sub_total><s_total><s_total_price>Rp. 39.000</s_total_price><s_cashprice>Rp. 50.000</s_cashprice><s_changeprice>Rp. 11.000</s_changeprice></s_total>
归一化编辑距离: 0.039603960396039604                                                                                                                                  
第29轮: 100%|█████████████| 200/200 [01:49<00:00,  1.82项/s, 损失=0.00327, 实验名称=train_cord, 实验版本=test_experiment]

一些重要参数：

• --config：模型训练的配置文件路径。
• --pretrained_model_name_or_path：字符串格式，可以是 Hugging Face Model Hub 中的模型名称或本地路径。
• --dataset_name_or_paths：字符串格式（JSON 格式），包含 Hugging Face 数据集中的数据集名称列表或本地路径。
• --result_path：用于保存模型输出和中间产物的文件路径。
• --exp_version：用于实验版本管理。输出文件将保存在 {result_path}/{exp_version}/* 目录下。

测试

使用训练好的模型、测试图像以及真实标注，可以获取推理结果和准确率分数。

python test.py --dataset_name_or_path naver-clova-ix/cord-v2 --pretrained_model_name_or_path ./result/train_cord/test_experiment --save_path ./result/output.json
100%|█████████████| 100/100 [00:35<00:00,  2.80项/s]
样本总数: 100，基于树编辑距离（TED）的准确率：0.9129639764131697，F1 准确率：0.8406020841373987

一些重要参数：

• --dataset_name_or_path：字符串格式，目标数据集的名称或本地路径。
• --pretrained_model_name_or_path：字符串格式，Hugging Face Model Hub 中的模型名称或本地路径。
• --save_path：用于保存预测结果和评分的文件路径。

引用方式

如果您觉得这项工作对您有帮助，请引用以下内容：

@inproceedings{kim2022donut,
  title     = {无OCR文档理解Transformer},
  author    = {Kim, Geewook 和 Hong, Teakgyu 和 Yim, Moonbin 和 Nam, JeongYeon 和 Park, Jinyoung 和 Yim, Jinyeong 和 Hwang, Wonseok 和 Yun, Sangdoo 和 Han, Dongyoon 和 Park, Seunghyun},
  booktitle = {欧洲计算机视觉大会 (ECCV)},
  year      = {2022}
}

许可证

MIT 许可证

版权所有 © 2022-present NAVER Corp.

特此授予任何人免费获得本软件及其相关文档文件（“软件”）副本的权利，以进行处理。在不受限制的情况下，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，以及允许向任何接收软件的人提供软件的权利，但须遵守以下条件：

上述版权声明和本许可声明应包含在所有副本或软件的重要部分中。

“软件”按“原样”提供，不提供任何形式的保证，无论是明示的还是默示的，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论这些责任是基于合同、侵权行为或其他原因产生的，与软件或其使用有关的一切责任均由作者或版权所有者承担。

Donut 🍩 快速上手指南

Donut (Document Understanding Transformer) 是一个无需 OCR 引擎的端到端文档理解模型。它可以直接从文档图像中提取结构化信息（如收据解析、文档分类、视觉问答等），支持多种语言，且在多项任务中达到了业界领先（SOTA）水平。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐) 或 macOS
• Python 版本: 3.7 及以上 (官方测试基于 3.7)
• GPU: 推荐使用 NVIDIA GPU 以加速推理和训练（需安装对应的 CUDA 驱动）
• 前置依赖:
  • PyTorch >= 1.11.0
  • torchvision >= 0.12.0
  • pytorch-lightning >= 1.6.4
  • transformers >= 4.11.3
  • timm >= 0.5.4

注意：由于依赖库更新频繁，本地环境配置可能会遇到兼容性问题。如果本地安装困难，建议优先使用官方提供的 Google Colab Demo 进行体验。

2. 安装步骤

您可以通过 PyPI 直接安装，或者克隆源码进行安装。

方法一：通过 pip 安装（推荐）

pip install donut-python

方法二：源码安装

如果您需要修改代码或使用最新特性，可以克隆仓库安装：

git clone https://github.com/clovaai/donut.git
cd donut/

# 创建并激活 conda 环境
conda create -n donut_official python=3.7
conda activate donut_official

# 安装依赖
pip install .

3. 基本使用

Donut 将所有的文档理解任务（分类、信息提取、VQA）统一视为 JSON 预测问题。您只需加载预训练模型，输入图像，即可得到结构化的 JSON 输出。

以下是一个最简单的 Python 使用示例，演示如何加载模型并对图像进行推理：

import torch
from PIL import Image
from donut import DonutProcessor, DonutModel

# 1. 加载处理器和模型
# 这里以 CORD (收据解析) 微调模型为例，其他任务可替换为对应的 model name
model_name = "naver-clova-ix/donut-base-finetuned-cord-v2"
processor = DonutProcessor.from_pretrained(model_name)
model = DonutModel.from_pretrained(model_name)

# 将模型移动到 GPU (如果可用)
device = "cuda" if torch.cuda.is_available() else "cpu"
model.to(device)

# 2. 准备图像
# 替换为您的图片路径
image_path = "receipt_example.png" 
image = Image.open(image_path).convert("RGB")

# 3. 预处理
# prompt 通常为空字符串，因为模型是端到端的，不需要额外的文本提示
task_prompt = ""
decoder_input_ids = processor.tokenizer(
    task_prompt, add_special_tokens=False, return_tensors="pt"
).input_ids

pixel_values = processor(image, return_tensors="pt").pixel_values

# 4. 生成预测
outputs = model.generate(
    pixel_values=pixel_values.to(device),
    decoder_input_ids=decoder_input_ids.to(device),
    max_length=model.decoder.config.max_position_embeddings,
    early_stopping=True,
    pad_token_id=processor.tokenizer.pad_token_id,
    eos_token_id=processor.tokenizer.eos_token_id,
    use_cache=True,
    num_beams=1,
    bad_words_ids=[[processor.tokenizer.unk_token_id]],
)

# 5. 解析结果
sequence = processor.batch_decode(outputs)[0]
# 移除可能存在的特殊标记并转换为 JSON
sequence = sequence.replace(processor.tokenizer.eos_token, "").replace(
    processor.tokenizer.pad_token, ""
)
sequence = sequence.split("<s_json_object>")[1].split("<e_json_object>")[0]

import json
result = json.loads(sequence)

print("提取结果:", result)

任务说明

• 文档分类 (Document Classification): 输出格式为 {"class": "类别名称"}。
• 信息提取 (Information Extraction): 输出为包含文档所有关键字段的完整 JSON 对象（例如收据中的菜品名、价格等）。
• 视觉问答 (Visual Question Answering): 输出为包含问题和答案候选项的列表。

您可以从 Hugging Face Models 找到针对不同任务（如火车票识别、RVL-CDIP 分类、DocVQA 等）的预训练模型权重，只需更改上述代码中的 model_name 即可切换任务。