# 12.Appendix-OCR-Integration-Strategy-and-Flow.md

> **Phụ lục tích hợp OCR – Giải pháp khả thi, rõ ràng, triển khai được ngay** cho hệ thống SharePoint → Search → RAG.
>
> ⚠️ Nguyên tắc của file này:
> - **Đứng độc lập**: có thể load lại trong session khác và tiếp tục thảo luận
> - **Chọn MỘT giải pháp chính** (không liệt kê mơ hồ nhiều hướng)
> - **Open‑source, on‑prem friendly**, không lock‑in
> - Thiết kế **mở để nâng cấp** về sau (fine‑tune / cloud nếu cần)

---

## 1. Tóm tắt nhanh quyết định (Executive Summary)

### Giải pháp OCR được chọn

> ✅ **PaddleOCR (Detection) + VietOCR (Recognition)** – triển khai on‑prem

### Vì sao chọn giải pháp này?

- Phù hợp **99% tài liệu tiếng Việt có dấu**
- Đã được cộng đồng Việt Nam sử dụng thực tế
- Hoàn toàn **open‑source**
- Không phụ thuộc cloud / API bên ngoài
- Dễ audit, dễ debug, dễ fine‑tune

➡️ Đây là giải pháp **khả thi nhất cho phase PoC → Pilot → Production**.

---

## 2. Vị trí của OCR trong toàn pipeline (nhắc lại để neo tư duy)

```text
File Ingestion
   ↓
Document Classification (file 10)
   ↓
PDF Inspection (file 11)
   ↓
IF SCAN_PDF
   → OCR Layer (file này)
   ↓
Normalized Text (page-wise)
   ↓
MarkItDown
   ↓
Chunking → Search → RAG
```

⚠️ OCR **KHÔNG** đứng độc lập, mà **chỉ là 1 stage có điều kiện**.

---

## 3. OCR Integration – Phạm vi áp dụng

OCR **CHỈ được gọi khi**:

- `doc_type = textual_document`
- `pdf_type = SCAN_PDF`

OCR **KHÔNG được gọi khi**:

- Drawing PDF
- Binary / CAD / Excel số liệu
- File pending classification

---

## 4. Kiến trúc OCR chi tiết (Logical Architecture)

```text
OCR Service (microservice)
 ├── Detector: PaddleOCR (DB / SAST)
 ├── Recognizer: VietOCR (Transformer)
 ├── Preprocess:
 │    - Deskew
 │    - Binarization
 │    - Resize
 ├── Output:
 │    - text
 │    - page
 │    - confidence
```

➡️ OCR được đóng gói dưới dạng **service riêng**, không embed cứng vào ingestion.

---
## 1. Tại Sao Lại Là Phân Tán VLM (Vision-Language Model)?

Trong giai đoạn đầu của PoC, chúng ta đã thử nghiệm kiến trúc cũ: **PaddleOCR** (để bóc khung chữ) kết hợp với **VietOCR** (để dịch tiếng Việt).
Tuy nhiên, phương pháp này đã bộc lộ những điểm yếu chí mạng:
- **PaddleOCR** cực kỳ yếu trong việc nhận diện dấu tiếng Việt (rụng dấu tả tơi).
- **VietOCR (vgg_seq2seq)** bị lỗi "Ảo giác" (Hallucination) sinh ra chữ tiếng Anh rác khi bị cắt ảnh không chuẩn xác.
- Quy trình `Cắt ảnh (Crop) -> Dịch -> Ghép lại` làm đứt gãy cấu trúc tự nhiên (Layout) của văn bản.

Vì vậy, kiến trúc đã được nâng cấp lên chuẩn **Enterprise Distributed AI**:
- Sử dụng mô hình **Vintern-3B** (Vision-Language Model) chạy trên một máy chủ chuyên dụng trong mạng LAN thông qua `llama.cpp` server.
- Hệ thống RAG (WSL) chỉ đóng vai trò là một VLM Client: Gửi ảnh sang máy chủ LAN và nhận về nguyên văn Markdown chuẩn xác, giữ nguyên cấu trúc bảng biểu, tiêu đề, và không bao giờ rớt dấu.

---

## 2. Distributed VLM Integration Flow (Kiến trúc phân tán)

```mermaid
sequenceDiagram
    participant P as Pipeline (sync.py)
    participant DCE as Classification (DCE)
    participant OS as OCR Service (Client)
    participant LAN as VLM Server (10.202.50.3)
    participant DB as Vector DB (OpenSearch)

    P->>DCE: Gửi PDF/Image
    DCE-->>P: file_type = "image/scanned_pdf"
    P->>OS: process_bytes(pdf_bytes)
    
    rect rgb(20, 50, 100)
    note right of OS: VLM Client Logic
    OS->>OS: Render trang PDF thành Ảnh (DPI=86)
    OS->>OS: Encode Ảnh sang Base64
    OS->>LAN: POST /v1/chat/completions (Base64 + Prompt)
    end
    
    rect rgb(80, 20, 20)
    note right of LAN: GPU/CPU Heavy Lifting
    LAN->>LAN: Chạy InternVL2 / Vintern-3B
    LAN->>LAN: Trích xuất toàn bộ Text và Bảng biểu
    LAN-->>OS: Trả về văn bản chuẩn Markdown
    end
    
    OS-->>P: List[OCRPageResult(text, confidence)]
    
    P->>P: Chunking (Semantic)
    P->>DB: Indexing
```

---

## 3. Kiến Trúc Modular Data Provider

Để hệ thống hoàn chỉnh ở mức độ cao cấp, chúng tôi đã tái cấu trúc (Refactor) lại tầng Ingestion:
1. **BaseStorageProvider:** Interface trừu tượng hoá việc lấy dữ liệu `fetch_changes()` và tải dữ liệu `download_file()`.
2. **SharePointProvider:** Kế thừa từ BaseStorageProvider, đóng gói toàn bộ logic Graph API.
3. Trong tương lai, chỉ cần viết thêm `GoogleDriveProvider`, `LocalDriveProvider` hoặc `S3Provider` là hệ thống RAG có thể nuốt mọi nguồn dữ liệu mà không cần sửa đổi Core logic.

---

## 4. Tách Biệt Cấu Hình (Decoupled Configuration)

Các thông số siêu nặng của VLM đã được tách biệt hoàn toàn khỏi mã nguồn:
- Thông số kết nối mạng LAN: `VLM_ENDPOINT`
- Thông số tinh chỉnh: `VLM_TEMPERATURE`, `VLM_MAX_TOKENS`
Tất cả được quản lý qua `core/config.py` và file `.env`. Việc đổi máy chủ AI giờ đây chỉ mất 1 giây thay đổi biến môi trường.

---

## 5. Confidence Handling (rất quan trọng cho RAG)

### Nguyên tắc

- OCR < threshold → **KHÔNG đưa vào RAG**
- OCR < threshold → vẫn search keyword + metadata

### Threshold gợi ý

- `confidence ≥ 0.90` → OK cho RAG
- `0.80 – 0.90` → Search only
- `< 0.80` → Flag review

---

## 10. Logging & Audit OCR

Mỗi OCR job phải log:

```json
{
  "file_id": "...",
  "page": 5,
  "ocr_engine": "PaddleOCR+VietOCR",
  "confidence": 0.91
}
```

➡️ Phục vụ:
- audit
- debug
- cải tiến model

---

## 11. Mở rộng tương lai (NHƯNG KHÔNG LÀM NGAY)

✅ Đã được thiết kế sẵn, **không lock‑in**:

- Fine‑tune VietOCR theo domain
- Thêm GPU để tăng tốc
- Thay recognition engine nếu cần
- Thêm OCR cloud fallback (optional)

➡️ **Không phá pipeline hiện tại**.

---

## 12. Tóm tắt quyết định kỹ thuật

- OCR là **service có điều kiện**, không phải default
- PaddleOCR + VietOCR là **giải pháp chính**
- On‑prem, open‑source, audit‑friendly
- Sẵn sàng cho PoC → Production

---

*Phụ lục này là tài liệu chốt cách tích hợp OCR cho toàn hệ thống.*