hataphu/PaddleOCR-VL-1.6-vi-gguf

PaddleOCR-VL-1.6 fine-tune tiếng Việt (v5) — bản GGUF

Đây là bản chuyển đổi sang định dạng GGUF của mô hình PaddlePaddle/PaddleOCR-VL-1.6 (~1 tỷ tham số) sau khi được fine-tune (LoRA) để nhận dạng chữ (OCR) tiếng Việt, dùng được với llama.cpp.

Danh sách file

File	Mô tả	Dung lượng
paddleocr-vl-1.6-vi-v5.bf16.gguf	Phần mô hình ngôn ngữ (đã merge trọng số LoRA), bf16	~933 MB
mmproj-paddleocr-vl-1.6-vi-v5.bf16.gguf	Phần vision encoder + projector (đọc ảnh), bf16	~882 MB

Cả 2 file đều cần thiết để chạy — thiếu file mmproj-* thì mô hình sẽ không "nhìn" được ảnh.

Quy trình huấn luyện

• Mô hình gốc: PaddleOCR-VL-1.6 — decoder ngôn ngữ ERNIE-4.5-0.3B + vision encoder dạng SigLIP + projector mlp_AR.
• Phương pháp: LoRA (rank=16, alpha=32, dropout=0.05) chỉ áp dụng lên self-attention/mlp của decoder ngôn ngữ và projector mlp_AR (không train vision encoder để tiết kiệm tài nguyên).
• Phần cứng: 1 GPU tiêu dùng 8GB VRAM (Turing, không có bf16 tensor core) — batch size 1, gradient accumulation, gradient checkpointing, bf16 thuần (fp16 gây NaN trên kiến trúc này).
• Dữ liệu:
  • Văn bản tiếng Việt tổng hợp dạng chữ in (synthetic): dòng chữ đơn render bằng PIL + font Noto + suy giảm ảnh ngẫu nhiên (mờ, nhiễu, nén JPEG, xoay nhẹ...) — ~40.000 mẫu train.
  • Đoạn văn tổng hợp nhiều câu dạng chữ in (synthetic đoạn dài): tương tự nhưng ghép nhiều câu thành đoạn văn xuống dòng, mô phỏng văn bản dạng đoạn dài — ~8.000 mẫu train.
  • Ảnh chữ viết tay thật (bộ dữ liệu công khai iAmHieu2012/vietnamese-ocr-dataset-aggregated) — ~3.000 mẫu train. Đính chính: tên bộ dữ liệu này gây hiểu nhầm là "chữ in" (printed), nhưng kiểm tra trực quan cho thấy toàn bộ là chữ viết tay (từ kiểu "in thường" rõ ràng đến chữ thảo nối nét). Vẫn giữ lại trong pipeline vì giúp mô hình học thêm khả năng đọc ảnh chụp/scan đời thực (không phải render sạch), nhưng không đại diện cho chữ in scan thật.
• Các phiên bản huấn luyện:
  1. v3: train trên dữ liệu synthetic dòng đơn — bị overfit nặng vào phong cách render tổng hợp, kém trên ảnh chụp/scan đời thực (chữ viết tay ở trên).
  2. v4: train tiếp (Phase 2) trên dữ liệu chữ viết tay thật — cải thiện rõ rệt độ chính xác trên ảnh đời thực.
  3. v5 (bản GGUF này): train tiếp từ v4, bổ sung dữ liệu đoạn văn dài tổng hợp (chữ in) + dữ liệu chữ viết tay thật.

Kết quả đánh giá (benchmark)

Đánh giá bằng suy luận tự hồi quy thực tế (không phải teacher-forcing), chỉ số CER (Character Error Rate) tính bằng thư viện jiwer.

Trên dữ liệu chữ in (synthetic + synthetic đoạn dài, 200 mẫu test)

Phiên bản	CER	Độ chính xác ký tự	Exact match
v5 (bản GGUF này)	0.0001	99.99%	99.5%

Trên đúng miền dữ liệu chữ in (font render sạch, không nhiễu nặng), mô hình gần như hoàn hảo — vượt xa mục tiêu 96%. Lưu ý: đây là tập test cùng pipeline render với dữ liệu train (không phải ảnh scan chữ in thật ngoài đời), nên số liệu có phần lạc quan hơn thực tế; xem phần "Hạn chế" bên dưới.

Trên dữ liệu chữ viết tay thật (100 mẫu test, iAmHieu2012)

Phiên bản	CER	Độ chính xác ký tự	Exact match
Mô hình gốc (zero-shot, chưa fine-tune)	~0.275	~72.5%	—
v3 (chỉ train synthetic chữ in)	0.2470	75.3%	0%
v4 (train thêm trên chữ viết tay thật)	0.1533	84.67%	6.0%
v5 (bản GGUF này)	0.1478	85.22%	9.0%

Phân tích theo độ dài văn bản (v5): dòng ngắn (địa chỉ, <100 ký tự) đạt CER 0.095 (90.5%), đoạn dài nhiều câu (≥100 ký tự) đạt CER 0.165 (83.5%) — nhận dạng chữ viết tay dạng đoạn dài vẫn là điểm yếu nhất.

Mục tiêu và hạn chế

Mục tiêu ban đầu của dự án là đạt 96% độ chính xác ký tự cho văn bản in tiếng Việt. Trên dữ liệu chữ in tổng hợp, mô hình đã vượt mục tiêu này (99.99%). Tuy nhiên:

• Dữ liệu "chữ in thật" (ảnh scan thật, không phải render tổng hợp) hiện chưa có trong quá trình huấn luyện — bộ dữ liệu thật duy nhất đang dùng (iAmHieu2012) hoá ra là chữ viết tay, không phải chữ in. Do đó con số 99.99% chưa được xác nhận trên ảnh scan chữ in thật ngoài đời (font lạ, nhiễu scan thật, độ phân giải thấp...).
• Khả năng đọc chữ viết tay (85.22%) là một "phần thưởng" phụ có được từ việc lỡ dùng nhầm bộ dữ liệu, không phải mục tiêu chính — nhận dạng chữ viết tay vốn khó hơn nhiều so với chữ in và không nằm trong phạm vi tối ưu ban đầu.
• Đã khảo sát các dataset chữ in tiếng Việt thật có sẵn công khai (HuggingFace, web) nhưng không tìm được lựa chọn nào vừa mở (không cần xin phép thủ công), vừa đúng là chữ in, vừa dùng được ngay (phần lớn bị gated thủ công, là chữ viết tay/scene-text trá hình, hoặc không rõ nguồn gốc/nội dung). Do đó dự án dừng ở kết quả đo được trên dữ liệu tổng hợp; con số 99.99% nên được hiểu là hiệu năng trên đúng phân phối render tổng hợp, chưa phải con số đã kiểm chứng trên ảnh chữ in scan thật ngoài đời.

Hướng dẫn sử dụng

1. Cài đặt llama.cpp

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release   # thêm -DGGML_CUDA=ON nếu có CUDA Toolkit để chạy bằng GPU
cmake --build build --config Release -j$(nproc)

Lưu ý: hỗ trợ kiến trúc PaddleOCR-VL đã được merge vào llama.cpp (qua PR #18825), nên cần bản llama.cpp đủ mới (không cần dùng fork riêng).

2. Tải 2 file GGUF

Tải cả paddleocr-vl-1.6-vi-v5.bf16.gguf và mmproj-paddleocr-vl-1.6-vi-v5.bf16.gguf từ repo này về cùng một thư mục.

3. Chạy OCR trên một ảnh

./build/bin/llama-mtmd-cli \
  -m paddleocr-vl-1.6-vi-v5.bf16.gguf \
  --mmproj mmproj-paddleocr-vl-1.6-vi-v5.bf16.gguf \
  --image duong_dan_anh_cua_ban.jpg \
  -p "OCR:" \
  --temp 0 \
  --jinja

Quan trọng: bắt buộc phải có cờ --jinja — mô hình này dùng chat template tùy chỉnh mà bộ so khớp template dựng sẵn của llama.cpp không xử lý được, thiếu cờ này chương trình sẽ báo lỗi và thoát.

Có thể tăng -n <số token> (mặc định giới hạn số token sinh ra) nếu ảnh chứa đoạn văn dài cần nhiều token hơn để sinh hết.

Ví dụ thực tế

Input: ảnh chụp một dòng địa chỉ viết tay.

Output mô hình:

16 đường 588 khu phố 1, Phường Phước Long A, Quận 9, TP Hồ Chí Minh

So với nhãn gốc: 16 Đường 588 Khu Phố 1, Phường Phước Long A, Quận 9, TP Hồ Chí Minh — chỉ khác biệt nhỏ về viết hoa/thường.

Giấy phép

Apache 2.0, kế thừa từ mô hình gốc PaddleOCR-VL-1.6.