244 lines
5.3 KiB
Markdown
244 lines
5.3 KiB
Markdown
# 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.*
|