kinyeah/BiMai-Chaoshu-OCR

筆脈 BiMai · Chaosu OCR

古籍直排草書／行草辨識 · Classical Chinese Cursive OCR

_{以 QLoRA 微調 Qwen3-VL-8B，輸出乾淨的繁體字串；搭配工作台可逐欄校對、整本書匯出。}

基準	原版 Qwen3-VL-8B	筆脈 v16	改善
字準 Accuracy	64.4%	72.2%	+7.8 pt
錯字率 CER	35.6%	27.8%	−21.9%（相對）

---

⚡ 快速開始 · Quick Start

# 1) 下載本 repo 的兩個檔案
#    caoshu-v16-merged-Q4_K_M.gguf      4.7 GB
#    caoshu-v16-merged-mmproj-F16.gguf  1.1 GB

# 2) 啟動（單檔，免 --lora）
llama-server -m caoshu-v16-merged-Q4_K_M.gguf \
  --mmproj caoshu-v16-merged-mmproj-F16.gguf \
  --host 127.0.0.1 --port 8800 --ctx-size 8192 --jinja

# 3) 送一張直列裁切圖
curl -s http://127.0.0.1:8800/v1/chat/completions -H 'Content-Type: application/json' -d '{
  "model": "default", "temperature": 0,
  "messages": [{"role":"user","content":[
    {"type":"text","text":"只根據圖中可見筆畫逐字釋讀。禁止默寫唐詩或名帖全文。只輸出你確實看見的繁體字，看不清就停。"},
    {"type":"image_url","image_url":{"url":"data:image/png;base64,<BASE64>"}}
  ]}]}'

輸入：單一直列（上→下）裁切圖，建議短邊 ≥ 300px、長邊 ≤ 3200px 輸出：連續繁體字串，無標點 提示詞：請與上方完全一致（訓練時即用此提示詞）

想換模型版本／自行合併？展開看兩種載入方式

# A. 合併單檔（推薦：最省事）
llama-server -m caoshu-v16-merged-Q4_K_M.gguf \
  --mmproj caoshu-v16-merged-mmproj-F16.gguf ...

# B. 基底 + LoRA（可隨時換版本、可續訓）
llama-server -m Qwen3-VL-8B-Instruct-Q4_K_M.gguf \
  --mmproj caoshu-v16-merged-mmproj-F16.gguf \
  --lora  caoshu-v16-lora-f16.gguf ...

基底模型 GGUF 可用 unsloth/Qwen3-VL-8B-Instruct-GGUF 的 Q4_K_M。

---

📦 檔案 · Files

檔案	大小	用途
caoshu-v16-merged-Q4_K_M.gguf	4.7 GB	推薦：基底＋v16 LoRA 已合併，單檔直接載入
caoshu-v16-merged-mmproj-F16.gguf	1.1 GB	對應視覺投影器（llama.cpp 恆為獨立檔）
caoshu-v16-lora-f16.gguf	175 MB	同一模型的 LoRA（換版／續訓用）
caoshu-v14-lora-f16.gguf	87 MB	上一世代（CER 28.7%）
caoshu-v13-lora-f16.gguf	174 MB	第三世代（CER 29.6%）
caoshu-v8-lora-f16.gguf	84 MB	初版（CER 34.7%）
caoshu-v8-merged-Q4_K_M.gguf	4.7 GB	v8 合併版（歷史存檔）
caoshu-v8-merged-mmproj-F16.gguf	1.1 GB	v8 用視覺投影器

---

📊 效能 · Benchmarks

基準：gold_test40 — 40 欄手工核對、331 字、無污染（訓練流程內建守門，洩漏必須為 0）。 量測方式：貪婪解碼（temperature=0）、同一提示詞、同一裁切圖、LCS 逐欄 CER。

與原版比較

模型	字準	CER	逐欄中位	≥80% 欄	<50% 欄
原版 Qwen3-VL-8B-Instruct（無 LoRA）	64.4%	35.6%	65.2	9 / 40	9 / 40
筆脈 v8（首次微調）	65.3%	34.7%	—	—	—
筆脈 v16（本模型）	72.2%	27.8%	75.0	13 / 40	4 / 40

微調把錯字率從 35.6% 壓到 27.8%（相對 −21.9%）；讀得很差的欄位由 9 欄降到 4 欄。 改善集中在生僻字與連筆字，並抑制原版「默寫名帖／跳字成句」的傾向。

版本演進

版本	CER	字準	訓練列數	變更
v8	34.7%	65.3%	1,215	初版微調
v13	29.6%	70.4%	1,965	資料淨化（移除 42 條洩漏列）＋新資料
v14	28.7%	71.3%	2,140	持續擴充語料
v15	29.0%	71.0%	2,347	深挖批次（1）
v16	27.8%	72.2%	2,708	修正資料路徑、首次吃滿全量深挖資料
v17	28.4%	71.6%	2,918	深挖批次（2）— 回退，顯示飽和
v18	29.3%	70.7%	2,583	標註加嚴 sim≥0.78 — 回退
32B 實驗	44.4%	—	—	過擬合，已棄用

🔬 深入分析：候選集上界（oracle）與人機協作

每欄取 10 個樣本（1 貪婪 + 9 取樣），取其中最好的一條可達 CER 22.19%（字準 77.8%）—— 說明正確讀法多半已在模型分佈中，缺的是「挑出正確那條」的選擇器。

我們實測並排除了四種自動選擇器：

選擇器	結果
置信度加權投票（vote_w）	27.5%（噪聲內，無顯著增益）
取最高置信度樣本（best_conf）	受控實驗 −1.2 pt，正式管線無效
4-gram 語言模型重排	+1.8 pt（有害）
跨模型集成（v13/v14/v16）	+2.8 pt（有害）
LLM 當驗證器	+1.6 pt（有害）

因此工作台改為 每欄顯示 2 條替代讀法、由使用者一鍵選用，並以「候選歧異度」標記 ⚠ 待校欄位， 把上界轉化為實際校對效率：人只需看一眼挑一個，而非重新打字。

---

🧭 建議用法 · Recommended Workflow

PDF / 書影 ──▶ 直列偵測 ──▶ 逐欄辨識 ──▶ 逐欄校對 ──▶ 全書匯出
              (切成一欄一條)    (本模型)      (人工挑選替代讀法)

1. 整頁直接餵模型效果較差（易跳字、易默寫）；請先切成單欄長條
2. 逐欄辨識的結果可定位、可校對，錯誤不會擴散到整頁
3. 搭配筆脈工作台（mochiocr 套件）可讀入 PDF／圖片夾／單圖路徑／網址圖／本機檔案， 逐欄確認狀態並整本書匯出

工作台介面示意（每欄）

[ 原圖裁切 ]
欄 @x402  ⚠ 待校                    ← 候選不一致時標紅
┌──────────────────┐
│ 春風吹白蘋醉上碧岩堯 │              ← 可直接編輯
└──────────────────┘
其他可能讀法（點選採用）：
  [ 春風吹白蘋醉上碧岩毫 ]
  [ 春風吹白鷴醉上碧岩毫 ]
        [ 標記已確認 ]

頁面上方統計：本頁 12 欄 · ✓ 已確認 3 · ⚠ 待校 5

---

🏋️ 訓練資料 · Training Data

項目	內容
語料規模	2,778 列直列裁切圖＋釋文（v16 使用 2,708 列）
來源	公開博物館數位典藏（含故宮書法名品釋文）＋ 私人收藏掃描頁
品質控管	DP 對照 + 品質閘門（相似度 sim ≥ 0.7）；金樣集列永不入訓練
配方	QLoRA：r=32、lr=2e-5、2 epochs、bf16 合併
硬體	單張 NVIDIA GPU（8B／2,700 列約 1 小時／輪）

資料飽和現象（重要）

資料量 1,215 → 2,918 列（+140%）只換得 CER 34.7% → 27.8%，且：

• v17（+210 列）→ 28.4%（回退）
• v18（標註加嚴 sim≥0.78，減 125 列）→ 29.3%（回退）

結論：在此語料範圍內「資料量」與「標註潔淨度」兩種槓桿皆已飽和。 若要再顯著下降，需要人工校訂的標註或不同技術路線。

---

⚠️ 限制 · Limitations

情境	表現
工整行草、常用字	良好（76–100% 字準）
狂草、連筆嚴重	錯誤率明顯上升，務必人工校對
拓本（碑帖黑白拓片）	未支援
雙行夾註版式	未支援
印刷體古籍	非訓練風域（可用但非特化）

本模型輸出僅供研究與輔助；出版或學術引用前請務必人工校對。

---

📄 授權 · Licence

• 模型權重：沿用基底模型 Qwen/Qwen3-VL-8B-Instruct 授權（Apache-2.0 兼容條款）
• 周邊程式碼（工作台／前處理管線）：MIT
• 使用即表示同意自行承擔辨識結果之校對責任

---

🇬🇧 English summary

BiMai · Chaosu OCR — LoRA adapters (and merged GGUF) for Qwen3-VL-8B, finetuned to transcribe vertical cursive (caoshu) and semi-cursive classical Chinese handwriting.

Results on a clean 40-column holdout (331 chars, greedy decoding, same prompt):

Model	Accuracy	CER
Original Qwen3-VL-8B-Instruct (no LoRA)	64.4%	35.6%
BiMai v16 (this model)	72.2%	27.8%

→ CER reduced by 21.9% relative (−7.8 points); median column accuracy 65.2% → 75.0%.

Usage: load caoshu-v16-merged-Q4_K_M.gguf + caoshu-v16-merged-mmproj-F16.gguf in llama.cpp, feed one vertical column crop per request, and use the exact prompt shown above.

Oracle note: best-of-10 samples reaches 22.19% CER, i.e. the correct reading is usually present in the model's distribution. Four automatic selectors (confidence voting, 4-gram LM reranking, cross-model ensemble, LLM-as-verifier) all failed to beat greedy decoding, so the companion workbench surfaces two alternative readings per column for one-click human selection.

Limitations: wild cursive, rubbings, interlinear annotations and printed pages are unreliable. Always proofread before publication. Weights inherit the base model licence (Apache-2.0 compatible).