sklearn.Pipeline 不支持两阶段任务，因其仅适配单输出场景；两阶段需第一阶段分类过滤、第二阶段对通过样本排序，须自定义TwoStageRanker类显式控制数据流。
为什么不能直接用 sklearn.pipeline.Pipeline 套两阶段任务
因为标准 Pipeline 只支持单输出（通常是分类或回归），而两阶段任务要求第一阶段输出标签用于过滤/分组，第二阶段在子集上做排序（比如“先判是否是垃圾邮件，再对非垃圾邮件按重要性打分”）。硬塞会导致 transform() 和 predict() 语义冲突，训练时标签对不齐，预测时无法分叉处理。
常见错误现象：AttributeError: 'Pipeline' object has no attribute 'predict_proba' 或排序结果混入被第一阶段筛掉的样本。
- 第一阶段必须是能输出置信度（如
predict_proba）或明确二值决策（predict）的分类器 - 第二阶段排序模型（如
sklearn.ensemble.GradientBoostingRegressor或xgboost.XGBRanker）只接收第一阶段“通过”的样本及其原始特征 - 不能把排序当作回归任务直接喂全量数据——那会污染排序信号
用 sklearn.compose.ColumnTransformer + 自定义类实现分叉逻辑
核心思路：写一个轻量级容器类，继承 BaseEstimator 和 TransformerMixin，在 fit_transform 中完成分类判断、索引切片、子集拟合排序模型三步。不依赖 Pipeline 的链式调用，而是显式控制数据流向。
示例关键结构：
class TwoStageRanker(BaseEstimator, TransformerMixin):
def __init__(self, clf, ranker, threshold=0.5):
self.clf = clf
self.ranker = ranker
self.threshold = threshold
<pre class="brush:php;toolbar:false;">def fit(self, X, y_class, y_rank=None):
# y_class 是二分类标签（0/1），y_rank 是仅对 y_class==1 的样本的有效排序目标
self.clf.fit(X, y_class)
proba = self.clf.predict_proba(X)[:, 1]
mask = proba >= self.threshold
if y_rank is not None:
# 只用通过样本训练排序器
self.ranker.fit(X[mask], y_rank[mask])
return self
def predict(self, X):
proba = self.clf.predict_proba(X)[:, 1]
mask = proba >= self.threshold
scores = np.zeros(len(X))
if mask.any():
scores[mask] = self.ranker.predict(X[mask])
return scores
注意：y_rank 必须与 X 对齐，且只在 mask 为 True 的位置有有效值；否则 ranker.fit() 会报错或学偏。
xgboost.XGBRanker 在第二阶段的实际约束
XGBRanker 不是直接替代回归器——它需要分组信息（group 参数）来建模文档对（pairwise）关系。但在两阶段场景中，你通常没有天然分组（比如“同一用户的所有邮件”），所以容易误用。
- 若无明确分组，改用
XGBRegressor+ 点击率/人工评分等标量目标更稳妥 - 若真有分组（如推荐场景中每个 query 一组 item），必须确保
fit()时传入的group数组长度等于通过样本数，且值为每组样本数的累计和（例如[3, 5, 2]表示三组分别含 3、2、2 个样本） -
XGBRanker的predict()输出不是概率，而是相对得分，需自行归一化或截断
验证阶段最容易漏掉的校验点
上线前必须检查三个独立输出的一致性：第一阶段分类结果、第二阶段排序得分、最终组合策略（比如“只返回 top-5 且 score > 0.1 的样本”）。漏掉任一环都会导致线上效果断层。
- 用
clf.predict_proba(X)[:, 1]和阈值生成的mask，必须与传给ranker.predict()的X[mask]行数一致——建议打印mask.sum()对齐 - 排序得分分布应明显分离：通过样本的得分中位数应显著高于被拒样本的占位零值（即
scores[~mask]全为 0） - 如果业务要求“至少返回 1 个结果”，需在
predict()末尾加兜底逻辑，比如当mask.sum() == 0时退回到clf.predict_proba最高分样本
两阶段管道真正的复杂点不在代码长度，而在各阶段目标函数的耦合——分类器优化的是准确率，排序器优化的是 NDCG，二者梯度不一致。实际中往往要靠阈值调优和重采样缓解，而不是指望端到端自动对齐。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
