flexsds 0.2.0__py3-none-any.whl

flexsds/server/local_runner.py

@@ -0,0 +1,208 @@
+"""Local serving runner and zero-zombie process management."""
+from __future__ import annotations
+
+import json
+import os
+import signal
+import socket
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:
+    from flexsds.cli.output import print_output as print
+except ModuleNotFoundError:
+    from src.flexsds.cli.output import print_output as print
+
+
+def finish_launch(proc, background: bool = False) -> int:
+    """Propagate startup/foreground failure without equating a process with readiness."""
+    if proc is None:
+        print("Launch failed; no serving readiness established.")
+        return 1
+    print("Serving process started; endpoint readiness is not verified.")
+    try:
+        code = proc.poll() if background else proc.wait()
+        return code if isinstance(code, int) else 0
+    except KeyboardInterrupt:
+        proc.terminate()
+        try:
+            proc.wait(timeout=15)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+        return 130
+
+
+class LocalServingRunner:
+    """Khởi chạy và quản lý vòng đời máy chủ vLLM cục bộ với FlexSDS."""
+
+    def build_command(self, config: Dict[str, Any], port: Optional[int] = None) -> List[str]:
+        """Tạo danh sách đối số dòng lệnh chạy vLLM phục vụ mô hình."""
+        serving_cfg = config.get("serving", config)
+        target_model = serving_cfg.get("target_model", "Qwen/Qwen2.5-7B-Instruct-AWQ")
+        draft_model = serving_cfg.get("draft_model", "duckhoi/qwen2.5-7b-eagle3.1-speculator")
+        draft_method = serving_cfg.get("draft_method", "eagle3")
+        use_hetero = serving_cfg.get("use_heterogeneous_vocab", True)
+
+        effective_port = port if port is not None else serving_cfg.get("port", 8000)
+        target_lower = target_model.lower()
+
+        # Xác định quantization và dtype
+        if "awq" in target_lower:
+            quantization = "awq_marlin"
+            dtype = "bfloat16"
+        elif "gptq" in target_lower:
+            quantization = "gptq"
+            dtype = "float16"
+        else:
+            quantization = serving_cfg.get("quantization", "none")
+            dtype = serving_cfg.get("dtype", "bfloat16")
+
+        speculative_config: Dict[str, Any] = {
+            "method": draft_method,
+            "model": draft_model,
+            "num_speculative_tokens": 4,
+            "num_speculative_tokens_per_batch_size": [[1, 32, 4]],
+            "draft_sample_method": "greedy",
+        }
+        if use_hetero:
+            speculative_config["use_heterogeneous_vocab"] = True
+
+        cmd: List[str] = [
+            "vllm",
+            "serve",
+            target_model,
+            "--host",
+            "0.0.0.0",
+            "--port",
+            str(effective_port),
+            "--served-model-name",
+            serving_cfg.get("served_model_name", "qwen2.5-7b-adaptive"),
+            "--dtype",
+            dtype,
+            "--generation-config",
+            "vllm",
+            "--gpu-memory-utilization",
+            str(serving_cfg.get("gpu_memory_utilization", 0.85)),
+            "--max-model-len",
+            str(serving_cfg.get("max_model_len", 4096)),
+            "--max-num-seqs",
+            str(serving_cfg.get("max_num_seqs", 32)),
+        ]
+
+        if quantization != "none":
+            cmd.extend(["--quantization", quantization])
+
+        if serving_cfg.get("enable_adaptive", True):
+            cmd.extend([
+                "--speculative-config", json.dumps(speculative_config),
+                "--scheduler-cls", "src.server.adaptive_scheduler.AdaptiveAsyncScheduler",
+                "--distributed-executor-backend", "src.server.lineage_executor.LineageUniProcExecutor",
+                "--per-request-spec-decode-metrics", "summary",
+            ])
+        else:
+            # Static speculation uses vLLM's default scheduler/executor, not the adaptive pair.
+            speculative_config.pop("num_speculative_tokens_per_batch_size", None)
+            cmd.extend(["--speculative-config", json.dumps(speculative_config)])
+
+        return cmd
+
+    def check_port_available(self, port: int) -> bool:
+        """Kiểm tra xem cổng port có đang khả dụng không."""
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                s.bind(("", port))
+                return True
+            except OSError:
+                return False
+
+    def setup_environment(self, config: Dict[str, Any]) -> Dict[str, str]:
+        """Thiết lập các biến môi trường cho FlexSDS Adaptive Scheduler."""
+        serving_cfg = config.get("serving", config)
+        env = dict(os.environ)
+        project_root = str(Path(__file__).resolve().parents[3])
+        existing_pythonpath = env.get("PYTHONPATH", "")
+        if project_root not in existing_pythonpath:
+            env["PYTHONPATH"] = f"{project_root}{os.pathsep}{existing_pythonpath}" if existing_pythonpath else project_root
+        env["ADAPTIVE_ENABLE_VRAM_GUARD"] = "1"
+        env["ADAPTIVE_TELEMETRY_PATH"] = os.path.abspath(
+            serving_cfg.get("telemetry_path", "telemetry/serving_trace.jsonl")
+        )
+        env["ADAPTIVE_MAX_K"] = str(serving_cfg.get("max_k", 4))
+        env["ADAPTIVE_MIN_BATCH_K"] = "0"
+        env["ADAPTIVE_PER_REQUEST"] = "1"
+        return env
+
+    def launch(
+        self,
+        config: Dict[str, Any],
+        port: Optional[int] = None,
+        background: bool = False,
+        pid_file: str = ".flexsds.pid",
+        dry_run: bool = False,
+    ) -> Optional[subprocess.Popen]:
+        """Khởi chạy tiến trình máy chủ cục bộ."""
+        effective_port = port if port is not None else config.get("serving", config).get("port", 8000)
+        cmd = self.build_command(config, port=effective_port)
+        env = self.setup_environment(config)
+
+        if dry_run:
+            print("\n[FlexSDS] Dry-run execution command:")
+            print(" ".join(cmd))
+            print(f"Environment: ADAPTIVE_ENABLE_VRAM_GUARD={env.get('ADAPTIVE_ENABLE_VRAM_GUARD')}")
+            return None
+
+        if not self.check_port_available(effective_port):
+            print(f"\n\033[31m[Lỗi]\033[0m Cổng {effective_port} đang bị chiếm dụng bởi tiến trình khác.")
+            print(f"  Gợi ý: Dùng cờ --port <cổng_khác> hoặc chạy: flexsds stop")
+            return None
+
+        if background and os.name == "nt":
+            print("Background process-group serving is unsupported on Windows; use foreground serving.")
+            return None
+
+        try:
+            if background:
+                log_path = "flexsds_server.log"
+                log_file = open(log_path, "a", encoding="utf-8")
+                proc = subprocess.Popen(
+                    cmd,
+                    env=env,
+                    preexec_fn=os.setsid,
+                    stdout=log_file,
+                    stderr=subprocess.STDOUT,
+                )
+                with open(pid_file, "w", encoding="utf-8") as f:
+                    f.write(f"{proc.pid}\n")
+                print(f"[FlexSDS] Server started in background (PID: {proc.pid}, Log: {log_path})")
+                return proc
+            else:
+                return subprocess.Popen(cmd, env=env)
+        except FileNotFoundError:
+            print("\n\033[31m[Error]\033[0m Server binary not found in PATH.")
+            return None
+
+    def stop(self, pid_file: str = ".flexsds.pid") -> bool:
+        """Dừng nhóm tiến trình máy chủ vLLM và dọn dẹp sạch tiến trình con."""
+        if os.name == "nt":
+            print("Local process-group stop is unsupported on Windows; stop the foreground session.")
+            return False
+        if not os.path.exists(pid_file):
+            return False
+
+        try:
+            with open(pid_file, "r", encoding="utf-8") as f:
+                content = f.read().strip()
+                if not content:
+                    return False
+                pid = int(content)
+
+            os.killpg(pid, signal.SIGTERM)
+        except (ProcessLookupError, ValueError):
+            pass
+        finally:
+            if os.path.exists(pid_file):
+                os.remove(pid_file)
+
+        return True

flexsds/server/modal_app.py

@@ -0,0 +1,50 @@
+"""Modal HTTP app; configuration is passed by the CLI, never embedded credentials.
+
+Development: modal serve. Persistent service: modal deploy.
+The web_server decorator owns startup readiness and endpoint exposure.
+"""
+from __future__ import annotations
+import json
+import os
+import subprocess
+from pathlib import Path
+
+from flexsds.server.local_runner import LocalServingRunner
+
+APP_NAME = "flexsds-serving"
+SERVING_CONFIG = json.loads(os.environ.get("FLEXSDS_SERVING_CONFIG", "{}"))
+PORT = int(SERVING_CONFIG.get("port", 8000))
+GPU = SERVING_CONFIG.get("target_gpu", "L4")
+if GPU not in {"L4", "T4", "A10G"} or not 1 <= PORT <= 65535:
+    raise ValueError("Unsupported Modal GPU or serving port")
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+
+try:
+    import modal
+except ImportError:
+    modal = None
+
+if modal is not None:
+    app = modal.App(APP_NAME)
+    image = (
+        modal.Image.debian_slim(python_version="3.11")
+        .pip_install("vllm==0.30.0", "fastapi", "psutil")
+        .env({"PYTHONPATH": "/root/project:/root/project/src",
+              "FLEXSDS_SERVING_CONFIG": json.dumps(SERVING_CONFIG)})
+        .add_local_dir(str(PROJECT_ROOT / "src"), remote_path="/root/project/src")
+        .add_local_file(str(PROJECT_ROOT / "experiments/scalar_vllm_source_manifest.json"),
+                        remote_path="/root/project/experiments/scalar_vllm_source_manifest.json")
+    )
+    volume = modal.Volume.from_name("ptit-model-cache", create_if_missing=True)
+
+    @app.function(image=image, gpu=GPU,
+                  volumes={"/root/.cache/huggingface": volume}, timeout=3600)
+    @modal.web_server(PORT, startup_timeout=600)
+    def serve():
+        runner = LocalServingRunner()
+        # Do not use the laptop's preflight here: the CLI evaluated the remote budget.
+        # vLLM and Modal's web-server startup check remain the runtime authorities.
+        subprocess.Popen(runner.build_command(SERVING_CONFIG),
+                         env=runner.setup_environment(SERVING_CONFIG))
+else:
+    app = None

flexsds/server/modal_runner.py

@@ -0,0 +1,98 @@
+"""Modal cloud serving runner for FlexSDS (BYOC, ephemeral, and persistent deploy)."""
+from __future__ import annotations
+
+import os
+import json
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:
+    from flexsds.cli.output import print_output as print
+    from flexsds.core.credentials import CredentialsManager
+except ModuleNotFoundError:
+    from src.flexsds.cli.output import print_output as print
+    from src.flexsds.core.credentials import CredentialsManager
+
+
+class ModalServingRunner:
+    """Quản lý triển khai FlexSDS Serverless trên nền tảng đám mây Modal.com."""
+
+    DEFAULT_APP_NAME = "flexsds-serving"
+
+    def __init__(self, credentials_manager: Optional[CredentialsManager] = None) -> None:
+        self.cred_mgr = credentials_manager or CredentialsManager()
+
+    def check_credentials(self) -> bool:
+        """Kiểm tra thông tin định danh Modal qua CredentialsManager, biến môi trường hoặc ~/.modal.toml."""
+        self.cred_mgr.inject_into_environ()
+
+        token_id = os.environ.get("MODAL_TOKEN_ID") or self.cred_mgr.get_credential("modal", "MODAL_TOKEN_ID")
+        token_secret = os.environ.get("MODAL_TOKEN_SECRET") or self.cred_mgr.get_credential("modal", "MODAL_TOKEN_SECRET")
+        if token_id and token_secret:
+            return True
+
+        toml_path = os.path.expanduser("~/.modal.toml")
+        if os.path.exists(toml_path):
+            return True
+
+        return False
+
+    def build_modal_command(self, config: Dict[str, Any], deploy: bool = False) -> List[str]:
+        """Tạo danh sách đối số dòng lệnh gọi công cụ CLI modal tới modal_app.py."""
+        app_path = str(Path(__file__).parent / "modal_app.py")
+        return ["modal", "deploy" if deploy else "serve", app_path]
+
+    def setup_environment(self, config: Dict[str, Any]) -> Dict[str, str]:
+        """Forward non-secret serving settings for app construction in either mode."""
+        cfg = config.get("serving", config)
+        keys = ("target_model", "draft_model", "draft_method", "use_heterogeneous_vocab",
+                "port", "enable_adaptive", "target_gpu", "max_model_len", "max_num_seqs")
+        env = dict(os.environ)
+        env["FLEXSDS_SERVING_CONFIG"] = json.dumps({k: cfg[k] for k in keys if k in cfg})
+        return env
+
+    def launch(
+        self,
+        config: Dict[str, Any],
+        deploy: bool = False,
+        dry_run: bool = False,
+    ) -> Optional[subprocess.Popen]:
+        """Khởi chạy ứng dụng Modal serverless."""
+        if not dry_run and not self.check_credentials():
+            print("\n\033[31m[Lỗi định danh]\033[0m Chưa cấu hình thông tin xác thực Modal.")
+            print("  Vui lòng chạy: flexsds auth login --provider modal")
+            print("  Hoặc cấu hình qua lệnh: modal setup")
+            return None
+
+        cmd = self.build_modal_command(config, deploy=deploy)
+
+        if dry_run:
+            mode_desc = "Persistent Deploy" if deploy else "Ephemeral Run"
+            print(f"\n[FlexSDS Modal] Dry-run command ({mode_desc}):")
+            print(" ".join(cmd))
+            print(f"Serving configuration: {self.setup_environment(config)['FLEXSDS_SERVING_CONFIG']}")
+            return None
+
+        try:
+            proc = subprocess.Popen(cmd, env=self.setup_environment(config))
+            return proc
+        except FileNotFoundError:
+            print("\n\033[31m[Lỗi]\033[0m Không tìm thấy công cụ CLI 'modal'. Cài đặt: pip install modal")
+            return None
+
+    def check_process_status(self, proc: subprocess.Popen) -> tuple[bool, Optional[int]]:
+        """Kiểm tra trạng thái tiến trình Modal; phát hiện sớm nếu ứng dụng dừng bất ngờ."""
+        code = proc.poll()
+        if code is None:
+            return True, None
+        return False, code
+
+    def stop(self, app_name: str = DEFAULT_APP_NAME) -> bool:
+        """Dừng ứng dụng đang chạy trên hạ tầng Modal Cloud."""
+        cmd = ["modal", "app", "stop", app_name]
+        try:
+            res = subprocess.run(cmd, capture_output=True, text=True)
+            return res.returncode == 0
+        except Exception:
+            return False

flexsds/server/vscode_cli.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+"""vscode cli.ipynb
+
+Automatically generated by Colab.
+
+Original file is located at
+    https://colab.research.google.com/drive/1PYNYxzD2gBAY6QiMm5a9O_gHod0q5aOC
+"""
+
+import os
+from google.colab import drive
+
+# CẤU HÌNH THÔNG TIN
+# Public clone URL; Git handles any configured credentials.
+REPO_OWNER = "theflyingkhui04"
+REPO_NAME = "do-an-ptit-d22"
+TARGET_DIR = f"/root/{REPO_NAME}"
+CLONE_URL = f"https://github.com/{REPO_OWNER}/{REPO_NAME}.git"
+
+VSCODE_DRIVE_BACKUP = "/content/drive/MyDrive/vllm_colab_backup"
+
+
+# BƯỚC 1: KẾT NỐI GOOGLE DRIVE
+print("\n" + "="*60)
+print("==> BƯỚC 1/4: KẾT NỐI GOOGLE DRIVE")
+print("="*60)
+drive.mount('/content/drive', force_remount=False)
+os.makedirs(f"{VSCODE_DRIVE_BACKUP}/.vscode-cli", exist_ok=True)
+
+
+# BƯỚC 2: ĐỒNG BỘ MÃ NGUỒN REPO
+print("\n" + "="*60)
+print("==> BƯỚC 2/4: ĐỒNG BỘ MÃ NGUỒN REPO TỪ GITHUB")
+print("="*60)
+if not os.path.exists(TARGET_DIR):
+    !git clone {CLONE_URL} {TARGET_DIR}
+else:
+    !git -C {TARGET_DIR} pull
+
+!chmod +x {TARGET_DIR}/scripts/*.sh
+
+
+# BƯỚC 3: CÀI ĐẶT MÔI TRƯỜNG vLLM
+print("\n" + "="*60)
+print("==> BƯỚC 3/4: CÀI ĐẶT vLLM TRÊN SSD COLAB")
+print("="*60)
+!pip install -r {TARGET_DIR}/requirements-server.txt
+
+print("\n--> Đang gỡ bỏ torchaudio để tránh xung đột CUDA...")
+!pip uninstall -y torchaudio
+
+
+
+# BƯỚC 4: THIẾT LẬP VS CODE CLI & KHỞI CHẠY TUNNEL
+print("\n" + "="*60)
+print("==> BƯỚC 4/4: KHỞI TẠO VS CODE TUNNEL 'colab-t4'")
+print("="*60)
+
+# 1. Tải CLI nếu chưa có (Sử dụng Direct Link của Microsoft để tránh lỗi DNS/Redirect trên T4 GPU)
+if os.path.exists("./code"):
+    print("--> Found existing VS Code CLI, removing for fresh install...")
+    !rm -rf ./code
+if os.path.exists("vscode_cli.tar.gz"):
+    print("--> Found existing vscode_cli.tar.gz, removing for fresh download...")
+    !rm -f vscode_cli.tar.gz
+
+print("--> Downloading and extracting VS Code CLI (Direct Link)...")
+!wget -O vscode_cli.tar.gz "https://update.code.visualstudio.com/latest/cli-alpine-x64/stable" && tar -xf vscode_cli.tar.gz
+
+# 2. Liên kết thư mục lưu trữ thông tin đăng nhập với Drive
+os.makedirs(f"{VSCODE_DRIVE_BACKUP}/.vscode-cli", exist_ok=True)
+!ln -sfn {VSCODE_DRIVE_BACKUP}/.vscode-cli /root/.vscode-cli
+
+# 3. Đăng nhập với cờ cố định là GitHub
+print("--> Kiểm tra đăng nhập GitHub:")
+!./code tunnel user login --provider github
+
+# 4. Bật Tunnel
+print("\n" + "="*60)
+print("  ĐANG KHỞI CHẠY TUNNEL 'colab-t4'...")
+print("="*60 + "\n")
+!./code tunnel --accept-server-license-terms --name colab-t4

flexsds-0.2.0.dist-info/METADATA

@@ -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.