DemandForecastModel

TÓM TẮT

Mô hình core sử dụng two-stage segmented approach: Stage 1 (Day Classifier) phân loại ngày → Stage 2 (Segment Regressors) dự báo theo segment. Giải quyết vấn đề intermittent demand trong e-commerce.

File: forecast_engine/src/core/model.py (~800 dòng)

Kiến trúc Two-Stage

Stage 1: Day Classifier

Phân loại mỗi ngày prediction vào 1 trong 5 segments dựa trên historical patterns:

Segment	Mô tả	Ví dụ
zero	Không có nhu cầu	Dead SKU, ngày lễ
low	Nhu cầu thấp	Ngày thường, SKU intermittent
mid	Nhu cầu trung bình	Ngày thường, SKU smooth
high	Nhu cầu cao	Payday, mini-spike
extreme	Nhu cầu cực cao	Double-day, Mega sale

LightGBM Classifier sử dụng tất cả 40+ features để quyết định segment.

Stage 2: Segment Regressors

Mỗi segment có LightGBM Regressor riêng được tối ưu cho demand regime đó:

• zero segment: Configurable threshold — nếu probability > threshold → pass cho regressor, ngược lại predict 0
• low/mid/high/extreme: Mỗi cái có hyperparameters riêng (learning_rate, num_leaves, etc.)

Quantile Prediction

Model output bao gồm 3 quantile predictions:

Quantile	Mô tả	Sử dụng
P10	Phân vị 10% (pessimistic)	Lower confidence bound
P50	Phân vị 50% (median)	Primary forecast
P90	Phân vị 90% (optimistic)	Upper confidence bound, staffing buffer

Training Flow

# Simplified training flow
model = DemandForecastModel()

# Stage 1: Train classifier
model.fit_classifier(X_train, y_segments)

# Stage 2: Train segment regressors
for segment in ['low', 'mid', 'high', 'extreme']:
    mask = y_segments == segment
    model.fit_regressor(segment, X_train[mask], y_train[mask])

# Threshold tuning
model.tune_thresholds(X_val, y_val)

Prediction Flow

# Prediction
y_pred = model.predict(X_test)

# Internal steps:
# 1. Classify each row into segment
# 2. Route to appropriate regressor
# 3. Apply threshold for 'zero' segment
# 4. Generate P10/P50/P90 quantiles

Config Parameters

Main hyperparameters (configurable via config.py or AutoML):

Group	Parameters
CLF_PARAMS	learning_rate, num_leaves, max_depth, n_estimators, min_child_samples
REG_PARAMS	Tương tự CLF + alpha (quantile loss parameter)
Thresholds	Per-segment probability thresholds

LƯU Ý KHI REFACTOR

Config params là module-level mutable dicts. Khi chạy concurrent improvement cycles, có thể gây data corruption. Xem IMP-01.

Tài liệu liên quan

• Feature Engineering — Input features
• Pipeline — Orchestration
• AutoML — Tự động tune params