truonggiabao7/ocrdoc-models

OcrDoc — Fine-tuned PP-OCRv6 for Vietnamese Identity Documents & Passports

Bộ trọng số ONNX chính thức được fine-tune chuyên biệt cho xử lý OCR Giấy tờ Tuỳ thân Việt Nam (Căn cước công dân / CMND) và Hộ chiếu quốc tế (ICAO 9303 TD1 / TD3), thuộc dự án mã nguồn mở e4glevlr/ocr-doc.

Tối ưu hóa để chạy 100% offline trên CPU, không cần GPU, siêu nhẹ và bảo mật dữ liệu tuyệt đối.

---

📦 Danh mục Tệp trong Repo

Tệp	Mô tả	Kích thước	SHA256 Checksum
detection.onnx	PP-OCRv6 DBNet (ngôn ngữ trung lập, phát hiện vùng chữ cho cả CCCD và Hộ chiếu)	~59 MB	eb13b44b25bb36f89528b68720af8a61d9cf381176107f465db1757b65d086e1
recognition.onnx	PP-OCRv6 medium rec fine-tuned tiếng Việt (Run 6, bản phát hành mặc định)	~59 MB	767305d37d06728fe9578ff8132595ce23f66139df5e2937fd4131bd1dc34f12
vi_v6_medium_rec_run5b.onnx	PP-OCRv6 medium rec fine-tuned (Run 5b, bản dự phòng ổn định cao cho Họ tên)	~59 MB	2297ec45ea875187ef6c3b06e266843817fc3976e842889d658115a8de899f86
charset.txt	Bảng mã 229 ký tự tiếng Việt đầy đủ gắn theo vị trí cố định của recognizer	680 B	5d801bf60472c4c1b184b6b6843aa2c754d8daf1429247e07658ee0bd79ab448

Lưu ý: Các bản fine-tune của PP-OCRv6 medium rec đều có cùng kích thước file (62.289.039 byte). Vui lòng đối chiếu SHA256 hoặc kiểm tra tên file để phân biệt chính xác.

---

📊 Kết quả Benchmark & Đánh đổi

PP-OCRv5/v6 nguyên bản (stock) đạt 0% exact match trên chữ tiếng Việt có dấu. Bộ model fine-tune này khắc phục triệt để vấn đề:

Thử nghiệm	PP-OCRv6 Stock	VietOCR (Tham chiếu)	Run 5b	Run 6 (Mặc định)
VinText Test Set (chữ có dấu)	0%	59.19%	78.40%	78.95% (+25.2% vs VietOCR)
name — CCCD đời 2021 (n=48)	-	-	93.8%	85.4% (4 trường hợp lỗi dấu)
name — CCCD 3 (n=42)	-	-	95.2%	100%
residence (địa chỉ) — CCCD 2021 (n=48)	-	60.4%	45.8%	60.4% (ngang VietOCR)
residence — CCCD 3 (n=156)	-	-	67.9%	69.9%
dob (ngày sinh) — CCCD 2021 (n=46)	-	-	89.1%	93.5%
MRZ TD1 (mặt sau CCCD)	-	-	148/150	148/150
id12 / sex	-	-	100% / 93.9%	100% / 93.9%

Lựa chọn giữa Run 6 và Run 5b:

• Run 6 (Mặc định): Giải quyết triệt để địa chỉ cột hẹp và nhãn dính liền trên CCCD 2021 (tăng từ 45.8% lên 60.4%, ngang ngửa VietOCR nhưng tốc độ nhanh hơn nhiều).
• Run 5b (Dự phòng): Nếu hệ thống của bạn ưu tiên độ chính xác tuyệt đối ở trường Họ tên trên CCCD 2021 hơn trường Địa chỉ, chỉ cần đổi sang dùng vi_v6_medium_rec_run5b.onnx.

---

🚀 Hướng dẫn Sử dụng

1. Dùng trực tiếp với OcrDoc CLI (.NET / C#)

Tải bản bundle hoặc tự build theo hướng dẫn tại e4glevlr/ocr-doc:

# Tải models từ Hugging Face
huggingface-cli download truonggiabao7/ocrdoc-models --local-dir models/

# Chạy OCR đối soát 2 mặt CCCD
ocrdoc-cli read --models models/ mat_truoc.jpg mat_sau.jpg

# Xuất định dạng JSON
ocrdoc-cli read --models models/ --json mat_truoc.jpg mat_sau.jpg > ket_qua.json

2. Tích hợp trong dự án C# (.NET 8)

using OcrDoc;

using var ocr = new DocumentOcr(new OcrOptions
{
    DetectionModelPath   = "models/detection.onnx",
    RecognitionModelPath = "models/recognition.onnx", // hoặc vi_v6_medium_rec_run5b.onnx
    DictionaryPath       = "models/charset.txt",
    NumThreads           = 0, // Dùng toàn bộ core CPU
    AutoOrient           = false
});

var result = ocr.ReadFiles("front.jpg", "back.jpg");
if (result.Type == DocumentType.Cccd && result.Cccd is { } cccd)
{
    Console.WriteLine($"CCCD: {cccd.Id.Value} (Confident: {cccd.Id.Confident})");
    Console.WriteLine($"Tên:  {cccd.Name.Value} (Confident: {cccd.Name.Confident})");
    Console.WriteLine($"Đ/c:  {cccd.Residence.Value}");
}

3. Tải và suy luận với Python (ONNXRuntime)

from huggingface_hub import hf_hub_download
import onnxruntime as ort

repo_id = "truonggiabao7/ocrdoc-models"

# Tải file trọng số
det_path = hf_hub_download(repo_id=repo_id, filename="detection.onnx")
rec_path = hf_hub_download(repo_id=repo_id, filename="recognition.onnx")
dict_path = hf_hub_download(repo_id=repo_id, filename="charset.txt")

# Khởi tạo session
det_session = ort.InferenceSession(det_path, providers=["CPUExecutionProvider"])
rec_session = ort.InferenceSession(rec_path, providers=["CPUExecutionProvider"])

---

⚙️ Ràng buộc Kỹ thuật khi Tự Cấu hình Recognizer

• Độ phân giải đầu vào cố định: Model được huấn luyện ở [3, 48, 320]. Recognizer chỉ nên chạy ở 2 bậc chiều rộng cố định: 320 (văn bản thường) và 640 (cho dòng MRZ dài). Kích thước động sẽ làm giảm tới 8.5% độ chính xác.
• Normalization: Chuẩn hoá pixel về (x / 255.0 - 0.5) / 0.5.

---

📜 Giấy phép (License)

• Model weights tuân thủ giấy phép Apache-2.0 (PaddleOCR).
• Mã nguồn và pipeline OcrDoc tuân thủ giấy phép MIT License.