用途：在表格数据上构建可上线的多分类器，默认选用 XGBoost，适用于目标含 2 个以上互斥离散类别（如情感 1-5、商品品类、意图分桶、故障类型），且每类至少有几百个样本。每个样本仅属一类；二分类应改用 binary-classification，多标签应改用 multilabel-classification，类别有天然顺序时可考虑有序回归。
主要能力：使用 objective="multi:softprob" 与 num_class=N，评估指标用 mlogloss；输出每类精确率、召回率、F1 与支持度；计算 macro、micro、weighted 三种 F1；绘制原始与按行归一化的混淆矩阵；支持 top-K 准确率；提供每类 SHAP 解释；通过 MLflow 记录参数、指标、标签与产物（模型、类别分布、混淆矩阵、每类指标图、ROC OvR、每类 SHAP）。
使用方式：项目含 data、src/train.py、src/predict.py、src/plots.py、notebooks/demo.py 与 mlruns。读数据用 ibis： import ibis
table = ibis.duckdb.connect().read_parquet("data/train.parquet") feature_cols = [c for c in table.columns if c.startswith("feature_")] data = (table.select(*feature_cols, "target").execute()) X = data[feature_cols] y = data["target"].astype(int) n_classes = int(y.max()) + 1
用 ColumnTransformer 加 StandardScaler 与 XGBClassifier 构建 Pipeline（n_estimators=300、max_depth=5、learning_rate=0.05、subsample=0.8、colsample_bytree=0.8、reg_lambda=1.0、eval_metric="mlogloss"）。处理不均衡用 compute_sample_weight(class_weight="balanced", y=y_train)，并传给 fit 的 clf__sample_weight；多分类不使用 scale_pos_weight。评估用 precision_recall_fscore_support、f1_score（average="macro"/"micro"/"weighted"）、confusion_matrix、top_k_accuracy_score。
适用场景与限制：类别数量不宜过多（超过 100 且只关心 top-K 时考虑分层 softmax 或 learning-to-rank）；类别有顺序时 XGBoost 会忽略顺序信息；predict_proba 返回 (n_samples, n_classes)，多分类 SHAP 返回三维数组需按类别切片；不要只看准确率，否则会掩盖少数类失败；不要在 Pipeline 上传 class_weight；不要忘记显式设置 num_class；不平衡数据上早停指标用 mlogloss 或加权 F1。演示见 demo.py（marimo 笔记本），生成 5 类不均衡合成数据对比有无 sample_weight 时的每类 F1 差异。其余细节暂未提供。