Donutとは?
(画像は、Geminiで作成)
文書の画像から、OCR を使わずに直接 JSON を生成する Donut を部品ごとに PyTorch で実装し、公式の学習済みの重みを読み込んで Hugging Face の実装と同じトークン列を生成することを確かめること。JSON をタグの列にして生成する仕組みと、評価の指標(木の編集距離の正解率と F1)を理解し、事前学習だけのモデルから追加学習を自分で書いて、公式のモデルの精度を再現できるようになること。
参考資料: OCR-free Document Understanding Transformer (Kim et al., ECCV 2022)。公式の実装は clovaai/donut(MIT)、本記事で使う学習済みの重みは Hugging Face の naver-clova-ix/donut-base と naver-clova-ix/donut-base-finetuned-cord-v2(どちらも MIT)です。
概要
レシートや請求書の画像から「商品名」「数量」「合計金額」のような項目を取り出す処理は、これまで 2 段階で行うのが普通でした。まず OCR(文字の位置の検出と、文字の認識)で画像の中の文字を読み、次に読んだ文字を項目に分類します。この方法には、OCR のモデルを別に用意する手間と計算がかかること、OCR の読み間違いが後の処理にそのまま伝わることという弱点があります。
Donut(Document Understanding Transformer、NAVER CLOVA, 2022)は、OCR を使わずに、文書の画像から直接、項目と値を表すトークンの列を生成するモデルです。画像のエンコーダ(Swin Transformer)と、テキストのデコーダ(mBART)だけからなる Encoder-Decoder で(基本の構成はTransformer の記事)、生成したトークンの列をそのまま JSON に戻せます。
- 事前学習: 文書の画像に書かれた文字を、左上から順に読み上げるタスクで学習します(合成の文書画像 SynthDoG と、実際の文書画像 IIT-CDIP)。
- 追加学習: レシートの項目を取り出す、文書を分類する、文書についての質問に答える、といったタスクごとに、正解の JSON をタグの列にして学習します。タスクはデコーダに最初に入れるプロンプトのトークンで切り替えます。
本記事では、まず Hugging Face の実装で、事前学習だけのモデルと追加学習したモデルの出力を比べ、仕組みを図で整理したうえで、Donut をスクラッチで実装します。公式の重みで Hugging Face と同じトークン列を生成することを確かめ、レシートのデータセット CORD のテストデータで、論文と同じ指標で精度を測ります。最後に、事前学習だけのモデルから、公式と同じ設定の追加学習を自分で書いて、公式のモデルの精度を再現します。
事前学習だけのモデルと、追加学習したモデル
準備:Google Colab の GPU で動かす
本記事のコードは、Google Colab の A100 GPU で実行しました。「ランタイム」→「ランタイムのタイプを変更」から A100 GPU を選んでください(Colab の有料プランが必要です)。最後の実験4の追加学習は、A100 で約 27 分(30 エポック、1 エポック約 54 秒)かかります。追加学習は GPU のメモリを約 38 GB 使うので、メモリが 40 GB 以上の GPU が必要です。
新しいセッションで、次を実行してください。zss は、実験3の評価で木の編集距離を計算するライブラリです。transformers(比較用の Donut)と datasets(CORD の読み込み)は Colab に最初から入っています。グラフの日本語表示には japanize-matplotlib を使い、Python 3.12 以降で import 時にエラーが出ないよう setuptools も入れます。
!pip install -q zss japanize-matplotlib setuptools
推論に利用するデータ
本記事では、インドネシアのレシートのデータセット CORD(v2、CC BY 4.0)を使います。学習 800 枚・検証 100 枚・テスト 100 枚のレシートの画像に、商品名・数量・価格・合計金額などの正解の JSON が付いています。Hugging Face の naver-clova-ix/cord-v2 から、コードの中で読み込みます。
実験1:同じレシートを、2 つのモデルに入れる
Hugging Face の実装で、CORD のテストデータの 1 枚を、事前学習だけのモデル(donut-base)と、CORD で追加学習したモデル(donut-base-finetuned-cord-v2)に入れます。
import json
import time
import numpy as np
import torch
import matplotlib.pyplot as plt
import japanize_matplotlib
from datasets import load_dataset
from transformers import DonutProcessor, VisionEncoderDecoderModel
device = "cuda"
cord = load_dataset("naver-clova-ix/cord-v2") # 学習 800 枚・検証 100 枚・テスト 100 枚のレシート
ex = cord["test"][21]
image = ex["image"].convert("RGB")
# 同じレシートを、事前学習だけのモデル(文字を読む)と、CORD で追加学習したモデル(JSON を出す)に入れる
runs = [("事前学習だけ", "naver-clova-ix/donut-base", "<s_synthdog>"),
("CORD で追加学習", "naver-clova-ix/donut-base-finetuned-cord-v2", "<s_cord-v2>")]
for name, model_id, prompt in runs:
processor = DonutProcessor.from_pretrained(model_id)
hf_model = VisionEncoderDecoderModel.from_pretrained(model_id).to(device).eval()
pixel_values = processor(image, return_tensors="pt").pixel_values.to(device)
prompt_ids = processor.tokenizer(prompt, add_special_tokens=False, return_tensors="pt").input_ids.to(device)
with torch.no_grad():
out = hf_model.generate(pixel_values, decoder_input_ids=prompt_ids, max_length=768,
eos_token_id=processor.tokenizer.eos_token_id, pad_token_id=processor.tokenizer.pad_token_id)
seq = processor.batch_decode(out)[0]
print(f"[{name}] 入力 {tuple(pixel_values.shape[2:])}、プロンプト {prompt}")
print(seq, "\n")
# 追加学習したモデルのタグの列を JSON に戻す
seq = seq.replace(processor.tokenizer.eos_token, "").replace("<s_cord-v2>", "")
print("JSON:", json.dumps(processor.token2json(seq), ensure_ascii=False))
print("正解:", json.dumps(json.loads(ex["ground_truth"])["gt_parse"], ensure_ascii=False))
plt.figure(figsize=(4.5, 6))
plt.imshow(image)
plt.axis("off")
plt.show()
- プロンプト: デコーダに最初に入れるトークンで、タスクを決めます。<s_synthdog> は事前学習の「文字を読む」タスク、<s_cord-v2> は CORD の追加学習で足したタスクのトークンです。
- 入力の大きさ: 事前学習のモデルは 2560×1920、CORD のモデルは 1280×960 の画像を入力にします(どちらも、それぞれのプロセッサの設定です)。
- max_length=768: 生成するトークンの数の上限で、CORD のモデルの位置埋め込みの数です。
- token2json: 生成した <s_menu><s_nm>…</s_nm> のようなタグの列を、辞書とリストに戻します。
実行結果
[事前学習だけ] 入力 (2560, 1920)、プロンプト <s_synthdog>
<s_synthdog> 1 35. 000 NASI G0R SFD TLR 1 3. 000 ES TEH TAWAR Rp35. 000 Rr3. 000 ***T0TAL <unk> ASH CHANGE Rr3B . 000 Rp50. 000 Rp12. 000</s>
[CORD で追加学習] 入力 (1280, 960)、プロンプト <s_cord-v2>
<s_cord-v2><s_menu><s_nm> NASI GOR SFD TLR</s_nm><s_unitprice> 35.000</s_unitprice><s_cnt> 1</s_cnt><s_price> Rp 35.000</s_price><sep/><s_nm> ES TEH TAWAR</s_nm><s_unitprice> 3.000</s_unitprice><s_cnt> 1</s_cnt><s_price> Rp 3.000</s_price></s_menu><s_total><s_total_price> Rp 38.000</s_total_price><s_cashprice> Rp 50.000</s_cashprice><s_changeprice> Rp 12.000</s_changeprice></s_total></s>
JSON: {"menu": [{"nm": "NASI GOR SFD TLR", "unitprice": "35.000", "cnt": "1", "price": "Rp 35.000"}, {"nm": "ES TEH TAWAR", "unitprice": "3.000", "cnt": "1", "price": "Rp 3.000"}], "total": {"total_price": "Rp 38.000", "cashprice": "Rp 50.000", "changeprice": "Rp 12.000"}}
正解: {"menu": [{"nm": "NASI GOR SFD TLR", "unitprice": "35.000", "cnt": "1", "price": "Rp 35.000"}, {"nm": "ES TEH TAWAR", "unitprice": "3.000", "cnt": "1", "price": "Rp 3.000"}], "total": {"total_price": "Rp 38.000", "cashprice": "Rp 50.000", "changeprice": "Rp 12.000"}}

(画像は、CORD v2(CC BY 4.0)のテストデータの 1 枚)
- 事前学習だけのモデル: レシートの文字を、そのまま読み上げました。「NASI G0R」(O をゼロと読んだ)、「T0TAL」、「Rr3. 000」のような読み間違いがあり、どの数字が何の金額かという区別もありません。事前学習は「画像の文字を順に読む」タスクだからです。
- CORD で追加学習したモデル: 同じ画像から、商品ごとの名前・単価・数量・価格と、合計・支払い・お釣りの金額を、タグの列で出しました。JSON に戻すと、正解の JSON と完全に一致しました。
同じ構造のモデルでも、追加学習で「何を、どの形で出すか」を教えれば、OCR を使わずに項目の抽出ができます。読み上げでは間違えていた「NASI GOR」や「Rp 38.000」も、追加学習したモデルは正しく読んでいます。
Donut の仕組み
全体の構成
Donut の全体は、次の図のとおりです(図は、後で実装する Donut クラスの構成です)。
(図は、diagram-designで作成)
- エンコーダ: Swin Transformer(Swin-B)で、画像を 1,200 個(40×30)の 1024 次元の特徴にします。
- デコーダ: mBART(多言語の BART)の最初の 4 層を使います。画像の特徴にクロス注意をかけながら、トークンを 1 つずつ生成します。
- 出力: 生成したトークンの列のうち、<s_キー> と </s_キー> で囲まれた部分を、JSON のキーと値に戻します。
エンコーダ:Swin Transformer
(図は、diagram-designで作成)
Swin Transformer の仕組みは、Swin Transformer の記事で詳しく説明しています。Donut の Swin-B は、画像分類の Swin-B と次の点が違います。
- 窓の大きさが 10: 画像分類の Swin(7)より大きな窓で、文書の細かい文字のまとまりを見ます。
- 大きな入力: 1280×960(事前学習は 2560×1920)の画像を、そのまま入れます。絶対位置の埋め込みがないので、入力の大きさを変えても、同じ重みで動きます。
- 最後の LayerNorm とプーリングがない: 1,200 個の特徴を、そのままデコーダに渡します。
デコーダ:mBART の 4 層
(図は、diagram-designで作成)
- 埋め込み: 単語の埋め込みに を掛け、位置の埋め込みを足して、LayerNorm をかけます。mBART の位置の埋め込みは、番号を 2 ずらして表から取り出します(Hugging Face の mBART と同じ)。
- デコーダの層: 前のトークンだけを見る自己注意 → 画像の特徴へのクロス注意 → FFN の順に、各部分の前に LayerNorm をかけ、後に残差を足します(Pre-LN)。
- 出力層: 単語の埋め込みと同じ重みで、次のトークンの logit を出します。
- 生成: 確率が最大のトークンを選んで足すこと(貪欲法)を、</s> が出るまでくり返します。自己注意の K・V は、トークンを足すたびに計算し直さず、保存しておいて使い回します(KV キャッシュ)。
JSON とトークンの列
(図は、diagram-designで作成)
- JSON からトークンの列へ: キーを <s_キー> と </s_キー> で囲み、リストの要素を <sep/> で区切ります。キーのタグは、1 つの特殊トークンとして語彙に足します。
- 学習: 正解のトークンの列をデコーダに入れ、各位置で 1 つ先のトークンを予測するクロスエントロピーで学習します(teacher forcing)。普通の言語モデルと同じ損失です。
- トークンの列から JSON へ: 生成したタグの列を、入れ子の辞書とリストに戻します。
Donut のスクラッチ実装
ここからは、Donut を部品ごとに実装します。部品の構造・次元・計算の順番は、Hugging Face の VisionEncoderDecoderModel(DonutSwinModel と MBartForCausalLM)と同じにしています。実験2で、学習済みの重みを読み込み、同じトークン列を生成することを確かめます。
エンコーダ
import math
import re
import torch.nn as nn
import torch.nn.functional as F
# ===== 画像エンコーダ:Swin Transformer(Donut 版) =====
def window_partition(x, ws):
"""(B, H, W, C) を、ws×ws の窓を並べた (B*窓の数, ws*ws, C) にする"""
B, H, W, C = x.shape
x = x.view(B, H // ws, ws, W // ws, ws, C)
return x.permute(0, 1, 3, 2, 4, 5).reshape(-1, ws * ws, C)
def window_reverse(windows, ws, H, W):
"""window_partition の逆"""
C = windows.shape[-1]
B = windows.shape[0] // ((H // ws) * (W // ws))
x = windows.view(B, H // ws, W // ws, ws, ws, C)
return x.permute(0, 1, 3, 2, 4, 5).reshape(B, H, W, C)
def shift_mask(H, W, ws, shift, device):
"""巡回シフトで貼り合わされた、元の画像では離れている位置の組に -100 を入れる (窓の数, N, N)"""
h_reg = (torch.arange(H, device=device) >= H - ws).long() + (torch.arange(H, device=device) >= H - shift).long()
w_reg = (torch.arange(W, device=device) >= W - ws).long() + (torch.arange(W, device=device) >= W - shift).long()
region = (h_reg[:, None] * 3 + w_reg[None, :]).float()[None, :, :, None] # 9 つの領域に番号を付ける
mw = window_partition(region, ws).squeeze(-1)
diff = mw[:, None, :] - mw[:, :, None]
return diff.masked_fill(diff != 0, -100.0)
class WindowAttention(nn.Module):
def __init__(self, dim, heads, ws):
super().__init__()
self.heads, self.ws = heads, ws
self.qkv = nn.Linear(dim, dim * 3)
self.proj = nn.Linear(dim, dim)
self.relative_position_bias_table = nn.Parameter(torch.zeros((2 * ws - 1) ** 2, heads))
c = torch.stack(torch.meshgrid(torch.arange(ws), torch.arange(ws), indexing="ij")).flatten(1)
rel = (c[:, :, None] - c[:, None, :]).permute(1, 2, 0) + (ws - 1) # (N, N, 2) の (dy, dx) を 0 始まりに
self.register_buffer("rel_index", rel[..., 0] * (2 * ws - 1) + rel[..., 1], persistent=False)
def forward(self, x, mask=None): # x: (B*窓の数, N, C)
Bw, N, C = x.shape
q, k, v = self.qkv(x).reshape(Bw, N, 3, self.heads, -1).permute(2, 0, 3, 1, 4)
attn = (q * q.shape[-1] ** -0.5) @ k.transpose(-2, -1)
attn = attn + self.relative_position_bias_table[self.rel_index].permute(2, 0, 1)[None]
if mask is not None:
nW = mask.shape[0]
attn = (attn.view(Bw // nW, nW, self.heads, N, N) + mask[None, :, None]).view(Bw, self.heads, N, N)
return self.proj((attn.softmax(-1) @ v).transpose(1, 2).reshape(Bw, N, C))
class SwinBlock(nn.Module):
def __init__(self, dim, heads, ws=10, shift=0):
super().__init__()
self.ws, self.shift = ws, shift
self.norm1, self.norm2 = nn.LayerNorm(dim), nn.LayerNorm(dim)
self.attn = WindowAttention(dim, heads, ws)
self.fc1, self.fc2 = nn.Linear(dim, 4 * dim), nn.Linear(4 * dim, dim)
def forward(self, x): # x: (B, H, W, C)
B, H, W, C = x.shape
ws, shift = self.ws, self.shift
if min(H, W) <= ws: # 特徴マップが窓より小さければ、全体を 1 つの窓にする
ws, shift = min(H, W), 0
h = self.norm1(x)
ph, pw = (-H) % ws, (-W) % ws # 窓の大きさで割り切れなければ、右と下を 0 で埋める
h = F.pad(h, (0, 0, 0, pw, 0, ph))
Hp, Wp = H + ph, W + pw
if shift > 0:
h = torch.roll(h, (-shift, -shift), (1, 2))
mask = shift_mask(Hp, Wp, ws, shift, x.device).to(x.dtype) if shift > 0 else None
h = window_reverse(self.attn(window_partition(h, ws), mask), ws, Hp, Wp)
if shift > 0:
h = torch.roll(h, (shift, shift), (1, 2))
x = x + h[:, :H, :W]
return x + self.fc2(F.gelu(self.fc1(self.norm2(x))))
class PatchMerging(nn.Module):
def __init__(self, dim):
super().__init__()
self.norm = nn.LayerNorm(4 * dim)
self.reduction = nn.Linear(4 * dim, 2 * dim, bias=False)
def forward(self, x):
x = F.pad(x, (0, 0, 0, x.shape[2] % 2, 0, x.shape[1] % 2)) # 奇数なら 1 行・1 列を埋める
x = torch.cat([x[:, 0::2, 0::2], x[:, 1::2, 0::2], x[:, 0::2, 1::2], x[:, 1::2, 1::2]], -1)
return self.reduction(self.norm(x))
class SwinEncoder(nn.Module):
"""Donut のエンコーダ:Swin-B(窓 10、深さ 2・2・14・2)。最後の LayerNorm とプーリングはない"""
def __init__(self, embed_dim=128, depths=(2, 2, 14, 2), heads=(4, 8, 16, 32), ws=10):
super().__init__()
self.patch_embed = nn.Conv2d(3, embed_dim, 4, 4)
self.patch_norm = nn.LayerNorm(embed_dim)
self.stages = nn.ModuleList()
self.downsamples = nn.ModuleList()
for i, (d, h) in enumerate(zip(depths, heads)):
dim = embed_dim * 2 ** i
self.stages.append(nn.Sequential(*[SwinBlock(dim, h, ws, 0 if j % 2 == 0 else ws // 2) for j in range(d)]))
if i < len(depths) - 1:
self.downsamples.append(PatchMerging(dim))
def forward(self, x): # x: (B, 3, H, W)
x = self.patch_norm(self.patch_embed(x).permute(0, 2, 3, 1))
for i, stage in enumerate(self.stages):
x = stage(x)
if i < len(self.downsamples):
x = self.downsamples[i](x)
return x.flatten(1, 2) # (B, H/32 × W/32, 1024)
- shift_mask: 窓を巡回シフトすると、元の画像では離れていた位置が同じ窓に入ります。縦と横をそれぞれ 3 つの領域に分けて番号を付け、番号が違う位置の組の注意に -100 を足して、見ないようにします。
- 窓で割り切れないとき: 窓の大きさで割り切れない特徴は、右と下を 0 で埋めてから窓に分け、注意の後で切り落とします。1280×960 の入力では割り切れますが、実験3で入力の大きさを変えるときに必要です。
- PatchMerging: 2×2 の隣り合う 4 つの位置を並べて 4 倍のチャンネルにし、LayerNorm と線形層で 2 倍のチャンネルにします。縦か横が奇数なら、1 行・1 列を 0 で埋めます。
- 深さ(2, 2, 14, 2)とヘッド(4, 8, 16, 32): Swin-B の設定で、Donut の公式の設定です。
デコーダ
# ===== テキストデコーダ:mBART の 4 層 =====
class MHA(nn.Module):
def __init__(self, dim=1024, heads=16):
super().__init__()
self.heads = heads
self.q_proj, self.k_proj, self.v_proj, self.out_proj = (nn.Linear(dim, dim) for _ in range(4))
def split(self, t):
return t.view(t.shape[0], t.shape[1], self.heads, -1).transpose(1, 2)
def forward(self, x, k, v, causal=False): # k, v は split 済み (B, heads, L, d)
q = self.split(self.q_proj(x))
o = F.scaled_dot_product_attention(q, k, v, is_causal=causal)
return self.out_proj(o.transpose(1, 2).reshape(x.shape[0], x.shape[1], -1))
class DecoderLayer(nn.Module):
def __init__(self, dim=1024, heads=16, ffn=4096):
super().__init__()
self.self_attn, self.encoder_attn = MHA(dim, heads), MHA(dim, heads)
self.self_attn_layer_norm, self.encoder_attn_layer_norm, self.final_layer_norm = (nn.LayerNorm(dim) for _ in range(3))
self.fc1, self.fc2 = nn.Linear(dim, ffn), nn.Linear(ffn, dim)
def forward(self, x, cross_kv, cache=None):
h = self.self_attn_layer_norm(x)
k, v = self.self_attn.split(self.self_attn.k_proj(h)), self.self_attn.split(self.self_attn.v_proj(h))
if cache is not None: # 生成中は、これまでのトークンの K・V を足して使い回す
if "k" in cache:
k, v = torch.cat([cache["k"], k], 2), torch.cat([cache["v"], v], 2)
cache["k"], cache["v"] = k, v
x = x + self.self_attn(h, k, v, causal=(x.shape[1] > 1))
x = x + self.encoder_attn(self.encoder_attn_layer_norm(x), *cross_kv)
return x + self.fc2(F.gelu(self.fc1(self.final_layer_norm(x))))
class Decoder(nn.Module):
def __init__(self, vocab=57580, dim=1024, layers=4, heads=16, ffn=4096, max_pos=768):
super().__init__()
self.embed_scale = math.sqrt(dim) # 単語の埋め込みに √d を掛ける(scale_embedding)
self.embed_tokens = nn.Embedding(vocab, dim)
self.embed_positions = nn.Embedding(max_pos + 2, dim) # mBART は位置の番号を 2 ずらして使う
self.layernorm_embedding = nn.LayerNorm(dim)
self.layers = nn.ModuleList(DecoderLayer(dim, heads, ffn) for _ in range(layers))
self.layer_norm = nn.LayerNorm(dim)
self.lm_head = nn.Linear(dim, vocab, bias=False)
self.lm_head.weight = self.embed_tokens.weight # 出力層は、単語の埋め込みと同じ重みを使う(共有)
def cross_kv(self, enc):
"""エンコーダの出力の K・V は、生成の最初に 1 回だけ計算する"""
return [(l.encoder_attn.split(l.encoder_attn.k_proj(enc)), l.encoder_attn.split(l.encoder_attn.v_proj(enc))) for l in self.layers]
def forward(self, ids, cross, caches=None, start=0):
pos = torch.arange(start, start + ids.shape[1], device=ids.device) + 2
x = self.layernorm_embedding(self.embed_tokens(ids) * self.embed_scale + self.embed_positions(pos))
for i, layer in enumerate(self.layers):
x = layer(x, cross[i], None if caches is None else caches[i])
return self.lm_head(self.layer_norm(x))
- MHA: PyTorch の scaled_dot_product_attention で注意を計算します。K・V は外で作って渡すので、自己注意の KV キャッシュと、クロス注意の K・V の使い回しを同じ部品で書けます。
- cross_kv: エンコーダの 1,200 個の特徴から、各層のクロス注意の K・V を、生成の最初に 1 回だけ計算します。
- causal=(x.shape[1] > 1): 複数のトークンを一度に入れるとき(学習と、生成の最初のプロンプト)は因果マスクをかけます。生成中に 1 つずつ入れるときは、キャッシュの全トークンを見てよいのでマスクは要りません。
- embed_positions: 位置の番号に 2 を足して表から取り出すので、表の大きさは最大の長さ + 2 です。
モデル全体
class Donut(nn.Module):
def __init__(self, vocab=57580, max_pos=768):
super().__init__()
self.encoder = SwinEncoder()
self.decoder = Decoder(vocab=vocab, max_pos=max_pos)
def forward(self, pixel_values, ids):
"""学習用:正解のトークン列を入れて、次のトークンの logit を一度に出す(teacher forcing)"""
enc = self.encoder(pixel_values)
return self.decoder(ids, self.decoder.cross_kv(enc))
@torch.no_grad()
def generate(self, pixel_values, prompt_ids, eos_id, max_len=768):
"""貪欲法:毎回、確率が最大のトークンを選んで足す。K・V のキャッシュで、新しいトークンだけを計算する"""
cross = self.decoder.cross_kv(self.encoder(pixel_values))
caches = [{} for _ in self.decoder.layers]
ids = prompt_ids
logits = self.decoder(ids, cross, caches, 0)
for _ in range(max_len - prompt_ids.shape[1]):
nxt = logits[:, -1].argmax(-1, keepdim=True)
ids = torch.cat([ids, nxt], 1)
if (nxt == eos_id).all():
break
logits = self.decoder(nxt, cross, caches, ids.shape[1] - 1)
return ids
model = Donut()
count = lambda m: sum(p.numel() for p in m.parameters())
print(f"エンコーダ(Swin-B): {count(model.encoder):>12,}")
print(f"デコーダ(mBART 4 層): {count(model.decoder):>12,}")
print(f" うち単語の埋め込み : {model.decoder.embed_tokens.weight.numel():>12,}")
print(f"全体 : {count(model):>12,}")
- forward: 学習用です。正解のトークン列を一度に入れて、各位置の次のトークンの logit を出します。
- generate: 推論用です。プロンプトを入れた後、確率が最大のトークンを 1 つずつ足します。</s>(eos_id)が出るか、768 個に達したら止めます。
実行結果
エンコーダ(Swin-B): 74,180,728
デコーダ(mBART 4 層): 126,941,184
うち単語の埋め込み : 58,961,920
全体 : 201,121,912
パラメータは約 2 億 112 万個で、エンコーダ(Swin-B)が約 7,418 万個、デコーダが約 1 億 2,694 万個です。デコーダの半分近く(約 5,896 万個)は、57,580 語の単語の埋め込みです。mBART は多言語のモデルなので語彙が大きく、層の数(4 層)に比べて埋め込みが大きくなっています。
実験2:公式の重みで、Hugging Face と同じトークン列を生成するか
公式の重みの読み込み
def load_hf_donut(model, sd):
"""Hugging Face の VisionEncoderDecoderModel(Donut)の重みを、スクラッチ実装の名前に付け替えて読み込む"""
out = {}
for k, v in sd.items():
n = k
n = n.replace("encoder.embeddings.patch_embeddings.projection.", "encoder.patch_embed.")
n = n.replace("encoder.embeddings.norm.", "encoder.patch_norm.")
n = re.sub(r"^encoder\.encoder\.layers\.(\d+)\.blocks\.(\d+)\.", r"encoder.stages.\1.\2.", n)
n = re.sub(r"^encoder\.encoder\.layers\.(\d+)\.downsample\.", r"encoder.downsamples.\1.", n)
n = n.replace("layernorm_before.", "norm1.").replace("layernorm_after.", "norm2.")
n = n.replace("attention.output.dense.", "attn.proj.").replace("attention.self.relative_position_bias_table", "attn.relative_position_bias_table")
n = n.replace("intermediate.dense.", "fc1.").replace("output.dense.", "fc2.")
n = n.replace("decoder.model.decoder.", "decoder.")
if n.startswith("decoder.lm_head") or "relative_position_index" in n:
continue # lm_head は埋め込みと同じ重み(共有)、位置の番号は計算で作る
out[n] = v
for k in list(out): # Hugging Face は Q・K・V を別々の層で持つので、1 つにまとめる
m = re.match(r"(encoder\.stages\.\d+\.\d+\.)attention\.self\.query\.(weight|bias)", k)
if m:
p, t = m.groups()
out[f"{p}attn.qkv.{t}"] = torch.cat([out.pop(f"{p}attention.self.{n}.{t}") for n in ("query", "key", "value")])
out["decoder.lm_head.weight"] = out["decoder.embed_tokens.weight"]
missing, unexpected = model.load_state_dict(out, strict=False)
assert not missing and not unexpected, (missing[:5], unexpected[:5])
return model
- 名前の付け替え: Hugging Face の重みの名前を、スクラッチ実装の名前に置き換えます。Hugging Face の Swin は Q・K・V を別々の線形層で持つので、1 つの qkv の層にまとめます。
- 読み込まない重み: relative_position_index は重みではなく、窓の中の位置の組の番号で、スクラッチ実装では計算で作ります。lm_head は単語の埋め込みと同じ重みです。
出力の一致を確かめる
model = load_hf_donut(Donut(), hf_model.state_dict()).to(device).eval()
eos_id = processor.tokenizer.eos_token_id
def timed(fn, n=5):
"""GPU の処理が終わるのを待って、n 回の平均の時間(秒)を測る"""
fn()
torch.cuda.synchronize()
t0 = time.time()
for _ in range(n):
out = fn()
torch.cuda.synchronize()
return out, (time.time() - t0) / n
with torch.no_grad():
enc_hf = hf_model.encoder(pixel_values).last_hidden_state
enc_me = model.encoder(pixel_values)
print(f"エンコーダの出力 {tuple(enc_me.shape)}:差の最大値 {(enc_hf - enc_me).abs().max().item():.2e}(値の最大 {enc_hf.abs().max().item():.0f})")
gen_hf, t_hf = timed(lambda: hf_model.generate(pixel_values, decoder_input_ids=prompt_ids, max_length=768,
eos_token_id=eos_id, pad_token_id=processor.tokenizer.pad_token_id))
gen_me, t_me = timed(lambda: model.generate(pixel_values, prompt_ids, eos_id))
print(f"生成したトークン列:HF {gen_hf.shape[1]} 個、スクラッチ {gen_me.shape[1]} 個、一致 {torch.equal(gen_hf, gen_me)}")
logit_hf = hf_model(pixel_values=pixel_values, decoder_input_ids=gen_hf).logits
logit_me = model(pixel_values, gen_hf)
print(f"同じトークン列を入れたときの logit の差の最大値 {(logit_hf - logit_me).abs().max().item():.2e}")
print(f"1 枚の処理時間(エンコーダ+生成):HF {t_hf * 1000:.0f} ms、スクラッチ {t_me * 1000:.0f} ms")
- エンコーダの出力: 同じ画像を入れて、1,200 個の特徴を比べます。
- 生成したトークン列: 実験1と同じレシートで、Hugging Face の generate(貪欲法)とスクラッチ実装の generate が、同じトークン列を出すかを比べます。
- logit: 同じトークン列を一度に入れて(teacher forcing)、各位置の logit を比べます。
- 処理時間: 5 回の平均で、エンコーダと生成を合わせた 1 枚の時間を測ります。
実行結果
エンコーダの出力 (1, 1200, 1024):差の最大値 8.79e-04(値の最大 177)
生成したトークン列:HF 62 個、スクラッチ 62 個、一致 True
同じトークン列を入れたときの logit の差の最大値 1.18e-04
1 枚の処理時間(エンコーダ+生成):HF 364 ms、スクラッチ 254 ms
- エンコーダの出力: 差の最大値は 8.79e-04 でした。特徴の値は最大で 177 と大きいので、相対的には 1e-5 程度の、計算の順番の違いによる誤差です。
- 生成したトークン列: Hugging Face もスクラッチ実装も 62 個のトークンを生成し、すべて一致しました。
- logit: 同じトークン列を入れたときの差の最大値は 1.18e-04 でした。
スクラッチ実装の計算は、Hugging Face と同じです。処理時間は、スクラッチ実装(254 ms)の方が Hugging Face(364 ms)より短くなりました。スクラッチ実装は貪欲法だけに絞った短い生成のループで、Hugging Face の generate は多くの生成方法に対応するための処理を含むためと考えられます。
タグの列を JSON に戻す
def token2json(seq):
"""<s_key>値</s_key> の入れ子のタグの列を、辞書とリストに戻す(<sep/> はリストの区切り)"""
out = {}
while seq:
start = re.search(r"<s_(.*?)>", seq)
if start is None:
break
key = start.group(1)
end = re.search(rf"</s_{re.escape(key)}>", seq)
if end is None: # 閉じタグがなければ、その開きタグを捨てて続ける
seq = seq.replace(start.group(), "", 1)
continue
inner = seq[start.end():end.start()]
if re.search(r"<s_.*?>", inner): # 中にタグがあれば、入れ子の辞書(<sep/> で区切ればリスト)
items = [token2json(part) for part in inner.split("<sep/>")]
items = [it for it in items if it]
if items:
out[key] = items[0] if len(items) == 1 else items
else: # 葉の値(<sep/> で区切ればリスト)
vals = [v.strip() for v in inner.split("<sep/>") if v.strip()]
if vals:
out[key] = vals[0] if len(vals) == 1 else vals
seq = seq[end.end():]
return out
mine = token2json(seq)
print(json.dumps(mine, ensure_ascii=False))
print("Hugging Face の token2json と同じ:", mine == processor.token2json(seq))
- 探し方: 先頭から <s_キー> を探し、同じキーの </s_キー> までを、そのキーの中身とします。
- 入れ子とリスト: 中身にさらにタグがあれば入れ子の辞書として同じ処理をくり返し、<sep/> で区切られていればリストにします。
- 閉じタグがないとき: 生成が途中で止まったときなどは、開きタグを捨てて続けます。
実行結果
{"menu": [{"nm": "NASI GOR SFD TLR", "unitprice": "35.000", "cnt": "1", "price": "Rp 35.000"}, {"nm": "ES TEH TAWAR", "unitprice": "3.000", "cnt": "1", "price": "Rp 3.000"}], "total": {"total_price": "Rp 38.000", "cashprice": "Rp 50.000", "changeprice": "Rp 12.000"}}
Hugging Face の token2json と同じ: True
自前の token2json は、Hugging Face の token2json と同じ辞書を返しました。
実験3:CORD のテストデータで、精度を測る
評価の指標
論文と同じ 2 つの指標で、予測した JSON と正解の JSON を比べます。
import zss
def edit_distance(a, b):
"""文字列の編集距離(挿入・削除・置換を 1 回 1 と数える)"""
d = list(range(len(b) + 1))
for i, ca in enumerate(a, 1):
prev, d[0] = d[0], i
for j, cb in enumerate(b, 1):
prev, d[j] = d[j], min(d[j] + 1, d[j - 1] + 1, prev + (ca != cb))
return d[-1]
def normalize(data):
"""キーを(長さ, 文字列)の順に並べ、値をすべてリストにする(公式の評価と同じ)"""
if not data:
return {}
if isinstance(data, dict):
out = {}
for k in sorted(data, key=lambda k: (len(k), k)):
v = normalize(data[k])
if v:
out[k] = v if isinstance(v, list) else [v]
return out
if isinstance(data, list):
if all(isinstance(x, dict) for x in data):
return [n for n in (normalize(x) for x in data) if n]
return [str(x).strip() for x in data if isinstance(x, (str, int, float)) and str(x).strip()]
return [str(data).strip()]
def flatten(data, key=""):
"""{"menu": [{"nm": ["A"]}]} を [("menu.nm", "A")] のような(項目, 値)の組の列にする"""
if isinstance(data, dict):
return [p for k, v in data.items() for p in flatten(v, f"{key}.{k}" if key else k)]
if isinstance(data, list):
return [p for v in data for p in flatten(v, key)]
return [(key, data)]
def f1_score(preds, answers):
"""項目単位の F1:(項目, 値)の組が正解に完全に一致すれば正解として数える"""
tp, fn_fp = 0, 0
for p, a in zip(preds, answers):
p, a = flatten(normalize(p)), flatten(normalize(a))
for field in p:
if field in a:
tp += 1
a.remove(field)
else:
fn_fp += 1
fn_fp += len(a)
return tp / (tp + fn_fp / 2)
def to_tree(data, name="<root>"):
"""辞書を木にする。リストの各要素の辞書は <subtree>、値は <leaf>値 のノードにする"""
node = zss.Node(name)
if isinstance(data, dict):
for k, v in data.items():
node.addkid(to_tree(v, k))
elif all(isinstance(x, dict) for x in data):
for x in data:
node.addkid(to_tree(x, "<subtree>"))
else:
for x in data:
node.addkid(zss.Node(f"<leaf>{x}"))
return node
def ins_del_cost(node):
return len(node.label[6:]) if node.label.startswith("<leaf>") else 1
def update_cost(a, b):
la, lb = a.label.startswith("<leaf>"), b.label.startswith("<leaf>")
if la and lb:
return edit_distance(a.label[6:], b.label[6:])
if la or lb:
return 1 + len((a.label if la else b.label)[6:])
return int(a.label != b.label)
def ted_accuracy(pred, answer):
"""木の編集距離を、空の予測から正解までの距離で割り、1 から引く(0 未満は 0)"""
dist = lambda x, y: zss.distance(x, y, zss.Node.get_children, ins_del_cost, ins_del_cost, update_cost)
t_ans = to_tree(normalize(answer))
return max(0.0, 1 - dist(to_tree(normalize(pred)), t_ans) / dist(to_tree(normalize({})), t_ans))
- F1(項目単位): JSON を「menu.nm = NASI GOR」のような(項目, 値)の組の列にし、正解と完全に一致した組を正解として数えます。値が 1 文字でも違えば不正解です。100 枚の全体で数えます。
- TED accuracy(木の編集距離の正解率): JSON を木にし、予測の木を正解の木に変えるのに必要な操作(ノードの挿入・削除・書き換え)の重みの合計を求めます。値の書き換えの重みは、文字列の編集距離です。空の予測から正解までの距離で割って 1 から引くので、正解と同じなら 1、何も出せなければ 0 になります。1 枚ごとに計算して平均します。値の少しの読み間違いは少しだけ減点されるので、F1 より甘い指標です。
- normalize: キーの並び順と、値が 1 つかリストかの違いで減点しないよう、キーを並べ替え、値をすべてリストにします(公式の評価と同じ)。
前処理
from PIL import Image, ImageOps
import torchvision.transforms.functional as TF
IMAGENET_MEAN, IMAGENET_STD = (0.485, 0.456, 0.406), (0.229, 0.224, 0.225)
def fit(image, size=(1280, 960)):
"""公式の前処理の前半:短い辺を min(size) にしてから、size(高さ, 幅)に収まるよう縮める"""
H, W = size
img = TF.resize(image.convert("RGB"), min(H, W))
img.thumbnail((W, H))
return img
def pad_normalize(img, size=(1280, 960), random_padding=False, mean=IMAGENET_MEAN, std=IMAGENET_STD):
"""公式の前処理の後半:余白を黒で埋めて size にし、ImageNet の平均と標準偏差で正規化する"""
H, W = size
dw, dh = W - img.width, H - img.height
if random_padding: # 学習では、画像を置く位置をランダムにずらす
left, top = np.random.randint(0, dw + 1), np.random.randint(0, dh + 1)
else:
left, top = dw // 2, dh // 2
img = ImageOps.expand(img, (left, top, dw - left, dh - top))
return TF.normalize(TF.to_tensor(img), mean, std)
def prepare(image, size=(1280, 960), **kw):
return pad_normalize(fit(image, size), size, **kw)
def predict(model, images, size, prompt_ids, tokenizer, **kw):
"""画像ごとに生成し、タグの列を JSON に戻す。1 枚あたりの時間も返す"""
preds, t = [], 0.0
for img in images:
x = prepare(img, size, **kw)[None].to(device)
torch.cuda.synchronize()
t0 = time.time()
ids = model.generate(x, prompt_ids, tokenizer.eos_token_id)
torch.cuda.synchronize()
t += time.time() - t0
seq = tokenizer.decode(ids[0, prompt_ids.shape[1]:]).replace(tokenizer.eos_token, "")
preds.append(token2json(seq))
return preds, t / len(images)
- 公式の前処理: 公式の実装(prepare_input)と同じく、短い辺を 960 にしてから 1280×960 に収まるよう縮め、余白を黒で埋めて真ん中に置きます。
- 正規化: 公式の実装は、ImageNet の平均(0.485, 0.456, 0.406)と標準偏差(0.229, 0.224, 0.225)で正規化します。Hugging Face のプロセッサは、平均と標準偏差をどちらも 0.5 にしています。
- fit と pad_normalize: 縮める処理と余白を埋める処理を分けています。実験4の学習で、縮める処理を先に 1 回だけ行うためです。
4 つの設定で評価する
test_images = [ex["image"] for ex in cord["test"]]
answers = [json.loads(ex["ground_truth"])["gt_parse"] for ex in cord["test"]]
settings = [("1280×960(公式の前処理)", (1280, 960), {}),
("1280×960(平均・標準偏差 0.5)", (1280, 960), dict(mean=(0.5,) * 3, std=(0.5,) * 3)),
("960×720", (960, 720), {}),
("640×480", (640, 480), {})]
results = {}
for name, size, kw in settings:
preds, sec = predict(model, test_images, size, prompt_ids, processor.tokenizer, **kw)
acc = np.mean([ted_accuracy(p, a) for p, a in zip(preds, answers)])
results[name] = preds
print(f"{name:<28s} TED accuracy {acc * 100:.1f} F1 {f1_score(preds, answers) * 100:.1f} {sec * 1000:.0f} ms/枚")
- 1280×960(公式の前処理): 公式の実装と同じ前処理です。
- 1280×960(平均・標準偏差 0.5): Hugging Face のプロセッサと同じ正規化です。正規化の違いが精度にどう効くかを確かめます。
- 960×720・640×480: 入力を小さくします。OCR を使わないモデルが、文字の小ささにどれだけ左右されるかを確かめます。縦横の比は 1280×960 と同じ 4 : 3 です。
実行結果
1280×960(公式の前処理) TED accuracy 88.5 F1 80.6 289 ms/枚
1280×960(平均・標準偏差 0.5) TED accuracy 87.9 F1 80.1 289 ms/枚
960×720 TED accuracy 76.8 F1 70.6 311 ms/枚
640×480 TED accuracy 65.0 F1 51.8 384 ms/枚
- 公式の前処理(1280×960): TED accuracy 88.5、F1 80.6 でした。論文の値(TED accuracy 90.9、F1 84.1)と公式の README の値(TED accuracy 91.3)より、少し低い値です。公式の推論は、生成で未知語のトークン <unk> を出さないよう禁止しています。本記事のコードには含めていませんが、Hugging Face の generate で bad_words_ids を指定して同じように禁止すると、100 枚で 15 個出ていた <unk> がなくなり、TED accuracy は 89.1 に上がりました(F1 は 80.6 のまま)。残りの差の原因は調べていません。
- 平均・標準偏差 0.5(Hugging Face と同じ正規化): TED accuracy 87.9、F1 80.1 で、公式の前処理との差は 1 ポイント未満でした。正規化の違いは、精度にはほとんど効きません。
- 入力を小さくする: 960×720 では TED accuracy 76.8・F1 70.6、640×480 では 65.0・51.8 と、大きく下がりました。OCR を使わない Donut は、画像の画素から直接文字を読むので、文字が小さくつぶれると読めなくなります。1280×960 で学習したモデルを、小さな入力で使うことも精度を下げます。
- 処理時間: 入力を小さくしても、1 枚の時間は短くなりませんでした(289 ms → 311 ms・384 ms)。エンコーダの計算は減りますが、読み間違えると同じ項目をくり返し生成するなど、生成するトークンが増えるためと考えられます。
Donut の精度は、入力の解像度に大きく左右されます。小さな文字を読むために、文書のモデルは画像分類のモデル(224×224 など)よりずっと大きな入力を使います。
実験4:事前学習だけのモデルから、追加学習を再現する
事前学習だけのモデル(donut-base)から、CORD の学習データで追加学習し、公式の追加学習済みモデルの精度を再現します。
実装方針:公式の追加学習との違い
| 項目 | 公式の追加学習(config/train_cord.yaml) | 本記事 |
|---|---|---|
| 初期の重み | donut-base(SynthDoG と IIT-CDIP で、文字を読む事前学習をしたモデル) | 同じ |
| データ | CORD v2 の学習 800 枚 | 同じ |
| 入力 | 1280×960、学習では画像を置く位置をランダムにずらす | 同じ |
| 最大のトークン数 | 768(位置埋め込みを 768 に切る) | 同じ |
| 最適化 | Adam、学習率 3e-5、最初の 300 回でウォームアップしてコサインで 0 まで下げる、勾配のクリップ 1.0 | 同じ |
| エポック・バッチ | 30 エポック、バッチ 8 | 同じ |
| 新しいトークンの埋め込み | transformers の resize_token_embeddings で増やす(初期値は transformers の版で異なる) | 既存の全単語の埋め込みの平均から始める(版によらず同じ結果にするため) |
| 計算の精度 | float16 の混合精度(precision=16) | bfloat16 の混合精度(A100 が対応しており、損失のスケーリングが要らないため) |
| 検証 | 3 エポックごとに検証データで評価 | なし(最後にテストデータで 1 回だけ評価する) |
学習データの準備
import math
import random
base_processor = DonutProcessor.from_pretrained("naver-clova-ix/donut-base")
tok = base_processor.tokenizer
def json2token(obj):
"""JSON を <s_key>値</s_key> のタグの列にする(キーの順番は CORD のまま。リストは <sep/> で区切る)"""
if isinstance(obj, dict):
return "".join(f"<s_{k}>{json2token(v)}</s_{k}>" for k, v in obj.items())
if isinstance(obj, list):
return "<sep/>".join(json2token(v) for v in obj)
return str(obj)
def keys_of(obj):
if isinstance(obj, dict):
return set(obj) | set().union(*(keys_of(v) for v in obj.values()))
if isinstance(obj, list):
return set().union(*(keys_of(v) for v in obj)) if obj else set()
return set()
train_parses = [json.loads(ex["ground_truth"])["gt_parse"] for ex in cord["train"]]
keys = set().union(*(keys_of(p) for p in train_parses))
new_tokens = ["<s_cord-v2>"] + [f"<s_{k}>" for k in sorted(keys)] + [f"</s_{k}>" for k in sorted(keys)]
n_added = tok.add_special_tokens({"additional_special_tokens": new_tokens})
print(f"CORD のキー {len(keys)} 種類、追加したトークン {n_added} 個、語彙 {len(tok):,}")
train_ids = [tok("<s_cord-v2>" + json2token(p) + tok.eos_token, add_special_tokens=False).input_ids for p in train_parses]
lens = [len(t) for t in train_ids]
print(f"正解のトークン列の長さ:中央値 {int(np.median(lens))}、最大 {max(lens)}")
print("例:", tok.decode(train_ids[0])[:160], "...")
- json2token: 正解の JSON をタグの列にします。CORD の追加学習では、キーを並べ替えずに、正解の JSON のままの順番にします(公式の設定 sort_json_key: False)。
- 特殊トークン: 学習データに出てくるキーの開きタグと閉じタグ、タスクのトークン <s_cord-v2> を語彙に足します。<sep/> は事前学習のモデルの語彙に最初からあります。
- トークン列: <s_cord-v2> から始め、</s> で終わる列にします。
実行結果
CORD のキー 27 種類、追加したトークン 55 個、語彙 57,580
正解のトークン列の長さ:中央値 61、最大 375
例: <s_cord-v2><s_menu><s_nm> Nasi Campur Bali</s_nm><s_cnt> 1 x</s_cnt><s_price> 75,000</s_price><sep/><s_nm> Bbk Bengil Nasi</s_nm><s_cnt> 1 x</s_cnt><s_price> 12 ...
追加したトークンは 55 個で、公式の追加学習済みモデルの語彙(57,580)と同じ数になりました。正解のトークン列は最長でも 375 個で、上限の 768 に収まります。
学習
del hf_model, model # 学習の GPU のメモリを空けるため、比較用のモデルを消す
torch.cuda.empty_cache()
def new_model():
"""donut-base の重みを読み込み、追加したトークンの埋め込みを作り、位置埋め込みを 768 まで切る"""
base = VisionEncoderDecoderModel.from_pretrained("naver-clova-ix/donut-base")
sd = base.state_dict()
emb = sd["decoder.model.decoder.embed_tokens.weight"]
extra = emb.mean(0, keepdim=True).repeat(len(tok) - emb.shape[0], 1) # 新しいトークンは、全単語の平均から始める
sd["decoder.model.decoder.embed_tokens.weight"] = torch.cat([emb, extra])
sd["decoder.model.decoder.embed_positions.weight"] = sd["decoder.model.decoder.embed_positions.weight"][:768 + 2]
return load_hf_donut(Donut(vocab=len(tok), max_pos=768), sd).to(device)
train_fit = [fit(ex["image"]) for ex in cord["train"]] # 縮める処理は毎回同じなので、先に 1 回だけ行う
def make_batch(idx):
x = torch.stack([pad_normalize(train_fit[i], random_padding=True) for i in idx]).to(device)
L = max(len(train_ids[i]) for i in idx)
ids = torch.full((len(idx), L), tok.pad_token_id)
for j, i in enumerate(idx):
ids[j, :len(train_ids[i])] = torch.tensor(train_ids[i])
labels = ids[:, 1:].clone()
labels[labels == tok.pad_token_id] = -100 # 埋めた部分は損失に入れない
return x, ids[:, :-1].to(device), labels.to(device)
def train(epochs=30, batch=8, lr=3e-5, warmup=300):
torch.manual_seed(2022)
random.seed(2022)
np.random.seed(2022)
m = new_model().train()
opt = torch.optim.Adam(m.parameters(), lr=lr)
total = epochs * math.ceil(len(train_ids) / batch)
# 公式と同じ、線形のウォームアップの後にコサインで 0 まで下げる学習率
sched = torch.optim.lr_scheduler.LambdaLR(opt, lambda s: s / warmup if s < warmup else
0.5 * (1 + math.cos(math.pi * (s - warmup) / (total - warmup))))
history, t0 = [], time.time()
for ep in range(1, epochs + 1):
order = list(range(len(train_ids)))
random.shuffle(order)
losses = []
for k in range(0, len(order), batch):
x, inp, labels = make_batch(order[k:k + batch])
with torch.autocast("cuda", dtype=torch.bfloat16):
logits = m(x, inp)
# プロンプト(<s_cord-v2>)の次のトークンから、正解のトークン列を予測するクロスエントロピー
loss = F.cross_entropy(logits.float().reshape(-1, logits.shape[-1]), labels.reshape(-1), ignore_index=-100)
opt.zero_grad(set_to_none=True)
loss.backward()
torch.nn.utils.clip_grad_norm_(m.parameters(), 1.0)
opt.step()
sched.step()
losses.append(loss.item())
history.append(np.mean(losses))
if ep % 5 == 0 or ep == 1:
print(f"エポック {ep:2d} 損失 {history[-1]:.3f} ({time.time() - t0:.0f} 秒)", flush=True)
return m.eval(), history
ft_model, history = train()
- new_model: donut-base の重みを読み込み、増やした 55 個のトークンの埋め込みを、既存の全単語の埋め込みの平均から始めます。位置の埋め込みは、事前学習の 1,536 個から 768 個に切ります(公式の max_length: 768)。
- make_batch: 8 枚の画像に、ランダムな位置の余白を付けます。トークン列はバッチの中の最長に合わせて埋め、埋めた部分は損失に入れません(-100)。
- 損失: 入力の列を 1 つずらした列を正解にした、トークンごとのクロスエントロピーです。プロンプト <s_cord-v2> は入力の最初にだけ置き、予測の対象にはしません。
- 学習率: 公式と同じく、最初の 300 回(3 エポック分)で 0 から 3e-5 まで上げ、その後コサインで 0 まで下げます。勾配のノルムは 1.0 で切ります。
- 乱数の種 2022: 公式の設定(seed: 2022)と同じ値です。
実行結果
エポック 1 損失 8.899 (54 秒)
エポック 5 損失 0.400 (267 秒)
エポック 10 損失 0.079 (534 秒)
エポック 15 損失 0.026 (800 秒)
エポック 20 損失 0.007 (1067 秒)
エポック 25 損失 0.003 (1333 秒)
エポック 30 損失 0.003 (1600 秒)
追加学習の前と後を比べる
# 追加学習の前(donut-base に新しいトークンを足しただけ)・後・公式の追加学習済みのモデルを、テストの 100 枚で比べる
prompt_new = tok("<s_cord-v2>", add_special_tokens=False, return_tensors="pt").input_ids.to(device)
before_model = new_model().eval()
compare = {}
with torch.no_grad():
for name, m, p in [("追加学習の前", before_model, prompt_new), ("追加学習の後(本記事)", ft_model, prompt_new)]:
preds, sec = predict(m, test_images, (1280, 960), p, tok)
compare[name] = preds
acc = np.mean([ted_accuracy(q, a) for q, a in zip(preds, answers)])
print(f"{name:<22s} TED accuracy {acc * 100:.1f} F1 {f1_score(preds, answers) * 100:.1f}")
acc = np.mean([ted_accuracy(q, a) for q, a in zip(results["1280×960(公式の前処理)"], answers)])
print(f"{'公式の追加学習済みモデル':<22s} TED accuracy {acc * 100:.1f} F1 {f1_score(results['1280×960(公式の前処理)'], answers) * 100:.1f}(実験3)")
実行結果
追加学習の前 TED accuracy 0.0 F1 0.0
追加学習の後(本記事) TED accuracy 86.9 F1 80.6
公式の追加学習済みモデル TED accuracy 88.5 F1 80.6(実験3)
- 追加学習の前: TED accuracy と F1 はどちらも 0 でした。事前学習だけのモデルは、新しく足したトークン <s_cord-v2> もキーのタグも学習していないので、項目を表すタグの列を出せません(実験1のレシートでは、JSON に戻すと空でした)。
- 追加学習の後(本記事): TED accuracy 86.9、F1 80.6 になりました。公式の追加学習済みモデル(同じ評価で TED accuracy 88.5、F1 80.6)に対して、F1 は同じ、TED accuracy は 1.6 ポイント低い値です。
公式と同じ設定の 30 エポックの追加学習で、公式のモデルとほぼ同じ精度を再現できました。TED accuracy の差は、新しいトークンの埋め込みの初期値、計算の精度(bfloat16 と float16)、乱数による学習のばらつきなど、表の違いによるものと考えられます(どれが効いているかは調べていません)。
損失の推移と、出力の例
fig, ax = plt.subplots(figsize=(6, 3.6))
ax.plot(range(1, len(history) + 1), history, marker="o", ms=3)
ax.set_xlabel("エポック")
ax.set_ylabel("学習の損失(エポックの平均)")
ax.set_yscale("log")
ax.grid(alpha=0.3)
plt.tight_layout()
plt.show()
# 実験1のレシート(テストの 21 番)で、追加学習の前と後の出力を並べる
for name in compare:
print(f"[{name}]", json.dumps(compare[name][21], ensure_ascii=False))
print("[正解]", json.dumps(answers[21], ensure_ascii=False))
実行結果
[追加学習の前] {}
[追加学習の後(本記事)] {"menu": [{"nm": "NASI GOR SFD TLR", "unitprice": "35.000", "cnt": "1", "price": "Rp 35.000"}, {"nm": "ES TEH TAWAR", "unitprice": "3.000", "cnt": "1", "price": "Rp 3.000"}], "total": {"total_price": "Rp 38.000", "cashprice": "Rp 50.000", "changeprice": "Rp 12.000"}}
[正解] {"menu": [{"nm": "NASI GOR SFD TLR", "unitprice": "35.000", "cnt": "1", "price": "Rp 35.000"}, {"nm": "ES TEH TAWAR", "unitprice": "3.000", "cnt": "1", "price": "Rp 3.000"}], "total": {"total_price": "Rp 38.000", "cashprice": "Rp 50.000", "changeprice": "Rp 12.000"}}
学習の損失(エポックの平均、縦軸は対数)は、1 エポック目の 8.9 から、10 エポックで 0.079、30 エポックで 0.003 まで下がりました。最初の 3 エポック(300 回)は学習率を 0 から上げている途中ですが、その間に損失は 1.7 ほどまで下がっています。学習データに対する損失は、ほぼ 0 になっています。
実験1のレシートでは、追加学習の前は空の JSON でしたが、追加学習の後は正解と完全に一致する JSON を出しました。
まとめ
本記事では、Donut(Swin-B のエンコーダと mBART の 4 層のデコーダ)を部品ごとに PyTorch で実装し、次のことを確かめました。
- OCR を使わない項目の抽出: 事前学習だけのモデルは、レシートの文字を読み上げるだけでしたが、CORD で追加学習したモデルは、同じ画像から商品名・単価・数量・合計金額などの JSON を生成し、実験1のレシートでは正解と完全に一致しました。
- Hugging Face との一致: 公式の重みを読み込むと、エンコーダの出力の差は最大 8.79e-04(値の最大は 177)、生成した 62 個のトークン列は完全に一致し、logit の差は最大 1.18e-04 でした。
- CORD のテストデータの精度: 公式の前処理で TED accuracy 88.5、F1 80.6 でした。正規化の違い(ImageNet の平均と標準偏差か、0.5 か)は 1 ポイント未満の差でしたが、入力を 640×480 にすると TED accuracy 65.0、F1 51.8 まで下がり、文字を読むには大きな入力が必要なことが分かりました。
- 追加学習の再現: 事前学習だけのモデルから、公式と同じ設定(Adam、学習率 3e-5、30 エポック、バッチ 8)で追加学習すると、A100 で約 27 分で、TED accuracy 86.9、F1 80.6 になり、公式のモデル(88.5、80.6)とほぼ同じ精度を再現できました。
Donut は、「JSON をタグの列にして、画像を条件に言語モデルとして生成する」という単純な形で、OCR を使わない文書理解を実現しています。項目の種類やタスクを変えたいときは、正解の JSON を用意して、タグのトークンを足して追加学習すれば対応できます。
ライセンスに関する注記
Donut の公式の実装(clovaai/donut)と、Hugging Face の学習済みの重み(naver-clova-ix/donut-base、naver-clova-ix/donut-base-finetuned-cord-v2)は、MIT ライセンスで公開されています。MIT ライセンスは、商用利用・改変・再配布ができるライセンスで、再配布するときは著作権の表示とライセンスの全文を含めてください。CORD のデータセットは CC BY 4.0 で公開されており、利用するときは出典の表示が必要です。本記事の説明は一般的な解釈で、法的な助言ではありません。 実際に利用する場合は、ライセンスの条文を確認してください。
出典・ライセンスについて
- Donut の実装: 公式の clovaai/donut(MIT)と Hugging Face の transformers(Apache-2.0)の構造を参考に、スクラッチで実装しています。追加学習の設定と評価の指標は、公式の実装(config/train_cord.yaml、donut/util.py)に合わせています。
- 学習済みのモデル: naver-clova-ix/donut-base と naver-clova-ix/donut-base-finetuned-cord-v2(どちらも MIT)を使用しています。
- データ: CORD v2(CC BY 4.0、Park et al., 2019)を使用しています。実験1の画像は、CORD v2 のテストデータの 1 枚です。
@inproceedings{kim2022donut,
title = {OCR-free Document Understanding Transformer},
author = {Kim, Geewook and Hong, Teakgyu and Yim, Moonbin and Nam, JeongYeon and Park, Jinyoung and Yim, Jinyeong and Hwang, Wonseok and Yun, Sangdoo and Han, Dongyoon and Park, Seunghyun},
booktitle = {European Conference on Computer Vision (ECCV)},
year = {2022}
}
@inproceedings{park2019cord,
title = {CORD: A Consolidated Receipt Dataset for Post-OCR Parsing},
author = {Park, Seunghyun and Shin, Seung and Lee, Bado and Lee, Junyeop and Surh, Jaeheung and Seo, Minjoon and Lee, Hwalsuk},
booktitle = {Workshop on Document Intelligence at NeurIPS 2019},
year = {2019}
}
参考文献
- G. Kim et al. (2022). OCR-free Document Understanding Transformer. ECCV 2022.
- NAVER Clova. clovaai/donut. GitHub.
- NAVER Clova. naver-clova-ix/donut-base. Hugging Face.
- NAVER Clova. naver-clova-ix/donut-base-finetuned-cord-v2. Hugging Face.
- S. Park et al. (2019). CORD: A Consolidated Receipt Dataset for Post-OCR Parsing. NeurIPS 2019 Workshop on Document Intelligence.
本記事の文章・構成の一部に生成AIを使用しています。