imblearn是专为不平衡学习设计的官方扩展库，提供SMOTE过采样、RandomUnderSampler欠采样及SMOTEENN等组合策略，需用imblearn.pipeline.Pipeline封装以避免数据泄露。
用 imblearn 替代原生 sklearn 的采样工具
Scikit-learn 本身不提供重采样功能，直接调用 sklearn.utils.resample 只能做简单随机抽样，无法针对性解决类别不平衡。必须引入 imbalanced-learn（imblearn），它是专为不平衡学习设计的官方扩展库。
安装命令：pip install imbalanced-learn，注意它依赖 scikit-learn >= 1.0，旧版本可能报 ImportError: cannot import name 'check_array'。
-
imblearn.over_sampling.SMOTE对少数类做合成过采样，基于 KNN 插值，比随机复制更鲁棒 -
imblearn.under_sampling.RandomUnderSampler随机删多数类样本，速度快但易丢信息 - 组合策略推荐
imblearn.combine.SMOTEENN：先 SMOTE 过采样，再用 Edited Nearest Neighbours 清理噪声边界点
训练前必须在 Pipeline 中完成重采样
把 SMOTE 或其它采样器直接用在完整数据集上再划分训练/测试集，会导致数据泄露——测试集样本被用于生成合成样本，评估结果严重虚高。
正确做法是只对训练集内部做重采样，并且必须封装进 imblearn.pipeline.Pipeline（不能用 sklearn.pipeline.Pipeline）：
立即学习“Python免费学习笔记（深入）”；
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
from imblearn.pipeline import Pipeline
from imblearn.over_sampling import SMOTE
from sklearn.ensemble import RandomForestClassifier
<p>pipe = Pipeline([
('smote', SMOTE(random_state=42)),
('clf', RandomForestClassifier())
])
pipe.fit(X_train, y_train) # 自动只对 X_train/y_train 重采样
- 如果混用
sklearn.pipeline.Pipeline，会报错AttributeError: 'SMOTE' object has no attribute 'transform' -
SMOTE的k_neighbors参数默认为 5；当少数类样本数 min(5, len(minority_samples)-1) - 分类器输出概率（如
predict_proba）仍基于重采样后的分布，校准需额外加CalibratedClassifierCV
慎用准确率，优先看 f1_score、average_precision_score 和 confusion_matrix
在 99:1 的不平衡数据上，全预测多数类也能拿到 99% 准确率，完全失效。必须切换评估视角：
- 二分类场景下，
f1_score(y_true, y_pred, average='binary')关注少数类召回与精确的调和平均 - 若模型输出概率，
average_precision_score比 AUC-ROC 更稳健（尤其正样本极少时） - 手动检查
confusion_matrix，确认少数类的真正例（TP）是否真实提升，而非靠过拟合边界点刷分 - 避免在重采样后用
class_weight='balanced'—— 它会和 SMOTE 叠加放大偏差，通常关掉
当 SMOTE 失效时，试试 imblearn.ensemble.BalancedRandomForestClassifier
合成数据可能引入噪声或不符合真实分布，尤其在高维稀疏特征（如文本 TF-IDF）或小样本场景下，SMOTE 效果常不如预期。
imblearn.ensemble.BalancedRandomForestClassifier 是更轻量的替代方案：它在每棵决策树训练时，对多数类进行随机欠采样，保持每棵树看到的类别比例均衡，最终集成投票。
- 无需预处理，不生成新样本，规避了 SMOTE 的插值失真风险
- 支持
sample_weight和class_weight，可进一步微调 - 训练速度比 SMOTE + 普通 RF 略慢，但省去 Pipeline 调试成本，适合快速验证
- 注意它不兼容
sklearn.ensemble.RandomForestClassifier的全部参数，例如没有max_features='sqrt'的自动推导逻辑，需显式指定
真实项目里，SMOTE 和 Balanced RF 往往要并行尝试；而最容易被忽略的是——重采样后，原始数据的业务分布已被改变，上线前必须用未重采样的验证集做 final check，否则模型在生产环境会突然“失明”。
