Hướng dẫn Developers

Tài liệu kỹ thuật chuyên sâu dành cho Developers: cài đặt môi trường, lệnh tạo Parquet, build model, kiến trúc toán học Chronos-2 (120M) + GBDT 28 biến và tích hợp API.

1.0 (Draft) ✓ Đã chốt giải pháp & mô hình dự báo

Dành cho Đội ngũ Kỹ thuật: Bạn không cần kết nối trực tiếp vào PostgreSQL DWH nếu đã có sẵn các tệp .parquet chuẩn trong out/export/ và model_lab/out/panel/. Toàn bộ bước huấn luyện mô hình và chạy dự báo đều đọc trực tiếp từ tệp Parquet.

Bản đồ Kỹ thuật Dành cho Đội ngũ Phát triển

Chuyên mục Hướng dẫn Developers cung cấp toàn bộ đặc tả kỹ thuật đã chốt để đội ngũ Kỹ thuật dữ liệu (Data Engineers), Kỹ sư Học máy (ML Engineers) và Lập trình viên Backend có thể thiết lập môi trường, kết xuất tệp Parquet từ DWH, huấn luyện (build) mô hình, chạy suy luận độc lập và tích hợp qua REST API / CLI.

Ngăn xếp Công nghệ Cốt lõi (Tech Stack)

Tầng Kỹ thuật	Công nghệ & Thư viện Chuẩn	Vai trò trong Hệ thống
Quản lý Môi trường & Gói	`Python 3.12+`, `uv`, `GNU Make`	Quản lý môi trường ảo độc lập và tự động hóa các tác vụ dữ liệu/mô hình.
Xử lý Dữ liệu & Parquet	`Polars >= 1.0`, `PyArrow`, `OpenPyXL`	Đọc/ghi tệp Parquet tốc độ cao, tổng hợp bộ nhớ đệm 16 cấp gộp trong vài chục mili-giây và xuất báo cáo Excel định dạng chuẩn.
Foundation Model & GBDT	`PyTorch` (`CPU` / `MPS` / `CUDA`), `chronos-forecasting >= 2.3.2`, `LightGBM`, `CatBoost`, `Scikit-Learn`, `Joblib`	Vận hành lõi `Amazon Chronos-2 (120M)` đa biến, `Chronos-Bolt-Small (48M)`, học phần dư trên 28 biến ngoại sinh và đóng gói model artifacts.
Phân rã & Đồng bộ Phân cấp	`Dual-Regime Empirical-Bayes`, `Exact Shapley (2^6 = 64)`, `Stein Hierarchical Reconciliation`	Khử lệch mùa vụ, quy chiếu dự báo về đẳng thức $\text{Base} \times (1 + \sum K)$ và bảo toàn tổng sản lượng xuyên suốt các cấp hạt.
Dịch vụ Đa Người Dùng & API	`FastAPI`, `Uvicorn`, `Pydantic`, `SQLite`	Cung cấp REST API đồng bộ độ trễ thấp, quản lý phiên bản CTKM, lưu kịch bản điều chỉnh hệ số và khóa sổ S&OP.