RagKB.Assistant — RAG Knowledge-Base Q&A System

Hệ thống Hỏi Đáp Tri Thức (RAG - Retrieval-Augmented Generation) hiệu năng cao được xây dựng trên nền tảng C# .NET 9 Minimal API, tích hợp Ollama cục bộ (bge-m3 embedding và qwen2.5:7b chat/generation) cùng cơ sở dữ liệu vector SQLite.

---

🌟 Tính Năng Nổi Bật

• 🚀 Kiến Trúc Tối Giản & Tốc Độ Cao: Sử dụng ASP.NET Core Minimal API.
• 🇻🇳 Hỗ Trợ Tiếng Việt Xuất Sắc:
  • Embedding đa ngôn ngữ 1024 chiều với bge-m3.
  • Sinh phản hồi thông minh, chính xác bằng qwen2.5:7b.
• 📂 Xử Lý Đa Định Dạng Tài Liệu:
  • Parse file Markdown (.md, .markdown) giữ trọn cấu trúc đề mục và code blocks.
  • Parse file Word (.docx) qua OpenXML SDK.
• ✂️ Recursive Character Chunker: Chia văn bản đệ quy 800 ký tự, overlap 100 ký tự theo ngữ cảnh heading.
• 🗄️ SQLite Vector Store Siêu Linh Hoạt:
  • Hỗ trợ extension sqlite-vec ảo bảng vec_chunks cho truy vấn vector cực nhanh.
  • Tích hợp fallback Cosine Similarity thuần C# mượt mà không phụ thuộc cài đặt native.
• ⚡ Hỗ Trợ Streaming & Non-Streaming: API hỗ trợ cả JSON response và SSE Streaming real-time token.

---

🏗️ Cấu Trúc Dự Án

RagKB.Assistant/
├── RagKB.Assistant.sln
├── backend/                            # Thư mục chứa mã nguồn backend .NET
│   ├── src/
│   │   └── RagKB.Assistant.Api/        # Dự án Web API
│   │       ├── Program.cs              # Host builder entry point
│   │       ├── Startup.cs              # ConfigureServices & Middleware pipeline
│   │       ├── appsettings.json
│   │       ├── Controllers/            # API Controllers (Ask, Ingest, Documents, Health)
│   │       ├── Services/               # Logic chi tiết từng service & pipeline
│   │       └── Data/                   # DatabaseInitializer & SQLite vector schema
│   └── tests/
│       └── RagKB.Assistant.Tests/      # Unit tests cho Parser, Chunker và Vector Store
├── frontend/                           # Thư mục chứa mã nguồn frontend React/Vite
│   ├── src/                            # Mã nguồn React components & pages
│   ├── public/                         # Các tài nguyên tĩnh
│   ├── package.json                    # Cấu hình npm và dependencies
│   └── vite.config.ts                  # Cấu hình Vite
├── databases/                          # Thư mục chứa dữ liệu SQLite
│   └── ragdb.sqlite
├── sample-kb/                          # Thư mục chứa tài liệu tri thức mẫu (.md, .docx)
└── README.md

---

⚙️ Yêu Cầu & Cài Đặt Môi Trường

1. Cài đặt Ollama và tải Models

Cài đặt Ollama và tải 2 models cần thiết:

# Model Embedding đa ngôn ngữ (1024 dimensions)
ollama pull bge-m3

# Model Chat / Generation hỗ trợ Tiếng Việt
ollama pull qwen2.5:7b

Đảm bảo Ollama đang chạy tại http://localhost:11434.

---

🚀 Hướng Dẫn Chạy Ứng Dụng

1. Build và Chạy Unit Tests

dotnet test backend/tests/RagKB.Assistant.Tests

2. Khởi Chạy API Backend

dotnet run --project backend/src/RagKB.Assistant.Api

Sau khi khởi động, truy cập giao diện Swagger UI tại: 👉 http://localhost:5000 hoặc http://localhost:5242

3. Khởi Chạy Frontend

cd frontend
npm install
npm run dev

Truy cập giao diện Web UI tại địa chỉ hiển thị trên terminal (thường là http://localhost:5173).

---

📡 Danh Sách REST API Endpoints

Method	Endpoint	Mô Tả
POST	/api/ask	Gửi câu hỏi tự nhiên, nhận câu trả lời kèm nguồn trích dẫn.
POST	/api/ask/stream	Hỏi đáp dạng Server-Sent Events (SSE) streaming token.
POST	/api/ingest	Upload file (multipart/form-data) chứa file .md, .docx.
POST	/api/ingest/directory	Nạp toàn bộ tài liệu từ thư mục sample-kb.
GET	/api/documents	Lấy danh sách tài liệu đã được nạp kèm số lượng chunks.
GET	/api/documents/{id}	Xem chi tiết một tài liệu theo ID.
DELETE	/api/documents/{id}	Xóa tài liệu và toàn bộ chunks/vectors liên quan.
GET	/api/health	Kiểm tra trạng thái kết nối Ollama và SQLite Database.

---

💡 Ví Dụ Sử Dụng (cURL / PowerShell)

1. Ingest tài liệu từ thư mục

curl -X POST "http://localhost:5000/api/ingest/directory"

2. Đặt câu hỏi (Q&A)

curl -X POST "http://localhost:5000/api/ask" \
     -H "Content-Type: application/json" \
     -d '{"question": "Thời gian làm việc cốt lõi bắt buộc khi làm việc từ xa là khi nào?"}'

Phản hồi mẫu:

{
  "answer": "Khung giờ làm việc cốt lõi bắt buộc khi làm việc từ xa là từ 09:00 đến 11:30 sáng và từ 13:30 đến 17:00 chiều các ngày làm việc (Thứ Hai đến Thứ Sáu). Trong khung giờ này, nhân viên bắt buộc phải online và phản hồi tin nhắn trong vòng 15 phút.",
  "sources": [
    {
      "fileName": "quy_dinh_lam_viec_tu_xa.md",
      "heading": "2. Thời Gian và Lịch Trình Làm Việc",
      "chunkPreview": "Nhân viên được phép đăng ký làm việc từ xa tối đa 2 ngày/tuần sau khi có sự phê duyệt của Trưởng bộ phận..."
    }
  ],
  "processingTimeMs": 1450
}

---

📄 Bản Quyền & Giấy Phép

Dự án được phân phối dưới giấy phép MIT License.