Tổng quan ML Engine

TÓM TẮT

ML Engine là FastAPI application tại forecast_engine/. Sử dụng LightGBM two-stage segmented model với 40+ features, walk-forward backtesting, và AutoML self-improvement qua DeepSeek LLM.

Kiến trúc Module

Cấu trúc thư mục

forecast_engine/
├── main.py                     # FastAPI entry, 13 routers
├── src/
│   ├── api/                    # 15 route files
│   │   ├── routes_forecast.py  # /forecast/* endpoints
│   │   ├── routes_train.py     # /train/* endpoints
│   │   ├── routes_backtest.py  # /backtest/* endpoints
│   │   ├── routes_automl.py    # /automl/* endpoints
│   │   ├── routes_override.py  # /override/* (manual adjustments)
│   │   ├── routes_evaluate.py  # /evaluate/*
│   │   ├── routes_models.py    # /models/*
│   │   ├── routes_calendar.py  # /calendar/*
│   │   └── ...                 # health, dashboard, profiler, improvement, llm_config
│   │
│   ├── core/                   # 29 module core
│   │   ├── model.py            # DemandForecastModel (two-stage)
│   │   ├── pipeline.py         # ForecastPipeline orchestrator
│   │   ├── features.py         # FeatureEngineer (40+ features)
│   │   ├── backtester.py       # BacktestEngine (walk-forward)
│   │   ├── calendar.py         # EventCalendar (VN e-commerce)
│   │   ├── config.py           # Global config (CLF/REG params)
│   │   ├── cross_auditor.py    # Level reconciliation
│   │   ├── data_profiler.py    # Dataset analysis
│   │   ├── data_quality_scorer.py  # Quality scoring
│   │   ├── future_forecast.py  # Future prediction generation
│   │   ├── override_manager.py # Manual override management
│   │   ├── staffing.py         # Backend staffing calculations
│   │   └── ...                 # 16 modules khác
│   │
│   ├── automl/                 # AutoML system
│   │   ├── orchestrator.py     # State machine (8 states)
│   │   ├── self_improver.py    # LLM-based suggestions
│   │   ├── llm_provider.py     # LLM abstraction layer
│   │   ├── deepseek_client.py  # DeepSeek API client
│   │   ├── local_optimizer.py  # Local optimization
│   │   ├── model_comparator.py # A/B model testing
│   │   └── tuner.py            # Parameter ranges
│   │
│   ├── data/                   # Data access
│   │   ├── repository.py       # Supabase CRUD operations
│   │   ├── sql_schemas.sql     # Table definitions
│   │   └── supabase_client.py  # Supabase connection
│   │
│   └── utils/                  # Utilities

Key Metrics

Metric	Mô tả	Target
wMAPE	Weighted Mean Absolute Percentage Error	≤ 20%
Bias	Systematic over/under prediction	~ 0%
FNR	False Negative Rate (bỏ lỡ demand)	≤ 10%
MAE	Mean Absolute Error	Minimize

Tài liệu liên quan

• DemandForecastModel — Chi tiết two-stage model
• Feature Engineering — 40+ features
• Pipeline — Pipeline orchestration
• Backtester — Walk-forward validation
• AutoML — Self-improvement loop