机器学习任务模板

本篇覆盖两类「经典机器学习」任务模板：

• sklearn：单个镜像内含一组 launcher-*.py 脚本，覆盖 adaboost / ar / arima / bayesian / decision-tree / gbdt / kmeans / knn / lightgbm / lr / random-forest / rf-regression / xgb 及通用 launcher-sklearn，用于表格数据的分类、回归、聚类与时间序列。
• ray-sklearn：基于 Ray + Joblib 的分布式 sklearn 训练/推理。

任务家族描述里所说的「sklearn 及其算法」即指 sklearn 目录下的多 launcher-*.py 算法子模板。

sklearn

源码目录：job-template/job/sklearn/。一个镜像内放了 13+ 个 launcher-*.py，每个算法是一个独立子模板，但共享同一套数据约定与参数风格。

共用约定

• 镜像：ccr.ccs.tencentyun.com/cube-studio/sklearn:20250801（见 job-template/job/sklearn/build.sh:5）。

  • 镜像内依赖（见 Dockerfile）：scikit-learn==1.6.1、xgboost==2.1.4、statsmodels==0.14.5、pandas==2.3.2、numpy==2.0.2、graphviz==0.21、matplotlib==3.9.4、joblib==1.5.2 等，基础镜像 python:3.9。

  注意：job-template/job/sklearn/Dockerfile:14 的 ENTRYPOINT 写的是 python3 launcher-skearn.py（拼写少了一个 l，且该文件不存在），实际可用脚本名为 launcher-sklearn.py。任务模板里通过「启动命令」覆盖入口（如 init-job-template.json:4828 的 python3 launcher-sklearn.py），所以正常使用不受该 ENTRYPOINT 影响；但镜像默认入口是坏的（如需可顺手修正 Dockerfile）。

• 启动命令：在任务模板里配置 python launcher-xxx.py，按算法选择对应脚本。

• 三种运行模式（由传入哪个数据集参数决定，绝大多数脚本一致）：

  • 传 --train_dataset：执行训练，输出模型 .pkl 与训练/测试评估指标；
  • 传 --val_dataset：执行评估，输出 val_result*.json；
  • 传 --inference_dataset：执行推理，输出 inference_result.csv。

• 通用参数（大多数脚本都有，少数算法做了裁剪，见下表「特有/裁剪」列）：

  参数	含义
  --train_dataset	训练集 CSV 路径
  --val_dataset	评估集 CSV 路径
  --inference_dataset	推理集 CSV 路径
  --feature_columns	特征列名，逗号分隔
  --label_columns	标签列名，逗号分隔（分类/回归用）
  --save_model_dir	模型与评估结果保存目录或 .pkl 路径
  --load_model_path	从指定 .pkl 加载模型（部分脚本支持）
  --model_params	JSON 字符串，传给具体模型的超参数，默认 {}

  以上参数名已逐一对照各 launcher-*.py 的 argparse 核实一致（如 launcher-lr.py:244-251、launcher-adaboost.py:246-253）。

各算法子模板速查

说明：分类脚本统一逻辑——二分类用 roc_auc_score 并绘制 ROC 曲线；多分类输出 accuracy/precision/recall/f1。模型路径由统一逻辑解析，支持「目录」或「.pkl 文件路径」两种写法。

注意：评估结果文件名实际为 val_result<model_params 的 JSON>.json（把超参数 JSON 拼进文件名，见 launcher-adaboost.py:205、launcher-xgb.py:230），并非固定的 val_result.json。

时间序列（ar / arima）参数

ar / arima 与分类脚本参数不同，核对 launcher-ar.py:61-67 / launcher-arima.py:61-67：

• --train_dataset：时间序列 CSV；
• --feature_col：单一数值列名（注意是 feature_col 单数，不是 feature_columns）；
• --time_col：时间列名，用于排序；
• --start / --end：预测起止位置（整数索引）；
• --lag（ar）：AR 滞后阶数，常用 1–30；
• --order（arima）：(p,d,q) 字符串，如 "(2,1,2)"；
• --save_model_dir：结果输出目录。

两者均按时间排序后 8:2 切分 train/test，输出 MSE 与 predict.csv。

通用分类模板支持的模型（launcher-sklearn.py）

通过 --model_name 选择，覆盖（核对自 README 与脚本注释）： RandomForestClassifier、GradientBoostingClassifier、AdaBoostClassifier、ExtraTreesClassifier、BaggingClassifier、LogisticRegression、RidgeClassifier、SGDClassifier、PassiveAggressiveClassifier、SVC、LinearSVC、GaussianNB、BernoulliNB、MultinomialNB、KNeighborsClassifier、DecisionTreeClassifier、MLPClassifier、LinearDiscriminantAnalysis、QuadraticDiscriminantAnalysis。

训练示例：

python launcher-sklearn.py \
  --train_dataset /mnt/admin/pipeline/example/ml/train.csv \
  --train_test_split_ratio 0.8 \
  --label_columns y \
  --feature_columns age,duration,campaign,pdays,previous,emp_var_rate,cons_price_idx,cons_conf_idx,euribor3m,nr_employed \
  --save_model_dir /mnt/admin/pipeline/example/ml/sklearn/ \
  --model_name RandomForestClassifier \
  --model_params '{"n_estimators":200,"max_depth":8,"min_samples_leaf":5}'

常用超参数建议（model_params）

• RandomForestClassifier / RandomForestRegressor：n_estimators 100–500、max_depth 3–20、min_samples_leaf 1–20、max_features "sqrt"/"log2"。
• LogisticRegression：C 0.01–10、penalty "l2"、solver "lbfgs"/"liblinear"、max_iter 100–2000。
• SVC/LinearSVC：C 0.1–10、kernel "linear"/"rbf"、gamma "scale"/"auto"。
• KNeighborsClassifier：n_neighbors 3–50、weights "uniform"/"distance"。
• DecisionTreeClassifier：max_depth 3–20、min_samples_leaf 1–20、criterion "gini"/"entropy"。
• AdaBoostClassifier：n_estimators 50–500、learning_rate 0.01–1、algorithm "SAMME"/"SAMME.R"。
• KMeans：n_clusters 2–20、init "k-means++"、max_iter 100–500、n_init 10–50。
• MultinomialNB（bayesian）：alpha 0.1–10、fit_prior true/false。
• XGBClassifier（xgb）：典型二分类 {"n_estimators":200,"max_depth":6,"learning_rate":0.1,"subsample":0.8,"colsample_bytree":0.8,"reg_lambda":1.0,"objective":"binary:logistic","eval_metric":"auc"}。
• LGBMClassifier（lightgbm）：典型 {"n_estimators":300,"learning_rate":0.05,"num_leaves":31,"max_depth":-1,"subsample":0.8,"colsample_bytree":0.8}。
• GradientBoostingClassifier（gbdt）：n_estimators 100–500、learning_rate 0.01–0.2、max_depth 3–10、subsample 0.6–1.0。

ray-sklearn

源码目录：job-template/job/ray-sklearn/（入口 launcher.py，模型映射 common.py 由 launcher 内联）。基于 Ray 的分布式能力，通过 Ray + Joblib 后端跑 sklearn 的训练与推理，适用于在 Kubernetes 上按需拉起 Ray 集群执行 sklearn 任务。

镜像与运行机制

• 镜像：ccr.ccs.tencentyun.com/cube-studio/ray-sklearn:20250301（见 build.sh:5，基于 cube-studio/ray:nightly，含 scikit-learn==1.6.1、pandas==1.5.3、numpy==1.26.4、joblib==1.4.2）。

• 启动命令：python3 launcher.py。

• K8s 账号：需 kubeflow-pipeline（launcher 要在命名空间内创建 Ray 集群）。

• 执行流程（核对 launcher.py:62-147）：

  1. 解析参数，校验「至少做训练或推理之一」、模型路径必填、训练时校验 label/feature 列；
  2. pd.read_csv(..., sep=',', header=0) 读取数据（逗号分隔、首行列名）；
  3. ray_launcher(num_worker, init_file, 'create') 创建 Ray 集群（1 Head + N Worker），设置 RAY_ADDRESS；
  4. register_ray() + with joblib.parallel_backend('ray') 内执行：训练则 model.fit 后 joblib.dump，推理则 joblib.load 后 model.predict，每行一个结果写入 --predict_result_path；
  5. ray_launcher(..., 'delete') 销毁集群。

  其中 Ray 集群通过 from job.pkgs.k8s.py_ray import ray_launcher 创建，--init_file 默认 /app/init.sh。

支持的模型（SUPPORT_MODELS）

核对 launcher.py:25-37，模型名不区分大小写与空格：

GaussianNB、MultinomialNB、BernoulliNB、CategoricalNB、ComplementNB、KNeighborsClassifier、LogisticRegression、RandomForestClassifier、DecisionTreeClassifier、GradientBoostingClassifier、SVC、SVR。

启动参数（与 launcher.py:152-162 一致）

提示：--train_csv_file_path 的 argparse help 文案写的是「| 分割」，但代码实际用 sep=','（逗号分隔，见 launcher.py:79）。以逗号为准。

使用示例

仅训练：

python3 launcher.py \
  --train_csv_file_path /mnt/admin/pipeline/example/sklearn/ml-label.csv \
  --label_columns y \
  --feature_columns age,duration,campaign \
  --model_name RandomForestClassifier \
  --model_args_dict '{"max_depth":5,"min_samples_leaf":10}' \
  --model_file_path /mnt/admin/pipeline/example/sklearn/model.joblib \
  --num_worker 2 \
  --init_file /app/init.sh

仅推理（需已有模型）：

python3 launcher.py \
  --predict_csv_file_path /mnt/admin/pipeline/example/sklearn/ml-nolabel.csv \
  --predict_result_path /mnt/admin/pipeline/example/sklearn/result.txt \
  --model_file_path /mnt/admin/pipeline/example/sklearn/model.joblib \
  --num_worker 2

训练 + 推理可在同一任务内先 fit 再 predict（同时传训练与推理参数）。

具体参数与默认值以各 launcher-*.py 源码为准，本篇仅供导航与检索。