flexsds 0.2.0__tar.gz

flexsds-0.2.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: flexsds
+Version: 0.2.0
+Summary: Flexible Speculative Decoding Serving Engine for LLMs
+Author: Can Duc Khoi, Bui Duc Dai, Nguyen The Duong
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: psutil
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+<div align="center">
+
+<img src="logo/flexsds_banner.gif" alt="PTIT - FlexSDS Banner" width="100%" />
+
+# FlexSDS: Hệ thống phục vụ suy luận phỏng đoán thích ứng nhận biết phần cứng
+
+**Bộ công cụ phục vụ suy luận phỏng đoán thông minh cho các mô hình ngôn ngữ lớn tự lưu trữ**  
+*Hardware-Aware Adaptive Speculative Decoding Serving Toolkit for Self-Hosted LLMs*
+
+[![PTIT](https://img.shields.io/badge/PTIT-Đồ%20án%20tốt%20nghiệp%20D22-ED1C24?style=for-the-badge&logoColor=white)](https://portal.ptit.edu.vn/)
+[![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.13-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
+[![vLLM](https://img.shields.io/badge/vLLM-0.30.0%20Core%20V1-blue?style=for-the-badge)](https://github.com/vllm-project/vllm)
+[![Modal](https://img.shields.io/badge/Modal-GPU%20L4%20Serverless-00C7B7?style=for-the-badge)](https://modal.com)
+[![Status](https://img.shields.io/badge/Trạng%20thái-Sprint%205%20%2F%20M4%20Freeze-brightgreen?style=for-the-badge)]()
+
+<br/>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="logo/icon_dark.webp">
+  <source media="(prefers-color-scheme: light)" srcset="logo/icon_white.webp">
+  <img alt="FlexSDS Logo" src="logo/icon_dark.webp" width="90" height="90">
+</picture>
+
+</div>
+
+---
+
+## 1. Tổng quan đề tài
+
+Trong các hệ thống xử lý tài liệu tự động và chuỗi tác vụ đa bước (multi-step LLM pipeline), **độ trễ sinh từ trong pha giải mã (Decode Latency)** là nút thắt cổ chai lớn nhất và bị tích lũy lũy tiến qua từng lời gọi mô hình. Kỹ thuật suy luận phỏng đoán truyền thống (Static Speculative Decoding) sử dụng cấu hình nháp cố định thường gặp phải hai rào cản nghiêm trọng trong môi trường triển khai thực tế:
+1. **Hiện tượng tăng tốc âm (Negative Speedup):** Khi gặp các tác vụ suy luận tự do có entropy cao hoặc khi hệ thống chịu tải đồng thời lớn ($c \ge 16$), việc ép chạy mô hình nháp vô ích biến nó thành tải ký sinh, làm giảm tốc độ thực tế (chỉ đạt $0.67\times - 0.81\times$ so với suy luận tuần tự cơ sở).
+2. **Nguy cơ tràn bộ nhớ (Out-Of-Memory - OOM):** Việc đồng thời nạp cả mô hình đích, mô hình nháp và phân bổ bộ đệm KV dễ dẫn đến tràn VRAM trên các dòng GPU phổ thông (NVIDIA Tesla T4 16GB, RTX 4090 24GB).
+
+**FlexSDS** (*Flexible Speculative Decoding Serving*) là giải pháp mã nguồn mở hoàn chỉnh do nhóm sinh viên PTIT nghiên cứu và phát triển. Hệ thống tích hợp lớp điều khiển thích ứng **TreeAdaptive**, tự động nhận diện phần cứng, nạp ma trận chi phí thực nghiệm và giải ngưỡng hòa vốn động $\alpha^*(N, B)$ theo thời gian thực để co giãn cấu trúc cây nháp hoặc ngắt về suy luận tuần tự cơ sở, **bảo đảm tăng tốc tối đa nhưng không bao giờ bị chậm hơn chế độ mặc định (Lossless Guarantee)**.
+
+---
+
+## 2. Ứng dụng thực nghiệm: Luồng đa tác vụ trên hóa đơn bán hàng
+
+Để kiểm chứng năng lực thích ứng trong môi trường thực tế, FlexSDS được triển khai phục vụ quy trình xử lý và phân tích hóa đơn bán hàng tiếng Việt (bộ dữ liệu MC-OCR) với 3 tác vụ đại diện:
+
+```text
+┌────────────────────────────────────────────────────────────────────────┐
+│             HỆ THỐNG ĐA TÁC VỤ TRÊN HÓA ĐƠN BÁN HÀNG                   │
+├────────────────────────────────────────────────────────────────────────┤
+│                      [Ảnh / Thư mục hóa đơn tải lên]                   │
+│                                     │                                  │
+│                                     ▼                                  │
+│ ┌────────────────────────────────────────────────────────────────────┐ │
+│ │ TÁC VỤ 1: TRÍCH XUẤT NỘI DUNG HÓA ĐƠN THÀNH JSON (MC-OCR W1)       │ │
+│ │ • Trích xuất 7 trường pháp lý: Người bán, MST, Ngày, Tiền, VAT...   │ │
+│ │ • Cú pháp JSON cố định, alpha > 90% -> Tăng tốc tối đa (1.35x-1.4x) │ │
+│ └──────────────────────────────────┬─────────────────────────────────┘ │
+│                                    │                                   │
+│                                    ▼                                   │
+│ ┌────────────────────────────────────────────────────────────────────┐ │
+│ │ TÁC VỤ 2: SINH MÃ SQL TRUY VẤN DỮ LIỆU HÓA ĐƠN (TEXT-TO-SQL W2)   │ │
+│ │ • Chuyển câu hỏi quản trị kinh doanh tiếng Việt sang truy vấn SQL  │ │
+│ │ • Cú pháp SQL bán cấu trúc, alpha ~ 80% -> Tăng tốc ổn định 1.3x    │ │
+│ └──────────────────────────────────┬─────────────────────────────────┘ │
+│                                    │                                   │
+│                                    ▼                                   │
+│ ┌────────────────────────────────────────────────────────────────────┐ │
+│ │ TÁC VỤ 3: HỎI ĐÁP & PHÂN TÍCH TÀI CHÍNH THÔNG MINH (INVOICE CHAT) │ │
+│ │ • Khung chat tương tác trực tiếp về các hóa đơn vừa xử lý          │ │
+│ │ • Văn bản tự do, alpha < 60% -> Tự ngắt nháp (k=0), tránh trễ âm   │ │
+│ └────────────────────────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Các đột phá kỹ thuật nổi bật
+
+* **Lớp thích ứng nhận biết phần cứng (Hardware-Aware TreeAdaptive v0.2):** Tự động nhận diện kiến trúc GPU (`sm_89` NVIDIA L4, `sm_75` Tesla T4) và giải nghiệm phương trình hòa vốn theo thời gian thực:
+  $$\alpha^*(N, B) = \arg_\alpha \left( \frac{\mathbb{E}[\tau(N, \alpha)]}{C(N, B)} = \frac{1}{C(0, B)} \right)$$
+* **Triệt tiêu hoàn toàn hiện tượng tăng tốc âm:** Khi tỷ lệ chấp nhận thực tế $\alpha < \alpha^*$ hoặc khi bộ đệm KV vượt ngưỡng $90\%$, hệ thống lập tức ngắt suy đoán về chế độ an toàn ($N=0$), bảo đảm tốc độ luôn $\ge 1.00\times$.
+* **Bộ gác cổng an toàn tương thích (Pre-flight Guard):** Quét dung lượng VRAM thực tế, kiểm tra độ lệch từ vựng (Heterogeneous Vocabulary) giữa mô hình đích và mô hình nháp trước khi khởi động tiến trình serving.
+* **Đa nền tảng phục vụ:** Hỗ trợ khởi chạy server vLLM cục bộ (Local Dedicated Runner) hoặc triển khai tức thì lên nền tảng đám mây không máy chủ (Modal Cloud GPU L4) với chuẩn giao tiếp OpenAI API `/v1/chat/completions`.
+* **Giao diện dòng lệnh tương tác (Interactive CLI Wizard):** Menu hỏi–đáp từng bước có nhận diện thương hiệu PTIT bằng ký tự khối Unicode và mã màu ANSI TrueColor 24-bit.
+
+---
+
+## 4. Bốn chế độ suy luận đối chứng (4 Serving Lanes)
+
+Hệ thống cung cấp cơ chế đo kiểm thực nghiệm chuẩn hóa giữa 4 làn phục vụ trên cùng một hạ tầng phần cứng:
+
+1. **Làn 1 (`vanilla`):** Giải mã tuần tự cơ sở của mô hình đích Qwen2.5-7B-Instruct (chuẩn đối chứng $1.00\times$).
+2. **Làn 2 (`static`):** Suy luận phỏng đoán tĩnh với mô hình nháp độc lập Qwen2.5-0.5B-Instruct ($k=3$ cố định).
+3. **Làn 3 (`adaptive`):** Suy luận phỏng đoán thích ứng động TreeAdaptive co giãn ngân sách nháp theo tải và $\alpha$.
+4. **Làn 4 (`eagle`):** Đầu nháp suy đoán chuyên biệt EAGLE-3.1 tự huấn luyện cho miền hóa đơn tiếng Việt (`duckhoi/qwen2.5-7b-eagle3.1-speculator`).
+
+---
+
+## 5. Hướng dẫn cài đặt và sử dụng nhanh
+
+### 5.1. Cài đặt package
+
+```bash
+# Clone kho mã nguồn từ GitHub
+git clone https://github.com/theflyingkhui04/do-an-ptit-d22.git
+cd do-an-ptit-d22
+
+# Cài đặt môi trường ở chế độ phát triển (Editable Mode)
+pip install -e .
+```
+
+### 5.2. Khởi chạy giao diện dòng lệnh tương tác (Interactive Wizard)
+
+Chỉ cần gõ lệnh `flexsds` trên terminal để khởi động trợ lý hướng dẫn từng bước:
+
+```bash
+flexsds
+```
+
+Trợ lý sẽ tự động:
+1. Quét thông số phần cứng GPU và hiển thị banner nhận diện thương hiệu PTIT.
+2. Hướng dẫn chọn tác vụ, mô hình đích (Target), mô hình nháp (Draft).
+3. Chạy Pre-flight Guard kiểm tra an toàn VRAM và xung đột bảng từ vựng.
+4. Tự động nạp ma trận chi phí thực nghiệm và khởi chạy server phục vụ.
+
+### 5.3. Sử dụng lệnh trực tiếp (Direct CLI Commands)
+
+```bash
+# Quét nhanh phần cứng và trạng thái VRAM
+flexsds detect
+
+# Khởi chạy endpoint serving trên nền tảng Modal Cloud
+flexsds serve --backend modal --target Qwen/Qwen2.5-7B-Instruct-AWQ --draft Qwen/Qwen2.5-0.5B-Instruct
+
+# Khởi chạy server phục vụ cục bộ trên GPU máy chủ
+flexsds serve --backend local --port 8000 --gpu-memory-utilization 0.90
+```
+
+---
+
+## 6. Web demo và bảng đo lường metrics đối chứng
+
+Hệ thống tích hợp giao diện web demo trực quan hỗ trợ:
+* Tải lên một hoặc nhiều ảnh hóa đơn (kéo thả cả thư mục hoặc chụp ảnh trực tiếp).
+* Lựa chọn 3 tác vụ xử lý độc lập: Trích xuất JSON, Sinh câu truy vấn SQL, hoặc Chat hỏi đáp tài chính.
+* **Thiết lập đa endpoint song song:** Cho phép thêm URL của nhiều server (Vanilla vs. Static vs. FlexSDS Adaptive) để chạy đồng thời cùng một dữ liệu đầu vào.
+* **Bảng so sánh metrics thời gian thực:**
+  * **TPOT (Time per Output Token - ms/token):** Đo tốc độ sinh từ thực tế của từng endpoint.
+  * **Throughput (tokens/s):** Tốc độ xả token ra màn hình.
+  * **Tỉ lệ chấp nhận nháp $\alpha$ (%):** Phản ánh đặc trưng ngữ nghĩa của tác vụ.
+  * **Trạng thái thích ứng:** Huy hiệu hiển thị quyết định co giãn cây của FlexSDS (`[Boost: k=4]`, `[Balanced: k=2]`, hoặc `[Fallback: k=0]`).
+  * **Hệ số tăng tốc (Speedup vs. Vanilla):** Trực quan hóa hiện tượng tăng tốc âm của chế độ tĩnh và khả năng duy trì tốc độ an toàn của FlexSDS.
+
+---
+
+## 7. Cấu trúc kho mã nguồn
+
+```text
+do-an-ptit-d22/
+├── logo/                              # Tài nguyên hình ảnh, logo PTIT và banner GIF
+│   ├── flexsds_banner.gif             # Banner động độ phân giải cao hiển thị trên README
+│   ├── flexsds_banner_static.webp     # Banner tĩnh
+│   ├── icon_dark.webp                 # Logo biểu tượng chế độ nền tối (Dark mode)
+│   └── icon_white.webp                # Logo biểu tượng chế độ nền sáng (Light mode)
+├── pyproject.toml                     # Cấu hình package Python và entrypoint dòng lệnh flexsds
+├── src/
+│   ├── flexsds/                       # Gói mã nguồn công cụ FlexSDS
+│   │   ├── cli/                       # Giao diện CLI, Interactive Wizard và banner ANSI
+│   │   ├── core/                      # Bộ quét phần cứng, bộ gác cổng an toàn & TreeAdaptive
+│   │   ├── profiles/                  # Danh mục ma trận chi phí thực nghiệm (GPU L4 & T4)
+│   │   └── server/                    # Bộ điều phối runner (Modal serverless & Local vLLM)
+│   ├── server/                        # Bộ lập lịch thích ứng vLLM AdaptiveAsyncScheduler
+│   ├── proposer/                      # Bộ điều khiển nháp và mô hình chi phí thực nghiệm
+│   └── pipeline/                      # Đường ống xử lý hóa đơn MC-OCR (JSON, SQL, Report)
+├── experiments/                       # Bộ công cụ đo benchmark 4 làn và kịch bản thực nghiệm
+├── docs/                              # Tài liệu kỹ thuật, quy định thiết kế và outline báo cáo
+└── tests/                             # Bộ kiểm thử tự động toàn diện (unit & regression tests)
+```
+
+---
+
+## 8. Đội ngũ thực hiện
+
+Nhóm áp dụng mô hình **Ghép cặp Luân phiên 70/30 (Pair-Rotation System)**: Mỗi thành viên chủ trì (Lead) 70% mảng chuyên môn cốt lõi, đồng thời luân phiên đồng hành (Partner) 30% ở các mảng còn lại:
+
+| Chuyên môn cốt lõi (Lead 70%) | Thành viên thực hiện | Vai trò trong dự án |
+| :--- | :--- | :--- |
+| **AI Systems & Core-Engine** | **Cấn Đức Khôi** ([@theflyingkhui04](https://github.com/theflyingkhui04)) | Lead Architecture & Core vLLM Scheduler |
+| **MLOps & Infrastructure** | **Bùi Đức Đại** | Lead Benchmark Harness & GPU Telemetry |
+| **AI Application & Data** | **Dương Nguyễn Thế** | Lead Pipeline MC-OCR & Invoices Analytics |
+| **Giảng viên hướng dẫn** | *(Cập nhật theo quyết định của khoa)* | Cố vấn khoa học & Giám sát chất lượng |
+
+---
+
+## 9. Bản quyền
+
+Dự án được phát triển phục vụ đồ án tốt nghiệp đại học tại **Học viện Công nghệ Bưu chính Viễn thông (PTIT)**, niên khóa 2022–2026. Mã nguồn được phát hành theo giấy phép mã nguồn mở Apache 2.0.

flexsds-0.2.0/README.md

@@ -0,0 +1,193 @@
+<div align="center">
+
+<img src="logo/flexsds_banner.gif" alt="PTIT - FlexSDS Banner" width="100%" />
+
+# FlexSDS: Hệ thống phục vụ suy luận phỏng đoán thích ứng nhận biết phần cứng
+
+**Bộ công cụ phục vụ suy luận phỏng đoán thông minh cho các mô hình ngôn ngữ lớn tự lưu trữ**  
+*Hardware-Aware Adaptive Speculative Decoding Serving Toolkit for Self-Hosted LLMs*
+
+[![PTIT](https://img.shields.io/badge/PTIT-Đồ%20án%20tốt%20nghiệp%20D22-ED1C24?style=for-the-badge&logoColor=white)](https://portal.ptit.edu.vn/)
+[![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.13-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
+[![vLLM](https://img.shields.io/badge/vLLM-0.30.0%20Core%20V1-blue?style=for-the-badge)](https://github.com/vllm-project/vllm)
+[![Modal](https://img.shields.io/badge/Modal-GPU%20L4%20Serverless-00C7B7?style=for-the-badge)](https://modal.com)
+[![Status](https://img.shields.io/badge/Trạng%20thái-Sprint%205%20%2F%20M4%20Freeze-brightgreen?style=for-the-badge)]()
+
+<br/>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="logo/icon_dark.webp">
+  <source media="(prefers-color-scheme: light)" srcset="logo/icon_white.webp">
+  <img alt="FlexSDS Logo" src="logo/icon_dark.webp" width="90" height="90">
+</picture>
+
+</div>
+
+---
+
+## 1. Tổng quan đề tài
+
+Trong các hệ thống xử lý tài liệu tự động và chuỗi tác vụ đa bước (multi-step LLM pipeline), **độ trễ sinh từ trong pha giải mã (Decode Latency)** là nút thắt cổ chai lớn nhất và bị tích lũy lũy tiến qua từng lời gọi mô hình. Kỹ thuật suy luận phỏng đoán truyền thống (Static Speculative Decoding) sử dụng cấu hình nháp cố định thường gặp phải hai rào cản nghiêm trọng trong môi trường triển khai thực tế:
+1. **Hiện tượng tăng tốc âm (Negative Speedup):** Khi gặp các tác vụ suy luận tự do có entropy cao hoặc khi hệ thống chịu tải đồng thời lớn ($c \ge 16$), việc ép chạy mô hình nháp vô ích biến nó thành tải ký sinh, làm giảm tốc độ thực tế (chỉ đạt $0.67\times - 0.81\times$ so với suy luận tuần tự cơ sở).
+2. **Nguy cơ tràn bộ nhớ (Out-Of-Memory - OOM):** Việc đồng thời nạp cả mô hình đích, mô hình nháp và phân bổ bộ đệm KV dễ dẫn đến tràn VRAM trên các dòng GPU phổ thông (NVIDIA Tesla T4 16GB, RTX 4090 24GB).
+
+**FlexSDS** (*Flexible Speculative Decoding Serving*) là giải pháp mã nguồn mở hoàn chỉnh do nhóm sinh viên PTIT nghiên cứu và phát triển. Hệ thống tích hợp lớp điều khiển thích ứng **TreeAdaptive**, tự động nhận diện phần cứng, nạp ma trận chi phí thực nghiệm và giải ngưỡng hòa vốn động $\alpha^*(N, B)$ theo thời gian thực để co giãn cấu trúc cây nháp hoặc ngắt về suy luận tuần tự cơ sở, **bảo đảm tăng tốc tối đa nhưng không bao giờ bị chậm hơn chế độ mặc định (Lossless Guarantee)**.
+
+---
+
+## 2. Ứng dụng thực nghiệm: Luồng đa tác vụ trên hóa đơn bán hàng
+
+Để kiểm chứng năng lực thích ứng trong môi trường thực tế, FlexSDS được triển khai phục vụ quy trình xử lý và phân tích hóa đơn bán hàng tiếng Việt (bộ dữ liệu MC-OCR) với 3 tác vụ đại diện:
+
+```text
+┌────────────────────────────────────────────────────────────────────────┐
+│             HỆ THỐNG ĐA TÁC VỤ TRÊN HÓA ĐƠN BÁN HÀNG                   │
+├────────────────────────────────────────────────────────────────────────┤
+│                      [Ảnh / Thư mục hóa đơn tải lên]                   │
+│                                     │                                  │
+│                                     ▼                                  │
+│ ┌────────────────────────────────────────────────────────────────────┐ │
+│ │ TÁC VỤ 1: TRÍCH XUẤT NỘI DUNG HÓA ĐƠN THÀNH JSON (MC-OCR W1)       │ │
+│ │ • Trích xuất 7 trường pháp lý: Người bán, MST, Ngày, Tiền, VAT...   │ │
+│ │ • Cú pháp JSON cố định, alpha > 90% -> Tăng tốc tối đa (1.35x-1.4x) │ │
+│ └──────────────────────────────────┬─────────────────────────────────┘ │
+│                                    │                                   │
+│                                    ▼                                   │
+│ ┌────────────────────────────────────────────────────────────────────┐ │
+│ │ TÁC VỤ 2: SINH MÃ SQL TRUY VẤN DỮ LIỆU HÓA ĐƠN (TEXT-TO-SQL W2)   │ │
+│ │ • Chuyển câu hỏi quản trị kinh doanh tiếng Việt sang truy vấn SQL  │ │
+│ │ • Cú pháp SQL bán cấu trúc, alpha ~ 80% -> Tăng tốc ổn định 1.3x    │ │
+│ └──────────────────────────────────┬─────────────────────────────────┘ │
+│                                    │                                   │
+│                                    ▼                                   │
+│ ┌────────────────────────────────────────────────────────────────────┐ │
+│ │ TÁC VỤ 3: HỎI ĐÁP & PHÂN TÍCH TÀI CHÍNH THÔNG MINH (INVOICE CHAT) │ │
+│ │ • Khung chat tương tác trực tiếp về các hóa đơn vừa xử lý          │ │
+│ │ • Văn bản tự do, alpha < 60% -> Tự ngắt nháp (k=0), tránh trễ âm   │ │
+│ └────────────────────────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. Các đột phá kỹ thuật nổi bật
+
+* **Lớp thích ứng nhận biết phần cứng (Hardware-Aware TreeAdaptive v0.2):** Tự động nhận diện kiến trúc GPU (`sm_89` NVIDIA L4, `sm_75` Tesla T4) và giải nghiệm phương trình hòa vốn theo thời gian thực:
+  $$\alpha^*(N, B) = \arg_\alpha \left( \frac{\mathbb{E}[\tau(N, \alpha)]}{C(N, B)} = \frac{1}{C(0, B)} \right)$$
+* **Triệt tiêu hoàn toàn hiện tượng tăng tốc âm:** Khi tỷ lệ chấp nhận thực tế $\alpha < \alpha^*$ hoặc khi bộ đệm KV vượt ngưỡng $90\%$, hệ thống lập tức ngắt suy đoán về chế độ an toàn ($N=0$), bảo đảm tốc độ luôn $\ge 1.00\times$.
+* **Bộ gác cổng an toàn tương thích (Pre-flight Guard):** Quét dung lượng VRAM thực tế, kiểm tra độ lệch từ vựng (Heterogeneous Vocabulary) giữa mô hình đích và mô hình nháp trước khi khởi động tiến trình serving.
+* **Đa nền tảng phục vụ:** Hỗ trợ khởi chạy server vLLM cục bộ (Local Dedicated Runner) hoặc triển khai tức thì lên nền tảng đám mây không máy chủ (Modal Cloud GPU L4) với chuẩn giao tiếp OpenAI API `/v1/chat/completions`.
+* **Giao diện dòng lệnh tương tác (Interactive CLI Wizard):** Menu hỏi–đáp từng bước có nhận diện thương hiệu PTIT bằng ký tự khối Unicode và mã màu ANSI TrueColor 24-bit.
+
+---
+
+## 4. Bốn chế độ suy luận đối chứng (4 Serving Lanes)
+
+Hệ thống cung cấp cơ chế đo kiểm thực nghiệm chuẩn hóa giữa 4 làn phục vụ trên cùng một hạ tầng phần cứng:
+
+1. **Làn 1 (`vanilla`):** Giải mã tuần tự cơ sở của mô hình đích Qwen2.5-7B-Instruct (chuẩn đối chứng $1.00\times$).
+2. **Làn 2 (`static`):** Suy luận phỏng đoán tĩnh với mô hình nháp độc lập Qwen2.5-0.5B-Instruct ($k=3$ cố định).
+3. **Làn 3 (`adaptive`):** Suy luận phỏng đoán thích ứng động TreeAdaptive co giãn ngân sách nháp theo tải và $\alpha$.
+4. **Làn 4 (`eagle`):** Đầu nháp suy đoán chuyên biệt EAGLE-3.1 tự huấn luyện cho miền hóa đơn tiếng Việt (`duckhoi/qwen2.5-7b-eagle3.1-speculator`).
+
+---
+
+## 5. Hướng dẫn cài đặt và sử dụng nhanh
+
+### 5.1. Cài đặt package
+
+```bash
+# Clone kho mã nguồn từ GitHub
+git clone https://github.com/theflyingkhui04/do-an-ptit-d22.git
+cd do-an-ptit-d22
+
+# Cài đặt môi trường ở chế độ phát triển (Editable Mode)
+pip install -e .
+```
+
+### 5.2. Khởi chạy giao diện dòng lệnh tương tác (Interactive Wizard)
+
+Chỉ cần gõ lệnh `flexsds` trên terminal để khởi động trợ lý hướng dẫn từng bước:
+
+```bash
+flexsds
+```
+
+Trợ lý sẽ tự động:
+1. Quét thông số phần cứng GPU và hiển thị banner nhận diện thương hiệu PTIT.
+2. Hướng dẫn chọn tác vụ, mô hình đích (Target), mô hình nháp (Draft).
+3. Chạy Pre-flight Guard kiểm tra an toàn VRAM và xung đột bảng từ vựng.
+4. Tự động nạp ma trận chi phí thực nghiệm và khởi chạy server phục vụ.
+
+### 5.3. Sử dụng lệnh trực tiếp (Direct CLI Commands)
+
+```bash
+# Quét nhanh phần cứng và trạng thái VRAM
+flexsds detect
+
+# Khởi chạy endpoint serving trên nền tảng Modal Cloud
+flexsds serve --backend modal --target Qwen/Qwen2.5-7B-Instruct-AWQ --draft Qwen/Qwen2.5-0.5B-Instruct
+
+# Khởi chạy server phục vụ cục bộ trên GPU máy chủ
+flexsds serve --backend local --port 8000 --gpu-memory-utilization 0.90
+```
+
+---
+
+## 6. Web demo và bảng đo lường metrics đối chứng
+
+Hệ thống tích hợp giao diện web demo trực quan hỗ trợ:
+* Tải lên một hoặc nhiều ảnh hóa đơn (kéo thả cả thư mục hoặc chụp ảnh trực tiếp).
+* Lựa chọn 3 tác vụ xử lý độc lập: Trích xuất JSON, Sinh câu truy vấn SQL, hoặc Chat hỏi đáp tài chính.
+* **Thiết lập đa endpoint song song:** Cho phép thêm URL của nhiều server (Vanilla vs. Static vs. FlexSDS Adaptive) để chạy đồng thời cùng một dữ liệu đầu vào.
+* **Bảng so sánh metrics thời gian thực:**
+  * **TPOT (Time per Output Token - ms/token):** Đo tốc độ sinh từ thực tế của từng endpoint.
+  * **Throughput (tokens/s):** Tốc độ xả token ra màn hình.
+  * **Tỉ lệ chấp nhận nháp $\alpha$ (%):** Phản ánh đặc trưng ngữ nghĩa của tác vụ.
+  * **Trạng thái thích ứng:** Huy hiệu hiển thị quyết định co giãn cây của FlexSDS (`[Boost: k=4]`, `[Balanced: k=2]`, hoặc `[Fallback: k=0]`).
+  * **Hệ số tăng tốc (Speedup vs. Vanilla):** Trực quan hóa hiện tượng tăng tốc âm của chế độ tĩnh và khả năng duy trì tốc độ an toàn của FlexSDS.
+
+---
+
+## 7. Cấu trúc kho mã nguồn
+
+```text
+do-an-ptit-d22/
+├── logo/                              # Tài nguyên hình ảnh, logo PTIT và banner GIF
+│   ├── flexsds_banner.gif             # Banner động độ phân giải cao hiển thị trên README
+│   ├── flexsds_banner_static.webp     # Banner tĩnh
+│   ├── icon_dark.webp                 # Logo biểu tượng chế độ nền tối (Dark mode)
+│   └── icon_white.webp                # Logo biểu tượng chế độ nền sáng (Light mode)
+├── pyproject.toml                     # Cấu hình package Python và entrypoint dòng lệnh flexsds
+├── src/
+│   ├── flexsds/                       # Gói mã nguồn công cụ FlexSDS
+│   │   ├── cli/                       # Giao diện CLI, Interactive Wizard và banner ANSI
+│   │   ├── core/                      # Bộ quét phần cứng, bộ gác cổng an toàn & TreeAdaptive
+│   │   ├── profiles/                  # Danh mục ma trận chi phí thực nghiệm (GPU L4 & T4)
+│   │   └── server/                    # Bộ điều phối runner (Modal serverless & Local vLLM)
+│   ├── server/                        # Bộ lập lịch thích ứng vLLM AdaptiveAsyncScheduler
+│   ├── proposer/                      # Bộ điều khiển nháp và mô hình chi phí thực nghiệm
+│   └── pipeline/                      # Đường ống xử lý hóa đơn MC-OCR (JSON, SQL, Report)
+├── experiments/                       # Bộ công cụ đo benchmark 4 làn và kịch bản thực nghiệm
+├── docs/                              # Tài liệu kỹ thuật, quy định thiết kế và outline báo cáo
+└── tests/                             # Bộ kiểm thử tự động toàn diện (unit & regression tests)
+```
+
+---
+
+## 8. Đội ngũ thực hiện
+
+Nhóm áp dụng mô hình **Ghép cặp Luân phiên 70/30 (Pair-Rotation System)**: Mỗi thành viên chủ trì (Lead) 70% mảng chuyên môn cốt lõi, đồng thời luân phiên đồng hành (Partner) 30% ở các mảng còn lại:
+
+| Chuyên môn cốt lõi (Lead 70%) | Thành viên thực hiện | Vai trò trong dự án |
+| :--- | :--- | :--- |
+| **AI Systems & Core-Engine** | **Cấn Đức Khôi** ([@theflyingkhui04](https://github.com/theflyingkhui04)) | Lead Architecture & Core vLLM Scheduler |
+| **MLOps & Infrastructure** | **Bùi Đức Đại** | Lead Benchmark Harness & GPU Telemetry |
+| **AI Application & Data** | **Dương Nguyễn Thế** | Lead Pipeline MC-OCR & Invoices Analytics |
+| **Giảng viên hướng dẫn** | *(Cập nhật theo quyết định của khoa)* | Cố vấn khoa học & Giám sát chất lượng |
+
+---
+
+## 9. Bản quyền
+
+Dự án được phát triển phục vụ đồ án tốt nghiệp đại học tại **Học viện Công nghệ Bưu chính Viễn thông (PTIT)**, niên khóa 2022–2026. Mã nguồn được phát hành theo giấy phép mã nguồn mở Apache 2.0.

flexsds-0.2.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flexsds"
+version = "0.2.0"
+description = "Flexible Speculative Decoding Serving Engine for LLMs"
+authors = [
+    {name = "Can Duc Khoi"},
+    {name = "Bui Duc Dai"},
+    {name = "Nguyen The Duong"}
+]
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "psutil",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+flexsds = "flexsds.cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["flexsds*", "server*", "proposer*", "pipeline*"]
+
+[tool.setuptools.package-data]
+flexsds = ["profiles/*.json", "assets/*"]
+pipeline = ["prompts/*.md", "schemas/*.json", "examples/*", "sqlite/*.sql"]

flexsds-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flexsds-0.2.0/src/flexsds/__init__.py

@@ -0,0 +1,4 @@
+"""FlexSDS: Flexible Speculative Decoding Serving Engine for LLMs."""
+
+__version__ = "0.2.0"
+__author__ = "Can Duc Khoi, Bui Duc Dai & Nguyen The Duong"

flexsds-0.2.0/src/flexsds/cli/__init__.py

@@ -0,0 +1 @@
+"""FlexSDS CLI module."""

flexsds-0.2.0/src/flexsds/cli/banner.py

@@ -0,0 +1,84 @@
+"""FlexSDS branding banner module with PTIT logo in ANSI TrueColor."""
+from __future__ import annotations
+
+import sys
+from typing import Optional
+try:
+    from flexsds.cli.output import ascii_text, print_output, supports_truecolor, supports_unicode
+    from flexsds.core.hardware import HardwareInfo, detect_hardware
+except ModuleNotFoundError:
+    from src.flexsds.cli.output import ascii_text, print_output, supports_truecolor, supports_unicode
+    from src.flexsds.core.hardware import HardwareInfo, detect_hardware
+
+# Pre-compiled ANSI grayscale half-blocks for the official PTIT logo (26 cols x 12 rows)
+# Zero-dependency, sub-millisecond monochrome rendering without PIL at runtime.
+PTIT_LOGO_ANSI = [
+    "            \033[38;2;181;181;181m▄\033[0m\033[38;2;112;112;112m▄\033[0m\033[38;2;185;185;185;48;2;119;119;119m▀\033[0m\033[38;2;128;128;128;48;2;154;154;154m▀\033[0m\033[38;2;95;95;95;48;2;176;176;176m▀\033[0m\033[38;2;81;81;81;48;2;175;175;175m▀\033[0m\033[38;2;83;83;83;48;2;145;145;145m▀\033[0m\033[38;2;103;103;103;48;2;95;95;95m▀\033[0m\033[38;2;140;140;140;48;2;72;72;72m▀\033[0m\033[38;2;214;214;214;48;2;87;87;87m▀\033[0m\033[38;2;196;196;196m▄\033[0m   ",
+    "         \033[38;2;170;170;170m▄\033[0m\033[38;2;202;202;202;48;2;165;165;165m▀\033[0m\033[38;2;139;139;139;48;2;222;222;222m▀\033[0m\033[38;2;150;150;150m▀\033[0m\033[38;2;221;221;221m▀\033[0m      \033[38;2;149;149;149m▀\033[0m\033[38;2;74;74;74;48;2;138;138;138m▀\033[0m\033[38;2;101;101;101;48;2;74;74;74m▀\033[0m\033[38;2;216;216;216m▄\033[0m  ",
+    "      \033[38;2;211;211;211m▄\033[0m\033[38;2;215;215;215;48;2;152;152;152m▀\033[0m\033[38;2;169;169;169m▀\033[0m\033[38;2;215;215;215m▀\033[0m           \033[38;2;222;222;222m▀\033[0m\033[38;2;76;76;76;48;2;99;99;99m▀\033[0m\033[38;2;206;206;206;48;2;214;214;214m▀\033[0m  ",
+    "     \033[38;2;221;221;221;48;2;108;108;108m▀\033[0m\033[38;2;125;125;125;48;2;217;217;217m▀\033[0m               \033[38;2;120;120;120;48;2;145;145;145m▀\033[0m   ",
+    "   \033[38;2;177;177;177m▄\033[0m\033[38;2;124;124;124;48;2;87;87;87m▀\033[0m\033[38;2;155;155;155m▀\033[0m             \033[38;2;231;231;231m▄\033[0m \033[38;2;208;208;208;48;2;187;187;187m▀\033[0m\033[38;2;187;187;187m▀\033[0m   ",
+    "  \033[38;2;160;160;160m▄\033[0m\033[38;2;80;80;80;48;2;71;71;71m▀\033[0m\033[38;2;160;160;160;48;2;227;227;227m▀\033[0m \033[38;2;185;185;185m▄\033[0m\033[38;2;181;181;181m▄\033[0m\033[38;2;178;178;178m▄\033[0m\033[38;2;212;212;212m▄\033[0m \033[38;2;183;183;183m▄\033[0m\033[38;2;185;185;185m▄\033[0m\033[38;2;193;193;193m▄\033[0m\033[38;2;176;176;176m▄\033[0m\033[38;2;210;210;210m▄\033[0m\033[38;2;232;232;232m▄\033[0m\033[38;2;230;230;230m▄\033[0m\033[38;2;218;218;218;48;2;181;181;181m▀\033[0m\033[38;2;219;219;219;48;2;207;207;207m▀\033[0m\033[38;2;229;229;229m▄\033[0m\033[38;2;227;227;227;48;2;170;170;170m▀\033[0m\033[38;2;173;173;173m▄\033[0m\033[38;2;181;181;181m▄\033[0m\033[38;2;166;166;166m▄\033[0m\033[38;2;198;198;198m▄\033[0m",
+    " \033[38;2;209;209;209m▄\033[0m\033[38;2;98;98;98;48;2;71;71;71m▀\033[0m\033[38;2;100;100;100;48;2;132;132;132m▀\033[0m \033[38;2;180;180;180;48;2;181;181;181m▀\033[0m\033[38;2;77;77;77;48;2;95;95;95m▀\033[0m\033[38;2;179;179;179;48;2;225;225;225m▀\033[0m\033[38;2;170;170;170;48;2;218;218;218m▀\033[0m\033[38;2;94;94;94;48;2;92;92;92m▀\033[0m\033[38;2;155;155;155;48;2;145;145;145m▀\033[0m\033[38;2;173;173;173m▀\033[0m\033[38;2;129;129;129;48;2;196;196;196m▀\033[0m\033[38;2;90;90;90;48;2;111;111;111m▀\033[0m\033[38;2;161;161;161m▀\033[0m\033[38;2;206;206;206;48;2;246;246;246m▀\033[0m\033[38;2;218;218;218;48;2;210;210;210m▀\033[0m\033[38;2;173;173;173;48;2;185;185;185m▀\033[0m\033[38;2;194;194;194;48;2;205;205;205m▀\033[0m\033[38;2;232;232;232m▀\033[0m \033[38;2;177;177;177m▀\033[0m\033[38;2;137;137;137;48;2;200;200;200m▀\033[0m\033[38;2;86;86;86;48;2;107;107;107m▀\033[0m\033[38;2;172;172;172m▀\033[0m\033[38;2;202;202;202m▀\033[0m",
+    " \033[38;2;165;165;165;48;2;138;138;138m▀\033[0m\033[38;2;66;66;66;48;2;68;68;68m▀\033[0m\033[38;2;149;149;149;48;2;149;149;149m▀\033[0m \033[38;2;183;183;183;48;2;173;173;173m▀\033[0m\033[38;2;86;86;86;48;2;86;86;86m▀\033[0m\033[38;2;143;143;143m▀\033[0m\033[38;2;138;138;138m▀\033[0m\033[38;2;168;168;168m▀\033[0m  \033[38;2;188;188;188;48;2;184;184;184m▀\033[0m\033[38;2;110;110;110;48;2;95;95;95m▀\033[0m \033[38;2;221;221;221m▄\033[0m\033[38;2;222;222;222;48;2;107;107;107m▀\033[0m\033[38;2;144;144;144;48;2;129;129;129m▀\033[0m\033[38;2;133;133;133;48;2;92;92;92m▀\033[0m   \033[38;2;190;190;190;48;2;186;186;186m▀\033[0m\033[38;2;106;106;106;48;2;92;92;92m▀\033[0m  ",
+    " \033[38;2;126;126;126;48;2;135;135;135m▀\033[0m\033[38;2;72;72;72;48;2;78;78;78m▀\033[0m\033[38;2;131;131;131;48;2;97;97;97m▀\033[0m \033[38;2;217;217;217m▀\033[0m\033[38;2;178;178;178m▀\033[0m     \033[38;2;221;221;221m▀\033[0m\033[38;2;182;182;182;48;2;157;157;157m▀\033[0m\033[38;2;198;198;198;48;2;68;68;68m▀\033[0m\033[38;2;81;81;81;48;2;101;101;101m▀\033[0m\033[38;2;106;106;106;48;2;224;224;224m▀\033[0m\033[38;2;197;197;197m▀\033[0m\033[38;2;179;179;179m▀\033[0m   \033[38;2;223;223;223m▀\033[0m\033[38;2;181;181;181m▀\033[0m  ",
+    " \033[38;2;193;193;193m▀\033[0m\033[38;2;74;74;74;48;2;165;165;165m▀\033[0m\033[38;2;77;77;77;48;2;96;96;96m▀\033[0m\033[38;2;145;145;145;48;2;86;86;86m▀\033[0m\033[38;2;152;152;152m▄\033[0m  \033[38;2;227;227;227m▄\033[0m\033[38;2;166;166;166m▄\033[0m\033[38;2;93;93;93m▄\033[0m\033[38;2;175;175;175;48;2;69;69;69m▀\033[0m\033[38;2;87;87;87;48;2;121;121;121m▀\033[0m\033[38;2;68;68;68;48;2;205;205;205m▀\033[0m\033[38;2;142;142;142m▀\033[0m           ",
+    "   \033[38;2;195;195;195m▀\033[0m\033[38;2;148;148;148;48;2;209;209;209m▀\033[0m\033[38;2;124;124;124;48;2;179;179;179m▀\033[0m\033[38;2;130;130;130;48;2;160;160;160m▀\033[0m\033[38;2;117;117;117;48;2;164;164;164m▀\033[0m\033[38;2;88;88;88;48;2;193;193;193m▀\033[0m\033[38;2;94;94;94;48;2;226;226;226m▀\033[0m\033[38;2;147;147;147m▀\033[0m\033[38;2;218;218;218m▀\033[0m              ",
+    "\033[38;2;125;125;125;48;2;141;141;141m▀\033[0m\033[38;2;118;118;118;48;2;136;136;136m▀\033[0m\033[38;2;119;119;119;48;2;137;137;137m▀\033[0m\033[38;2;120;120;120;48;2;138;138;138m▀\033[0m\033[38;2;125;125;125;48;2;137;137;137m▀\033[0m\033[38;2;130;130;130;48;2;136;136;136m▀\033[0m\033[38;2;133;133;133;48;2;136;136;136m▀\033[0m\033[38;2;132;132;132;48;2;137;137;137m▀\033[0m\033[38;2;128;128;128;48;2;138;138;138m▀\033[0m\033[38;2;122;122;122;48;2;140;140;140m▀\033[0m\033[38;2;118;118;118;48;2;141;141;141m▀\033[0m\033[38;2;113;113;113;48;2;136;136;136m▀\033[0m\033[38;2;148;148;148;48;2;141;141;141m▀\033[0m\033[38;2;149;149;149;48;2;144;144;144m▀\033[0m\033[38;2;114;114;114;48;2;134;134;134m▀\033[0m\033[38;2;118;118;118;48;2;143;143;143m▀\033[0m\033[38;2;118;118;118;48;2;140;140;140m▀\033[0m\033[38;2;118;118;118;48;2;140;140;140m▀\033[0m\033[38;2;118;118;118;48;2;140;140;140m▀\033[0m\033[38;2;118;118;118;48;2;139;139;139m▀\033[0m\033[38;2;119;119;119;48;2;139;139;139m▀\033[0m\033[38;2;119;119;119;48;2;138;138;138m▀\033[0m\033[38;2;119;119;119;48;2;138;138;138m▀\033[0m\033[38;2;119;119;119;48;2;137;137;137m▀\033[0m\033[38;2;119;119;119;48;2;137;137;137m▀\033[0m\033[38;2;119;119;119;48;2;137;137;137m▀\033[0m",
+]
+
+def render_banner(hw_info: Optional[HardwareInfo] = None) -> str:
+    """Builds and returns the complete side-by-side FlexSDS banner."""
+    if hw_info is None:
+        hw_info = detect_hardware()
+
+    gpu_str = hw_info.summary()
+
+    info_lines = [
+        "\033[1;37m  ███████╗██╗     ███████╗██╗  ██╗███████╗██████╗ ███████╗\033[0m",
+        "\033[1;37m  ██╔════╝██║     ██╔════╝╚██╗██╔╝██╔════╝██╔══██╗██╔════╝\033[0m",
+        "\033[1;37m  █████╗  ██║     █████╗   ╚███╔╝ ███████╗██║  ██║███████╗\033[0m",
+        "\033[1;37m  ██╔══╝  ██║     ██╔══╝   ██╔██╗ ╚════██║██║  ██║╚════██║\033[0m",
+        "\033[1;37m  ██║     ███████╗███████╗██╔╝ ██╗███████║██████╔╝███████║\033[0m",
+        "",
+        "  \033[1;37mFlexSDS\033[0m \033[90m· Speculative Decoding Serving Engine · v0.2.0-alpha\033[0m",
+        "  \033[90mNhóm đồ án D22\033[0m",
+        "  \033[90mHọc viện Công nghệ Bưu chính Viễn thông (PTIT)\033[0m",
+        "",
+        f"  \033[90m•\033[0m \033[37mHardware\033[0m    : \033[90m{gpu_str}\033[0m",
+        "  \033[90m•\033[0m \033[37mEngine\033[0m      : \033[90mHardwareAdaptive v0.2\033[0m",
+        "  \033[90m•\033[0m \033[37mBackends\033[0m    : \033[90mModal / Colab / Local vLLM\033[0m",
+    ]
+
+    max_rows = max(len(PTIT_LOGO_ANSI), len(info_lines))
+    col_logo = list(PTIT_LOGO_ANSI) + [" " * 26] * (max_rows - len(PTIT_LOGO_ANSI))
+    col_info = list(info_lines) + [""] * (max_rows - len(info_lines))
+
+    output = []
+    for l, r in zip(col_logo, col_info):
+        output.append(f" {l}  {r}")
+    return "\n".join(output)
+
+
+def render_ascii_banner(hw_info: HardwareInfo) -> str:
+    """Compact branding/status fallback; hardware logic remains in HardwareInfo."""
+    return ascii_text(
+        "FlexSDS | Speculative Decoding Serving Engine | v0.2.0-alpha\n"
+        "PTIT | Hoc vien Cong nghe Buu chinh Vien thong | Nhom do an D22\n"
+        f"Hardware: {hw_info.summary()}\n"
+        "Engine: TreeAdaptive v0.2\n"
+        "Backends: Modal / Colab / Local vLLM"
+    )
+
+
+def print_banner(hw_info: Optional[HardwareInfo] = None) -> None:
+    """Preserve rich branding on capable terminals; otherwise use plain ASCII."""
+    if hw_info is None:
+        hw_info = detect_hardware()
+    fallback = render_ascii_banner(hw_info)
+    rich = supports_unicode(sys.stdout) and supports_truecolor(sys.stdout)
+    print_output(render_banner(hw_info) if rich else fallback, fallback=fallback)
+
+
+if __name__ == "__main__":
+    print_banner()