自定义转换器必须继承baseestimator和transformermixin，实现fit()和transform()，注意返回self、保持输入输出类型一致、保留列名、显式设置remainder='passthrough'、状态参数命名以_结尾并校验shape。
自定义转换器必须继承 BaseEstimator 和 TransformerMixin
不继承这两个基类，fit_transform() 会报错或无法被 Pipeline 识别。常见错误是只写个普通类，调用时抛出 AttributeError: 'MyTransformer' object has no attribute 'transform' 或 NotFittedError。
正确做法是显式继承，并实现 fit() 和 transform()（fit_transform 由 TransformerMixin 自动提供）：
from sklearn.base import BaseEstimator, TransformerMixin
<p>class LogScaler(BaseEstimator, TransformerMixin):
def <strong>init</strong>(self, offset=1):
self.offset = offset</p><pre class="brush:python;toolbar:false;">def fit(self, X, y=None):
return self # 无状态转换器，无需拟合参数
def transform(self, X):
return np.log(X + self.offset)
注意：fit() 必须返回 self；transform() 输入输出都应是 numpy.ndarray 或 pandas.DataFrame，且行数不变。
处理 DataFrame 时别直接用 .values 丢弃列名
很多自定义转换器在 transform() 里粗暴调用 X.values，结果返回纯 ndarray，下游模型（如 ColumnTransformer 或特征重要性分析）就丢失列信息，调试时发现特征顺序对不上。
保留结构的写法更稳妥：
- 若输入是
pandas.DataFrame，优先用X.copy()+ 列操作，最后返回同类型对象 - 用
pd.DataFrame(transformed_data, columns=X.columns, index=X.index)显式重建 - 在
fit()中检查输入类型：if hasattr(X, 'columns')分支处理
例如：对数值列做 z-score 归一化但保留列名：
def transform(self, X):
X_out = X.copy()
cols = self.columns_ if hasattr(self, 'columns_') else X.select_dtypes('number').columns
X_out[cols] = (X_out[cols] - self.means_) / self.stds_
return X_out
ColumnTransformer 里嵌套自定义转换器要指定 remainder='passthrough'
默认 remainder='drop'，非目标列会被静默删掉，容易导致训练/预测维度不一致——尤其在线上推理时，新增字段直接让 pipeline 崩溃。
显式声明更安全：
-
remainder='passthrough'：保留未指定列（推荐） - 若需丢弃，改用
remainder='drop'并加日志提醒 - 避免混用
ColumnTransformer和手动pd.concat()，后者破坏 pipeline 的可复现性
示例：
from sklearn.compose import ColumnTransformer
ct = ColumnTransformer(
transformers=[('log', LogScaler(), ['price', 'area'])],
remainder='passthrough' # 关键！
)
带状态的转换器必须在 fit() 中保存参数并校验 shape
比如计算均值、分位数、编码映射表等，必须存为实例属性（如 self.means_），且命名以 _ 结尾——这是 scikit-learn 的约定，否则 get_params() 无法序列化，joblib.dump() 会漏掉关键状态。
常见坑：
- 在
transform()里重新计算统计量（违背“fit once, transform many”原则） - 没检查
X.shape[1]是否与fit()时一致，导致线上数据列数变化时报ValueError: shapes not aligned - 对空 DataFrame 或全 NaN 列没做防御，
np.mean()返回nan，后续运算崩
建议在 fit() 开头加简单校验：
def fit(self, X, y=None):
if X.shape[1] == 0:
raise ValueError("X has no features")
self.means_ = np.nanmean(X, axis=0)
return self
真正麻烦的是跨环境一致性：本地开发用 pandas 1.5，生产是 2.0，DataFrame 构造行为微变；或者 numpy 版本差异导致 nan 处理逻辑不同。上线前务必用真实数据集跑一遍 fit() → dump() → load() → transform() 全链路验证。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
