🧭 AGENT ARCHITECTURE MAP (LIVING DOCUMENT)

Đây là tài liệu dẫn đường dành riêng cho các AI Agent tương lai và lập trình viên bảo trì. Không quét toàn bộ code, hãy đọc file này trước.

Lần cập nhật cuối: Phase 6 (Hoàn thiện Semantic Chunking & Vector Indexing) Trạng thái Dự án: Đã hoàn thành Ingestion, Extraction, Chunking & Indexing. Chuẩn bị bước vào Phase 7 (RAG Search & Chat API).

1. Bản Đồ Kiến Trúc Lõi (Core Architecture Patterns)

A. Tầng Ingestion (Thu thập dữ liệu) - Mẫu Modular Provider Pattern

Mục tiêu: Tách biệt lõi hệ thống khỏi nền tảng lưu trữ (SharePoint, Google Drive, v.v.).
Interface gốc: ingestion/providers/base_provider.py (Bắt buộc phải implement fetch_changes và download_file).
Implement hiện tại: ingestion/providers/sharepoint_provider.py. Nó bọc lại GraphClient và tự động xử lý thuật toán phân trang (pagination) để lấy dữ liệu Delta.
Nếu cần thêm nguồn dữ liệu mới (ví dụ: NAS, Google Drive): Chỉ cần tạo một class mới kế thừa BaseStorageProvider. Lõi hệ thống không cần biết về API của nguồn đó.

B. Tầng Extraction (Xử lý chữ & Ảnh) - Mẫu Distributed VLM Pattern

Lịch sử: Đã từng dùng PaddleOCR + VietOCR nhưng gặp lỗi "Rụng dấu" và "Ảo giác" do cắt ảnh sai.
Kiến trúc hiện tại: Hệ thống đóng vai trò như một VLM Client.
Cách hoạt động: extraction/ocr_service.py render file PDF thành ảnh (DPI=86), nén Base64 và bắn POST Request sang một Server LLM khác trong mạng LAN (chạy llama.cpp với model Vintern-3B).
Lợi ích: Giải phóng hoàn toàn RAM cho máy chủ RAG, loại bỏ các thư viện AI nặng nền (Torch, Paddle). Lấy được Markdown nguyên bản, không gãy vỡ layout bảng biểu.

C. Tầng Chunking & Vector DB (Semantic Indexing)

Chunking: chunking/markdown_chunker.py chia nhỏ văn bản bằng Markdown Rules (nhận biết Header #, duy trì overlap chống đứt gãy ngữ cảnh), tự động theo dõi page_from, page_to chuẩn xác.
Embedding: Dùng thư viện sentence-transformers với model keepitreal/vietnamese-sbert chạy Local/Offline. Tạo ra Vector 768 chiều chuyên biệt cho Tiếng Việt.
Database: indexing/vector_store.py cấu hình OpenSearch với thuật toán k-NN HNSW. Index mặc định là poc_sharepoint_docs hoặc sharepoint_docs.

D. Tầng Cấu hình (Decoupled Configuration)

Toàn bộ thông số hệ thống, đặc biệt là IP máy chủ VLM, Token của SharePoint đều nằm trong .env.
Mã nguồn load cấu hình thông qua core/config.py.
Tuyệt đối KHÔNG hardcode URL, Token hay Password trong code.

2. Bản Đồ File & Thư Mục Quan Trọng

📁 poc_system/
├── 📁 core/
│   ├── config.py         # ⚙️ Trái tim cấu hình (Load từ .env)
│   └── models.py         # 🧩 Định nghĩa Data Classes (OCRPageResult, v.v.)
├── 📁 ingestion/
│   ├── sync.py           # 🔄 Bộ điều phối đồng bộ (Đang chuẩn bị ghép với BaseStorageProvider)
│   ├── graph_client.py   # 🌐 Microsoft Graph API Client (Bọc Auth)
│   └── 📁 providers/     # 🔌 Nơi chứa các plugin kết nối dữ liệu
│       ├── base_provider.py
│       └── sharepoint_provider.py
├── 📁 extraction/
│   └── ocr_service.py    # 👁️ VLM Client (Chuyển ảnh -> Text Markdown qua LAN)
├── .env                  # 🔑 Chìa khoá và địa chỉ mạng (KHÔNG commit file này)
└── test_modular_architecture.py # 🧪 Script kiểm tra nhanh kết nối các module

3. Lịch Sử Các Lỗi Khét Tiếng & Cách Xử Lý (Known Gotchas)

Lỗi 401 Unauthorized khi tải file từ SharePoint:
- Nguyên nhân: Microsoft chặn download trực tiếp bằng @microsoft.graph.downloadUrl nếu dùng App-Only Token.
- Giải pháp: Dùng endpoint .../items/{item_id}/content kèm Bearer Token (Đã cài đặt trong graph_client.py).
Lỗi 500 Internal Server Error từ Llama.cpp VLM:
- Nguyên nhân: Bức ảnh ném vào VLM có độ phân giải quá cao (Matrix 2.0) làm tràn Context Window (ví dụ: Token ảnh > 4096).
- Giải pháp: Hạ Matrix xuống 1.2, hoặc khởi chạy Server Llama.cpp với -c 8192. Bắt buộc phải có file --mmproj.
Lỗi Rụng dấu / Ảo giác của VietOCR:
- Nguyên nhân: PaddleOCR bắt khung quá khít, làm cụt phần đuôi của các chữ tiếng Việt có dấu. Mô hình vgg_seq2seq tự nội suy ra từ tiếng Anh linh tinh.
- Giải pháp triệt để: Đã loại bỏ hoàn toàn VietOCR, chuyển sang dùng VLM (Vintern-3B).
Lỗi UTF-8 Surrogate (\udcc3) trong Terminal WSL:
- Hiện tượng: Câu hỏi đầu tiên đúng, nhưng từ câu thứ 2 bị lỗi mã hóa khi dùng input().
- Nguyên nhân: Do sự không đồng nhất giữa sys.stdin và bộ đệm Terminal sau khi in lượng lớn dữ liệu từ LLM.
- Giải pháp: Sử dụng sys.stdin.buffer.readline() để đọc dữ liệu thô (Bytes) và tự decode bằng UTF-8. Đây là giải pháp cho môi trường CLI, khi lên Web API (FastAPI) sẽ không bị ảnh hưởng.

4. Nhiệm Vụ Tiếp Theo (Dành cho Lập Trình Viên/AI Agent)

Phase 7: Bọc thành API Backend bằng FastAPI.

5. Tiêu chuẩn Lập trình & Môi trường (Coding Standards)

A. Quản lý Mã hóa (Encoding)

Quy tắc vàng: Luôn sử dụng encoding='utf-8' trong mọi lệnh open(). Tuyệt đối không dựa dẫm vào encoding mặc định của hệ điều hành.
Môi trường: Hệ thống được thiết kế để chạy trong môi trường UTF-8. Trong Docker hoặc WSL, luôn đảm bảo biến môi trường PYTHONIOENCODING=utf-8 được thiết lập. Điều này giúp hệ thống tương thích 100% với các ký tự Tiếng Việt từ LLM mà không cần hack code.

B. Mẫu Provider (Provider Pattern)

Mọi kết nối tới dịch vụ bên thứ ba (Storage, LLM) phải thông qua Interface/BaseClass để đảm bảo tính "Cắm rút" (Pluggable).

6.5 KiB Raw Blame History