Phase 7: Hoàn thiện Modular RAG Backend với FastAPI và Đa LLM Provider
This commit is contained in:
243
doc/1.phan-tich-kien-truc-tra-cuu-sharepoint.md
Normal file
243
doc/1.phan-tich-kien-truc-tra-cuu-sharepoint.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Kiến trúc và định hướng xây dựng hệ thống tra cứu tài liệu scan SharePoint
|
||||
|
||||
## 1. Mục tiêu tổng thể
|
||||
Hệ thống nhằm giải quyết ba vấn đề cốt lõi trong doanh nghiệp:
|
||||
1. **Biến kho tài liệu scan trên SharePoint thành dữ liệu có thể tìm kiếm theo ngữ nghĩa**.
|
||||
2. **Tìm nhanh → đúng tài liệu → đúng vị trí trong tài liệu**.
|
||||
3. **Giữ nguyên tính kiểm soát, phân quyền và tuân thủ (compliance)** của Microsoft 365.
|
||||
|
||||
Hệ thống không thay thế SharePoint, mà **tăng cường khả năng tra cứu và hiểu nội dung**.
|
||||
|
||||
---
|
||||
|
||||
## 2. Nguyên tắc thiết kế
|
||||
|
||||
### 2.1. Không lock-in
|
||||
- Ưu tiên **Open Source** cho lõi xử lý.
|
||||
- Có thể thay OCR / embedding / LLM trong tương lai.
|
||||
|
||||
### 2.2. File gốc là "nguồn chân lý"
|
||||
- File **luôn ở SharePoint**.
|
||||
- Hệ thống chỉ lưu **nội dung trích xuất + metadata + index**.
|
||||
|
||||
### 2.3. Permission-aware từ đầu
|
||||
- Không index kiểu "public rồi filter sau".
|
||||
- Mỗi kết quả search phải map được tới **ACL tương ứng trên SharePoint**.
|
||||
|
||||
---
|
||||
|
||||
## 3. Kiến trúc tổng thể (Logical Architecture)
|
||||
|
||||
```
|
||||
SharePoint (Files, PDFs scan)
|
||||
│
|
||||
▼
|
||||
Ingestion & Sync Layer (tự viết – vibecode)
|
||||
│
|
||||
├── Fetch file
|
||||
├── Fetch metadata & permissions
|
||||
└── Versioning
|
||||
▼
|
||||
Extraction Layer
|
||||
│
|
||||
├── OCR (scan PDF)
|
||||
└── MarkItDown (→ Markdown)
|
||||
▼
|
||||
Normalization & Enrichment
|
||||
│
|
||||
├── Chunking
|
||||
├── Metadata mapping
|
||||
└── Page / section anchoring
|
||||
▼
|
||||
Index Layer (OpenSearch)
|
||||
│
|
||||
├── Full-text index
|
||||
├── Vector index
|
||||
└── Metadata filter
|
||||
▼
|
||||
Search / Chat UI
|
||||
└── Click → mở đúng file SharePoint
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Thành phần chi tiết và trách nhiệm
|
||||
|
||||
### 4.1. Ingestion Layer (then chốt nhất)
|
||||
|
||||
**Nhiệm vụ**:
|
||||
- Kết nối SharePoint bằng Microsoft Graph API.
|
||||
- Theo dõi thay đổi file (delta query / webhook).
|
||||
- Tải file + metadata.
|
||||
|
||||
**Metadata bắt buộc**:
|
||||
- site_id
|
||||
- drive_id / library
|
||||
- file_id
|
||||
- file_name
|
||||
- file_url (mở trực tiếp trên SharePoint)
|
||||
- created_by, modified_by
|
||||
- created_at, modified_at
|
||||
- permission_groups / users
|
||||
|
||||
> Lưu ý: permission cần map thành dạng filter-friendly (list group/user IDs).
|
||||
|
||||
---
|
||||
|
||||
### 4.2. Extraction Layer
|
||||
|
||||
#### OCR
|
||||
- Scan PDF thường là image → cần OCR.
|
||||
- Định hướng:
|
||||
- Tesseract / PaddleOCR cho local.
|
||||
- Có thể thay bằng model mới sau.
|
||||
|
||||
#### MarkItDown
|
||||
- Chuyển output OCR → Markdown sạch.
|
||||
- Ưu điểm:
|
||||
- Giữ cấu trúc
|
||||
- Thuận lợi cho chunk & embedding
|
||||
|
||||
Output cần lưu:
|
||||
```json
|
||||
{
|
||||
"file_id": "...",
|
||||
"page": 12,
|
||||
"content_md": "## Điều 3...",
|
||||
"bbox_hint": "page=12"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.3. Normalization & Chunking
|
||||
|
||||
**Mục tiêu**: mỗi đơn vị index phải vừa đủ nhỏ để search chính xác, vừa đủ lớn để có ngữ cảnh.
|
||||
|
||||
Chiến lược chunk:
|
||||
- Ưu tiên theo:
|
||||
1. Heading (##, ###)
|
||||
2. Trang (page)
|
||||
3. Đoạn văn
|
||||
|
||||
Mỗi chunk gồm:
|
||||
- chunk_id
|
||||
- text
|
||||
- file_id
|
||||
- page_from / page_to
|
||||
- sharepoint_url_with_anchor
|
||||
|
||||
---
|
||||
|
||||
### 4.4. Index Layer (OpenSearch)
|
||||
|
||||
**Hai loại index song song**:
|
||||
|
||||
1. **Full-text index**
|
||||
- Phục vụ search truyền thống
|
||||
- Có highlight
|
||||
|
||||
2. **Vector index**
|
||||
- Phục vụ semantic search
|
||||
- Dùng embedding OSS (bge, e5, etc.)
|
||||
|
||||
**Schema gợi ý**:
|
||||
|
||||
```json
|
||||
{
|
||||
"chunk_id": "...",
|
||||
"text": "...",
|
||||
"embedding": [ ... ],
|
||||
"file_id": "...",
|
||||
"file_name": "...",
|
||||
"sharepoint_url": "...",
|
||||
"page_from": 10,
|
||||
"page_to": 11,
|
||||
"site_id": "...",
|
||||
"permissions": ["groupA", "userB"],
|
||||
"updated_at": "..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Search & UX định hướng
|
||||
|
||||
### 5.1. Search mode
|
||||
- Keyword search
|
||||
- Semantic search
|
||||
- Hybrid (khuyên dùng)
|
||||
|
||||
### 5.2. Kết quả search bắt buộc có
|
||||
- Trích đoạn nội dung
|
||||
- Tên file
|
||||
- Thư mục / site
|
||||
- Trang (page)
|
||||
- Link mở đúng file
|
||||
|
||||
### 5.3. UX nguyên tắc
|
||||
- Tìm ≤ 3s
|
||||
- Click ≤ 1 lần để mở file
|
||||
- Người dùng **không cần biết file nằm ở đâu**
|
||||
|
||||
---
|
||||
|
||||
## 6. Vibecode: nên tập trung viết gì?
|
||||
|
||||
✅ NÊN tự viết:
|
||||
- SharePoint ingestion & sync
|
||||
- Permission mapping
|
||||
- Metadata chuẩn hóa
|
||||
- UI search phù hợp nghiệp vụ
|
||||
|
||||
❌ KHÔNG nên tự viết:
|
||||
- OCR engine
|
||||
- Search engine
|
||||
- Vector index
|
||||
|
||||
---
|
||||
|
||||
## 7. Lộ trình triển khai thực tế
|
||||
|
||||
### Phase 1 – PoC (2–4 tuần)
|
||||
- Lấy 1 site SharePoint
|
||||
- OCR + MarkItDown
|
||||
- Full-text search
|
||||
|
||||
### Phase 2 – Semantic search
|
||||
- Chunking
|
||||
- Embedding
|
||||
- Vector search
|
||||
|
||||
### Phase 3 – Permission & scale
|
||||
- ACL filtering
|
||||
- Delta sync
|
||||
- Monitoring
|
||||
|
||||
---
|
||||
|
||||
## 8. Tương tác AI agent trong tương lai
|
||||
|
||||
Hệ thống này có thể:
|
||||
- Gắn Chat UI (RAG)
|
||||
- Tóm tắt tài liệu
|
||||
- So sánh nhiều file
|
||||
- Trả lời câu hỏi trích dẫn rõ nguồn
|
||||
|
||||
---
|
||||
|
||||
## 9. Kết luận
|
||||
|
||||
Bài toán của bạn **không mới nhưng rất ít hệ thống làm đúng**.
|
||||
|
||||
Việc kết hợp:
|
||||
- SharePoint (nguồn tin cậy)
|
||||
- MarkItDown (chuẩn hóa nội dung)
|
||||
- OpenSearch (index & search)
|
||||
- Vibecode (điều phối thông minh)
|
||||
|
||||
là **hướng kiến trúc bền vững, mở rộng được nhiều năm**.
|
||||
|
||||
---
|
||||
|
||||
*Tài liệu này được thiết kế để AI agent hoặc dev khác có thể đọc và triển khai tiếp mà không cần giải thích lại.*
|
||||
Reference in New Issue
Block a user