使用 scikit-learn 的 GradientBoostingClassifier 對表格式 CSV 資料進行訓練與推論的命令列（主控台）流程，並附上 SHAP 可解釋性圖表，可在 Windows 11 與 Ubuntu Linux 24.04 執行。內附範例資料集 titanic（4 個特徵：Pclass、Age、Fare、Sex，預測 Survived 是否生存）與訓練完成的模型。訓練與推論都會回報準確率（accuracy）。

 

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

 

Data-Gradient-Boosting-Classification-inference-Jupyter.png

 

[資料夾結構]

  • CLAUDE.md / AGENT.md：程式規格文件，兩個檔案內容完全相同。
  • CHANGELOG.md：版本變更紀錄。
  • copyright.txt：版權聲明。
  • data/titanic/：輸入資料 train_input.csv 與 inference_input.csv；輸出資料 train_output.csv 與 inference_output.csv（由程式產生，內容為輸入資料列加上一欄 prediction 預測值）。
  • model/titanic/：model.sav（訓練完成的分類器）、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 titanic：資料集資料夾名稱
  • --estimators 1000：Estimators 的數量
  • --learning-rate 0.1：學習率
  • --max-depth 10：樹的最大深度
  • --shap-index 1：SHAP waterfall / force 圖所要解釋的資料列索引

程式使用固定的 random_state=0。會先擬合 MinMaxScaler 再進行訓練，於終端機顯示準確率，並輸出 model.sav、scaler.pkl、train_output.csv，以及一整組圖表：特徵重要度、SHAP 的 waterfall 與 force（對應 --shap-index 指定的資料列）、summary、bar，以及針對最重要的兩個特徵（自動挑選）繪製的 dependence 與 scatter 圖。

 

src/inference.py

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

程式會將已儲存的正規化器與模型套用到 inference_input.csv，針對標籤欄位顯示準確率，並輸出 inference_output.csv 與一整組 SHAP 圖表（檔名前綴為 inference_）。

 

兩支程式都以無視窗（headless）方式執行（matplotlib 使用 Agg 後端），所有圖表都會存放於 model/{dataset}/plots/。分類器的 SHAP 值是在 log-odds 空間（也就是模型的決策邊際）。

[快速開始]

Windows 11

src\01_venv_create.bat

src\03_train.bat --dataset titanic

src\04_inference.bat --dataset titanic

 

Ubuntu 24.04

bash src/01_venv_create.sh

bash src/03_train.sh --dataset titanic

bash src/04_inference.sh --dataset titanic

 

以 CPU 訓練 titanic 範例只需數秒即可完成，不需要 GPU 或 CUDA。

[使用自己的資料集]

  1. 依照上述 CSV 資料格式慣例，建立 data/{名稱}/train_input.csv 與 data/{名稱}/inference_input.csv（第一欄為編號、最後一欄為標籤，其餘為數值型特徵；類別型特徵請先編碼成數字，例如範例中的 Sex 以 0 / 1 表示）。
  2. 執行 03_train --dataset {名稱}，模型、正規化器與圖表會輸出至 model/{名稱}/。
  3. 執行 04_inference --dataset {名稱}。

SHAP 的 dependence 與 scatter 圖所使用的特徵名稱，會依模型的特徵重要度自動挑選，因此不需要修改任何程式碼。

[疑難排解]

  • 載入模型時出現 ModuleNotFoundError 並提到某個 sklearn 內部模組：表示該 pickle 檔是由舊版 scikit-learn 產生的，新版無法載入。請重新執行 03_train 即可 —— 訓練過程是確定性的（random_state=0），因此可由相同資料重現出同一個模型。
  • SHAP 相關錯誤：程式不會直接中止，而是顯示警告後略過解釋性圖表（模型與預測結果 CSV 都已正常儲存），並印出目前安裝的 shap 版本。若要修正，請在虛擬環境中執行 pip install -U shap。

[參考資料]

 

執行後，即可看到 Gradient Boosting 分類的結果。

 

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

 

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