Cài đặt Môi trường & Cấu trúc Repository

Hướng dẫn cài đặt môi trường Python 3.12 với uv, cấu trúc thư mục mã nguồn và cấu hình kết nối DWH.

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

Yêu cầu Hệ thống & Công nghệ Cốt lõi

Module dự báo được phát triển và kiểm thử trên nền tảng:

Python: 3.12+ (quản lý gói và môi trường ảo bằng uv).
Xử lý Dữ liệu Bảng & Parquet: polars >= 1.0, pyarrow, openpyxl.
Hệ sinh thái Học máy & Foundation Model:
- torch (hỗ trợ CPU & Apple Silicon MPS / CUDA).
- chronos-forecasting >= 2.3.2 (cung cấp Chronos2Pipeline cho amazon/chronos-2 120M và ChronosBoltPipeline cho amazon/chronos-bolt-small 48M).
- lightgbm, catboost, scikit-learn, scipy, joblib.
Tầng API & Dịch vụ Web: fastapi, uvicorn, pydantic, sqlite3.

Cấu trúc Thư mục Dự án (Repository Layout)

forecast_engineer/
├── Makefile                        # Lệnh chuẩn cấp cao: tải và chuẩn hóa Parquet từ DWH
├── forecast_pipeline/              # Đường ống chung: Parquet từ DWH & dự báo 3 Grain
│   ├── Makefile
│   ├── sql/full_dwh.sql            # Truy vấn SQL hợp nhất toàn bộ DWH theo ngày
│   └── src/forecast_pipeline/
│       ├── core/paths.py           # Mọi đường dẫn, khai báo một lần
│       ├── export/
│       │   ├── full_dwh.py         # Kéo và cập nhật bảng phẳng 353 cột từ DWH + lịch sử 2021+
│       │   ├── columns.py          # Từ điển schema 354 cột nghiêm ngặt
│       │   └── ml_parquet.py       # Lọc dòng nhiễu, làm sạch tồn kho, xuất Parquet 329 cột
│       └── forecast/
│           ├── monthly.py          # Entrypoint Production dự báo đầu tháng 3 Grain
│           └── yearly_3grains.py   # Engine Chronos-2 Đa biến + 28 biến ngoại sinh + Stein
├── model_lab/                      # Thư viện lõi Mô hình AI, Đặc trưng & Kiểm định (Core Library)
│   ├── pyproject.toml
│   ├── Makefile
│   └── src/model_lab/
│       ├── core/                   # Kết nối DB, cấu hình, tiện ích dùng chung
│       ├── data/                   # Xây dựng đặc trưng (features.py), chuỗi SKU (sku_series.py)
│       ├── models/                 # 40 mô hình: catalog.py, frontier.py, chronos2_exp.py
│       ├── decompose/              # Phân rã Shapley 6 khe hệ số K (Base × (1 + ΣK))
│       └── scoring/                # Đánh giá WMAPE, Bias, phân cụm nhịp bán KMeans
├── forecast_demo/                  # Module Dịch vụ Vận hành, API, CLI & Lưu trữ Lượt chạy
│   ├── pyproject.toml
│   ├── Makefile
│   └── src/forecast_demo/
│       ├── core/                   # Cấu hình luật vận hành (settings.py, paths.py)
│       ├── store/                  # Quản lý SQLite (CTKM, lượt chạy, điều chỉnh hệ số, chốt bản)
│       ├── ingest/                 # Bộ đọc và kiểm tra hợp lệ tệp Excel CTKM
│       ├── engine/                 # Dựng khung dòng (skeleton), định tuyến grain, tính dự báo
│       ├── api/                    # FastAPI REST endpoints
│       └── cli/                    # Giao diện dòng lệnh (forecast-demo)
├── out/
│   └── export/                     # Nơi lưu trữ các tệp Parquet chuẩn hóa theo DWH
└── online_docs/                    # Cổng tài liệu trực tuyến (Hugo)

Cài đặt Môi trường Phát triển

Cài đặt môi trường cho `model_lab` và `forecast_demo`

# 1. Cài đặt môi trường thư viện mô hình lõi (model_lab)
cd model_lab
uv sync

# 2. Cài đặt môi trường dịch vụ vận hành & API (forecast_demo)
cd ../forecast_demo
make install

Cấu hình Biến môi trường Kết nối DWH (`.env`)

Lưu ý: Kết nối PostgreSQL DWH chỉ cần thiết khi bạn chạy lệnh kéo/cập nhật tệp Parquet mới từ DWH. Nếu đã có sẵn các tệp .parquet trong out/export/ và model_lab/out/panel/, bạn không cần kết nối DB để build model hay chạy dự báo.

Tạo tệp model_lab/.env từ model_lab/.env.example:

DB_HOST=localhost
DB_PORT=3022        # 3022 = PROD (SSH tunnel từ daithuan.bi), 3021 = DEV
DB_USER=postgres
DB_PASSWORD=<mat_khau_dwh>
DB_NAME=bi_dw

Chạy Kiểm thử Tự động (Unit & Integration Tests)

Trước khi thay đổi mã nguồn ở tầng đặc trưng hoặc tầng động cơ dự báo, luôn chạy bộ kiểm thử để đảm bảo các bất biến toán học (như cộng dồn cấp gộp $\sum \text{nhóm} = \text{tổng}$ và đẳng thức $\text{Dự báo} = \text{Base} \times (1 + \sum K)$ ) không bị phá vỡ:

# Kiểm thử thư viện lõi model_lab
cd model_lab && uv run pytest

# Kiểm thử tầng dịch vụ và API forecast_demo
cd ../forecast_demo && uv run pytest