phuongtc/poc_system

Fork 0

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

5.3 KiB

Raw Blame History

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:

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.
Tìm nhanh → đúng tài liệu → đúng vị trí trong tài liệu.
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:

{
  "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:

Full-text index

Phục vụ search truyền thống
Có highlight

Vector index

Phục vụ semantic search
Dùng embedding OSS (bge, e5, etc.)

Schema gợi ý:

{
  "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.

5.3 KiB Raw Blame History Unescape Escape