Files

phuongtc 26d1298cf6 Phase 7: Hoàn thiện Modular RAG Backend với FastAPI và Đa LLM Provider

2026-05-08 07:30:30 +00:00

4.8 KiB

Raw Blame History

Extraction & Normalization – OCR + MarkItDown Playbook (Reusable)

Tài liệu này nối tiếp SharePoint Ingestion Playbook. Mục tiêu: biến file ingest thành Markdown sạch, có cấu trúc, có thể search – RAG – truy vết trang gốc. Viết để tái sử dụng lâu dài, không phụ thuộc session.

Mục lục

Vị trí của Extraction trong kiến trúc
Nguyên tắc thiết kế
Luồng xử lý tổng thể
Phân loại tài liệu & chiến lược xử lý
OCR Strategy cho tài liệu scan
MarkItDown – tích hợp & cấu hình
Page Mapping & Anchoring (đi tới đúng trang)
Normalization & Cleanup
Chunking Strategy (chuẩn cho Search & RAG)
Output Contract (interface dữ liệu)
Error handling & Retry
Performance & Scale
Checklist triển khai

1. Vị trí của Extraction trong kiến trúc

Ingestion (file + metadata + ACL)
        │
        ▼
Extraction Layer (OCR + MarkItDown)
        │
        ▼
Normalization & Chunking
        │
        ▼
Index / Search / RAG

Extraction không biết Search, không biết User, chỉ biết:

Input: file + metadata
Output: Markdown + page mapping + structural hints

2. Nguyên tắc thiết kế

Deterministic: cùng file + version → output giống nhau
Lossless về nội dung: ưu tiên giữ text hơn làm đẹp
Trang là đơn vị neo (anchor) – đặc biệt với PDF
Tách OCR khỏi Markdown (để thay engine sau này)
Không embed business logic vào bước này

3. Luồng xử lý tổng thể

[Receive File Job]
  ↓
[Detect File Type]
  ↓
[If Scan → OCR]
  ↓
[MarkItDown Convert → Markdown]
  ↓
[Normalize Markdown]
  ↓
[Split by Page / Heading]
  ↓
[Emit Document Units]

4. Phân loại tài liệu & chiến lược xử lý

Loại	Dấu hiệu	Chiến lược
PDF scan	Không có text layer	OCR → MD
PDF text	Có selectable text	Direct → MD
DOCX	Word	Direct → MD
PPTX	Slide	Slide-wise MD
Image	jpg/png	OCR → MD

✅ Phân loại phải tự động, không dựa vào extension duy nhất.

5. OCR Strategy

5.1 Khi nào OCR?

PDF không có text layer
Image-based document

5.2 Output OCR yêu cầu tối thiểu

{
  "page": 5,
  "text": "Nội dung nhận dạng...",
  "confidence": 0.92
}

5.3 Nguyên tắc

OCR theo từng trang
Không gộp toàn file thành một blob text

6. MarkItDown – tích hợp & cấu hình

6.1 Vai trò

Biến input (PDF/DOCX/image) thành Markdown có cấu trúc

6.2 Mode sử dụng

Input: file path hoặc stream
Output: Markdown + page breaks

6.3 Quy ước page break (rất quan trọng)

<!-- page:1 -->
# Trang 1
...
<!-- page:2 -->
# Trang 2

➡️ Page marker này là khóa để click mở đúng trang PDF.

7. Page Mapping & Anchoring

7.1 Mục tiêu

Người dùng search → click → mở đúng trang, đúng vị trí

7.2 Cách làm

Mỗi block Markdown phải mang theo:

{
  "file_id": "...",
  "page_from": 3,
  "page_to": 4,
  "sharepoint_url": "...?page=3"
}

8. Normalization & Cleanup

8.1 Những việc NÊN làm

Remove header/footer lặp
Strip ký tự OCR rác
Normalize whitespace
Chuẩn hóa heading

8.2 Những việc KHÔNG NÊN làm

Rewrite nội dung
Tóm tắt
Suy diễn

➡️ Bước này không dùng LLM.

9. Chunking Strategy

9.1 Thứ tự ưu tiên

Heading (##, ###)
Trang PDF
Đoạn văn

9.2 Kích thước gợi ý

300–800 tokens
Không cắt giữa câu

9.3 Schema chunk

{
  "chunk_id": "uuid",
  "text": "...",
  "file_id": "...",
  "page_from": 5,
  "page_to": 6,
  "section": "Điều 3",
  "source_url": "..."
}

10. Output Contract

10.1 Đầu ra cho Index Layer

{
  "file_id": "...",
  "chunks": [ ... ],
  "metadata": { ... }
}

10.2 Tính chất

Self-contained
Không cần gọi lại SharePoint
Có thể re-index lại từ output này

11. Error handling & Retry

Lỗi	Xử lý
OCR fail	Retry / flag manual
File corrupt	Log + skip
MarkItDown error	Retry with fallback

Mỗi file có processing status riêng.

12. Performance & Scale

OCR là bottleneck → async
1 file lớn = nhiều page jobs
Scale theo số trang, không theo số file

13. Checklist triển khai

✅ Detect scan vs text ✅ OCR page-wise ✅ Page marker trong Markdown ✅ Chunk có page mapping ✅ Output contract rõ ràng

Kết thúc Extraction & Normalization Playbook. File này nối trực tiếp sang Index/Search.

4.8 KiB Raw Blame History Unescape Escape