Donut端到端票据识别：小票图像直出结构化JSON

1. 项目概述：一张小票，如何让AI“看懂”并结构化输出？

你有没有试过把超市小票拍张照，想让手机自动提取“总金额：¥89.50”“商品：牛奶×2”“时间：2024-03-12 18:23”这些信息？不是OCR识别出一堆乱序文字，而是直接返回一个干净的JSON——{"total": "89.50", "items": [{"name": "纯牛奶", "qty": 2, "price": "12.80"}], "date": "2024-03-12"}。这正是Donut模型要干的事：它不靠传统OCR+规则匹配的老路，而是用端到端视觉语言理解，把整张图像当“文档”直接读取、理解、生成结构化文本。我第一次在实验室用它处理本地菜市场手写收据时，只改了不到20行代码，模型就在3小时后准确识别出“青椒 ¥6.5/斤 × 1.2斤 = ¥7.80”这种带计算逻辑的条目——而此前用Tesseract+正则硬啃，光写匹配规则就花了两天，还总被“¥”和“￥”符号搞崩溃。Donut的核心价值，不是替代OCR，而是跳过OCR这个中间环节，让模型自己学会“看图说话”。它特别适合处理格式多变、印刷质量差、含手写体、有表格线或印章遮挡的票据类图像，比如餐饮小票、物流面单、医疗处方、银行回单。如果你正在做财务自动化、报销系统、供应链单据处理，或者只是想给自家小店做个扫码记账工具，Donut就是那个能让你从“调参炼丹”回归“业务落地”的务实选择。它不要求你有GPU集群，一台带32GB内存的MacBook Pro M2 Max就能跑通全流程；它也不要求你精通Transformer架构，真正需要你动手写的，就是数据准备、微调脚本和结果后处理三块。接下来我会带你从零开始，把Donut模型真正变成你手边可用的“小票翻译器”，每一步都附上我踩过的坑、实测有效的参数和可直接复制的命令。

2. 核心技术拆解：为什么Donut是票据识别的“最优解”？

2.1 Donut到底是什么？它和传统OCR的根本区别在哪？

Donut（Document Understanding Transformer）不是OCR引擎，也不是NLP模型，而是一个视觉-语言联合建模的端到端生成式模型。它的名字直译是“甜甜圈”，但技术内核非常扎实：输入是一张票据图像，输出是结构化文本（如JSON字符串），整个过程没有显式的文本检测、识别、版面分析等中间步骤。你可以把它想象成一个刚入职的财务实习生——你给他看一张小票照片，他不需要先用放大镜逐字抄下来（OCR），再拿纸笔比对模板填空（规则匹配），而是直接盯着图片，结合上下文（比如“TOTAL”旁边大概率是数字，“ITEM”下面跟着的是商品名），一口气把关键信息“说”出来。这个“说”的过程，用的是类似ChatGPT的自回归语言生成机制，但它的“词汇表”里不仅有文字，还有图像特征编码。具体来说，Donut由两部分组成：Swin Transformer视觉编码器和BART-style文本解码器。Swin负责把整张小票压缩成一组富含语义的视觉向量（比如“右下角红色印章区域”“左上角模糊的日期字体”“中间带虚线分隔的商品列表”），BART则根据这些视觉向量，像写作文一样，一个token一个token地生成JSON字符串。这种设计绕开了OCR的致命短板：当小票被咖啡渍晕染、被折叠压痕、或使用非标准字体时，OCR引擎（如Tesseract）会把“¥89.50”识别成“Y89.50”或“¥89.S0”，后续所有规则都崩盘。而Donut看到的是“整体视觉模式”，只要“总价”区域的形状、位置、颜色对比度足够典型，它就能稳定输出正确数字。我做过对比测试：在100张模糊小票上，Tesseract+正则的准确率是63%，而Donut微调后达到89%。这不是算法玄学，而是端到端学习带来的鲁棒性提升。

2.2 为什么必须微调（Fine-tune）？预训练模型不能直接用吗？

Donut官方发布的预训练模型（如naver-clova/donut-base-finetuned-docvqa）是在DocVQA（文档视觉问答）数据集上训练的，任务是回答“这张发票的供应商是谁？”这类问题。它擅长理解文档结构，但对“小票”这个特定领域毫无概念。就像一个精通法律文书的律师，突然让他去解读菜市场手写收据，他得先学“青椒”“毛豆”“称重”这些本地词汇和常见格式。微调的本质，就是用你的小票数据，教会模型“小票的语言”。这里的关键洞察是：Donut的微调成本极低。它不像BERT那样需要海量标注数据，因为它的解码器是自回归的，只要提供“图像→JSON”这对样本，模型就能通过最大似然估计学习映射关系。我们团队实测，用仅200张高质量标注小票（覆盖不同超市、不同打印质量、含手写备注），微调10个epoch，模型在验证集上的字段级F1值就从预训练的41%跃升至78%。更关键的是，Donut的微调不涉及修改视觉编码器权重——我们只训练解码器和连接层，这使得显存占用大幅降低。在RTX 3090上，batch size=2时，单步训练耗时仅1.2秒，而全参数微调要3.8秒。这意味着你完全可以用消费级显卡，在下班前启动训练，第二天早上就能拿到可用模型。很多人误以为微调=重头训练，其实Donut的微调更像“给模型装上一副新眼镜”，让它专注看清小票的细节，而不是换掉整个大脑。

2.3 数据准备：为什么“200张好数据”比“2000张烂数据”管用十倍？

这是我在三个客户项目中反复验证的铁律：票据识别效果的天花板，80%取决于数据质量，而非模型复杂度。Donut对噪声极其敏感——如果标注JSON里把“subtotal”错写成“sub_total”，模型会认真学会这个错误，并在推理时稳定复现。因此，数据准备阶段必须像审计账目一样严谨。核心原则就一条：标注必须100%忠实于图像呈现，不做任何推断或补全。例如，一张小票上“优惠：-¥5.00”被油渍盖住后半部分，你只能标"discount": "-¥5."，绝不能脑补成"-5.00"；如果“日期”栏是手写的“3/12”，你必须标"date": "3/12"，而不是标准化为"2024-03-12"。后者看似“友好”，实则教会模型忽略原始视觉线索。我们内部有一套数据清洗checklist：

1. 图像分辨率统一为1280×1800像素（Donut默认输入尺寸），用双三次插值缩放，避免拉伸变形；
2. 每张图必须有且仅有一个JSON文件，文件名与图像同名，内容为扁平化JSON（无嵌套数组，除非业务强需求）；
3. 字段命名全部小写+下划线（如total_amount,item_list），禁用驼峰和空格；
4. 所有数值字段保留原始格式（含货币符号、千分位逗号），后期用正则清洗；
5. 对模糊/遮挡区域，用<unk>占位符（如"cashier": "<unk>"），而非留空。
   这套规则让我们在客户现场验收时，一次通过率从35%提升到92%。记住，Donut不是在学“财务知识”，它在学“图像到字符串的映射”。你给它什么，它就记住什么。

3. 实操全流程：从环境搭建到部署上线的每一步

3.1 环境配置：避开CUDA版本陷阱的实操指南

Donut对PyTorch和CUDA版本极其挑剔，这是我踩过最深的坑。官方文档推荐PyTorch 1.13 + CUDA 11.7，但实际在Ubuntu 22.04上，pip install torch==1.13.1+cu117会因cuDNN版本冲突导致训练时显存泄漏。经过三天编译测试，我确认最稳组合是PyTorch 2.0.1 + CUDA 11.8。以下是经过10台服务器验证的安装命令（请严格按顺序执行）：

# 卸载所有旧torch pip uninstall torch torchvision torchaudio -y # 安装指定版本（注意：必须用--force-reinstall，否则conda可能缓存旧包） pip install --force-reinstall torch==2.0.1+cu118 torchvision==0.15.2+cu118 torchaudio==2.0.2+cu118 --extra-index-url https://download.pytorch.org/whl/cu118 # 安装Donut依赖（注意：transformers必须>=4.27.0，否则解码器报错） pip install transformers==4.35.2 datasets==2.15.0 sentencepiece==0.1.99 python-Levenshtein==0.21.1 # 验证CUDA是否生效（运行后应显示True） python -c "import torch; print(torch.cuda.is_available())"

提示：如果你用Mac M系列芯片，直接跳过CUDA安装，用pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2即可。Donut在M2 Max上推理速度比RTX 3060快15%，因为其Swin编码器对Apple Neural Engine优化极好。

环境配好后，务必测试基础功能。创建test_donut.py：

from transformers import DonutProcessor, VisionEncoderDecoderModel processor = DonutProcessor.from_pretrained("naver-clova/donut-base-finetuned-docvqa") model = VisionEncoderDecoderModel.from_pretrained("naver-clova/donut-base-finetuned-docvqa") print("✅ 环境验证通过：模型加载成功")

运行无报错，说明环境已就绪。这一步看似简单，但能帮你避开后续80%的“ModuleNotFoundError”和“CUDA out of memory”问题。

3.2 数据集构建：用Python脚本自动化生成合规数据集

手工整理200张小票的JSON太反人类。我写了一个轻量脚本build_dataset.py，它能自动完成三件事：图像预处理、JSON模板生成、数据集目录结构化。核心逻辑如下：

import os from PIL import Image import json def preprocess_image(image_path, output_path): """统一缩放+锐化，提升小票文字清晰度""" img = Image.open(image_path).convert("RGB") # Donut最佳输入尺寸：1280x1800（宽高比≈0.71） img = img.resize((1280, 1800), Image.Resampling.BICUBIC) # 对文字区域做轻微锐化（增强OCR-like特征） from PIL import ImageFilter img = img.filter(ImageFilter.UnsharpMask(radius=1, percent=150, threshold=3)) img.save(output_path) def generate_json_template(image_name): """生成标准JSON模板，字段按小票常见顺序排列""" return { "store_name": "", "date": "", "time": "", "items": [], "subtotal": "", "tax": "", "total_amount": "", "payment_method": "" } # 批量处理 raw_dir = "./raw_images" proc_dir = "./dataset/images" os.makedirs(proc_dir, exist_ok=True) for img_file in os.listdir(raw_dir): if img_file.lower().endswith(('.png', '.jpg', '.jpeg')): # 预处理图像 preprocess_image(os.path.join(raw_dir, img_file), os.path.join(proc_dir, img_file)) # 生成JSON模板 json_data = generate_json_template(img_file) json_path = os.path.join("./dataset/jsons", img_file.replace(".jpg", ".json").replace(".png", ".json")) os.makedirs(os.path.dirname(json_path), exist_ok=True) with open(json_path, 'w', encoding='utf-8') as f: json.dump(json_data, f, ensure_ascii=False, indent=2)

运行此脚本后，你会得到标准的dataset/目录：

dataset/ ├── images/ # 处理后的1280x1800 JPG ├── jsons/ # 空白JSON模板（待人工填写） └── train_val_split.json # 训练/验证集划分（8:2）

注意：train_val_split.json必须手动编写，格式为{"train": ["IMG_001.jpg", "IMG_002.jpg"], "validation": ["IMG_199.jpg"]}。别用随机划分！要把同一超市、同一批次打印的小票尽量分在同一集合，避免数据泄露。

3.3 微调训练：用Hugging Face Trainer实现零代码训练

Donut的微调无需写训练循环，Hugging Face的Trainer类已封装好所有细节。关键在于配置TrainingArguments——这里全是血泪经验：

from transformers import TrainingArguments, Trainer from donut_dataset import DonutDataset # 自定义数据集类（后文详解） # 数据集加载（重点：必须用Donut专用数据集类） train_dataset = DonutDataset( dataset_name="my_receipts", max_length=512, split="train", task_start_token="<s_receipt>", prompt_end_token="</s>" ) # 训练参数（实测最优值） training_args = TrainingArguments( output_dir="./donut-finetuned", per_device_train_batch_size=2, # RTX 3090最大安全值 per_device_eval_batch_size=1, # 验证时显存更紧张 gradient_accumulation_steps=4, # 模拟batch_size=8，解决小批量不稳定 num_train_epochs=10, # 少于8轮欠拟合，多于12轮过拟合 warmup_ratio=0.1, # 前10%步数线性升温，防初期震荡 learning_rate=3e-5, # Donut解码器敏感，>5e-5必发散 adam_beta2=0.999, # 官方推荐，提升收敛稳定性 fp16=True, # 必开！节省40%显存，加速30% save_strategy="epoch", evaluation_strategy="epoch", logging_steps=5, save_total_limit=2, remove_unused_columns=False, # 关键！Donut需要原始图像列 push_to_hub=False, report_to="none", # 关闭W&B，避免网络超时 ) # 初始化Trainer trainer = Trainer( model=model, args=training_args, train_dataset=train_dataset, eval_dataset=eval_dataset, tokenizer=processor, # Donut用processor当tokenizer ) trainer.train()

关键参数解析：gradient_accumulation_steps=4意味着模型每4个batch才更新一次权重，这相当于用小批量模拟大批量，既保证显存不爆，又让梯度更稳定。learning_rate=3e-5是Donut的黄金值——我试过2e-5（收敛慢）、4e-5（loss曲线剧烈抖动），只有3e-5能让loss从12.5平稳降到2.1。fp16=True不是可选项，是必需项，否则RTX 3090会在第3个epoch直接OOM。

3.4 自定义数据集类：解决图像加载的“最后一公里”

Hugging Face的datasets库无法直接加载图像+JSON对，必须自定义DonutDataset类。这个类要处理三件事：图像解码、JSON序列化、prompt拼接。以下是精简版核心代码（完整版见GitHub仓库）：

from datasets import Dataset from PIL import Image import torch class DonutDataset(torch.utils.data.Dataset): def __init__(self, dataset_name, max_length, split, task_start_token, prompt_end_token): self.dataset = load_dataset(dataset_name, split=split) # 加载HuggingFace数据集 self.max_length = max_length self.task_start_token = task_start_token self.prompt_end_token = prompt_end_token def __len__(self): return len(self.dataset) def __getitem__(self, idx): sample = self.dataset[idx] # 1. 加载并预处理图像 image = Image.open(sample["image_path"]).convert("RGB") pixel_values = processor(image, random_padding=False).pixel_values # Donut专用预处理 # 2. 构建prompt："<s_receipt><s_answer>...JSON...</s>" json_string = json.dumps(sample["ground_truth"], ensure_ascii=False) prompt = f"{self.task_start_token}{self.prompt_end_token}{json_string}" # 3. 编码prompt（注意：Donut用processor.encode，非tokenizer） labels = processor.tokenizer( prompt, add_special_tokens=False, max_length=self.max_length, padding="max_length", truncation=True, return_tensors="pt" ).input_ids return { "pixel_values": torch.tensor(pixel_values), "labels": labels.squeeze(0) # 移除batch维度 }

这个类的关键在于processor(image)——Donut的DonutProcessor会自动将图像转为pixel_values张量，并做归一化（mean=[0.5,0.5,0.5], std=[0.5,0.5,0.5]）。如果你用transforms.ToTensor()手动处理，会导致输入分布不匹配，训练loss永远卡在10以上。

3.5 推理与后处理：把模型输出变成真正可用的数据

训练完的模型输出是token ID序列，需解码为JSON。但Donut的输出常含噪音，必须后处理：

def inference(model, processor, image_path): # 1. 图像预处理 image = Image.open(image_path).convert("RGB") pixel_values = processor(image, return_tensors="pt").pixel_values # 2. 生成（关键参数：no_repeat_ngram_size防重复） task_prompt = "<s_receipt>" decoder_input_ids = processor.tokenizer( task_prompt, add_special_tokens=False, return_tensors="pt" ).input_ids outputs = model.generate( pixel_values, decoder_input_ids=decoder_input_ids, max_length=processor.tokenizer.model_max_length, 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, # Donut用贪婪搜索比beam search更准 bad_words_ids=[[processor.tokenizer.unk_token_id]], # 禁用<unk> no_repeat_ngram_size=3 # 防止"total total total"式重复 ) # 3. 解码并清洗 seq = processor.batch_decode(outputs, skip_special_tokens=True)[0] # 清洗：移除prompt头尾，修复JSON格式 seq = seq.replace(task_prompt, "").strip() try: result = json.loads(seq) return result except json.JSONDecodeError: # JSON解析失败时，用正则提取关键字段（保底方案） import re result = {} result["total_amount"] = re.search(r'"total_amount"\s*:\s*"([^"]+)"', seq) result["date"] = re.search(r'"date"\s*:\s*"([^"]+)"', seq) return {k: v.group(1) if v else "" for k, v in result.items()} # 使用示例 result = inference(model, processor, "./test_receipt.jpg") print(json.dumps(result, indent=2, ensure_ascii=False))

实操心得：num_beams=1（贪婪搜索）比num_beams=3准确率高7%，因为Donut的解码器在小样本上容易被beam search带偏。no_repeat_ngram_size=3能有效防止“amount amount amount”这种灾难性重复。后处理中的正则保底方案，是我们在线上服务中必备的“安全阀”，哪怕模型崩了，也能返回部分关键字段。

4. 常见问题与避坑指南：那些文档里不会写的实战真相

4.1 “Loss不下降”问题排查：90%的情况是数据路径错了

这是新手最常遇到的“幽灵bug”。训练启动后，loss恒定在12.5左右，几小时不动。别急着调学习率！先检查三件事：

诊断命令：在训练前加一行print(next(iter(train_dataset)))，确认输出的pixel_values是torch.Size([3, 1280, 1800])，labels是torch.Size([512])。如果不是，问题一定出在数据集类。

4.2 “CUDA Out of Memory”终极解决方案

即使batch_size=1也OOM？试试这四个组合拳：

1. 降分辨率：Donut支持最小输入尺寸768x1024。在DonutDataset.__getitem__中，把processor(image)改为processor(image, size={"height": 1024, "width": 768})，显存占用立降35%；
2. 关掉梯度检查点：Donut默认开启gradient_checkpointing=True，但它在小图像上反而增加显存。在TrainingArguments中添加gradient_checkpointing=False；
3. 用CPU offload：在Trainer初始化时传入args=training_args, data_collator=collator，其中collator把pixel_values移到CPU，只在forward时加载到GPU；
4. 终极手段：量化。用bitsandbytes库对解码器做4-bit量化：

   from bitsandbytes import quantize_model model.decoder = quantize_model(model.decoder, quant_type="bnb.nn.Linear4bit")

我们用这四招，把RTX 3060（12GB）的极限batch_size从1提升到4，训练速度反增12%。

4.3 字段识别不准？可能是prompt设计没对齐

Donut对prompt极其敏感。如果你发现"total_amount"总被识别成"subtotal"，不是模型问题，是prompt没教对。正确做法：

• 在JSON模板中，把"total_amount"字段放在"subtotal"之后，强制模型学习顺序；
• 在DonutDataset.__getitem__中，把prompt构造为：

  prompt = f"{self.task_start_token}<s_answer>{{'total_amount': '{sample['total_amount']}'}}</s>"

  而不是直接拼整个JSON。这样模型聚焦学习单字段，再逐步扩展。

我们有个客户，小票的“合计”字样被印在红色印章上，OCR永远识别错。改用单字段prompt后，准确率从42%飙升至91%——因为模型不再被其他字段干扰，专攻“红色区域+数字”的视觉模式。

4.4 部署到生产环境：Flask API的轻量级封装

训练好的模型要集成到报销系统，用Flask写个API最简单：

from flask import Flask, request, jsonify from PIL import Image import io app = Flask(__name__) # 全局加载模型（避免每次请求都加载） model = VisionEncoderDecoderModel.from_pretrained("./donut-finetuned") processor = DonutProcessor.from_pretrained("./donut-finetuned") @app.route('/extract', methods=['POST']) def extract_receipt(): if 'image' not in request.files: return jsonify({"error": "No image provided"}), 400 image_file = request.files['image'] image = Image.open(io.BytesIO(image_file.read())).convert("RGB") # 推理（加超时保护） try: result = inference(model, processor, image) # 复用前述inference函数 return jsonify(result) except Exception as e: return jsonify({"error": f"Inference failed: {str(e)}"}), 500 if __name__ == '__main__': app.run(host='0.0.0.0', port=5000, debug=False) # 生产环境关debug

部署时注意：用gunicorn启动，worker数设为CPU核心数，每个worker内存限制2GB。我们线上服务QPS稳定在12（RTX 3090），平均响应时间380ms，完全满足财务系统需求。

5. 进阶技巧与场景扩展：让Donut成为你的业务引擎

5.1 多语言小票支持：只需替换prompt token

Donut原生支持多语言，但需要微调prompt。比如处理日文小票，把task_start_token从"<s_receipt>"改为"<s_receipt_ja>"，并在训练时加入日文JSON样本。我们为一家跨国零售客户做了中/英/日三语支持，方法很简单：在DonutDataset中，根据图像文件名后缀（_cn.jpg,_en.jpg,_jp.jpg）动态切换prompt，模型自动学会区分。无需重新训练，只需在原有checkpoint上继续微调5个epoch。

5.2 手写体增强：用StyleGAN3合成训练数据

小票手写部分识别率低？别收集真实手写数据——太慢。用StyleGAN3生成合成手写体。我们训练了一个轻量StyleGAN3（仅2层生成器），输入是打印体文本（如“青椒 ￥6.50”），输出是带自然笔迹、墨水晕染的手写图。生成1000张后，微调Donut，手写字段F1从58%提升至83%。关键技巧：生成时加入“纸张纹理”和“轻微旋转”，让合成数据更接近真实扫描件。

5.3 与RPA流程集成：用UiPath调用Donut API

财务机器人（RPA）需要结构化数据。在UiPath中，用“HTTP Request”活动调用/extract接口，返回JSON后，用“Deserialize JSON”活动转为字典，再用“Excel Application Scope”写入报销表。我们帮客户实现了“员工拍照→RPA调用Donut→自动填入SAP报销单”的全自动流程，报销处理时效从2天缩短至15分钟。

5.4 持续学习机制：当新小票格式出现时怎么办？

业务永远在变。上周客户新增了电子发票二维码，Donut不认识。我们的方案是：

1. 用ZBar库从图像中定位二维码区域；
2. 把二维码截图作为新样本，标注{"qr_code_data": "https://invoice.xxx.com/12345"}；
3. 用LoRA（Low-Rank Adaptation）技术，只训练0.1%的参数，1小时完成增量微调。
   这套机制让模型始终保持对新格式的适应力，客户再也不用等我们“升级模型”。

我个人在实际操作中发现，Donut的价值不在技术多炫酷，而在它把一个原本需要3个工程师（OCR专家+规则引擎开发+前端对接）的项目，压缩成1个懂Python的业务分析师就能交付。上周我帮朋友的小餐馆上线扫码记账，从拍第一张小票到APP里显示“今日营收¥2,348”，总共用了4小时17分钟——其中3小时52分钟在等模型训练，剩下15分钟写了个微信小程序前端。技术终将退场，而解决实际问题的快感，永远新鲜。