Quy trình Tạo Parquet, Build Model & Chạy Dự báo

Hướng dẫn thực thi từ bước tải Parquet chuẩn DWH, làm sạch dữ liệu ML, huấn luyện mô hình đến chạy suy luận gắn Parquet.

Tổng quan Quy trình Thực thi 3 Bước

Module dự báo được vận hành theo quy trình tuần tự 3 bước độc lập:

Bước 1: Tạo & Cập nhật File Parquet Chuẩn từ DWH

Tại thư mục gốc của repository (forecast_engineer/), sử dụng Makefile đã được chuẩn hóa:

Tải / Cập nhật Bản sao 1-1 từ DWH (354 cột)

make parquet-ml-full-download
# Hoặc alias tương đương:
make parquet-ml-full-download

• Script thực thi: forecast_pipeline/src/forecast_pipeline/export/full_dwh.py
• Cơ chế hoạt động:
  • Tự động đối chiếu fingerprint của từng tháng (ym >= 202504, kể cả các tháng tương lai) trên PostgreSQL DWH với các phân mảnh cục bộ trong out/export/_parts_full_dwh_daily/.
  • Chỉ tải lại những tháng mới phát sinh hoặc có dữ liệu thay đổi trên DWH.
  • Ghi nhận cột nguồn đơn hàng chuẩn order_source từ dwh.fact_order_lines.order_source: chỉ nhận 2 giá trị 'ERP' hoặc 'DMS' (các đơn vừa thuộc ERP vừa thuộc DMS có cột mã DMS để tham chiếu trên DWH nhưng DWH lấy 'ERP' làm chuẩn).
  • Tự động nối thêm lịch sử dài hạn 202101–202503 từ phkt_dtd_202101_202506.parquet.
• Đầu ra:
  • out/export/panel_full_dwh_daily.parquet (354 cột)
  • out/export/panel_full_dwh_daily_columns.csv (Từ điển cột kèm kiểu dữ liệu và quy tắc cộng)

Làm sạch & Xuất File Parquet Chuẩn hóa cho AI/ML (341 cột)

make parquet-ml-processing
# Hoặc alias tương đương:
make parquet-ml-processing

• Script thực thi: forecast_pipeline/src/forecast_pipeline/export/ml_parquet.py
• Cơ chế hoạt động:
  • Đọc out/export/panel_full_dwh_daily.parquet (354 cột).
  • Lọc chỉ giữ thành phẩm thương mại (product_code_prefix == '11'), bỏ cửa hàng không xác định (UNKNOWN), kho thử nghiệm (TEST), kênh thanh lý nội bộ (Khách hàng GT Nội bộ) và các dòng rác kỹ thuật.
  • Loại bỏ 25.849 dòng bất thường số liệu trong tập thương mại: 4 đơn lỗi nhập liệu cực đoan > 5.000 thùng/ngày trên DWH (Satrafoods & Co.opMart SCA Goldsilk), 48 dòng lỗi tràn/gán cứng doanh thu 99.999.999,99 đồng/dòng (hoặc bội số khi gộp dòng), 24.527 dòng thanh lý nội bộ (Khách hàng GT Nội bộ), 495 dòng thương mại có doanh thu thuần $\le 0$, 470 dòng sản lượng đặt âm, 265 dòng phiếu giao gõ nhầm năm tương lai (202611–203008 không có đơn đặt) và 60 dòng kho TEST; đồng thời chuẩn hóa rsm_code '300002' $\to$ '3000002'.
  • Tính lại 18 cột tồn kho sạch (chỉ giữ subinventory đầu 1, loại 2/3/4 và loại locator chứa CXL/CXK).
  • Thêm 7 biến mục tiêu và đặc trưng dẫn xuất chuẩn hóa (net_commercial_ordered_qty_carton, effective_unit_price_per_carton, effective_discount_rate…), giữ nguyên cột order_source ('ERP' / 'DMS') và cắt bỏ 20 cột khóa/kiểm toán nội bộ thừa (giữ nguyên 15 cột chờ DWH bổ sung dữ liệu trong tương lai).
• Đầu ra:
  • out/export/panel_ml_processed.parquet (và đồng bộ sang notebooks/drive_root/dataset/panel_ml_processed.parquet — 341 cột)
  • out/export/panel_ml_processed_columns.csv

Bước 2: Build Model & Chạy Dự báo Đầu Tháng 3 Grain (Production Pipeline)

Điểm vào chuẩn cho chu trình dự báo đầu tháng (M+1) trên 3 cấp hạt vận hành cốt lõi (01_SKU_x_Subinventory, 02_SKU_x_He_Thong, 03_SKU_x_Store) là forecast_pipeline/src/forecast_pipeline/forecast/monthly.py:

Chạy Huấn luyện & Suy luận Lại Toàn bộ từ File Parquet (--retrain)

Khi vừa cập nhật tệp Parquet mới cho kỳ đóng sổ mới, chạy lệnh --retrain để huấn luyện lại mô hình Amazon Chronos-2 (120M) Đa biến + tổ hợp LightGBM L1 & CatBoost MAE trên 28 biến ngoại sinh và đồng bộ phân cấp Stein Reconciliation:

make -C forecast_pipeline forecast-monthly-retrain

• Thời gian chạy: ~5 phút trên CPU tiêu chuẩn.
• Đầu ra Parquet (100% số dòng, phục vụ nạp thẳng vào BI / Hệ thống khác):
  • model_lab/out/panel/forecast_dau_thang_m1_sku_subinv_202609.parquet (7.340 dòng)
  • model_lab/out/panel/forecast_dau_thang_m1_sku_chain_202609.parquet (2.668 dòng)
  • model_lab/out/panel/forecast_dau_thang_m1_sku_store_202609.parquet (244.783 dòng)
  • model_lab/out/panel/forecast_dau_thang_m1_sku_subinv_202610.parquet (7.340 dòng)
  • model_lab/out/panel/forecast_dau_thang_m1_sku_chain_202610.parquet (2.668 dòng)
  • model_lab/out/panel/forecast_dau_thang_m1_sku_store_202610.parquet (273.115 dòng)

Kết xuất Nhanh Báo cáo Excel từ Bộ Parquet Đã Chốt

Nếu bộ tệp Parquet dự báo đã được tính toán sẵn, chạy lệnh không tham số để xuất nhanh các workbook Excel 3-Sheet chuẩn định dạng (có dòng TỔNG CỘNG khớp 100% phép SUM từ dưới lên) trong < 90 giây:

make -C forecast_pipeline forecast-monthly

• Đầu ra Excel:
  • model_lab/out/Bao_Cao_Du_Bao_Dau_Thang_3_Grain_202609.xlsx
  • model_lab/out/Bao_Cao_Du_Bao_Dau_Thang_3_Grain_202610.xlsx

Bước 3: Đóng gói Model Artifacts & Vận hành Đa Cấp Gộp (forecast_demo)

Đối với dịch vụ web và CLI phục vụ người dùng tương tác trực tiếp trên 16 cấp gộp và điều chỉnh 6 hệ số $K$ (forecast_demo/):

cd forecast_demo

# 1. Đồng bộ tệp Parquet từ model_lab sang thư mục dữ liệu độc lập của dịch vụ
make sync-data

# 2. Huấn luyện & đóng gói các tệp model (.joblib) cho các tầm dự báo M+1..M+3
make train-models

# 3. Khởi tạo bộ nhớ đệm phân rã (data/cache/h*/decomposed_{model}.parquet) và bật server
make demo

Khi máy chủ đã chạy hoặc bộ nhớ đệm Parquet đã sẵn sàng, Developer hoặc hệ thống tích hợp có thể truy vấn nhanh kết quả theo bất kỳ cấp gộp nào qua CLI:

# Liệt kê toàn bộ 16 cấp gộp khả dụng
uv run forecast-demo breakdown --horizon 2 --grain '?'

# Truy vấn dự báo tại cấp Kho con (subinv), Hệ thống chuỗi (chain) hoặc Thương hiệu (brand)
uv run forecast-demo breakdown --horizon 2 --grain subinv
uv run forecast-demo breakdown --horizon 2 --grain chain
uv run forecast-demo breakdown --horizon 2 --grain brand