README.md

---
license: apache-2.0
language:
- ja
base_model: Qwen/Qwen3-VL-2B-Instruct
library_name: mlx
pipeline_tag: image-text-to-text
tags:
- mlx
- japanese
- document-understanding
- invoice
- lora
---

# jp-invoice-reader-2b (MLX bf16 fused) — 日本語帳票リーダー

Qwen3-VL-2B-Instructを**合成日本語帳票データ（GT既知方式）でLoRA post-training**した、tokimoa初の自作派生モデルです。請求書・見積書・納品書・領収書の読み取り（QA・構造化JSON抽出）に特化しています。LoRA融合済みの単体モデル（4.0GB）で、そのまま`load()`で動きます。

**設計思想**: ベースの2B VLMは帳票の数値は読めるのに「請求元を聞くと宛先を答える」「表参照で回避回答する」など応答行動が未調教でした（実測で特定）。訓練データは自作ジェネレータで合成し（画像を自分で生成するのでGTが完全に既知）、この行動を狙い撃ちで矯正しています。

## 実測スコア（未見語彙の合成評価セット300枚: QA1,200問・抽出2,100フィールド）

| 構成 | ja-docs QA | 帳票QA | 抽出フィールド |
|---|---|---|---|
| ベース（Qwen3-VL-2B 4bit） | 5/6 | 52.7% | 0.3% |
| このモデル（fused bf16） | **6/6** | **93.5%** | **90.1%** |

- 評価は訓練と**語彙を完全分離**（会社名・品目の語幹レベルで分離）した未見データ
- 金額系はほぼ完璧（合計299/300・税295/300・明細293/300）。残る誤りは未見カタカナ社名の1文字誤読が中心
- 兄弟構成: [8bit](https://huggingface.co/tokimoa/jp-invoice-reader-2b-8bit)（2.5GB）/ [4bit+adapter](https://huggingface.co/tokimoa/jp-invoice-reader-2b-4bit-adapter)（**最高精度94.3%**・1.7GB）

## 使い方

```python
from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template
from mlx_vlm.utils import load_config

repo = "tokimoa/jp-invoice-reader-2b"
model, processor = load(repo)
config = load_config(repo)
prompt = apply_chat_template(processor, config, "この帳票から主要項目を抽出してJSONで出力してください。", num_images=1)
out = generate(model, processor, prompt, image=["invoice.png"], max_tokens=600, temperature=0.0)
print(out.text)
```

## 訓練情報

- ベース: `Qwen/Qwen3-VL-2B-Instruct`（Apache-2.0）
- データ: 自作合成帳票ジェネレータ（4帳票種×2レイアウト・会社名5,415種・768px低DPIスキャン相当）train 6,000枚/24,000ペア（抽出JSON1:QA3・発行元/宛先の役割問題を必須収録）
- 訓練: mlx-vlm QLoRA（rank 8・4bitベース・batch1×accum4・lr1e-4・6,000 iters・M4 Max単機約3.3時間）
- 制約: 手書き・特殊レイアウトは未検証です（スキャン・撮影劣化への耐性は下の頑健性節に実測があります）

## 入力劣化への頑健性（実測）

スキャン・スマホ撮影を模した劣化を同一評価セットに適用して実測しました（各条件30枚: QA120問・抽出210フィールド。劣化はGT不変の後段画像変換で、スキャン風=紙色・照明ムラ・微回転・JPEG再圧縮、スマホ撮影風=透視歪み・影・ブラー・強めのJPEG）。

| 入力条件 | ja-docs QA | 帳票QA | 抽出フィールド |
|---|---|---|---|
| クリーン | 6/6 | 95.0% | 89.5% |
| スキャン風劣化 | 6/6 | 94.2% | 85.7% |
| スマホ撮影風劣化 | 6/6 | 91.7% | 80.0% |

スキャナ経由の帳票はクリーン比4pt以内の低下で、そのまま実用域です。スマホ撮影は抽出が約10pt下がり、誤りは明細行・税額など小さい文字に集中します。撮影入力で使う場合は正対・影を避けた撮影が効きます。

## 更新履歴

- 2026-07-30: 入力劣化（スキャン風・スマホ撮影風）の頑健性実測を追加

## ライセンス

Apache-2.0（ベースモデルに準拠）

*Built with a synthetic-data pipeline where ground truth is known by construction — 検証方法・データ製法の詳細は追って技術記事で公開予定です。*