Phase 7: Hoàn thiện Modular RAG Backend với FastAPI và Đa LLM Provider
This commit is contained in:
241
doc/3.extraction-markdown-normalization-playbook.md
Normal file
241
doc/3.extraction-markdown-normalization-playbook.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# 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
|
||||
1. Vị trí của Extraction trong kiến trúc
|
||||
2. Nguyên tắc thiết kế
|
||||
3. Luồng xử lý tổng thể
|
||||
4. Phân loại tài liệu & chiến lược xử lý
|
||||
5. OCR Strategy cho tài liệu scan
|
||||
6. MarkItDown – tích hợp & cấu hình
|
||||
7. Page Mapping & Anchoring (đi tới đúng trang)
|
||||
8. Normalization & Cleanup
|
||||
9. Chunking Strategy (chuẩn cho Search & RAG)
|
||||
10. Output Contract (interface dữ liệu)
|
||||
11. Error handling & Retry
|
||||
12. Performance & Scale
|
||||
13. Checklist triển khai
|
||||
|
||||
---
|
||||
|
||||
## 1. Vị trí của Extraction trong kiến trúc
|
||||
|
||||
```text
|
||||
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ế
|
||||
|
||||
1. **Deterministic**: cùng file + version → output giống nhau
|
||||
2. **Lossless về nội dung**: ưu tiên giữ text hơn làm đẹp
|
||||
3. **Trang là đơn vị neo (anchor)** – đặc biệt với PDF
|
||||
4. **Tách OCR khỏi Markdown** (để thay engine sau này)
|
||||
5. **Không embed business logic** vào bước này
|
||||
|
||||
---
|
||||
|
||||
## 3. Luồng xử lý tổng thể
|
||||
|
||||
```text
|
||||
[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
|
||||
```json
|
||||
{
|
||||
"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)
|
||||
```markdown
|
||||
<!-- 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:
|
||||
```json
|
||||
{
|
||||
"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
|
||||
1. Heading (##, ###)
|
||||
2. Trang PDF
|
||||
3. Đ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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```json
|
||||
{
|
||||
"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.*
|
||||
Reference in New Issue
Block a user