使用 LightGBM 迴歸模型對表格式 CSV 資料進行訓練與推論的命令列（主控台）流程，並附上 SHAP 可解釋性圖表，可在 Windows 11 與 Ubuntu Linux 24.04 執行。內附範例資料集 housing（波士頓房價，13 個特徵，預測房價中位數 medv）與訓練完成的模型。模型以 LightGBM 原生的 lgb.train API 訓練（objective 為 regression，評估指標為 l1 與 l2）；訓練與推論都會回報 RMSE 與 R²。

 

CSV 資料格式慣例：第一欄為資料列編號（會被捨棄），最後一欄為迴歸的目標值，其餘各欄皆為數值型特徵（類似 "1,234" 的千分位符號會自動去除）。若出現空白或非數值的儲存格，程式會中止執行並顯示該儲存格的位置。

 

Data-LightGBM-Regression-inference-Jupyter.png

 

[資料夾結構]

  • CLAUDE.md / AGENT.md：程式規格文件，兩個檔案內容完全相同。
  • CHANGELOG.md：版本變更紀錄。
  • copyright.txt：版權聲明。
  • NIPS-2017-lightgbm-...-Paper.pdf：LightGBM 參考論文。
  • data/housing/：輸入資料 train_input.csv 與 inference_input.csv；輸出資料 train_output.csv 與 inference_output.csv（由程式產生，內容為輸入資料列加上一欄 prediction 預測值）。
  • model/housing/：model.sav（訓練完成的 booster）、scaler.pkl（已擬合的 MinMaxScaler）、plots/（實際值對預測值、特徵重要度與 SHAP 圖表；推論產生的圖表檔名前綴為 inference_）。
  • tool/tools.py：共用工具函式，project_root 與 delete_ipynb_checkpoints。
  • src/：原始程式碼、啟動腳本與本說明文件。
  • venv/：Python 虛擬環境，由步驟 01 建立。

[操作步驟及說明]

每個步驟都同時提供 Windows 批次檔（.bat）與 Linux shell 腳本（.sh），行為完全相同。所有啟動腳本都會先切換到專案根目錄，因此可從任何目錄執行。

 

1. 01_venv_create.bat / 01_venv_create.sh

刪除舊的 venv/，建立全新的虛擬環境，並安裝 src/requirements.txt 中的相依套件。若 pip 安裝失敗，會直接中止並顯示錯誤訊息。

 

2. 02_venv_activate.bat / 02_venv_activate.sh

啟用虛擬環境。Linux 請以 source 方式執行：source src/02_venv_activate.sh。

 

3. 03_train.bat / 03_train.sh

訓練迴歸模型。額外加上的參數會直接往後傳遞給 train.py。

 

4. 04_inference.bat / 04_inference.sh

使用訓練好的模型進行推論。額外加上的參數會直接往後傳遞給 inference.py。

 

5. 99_venv_clear.bat / 99_venv_clear.sh

刪除 venv/ 虛擬環境資料夾。

 

[Python 程式進入點]

src/train.py

  • --dataset housing：資料集資料夾名稱
  • --iterations 2000：疊代次數
  • --num-leaves 31：葉節點數量
  • --learning-rate 0.05：學習率
  • --shap-index 1：SHAP waterfall / force 圖所要解釋的資料列索引

其餘沿用原始 Notebook 的固定參數：boosting_type 為 gbdt、objective 為 regression、評估指標為 l1 與 l2、feature_fraction 0.9、bagging_fraction 0.8、bagging_freq 5。程式會先擬合 MinMaxScaler，再透過 lgb.train 進行訓練，於終端機顯示 RMSE 與 R²，並輸出 model.sav、scaler.pkl、train_output.csv，以及一整組圖表：實際值對預測值的折線圖與散布圖、特徵重要度（以 gain 計算）、SHAP 的 waterfall 與 force（對應 --shap-index 指定的資料列）、summary、bar，以及針對最重要的兩個特徵（依 gain 自動挑選；housing 資料集為 rm 與 lstat）繪製的 dependence 與 scatter 圖。

 

src/inference.py

  • --dataset housing：資料集資料夾名稱
  • --shap-index 1：SHAP waterfall / force 圖所要解釋的資料列索引

程式會將已儲存的正規化器與 booster 套用到 inference_input.csv，針對目標欄位顯示 RMSE 與 R²，並輸出 inference_output.csv 與同一組圖表（檔名前綴為 inference_）。

 

兩支程式都以無視窗（headless）方式執行（matplotlib 使用 Agg 後端），所有圖表都會存放於 model/{dataset}/plots/。

[快速開始]

Windows 11

src\01_venv_create.bat

src\03_train.bat --dataset housing

src\04_inference.bat --dataset housing

 

Ubuntu 24.04

bash src/01_venv_create.sh

bash src/03_train.sh --dataset housing

bash src/04_inference.sh --dataset housing

 

以 CPU 訓練 housing 範例只需數秒即可完成，不需要 GPU 或 CUDA。僅 macOS 需先執行 brew install libomp。

[使用自己的資料集]

  1. 依照上述 CSV 資料格式慣例，建立 data/{名稱}/train_input.csv 與 data/{名稱}/inference_input.csv（第一欄為編號、最後一欄為目標值，其餘為數值型特徵）。
  2. 執行 03_train --dataset {名稱}，模型、正規化器與圖表會輸出至 model/{名稱}/。
  3. 執行 04_inference --dataset {名稱}。

SHAP 的 dependence 與 scatter 圖所使用的特徵名稱，會依 booster 的 gain 重要度自動挑選，因此不需要修改任何程式碼。參數調校可參考 LightGBM Parameters-Tuning。

[疑難排解]

  • macOS 出現 libomp 相關錯誤：請執行 brew install libomp。
  • SHAP 相關錯誤：程式不會直接中止，而是顯示警告後略過解釋性圖表（模型與預測結果 CSV 都已正常儲存），並印出目前安裝的 shap 版本。若要修正，請在虛擬環境中執行 pip install -U shap。

[參考資料]

 

執行後，即可看到 LightGBM 迴歸的結果。

 

這個 SDK 內建於 MYAI Studio 人工智慧開發工具。

 

單獨購買價格：5,000元，永久授權，單一 SDK 授權，單機授權，一次下載，無更新服務，一年電子郵件範例諮詢服務。如果是軟體客製化問題，請購買我們的客製化顧問服務點數。