benchmark/parser/README.md

Benchmark — Đánh giá phân tích bố cục (parser vs OmniDocBench)

Đo độ chính xác của StageAParser (giai đoạn phân tích cấu trúc của PDFTranslator) bằng cách đối chiếu trực tiếp với ground truth của OmniDocBench. Quy trình gồm hai giai đoạn:

1. Sinh prediction — chạy parser trên toàn bộ trang OmniDocBench → cần GPU (nên dùng Google Colab A100).
2. Chấm điểm (eval) — tính các độ đo (định vị, phân loại, OCR, thứ tự đọc, công thức, bảng) → chỉ cần CPU, chạy local. Riêng chỉ số CDM cho công thức cần thêm TeX Live + ImageMagick.

---

Cấu trúc thư mục

benchmark/parser/
├── run_parser/          # build_pdfs.py, run_parser.py   (sinh prediction — cần GPU)
├── evaluation/          # eval_layout / eval_formula / eval_table / eval_formula_cdm
│                        # aggregate_reports.py, compare_matchers.py, download_dataset.py
│                        # requirements-eval.txt
├── data/                # OmniDocBench.json + images/ + pdfs/      (tải/tạo ở bước 1)
├── parser_results/      # batch_*.json (ParsedDocument) + mapping.json   (đầu ra parser)
└── eval_results/        # *.json report + eval_summary_*.csv            (đầu ra eval)

---

0. Chuẩn bị

git clone https://github.com/HoanggNguyen/PDFTranslator.git
cd PDFTranslator
# repo OmniDocBench chỉ cần cho CDM (đánh giá công thức):
git clone https://github.com/opendatalab/OmniDocBench.git
cd benchmark/parser

---

1. Sinh prediction bằng parser (GPU)

Giai đoạn này cần GPU lớn. Nếu GPU laptop không đủ thì dùng GoogleColab.

1a. Kiểm tra GPU và tạo môi trường ảo

nvidia-smi

Trên Colab, tạo môi trường ảo riêng để tránh xung đột với các gói cài sẵn:

pip install virtualenv
virtualenv myenv
./myenv/bin/pip install -r ../../requirements.txt

(Nếu chạy local có GPU đủ: dùng venv của repo và pip install -r ../../requirements.txt.)

1b. Tải dữ liệu → gộp PDF → chạy parser

# (1) tải ảnh + OmniDocBench.json về data/
./myenv/bin/python evaluation/download_dataset.py --out data

# (2) gộp ảnh thành PDF 32 trang/PDF (tạo kèm data/pdfs/mapping.json)
./myenv/bin/python run_parser/build_pdfs.py \
    --images data/images --out data/pdfs --per-pdf 32

# (3) chạy parser -> parser_results/batch_*.json + báo cáo thời gian
./myenv/bin/python run_parser/run_parser.py \
    --pdfs   data/pdfs \
    --out    parser_results \
    --timing eval_results/parser_timing.json \
    --device cuda

Tuỳ chọn hữu ích của run_parser.py:

• Batch size (điều chỉnh theo VRAM): --layout-batch-size, --detection-batch-size, --ocr-batch-size, --table-batch-size, --page-batch-size (mặc định hợp cho A100).
• Ngưỡng detector: --blank-threshold, --text-threshold.
• --limit N: chỉ chạy N PDF đầu (test nhanh); --overwrite: chạy lại PDF đã có JSON.

build_pdfs.py ghi mapping.json cạnh các PDF (data/pdfs/mapping.json). Để các lệnh eval ở Giai đoạn 2 chạy nguyên trạng, sau khi chạy parser hãy copy nó vào parser_results/: cp data/pdfs/mapping.json parser_results/.

• Tải parser_results/ từ Colab về máy để chấm điểm ở Giai đoạn 2.

---

2. Chấm điểm (eval — CPU, chạy local)

2a. Môi trường eval

python3 -m venv .venv
.venv/bin/pip install -r evaluation/requirements-eval.txt

sudo apt install -y texlive-latex-base texlive-latex-extra \
                    texlive-fonts-recommended imagemagick

Đặt cho gọn: PY=.venv/bin/python.

2b. Localization + Classification + OCR + Reading order

# fine (bung merge_list — khuyến nghị)
$PY evaluation/eval_layout.py \
    --gt data/OmniDocBench.json --pred parser_results \
    --mapping parser_results/mapping.json \
    --gt-granularity fine --out eval_results/eval_report_fine.json

# merged (box top-level như OmniDocBench)
$PY evaluation/eval_layout.py \
    --gt data/OmniDocBench.json --pred parser_results \
    --mapping parser_results/mapping.json \
    --gt-granularity merged --out eval_results/eval_report_merged.json

# fine + mask-math (thay công thức inline bằng token -> CER/WER text thuần)
$PY evaluation/eval_layout.py \
    --gt data/OmniDocBench.json --pred parser_results \
    --mapping parser_results/mapping.json \
    --gt-granularity fine --mask-math \
    --out eval_results/eval_report_fine_maskmath.json

2c. Công thức (edit distance) + Bảng (nội dung)

$PY evaluation/eval_formula.py \
    --gt data/OmniDocBench.json --pred parser_results \
    --mapping parser_results/mapping.json \
    --out eval_results/eval_report_formula.json

$PY evaluation/eval_table.py \
    --gt data/OmniDocBench.json --pred parser_results \
    --mapping parser_results/mapping.json \
    --out eval_results/eval_report_table.json

2d. Công thức CDM (chuẩn vàng — cần TeX Live + ImageMagick + pylatexenc)

$PY evaluation/eval_formula_cdm.py \
    --gt data/OmniDocBench.json --pred parser_results \
    --mapping parser_results/mapping.json \
    --omnidocbench ../../OmniDocBench \
    --out eval_results/eval_report_formula_cdm.json
# thêm --limit 200 để test nhanh

2e. Gom kết quả thành CSV

$PY evaluation/aggregate_reports.py \
    --layout  fine=eval_results/eval_report_fine.json \
    --layout  merged=eval_results/eval_report_merged.json \
    --layout  fine_maskmath=eval_results/eval_report_fine_maskmath.json \
    --formula eval_results/eval_report_formula.json \
    --report  table=eval_results/eval_report_table.json \
    --out     eval_results/eval_summary

2f. (tuỳ chọn) So sánh 3 cách matching localization

$PY evaluation/compare_matchers.py --iou 0.5 --granularity fine

---

Ghi chú

• GT↔pred nối theo tên ảnh (image_path) qua mapping.json — khớp 1:1.
• Eval chạy CPU (trừ CDM cần TeX Live). Chỉ Giai đoạn 1 (parser) mới cần GPU.
• Các script trong evaluation/ import lẫn nhau theo thư mục cạnh bên; hãy gọi bằng python evaluation/<script>.py (đừng đổi tên/di chuyển lẻ từng file).