1. 这不是模板，是我在真实项目里反复打磨出的“最小可靠基线”

“Regression/Classification Basic Pipeline”——看到这个标题，别急着划走。它不是教科书里那个被讲烂了的“加载数据→训练模型→打分”的三行代码demo，而是我过去八年带过27个跨行业AI落地项目后，亲手拆解、验证、压测、再重构出来的 工业级最小可行基线流程 。它不炫技，不堆参数，但每次新项目启动，我第一件事就是把它拉出来跑通：用真实业务数据喂进去，看它能不能在30分钟内给出一个“说得过去、站得住脚、改得动、能上线”的初始结果。它解决的从来不是“能不能跑”，而是“跑出来的结果，值不值得工程师花接下来三天去优化”。关键词就三个： 回归（Regression） 、 分类（Classification） 、 Pipeline（流水线） ——注意，这里Pipeline不是指scikit-learn里的Pipeline类，而是指一套贯穿数据准备、特征工程、模型选择、评估验证、结果解释的完整工作流闭环。它适合刚转行的数据分析师，也适合卡在模型调优瓶颈期的算法工程师；适合想快速验证业务假设的产品经理，也适合需要向非技术高管汇报“我们到底干了什么”的技术负责人。你不需要记住所有公式，但必须理解每一步背后的“业务代价”：比如为什么标准化必须在交叉验证外做？为什么分类问题里accuracy永远是第一个该被扔掉的指标？为什么一个没加异常值处理的回归模型，在生产环境里可能比完全不预测还危险？下面我就用自己上个月刚交付的一个电商销量预测项目（回归任务）和一个银行信贷审批项目（二分类任务）作为双主线，把这套流程掰开揉碎，告诉你每一行代码背后的真实战场逻辑。

2. 整体设计思路：为什么必须放弃“端到端黑箱”，拥抱“可拆解、可审计、可归因”的流水线

2.1 核心矛盾：学术benchmark vs. 工业现场

很多人一上来就想套用XGBoost或LightGBM，觉得“模型越新越强”。我试过——在Kaggle房价预测赛上，用LGBM调参后R²达到0.92；但拿到某家居品牌的真实销售数据时，同一套代码跑出来R²只有0.41，且上线后首周预测误差均值暴涨37%。问题出在哪？不是模型不行，是 Pipeline设计本身存在结构性缺陷 。学术场景默认数据干净、分布稳定、标签无噪声；而工业现场，80%的问题出在Pipeline前端：原始订单表里“预计发货日期”字段有12%是空值，但被pandas自动填成NaT，后续做时间特征时直接变成1970年；用户行为日志里“页面停留时长”最大值是99999秒（约27小时），明显是埋点bug，但没做截断就进了模型，把整个特征分布拖偏。所以这套Basic Pipeline的第一设计原则，就是 强制分层、显式隔离、逐层审计 。它不是一条从左到右的直线，而是一个由五个可独立验证、可单独替换、可向前回溯的模块组成的环形结构：数据接入 → 基础清洗 → 特征构造 → 模型拟合 → 评估归因。每个模块输出必须是确定性结果（比如清洗后缺失率报表、特征相关性热力图），而不是“模型跑完了”。

2.2 为什么坚持用sklearn原生工具链，而非AutoML或PyCaret？

有人会问：现在有H2O.ai、TPOT、AutoGluon，一键就能出结果，何必自己搭？我的答案很直接： AutoML解决的是“如何更快找到好模型”，而Basic Pipeline解决的是“如何确认当前结果是否可信” 。上个月帮一家连锁药店做慢病用药续方预测（二分类），用AutoGluon跑出AUC 0.89，但当我用Basic Pipeline的评估模块去深挖时发现：模型在“糖尿病患者”子群体上AUC只有0.63，而该群体占业务量的65%。AutoML不会告诉你这个，它只给你一个全局分数。而我们的Pipeline强制要求：所有评估必须分层（按地域、按年龄组、按病种）、必须可视化（PR曲线+混淆矩阵+特征重要性排序）、必须导出bad case样本（比如把“高概率预测为续方但实际未续方”的前20条订单ID列出来）。这背后是成本考量——药店运营团队需要知道，到底是模型错了，还是他们自己的随访动作没跟上。所以工具选型逻辑非常朴素：sklearn + pandas + matplotlib + joblib，全部是Python生态最稳定、文档最全、debug最透明的组合。LightGBM和XGBoost只作为可选模型后端，不是Pipeline核心。核心是那套 数据-特征-模型-评估的契约接口 ：只要输入是pandas.DataFrame，输出是标准化的评估字典，中间任何模块都可以换——今天用RandomForest，明天换成CatBoost，甚至手工写个规则模型，都不影响整体流程运转。

2.3 回归与分类的本质差异，决定了Pipeline的分叉点

这是最容易被忽略的关键点。很多初学者以为“换掉最后的estimator就行”，比如把LogisticRegression换成LinearRegression。错。回归和分类在Pipeline中至少有四个不可共享的环节：

1. 目标变量预处理 ：回归任务中，对数变换（log1p）几乎是标配，因为销量、价格等右偏分布经log后更接近正态，模型残差更稳定；而分类任务的目标变量必须是整数编码（0/1）或one-hot，且需检查标签平衡性（如信贷审批中坏账率仅1.2%，必须用SMOTE或class_weight）。

2. 评估指标体系 ：回归看MAE（平均绝对误差）、RMSE（均方根误差）、MAPE（平均绝对百分比误差）；分类看Precision/Recall/F1、AUC、KS统计量。特别注意：MAPE对零值敏感，若预测目标含大量0（如冷门商品销量），必须改用SMAPE（对称平均绝对百分比误差）。

3. 异常值处理策略 ：回归中，目标变量的异常值（如单笔订单金额超百万）会直接扭曲损失函数，必须用IQR或MAD法识别并截断；分类中，异常值更多体现在特征维度（如用户月均登录次数达1000次），需结合业务逻辑判断是刷单行为还是VIP用户，不能简单删除。

4. 结果解释方式 ：回归模型输出是连续值，需配套业务阈值（如“预测销量>500件则触发补货”）；分类模型输出是概率，需校准（Platt Scaling或Isotonic Regression），否则原始概率值无法直接对应业务风险等级。

所以我们的Pipeline不是“一个代码库两套配置”，而是 在基础框架上，用装饰器模式动态注入回归专用模块或分类专用模块 。比如 feature_engineering.py 里有一个 @regression_only 装饰器，标记的函数只在回归任务中执行； evaluation.py 里 get_classification_metrics() 和 get_regression_metrics() 完全独立，互不调用。

3. 核心细节解析：从数据接入到评估归因的7个关键控制点

3.1 数据接入层：拒绝“pd.read_csv”直连，必须通过Schema校验网关

很多项目死在第一步：数据源变更。上周合作的一家生鲜平台，其订单表突然新增了“冷链温控记录”字段，类型为JSON字符串。旧Pipeline直接 pd.read_csv 后，该列被识别为object，后续特征工程中调用 .str.len() 报错，整个流程中断。我们的解决方案是建立 Schema定义文件（schema.yaml） ，内容如下：

order_id: {dtype: string, required: true, pattern: "ORD-[0-9]{8}"}
order_date: {dtype: datetime, required: true, min: "2023-01-01", max: "2025-12-31"}
actual_amount: {dtype: float, required: true, min: 0.01, max: 999999.99}
is_refund: {dtype: bool, required: false, default: false}
# 新增字段，明确要求解析为dict
cold_chain_log: {dtype: json, required: false, keys: ["temp_min", "temp_max", "duration_hours"]}

接入时调用 validate_and_load_data("orders.csv", "schema.yaml") ，该函数会：

• 自动推断CSV分隔符、编码（支持gbk、utf-8-sig）
• 对每列执行类型转换（datetime列用 pd.to_datetime(..., errors='coerce') ，失败值转NaT）
• 校验业务规则（如 order_date 不能晚于当前日期， actual_amount 不能为负）
• 对JSON字段，尝试 json.loads() ，失败则记录警告并置空

提示：Schema校验不是性能瓶颈。实测100万行数据校验耗时<3秒，但能避免90%的线上事故。我们把它做成CI/CD流水线的必过环节——任何数据源变更，必须先更新schema.yaml并跑通校验，否则禁止合并代码。

3.2 基础清洗层：缺失值处理不是“fillna(0)”，而是“业务归因决策”

缺失值填充是最常被滥用的操作。在电商销量预测中，“用户最近一次购买时间”缺失，填0意味着“从未买过”，但实际可能是新注册用户（应填“注册时间”）或数据同步延迟（应填“待同步”）。我们的清洗层强制执行 三步归因法 ：

1. 统计缺失模式 ：用 missingno.matrix(df) 生成缺失矩阵图，识别是随机缺失（MCAR）、服从某种规律缺失（MAR）还是完全缺失（MNAR）。例如，发现“优惠券使用金额”缺失集中在“支付方式=余额支付”的订单中——这是业务逻辑：余额支付不支持叠加优惠券，缺失即代表“不适用”，应填0而非NaN。

2. 分列制定策略 ：对数值型列，提供三种选项：

   • fill_mean ：适用于近似正态分布且缺失率<5%的列（如“商品重量”）
   • fill_median ：适用于右偏分布（如“用户历史总消费”）
   • fill_business_rule ：自定义函数，如 lambda x: x["register_date"] if pd.isna(x["last_purchase_date"]) else x["last_purchase_date"]

3. 保留缺失痕迹 ：对所有被填充的列，同步生成 {col}_is_imputed 布尔列（如 last_purchase_date_is_imputed ），供后续特征工程使用。模型可学习“填充样本”的共性模式，避免将人工干预误判为真实信号。

注意：绝不允许全局 df.fillna(0) 。我踩过的最大坑是：某次将“用户年龄”缺失统一填0，导致模型学到“年龄=0的用户复购率最高”——其实是新注册用户，后续运营团队据此给0岁用户发优惠券，引发客诉。

3.3 特征构造层：拒绝“暴力特征工程”，坚持“业务可解释性优先”

特征工程常陷入两个极端：一是手工硬编码几十个特征，二是用FeatureTools自动生成200+个特征。我们的做法是 聚焦3类高价值特征 ：

特征类型	构造方法	业务意义	实例（销量预测）
时序聚合特征	按用户/商品/地域，滚动窗口计算均值、标准差、斜率	捕捉短期趋势与稳定性	近7天同品类销量均值、近30天销量标准差
比率型特征	分子/分母，且分母有业务下限	消除量纲，反映效率	用户点击率 = 点击次数 / 曝光次数（曝光<100时置空）
分箱离散特征	用 pd.qcut 按分位数分箱，非等宽	处理长尾分布，增强鲁棒性	将“用户历史总消费”分为5档：低、中低、中、中高、高

关键技巧：所有特征构造函数必须带 __doc__ 字符串，说明业务含义。例如：

def calc_7d_avg_sales_by_category(df: pd.DataFrame) -> pd.Series:
    """计算每个商品在所属品类下的近7天销量均值。
    用途：衡量商品在品类内的相对热度，避免绝对值受大促干扰。
    注意：仅对order_date>=7天前的订单生效，新上架商品返回0。
    """
    # 实现代码...

这样，当业务方质疑“为什么这个特征权重这么高”，你能立刻拿出文档解释，而不是说“模型自己学的”。

3.4 模型拟合层：交叉验证不是“cv=5”，而是“模拟线上数据漂移”

sklearn的 cross_val_score 默认用 KFold ，但现实世界数据是按时间流动的。用随机K折，等于把未来的数据拿来训练过去的模型，严重高估性能。我们的解决方案是 TimeSeriesSplitPlus ——在标准 TimeSeriesSplit 基础上增加两个增强：

1. gap参数 ：在训练集和验证集间插入n天空白期，模拟线上模型更新延迟。例如，训练用1-30日数据，验证用35-40日数据（留出5天gap），确保模型没见过验证期前的数据。

2. expanding window ：首折用最小训练集（如7天），后续每折增加1天，模拟模型持续学习过程。代码实现：

from sklearn.model_selection import TimeSeriesSplit

class TimeSeriesSplitPlus(TimeSeriesSplit):
    def __init__(self, n_splits=5, gap=3, min_train_size=7):
        super().__init__(n_splits=n_splits)
        self.gap = gap
        self.min_train_size = min_train_size
    
    def split(self, X, y=None, groups=None):
        n_samples = len(X)
        indices = np.arange(n_samples)
        # 首折：训练集从min_train_size开始，验证集从min_train_size+gap开始
        train_start = 0
        for i in range(self.n_splits):
            train_end = self.min_train_size + i
            if train_end >= n_samples - self.gap:
                break
            test_start = train_end + self.gap
            test_end = min(test_start + 5, n_samples)  # 每次验证5天
            yield indices[train_start:train_end], indices[test_start:test_end]

实操心得：在银行信贷项目中，用标准KFold得到AUC 0.85，但用TimeSeriesSplitPlus（gap=30）后降至0.72——这才是真实水平。上线后首月监控显示，模型AUC稳定在0.71-0.73区间，证明该验证方式有效。

3.5 评估归因层：拒绝“单一数字”，坚持“四维诊断报告”

模型评估输出不是一行 print(f"Accuracy: {acc}") ，而是生成PDF格式的 四维诊断报告 ，包含：

1. 全局指标页 ：回归任务展示MAE/RMSE/MAPE，分类任务展示Precision/Recall/F1/AUC，并标注行业基准（如电商销量预测MAPE<15%为优秀）。

2. 分群分析页 ：按关键业务维度切片，如：

   • 回归：按商品价格带（<50元、50-200元、>200元）分别统计MAPE
   • 分类：按用户地域（华东、华北、华南）分别统计Recall（坏账召回率）

3. bad case分析页 ：列出预测误差Top20样本，包含原始特征、预测值、真实值、误差绝对值，并高亮异常特征值（如“预测销量1000件，但该商品历史最高日销仅200件”）。

4. 特征归因页 ：用SHAP值绘制瀑布图，解释单个样本预测结果。例如，对一笔被错误预测为“高风险”的贷款，SHAP图显示：“用户月收入-25分，但‘近3月查询征信次数’贡献+42分，主导了高风险判断”。

该报告由 generate_evaluation_report(model, X_test, y_test, feature_names) 一键生成，业务方无需懂代码，直接看PDF就能定位问题。

3.6 模型持久化层：不止保存.pkl，更要存“可执行上下文”

joblib.dump(model, "model.pkl") 只能保存模型权重，但线上部署需要完整上下文。我们的持久化模块输出一个 model_bundle/ 目录，包含：

• model.pkl ：训练好的模型对象
• preprocessor.pkl ：完整的特征预处理器（含StandardScaler、OneHotEncoder等）
• feature_config.json ：特征构造逻辑的JSON描述，如 {"sales_7d_avg": {"type": "rolling_mean", "window": 7, "groupby": ["category_id"]}}
• schema.yaml ：训练时使用的数据Schema
• requirements.txt ：精确到小数点后两位的依赖版本（如 scikit-learn==1.3.0 ）

这样，当运维同事要部署时，只需运行 deploy_model("model_bundle/") ，该函数会：

• 校验当前环境Python版本、依赖版本是否匹配
• 加载preprocessor对新数据做一致转换
• 调用模型预测，并自动附加 prediction_confidence （基于预测值与训练集目标分布的距离）

注意：绝不允许“模型训练环境”和“线上推理环境”分离。我们强制要求：所有模型必须在Docker容器中训练，镜像打包进 model_bundle/ ，确保100%环境一致性。

3.7 Pipeline编排层：用DAG图替代脚本，让流程“看得见、管得住”

最终，所有模块不是写在 main.py 里顺序执行，而是用 轻量级DAG引擎 编排。我们选用 ploomber （非Airflow，因其更轻量），定义 pipeline.yaml ：

tasks:
  - source: src.data.load_data
    product: data/raw.parquet
    params:
      file_path: "s3://bucket/orders.csv"
  
  - source: src.data.clean_data
    product: data/clean.parquet
    upstream: [src.data.load_data]
  
  - source: src.features.build_features
    product: data/features.parquet
    upstream: [src.data.clean_data]
    params:
      target_col: "sales_quantity"  # 动态传入回归/分类标识
  
  - source: src.model.train_model
    product: models/best_model.joblib
    upstream: [src.features.build_features]
    params:
      task_type: "regression"  # 或 "classification"

执行 ploomber build 即可按依赖关系自动调度。好处是：当某环节失败（如特征构造报错），DAG引擎会精准定位到 src.features.build_features ，并显示上游输入 data/clean.parquet 的SHA256哈希值——你可以立刻判断，是数据变了，还是代码逻辑错了。

4. 实操过程：以电商销量预测（回归）为例，完整走一遍从0到1

4.1 环境准备与依赖安装

我们不推荐conda或venv，而是用 Poetry 管理依赖，确保可重现性。创建 pyproject.toml ：

[tool.poetry.dependencies]
python = "^3.9"
pandas = "^2.0.3"
scikit-learn = "^1.3.0"
lightgbm = "^3.3.5"
matplotlib = "^3.7.2"
seaborn = "^0.12.2"
joblib = "^1.3.2"
ploomber = "^0.22.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

安装命令：

curl -sSL https://install.python-poetry.org | python3 -
poetry install
poetry shell  # 进入隔离环境

实操心得：曾因 scikit-learn 版本从1.2.2升到1.3.0， StandardScaler 的 with_mean 默认值从True变为False，导致线上模型预测结果整体偏移。Poetry锁死版本后，此类问题归零。

4.2 数据接入与Schema校验

假设原始数据 orders.csv 在本地，内容节选：

order_id,order_date,product_id,category_id,actual_amount,user_id
ORD-20230001,2023-01-01,PROD-001,CAT-001,299.00,USR-1001
ORD-20230002,2023-01-01,PROD-002,CAT-002,59.90,USR-1002

创建 schema.yaml ：

order_id: {dtype: string, required: true, pattern: "ORD-[0-9]{8}"}
order_date: {dtype: datetime, required: true}
product_id: {dtype: string, required: true}
category_id: {dtype: string, required: true}
actual_amount: {dtype: float, required: true, min: 0.01}
user_id: {dtype: string, required: true}

执行校验加载：

from src.data.load_data import validate_and_load_data
df = validate_and_load_data("orders.csv", "schema.yaml")
print(f"加载成功，共{len(df)}行，缺失率：{df.isnull().mean().round(3).to_dict()}")
# 输出：加载成功，共124582行，缺失率：{'order_id': 0.0, 'order_date': 0.0, ...}

4.3 基础清洗：处理时间字段与业务缺失

原始数据中 order_date 是字符串，需转为datetime并提取特征：

# src/data/clean_data.py
def clean_orders(df: pd.DataFrame) -> pd.DataFrame:
    df = df.copy()
    # 强制转换，错误值转NaT
    df["order_date"] = pd.to_datetime(df["order_date"], errors="coerce")
    # 删除order_date为空的行（业务上不可能）
    df = df.dropna(subset=["order_date"])
    # 补充缺失的category_id：根据product_id映射表
    product_to_cat = load_product_mapping()  # 从数据库加载映射
    df["category_id"] = df["product_id"].map(product_to_cat).fillna("UNKNOWN")
    # 标记category_id是否为填充值
    df["category_id_is_imputed"] = df["category_id"] == "UNKNOWN"
    return df

清洗后， df.info() 显示 category_id_is_imputed 列为bool类型，为后续特征工程提供信号。

4.4 特征构造：构建销量预测的核心特征集

目标变量是 sales_quantity （需从订单表聚合得出），构造以下特征：

# src/features/build_features.py
def build_sales_features(df: pd.DataFrame) -> pd.DataFrame:
    # 1. 时序聚合：各维度7天销量均值
    df["sales_7d_by_product"] = df.groupby("product_id")["actual_amount"].transform(
        lambda x: x.rolling(7, min_periods=1).mean().shift(1)
    )
    
    # 2. 比率特征：品类渗透率 = 该商品销量 / 品类总销量
    cat_total = df.groupby("category_id")["actual_amount"].transform("sum")
    df["penetration_rate"] = df["actual_amount"] / cat_total
    
    # 3. 分箱特征：用户价值分层
    df["user_value_bin"] = pd.qcut(
        df.groupby("user_id")["actual_amount"].transform("sum"),
        q=5, labels=["L", "ML", "M", "MH", "H"],
        duplicates="drop"
    ).astype(str)
    
    return df

关键点：所有 transform 操作都带 min_periods=1 ，避免首行因窗口不足返回NaN； shift(1) 确保不使用未来信息。

4.5 模型训练：用TimeSeriesSplitPlus进行稳健验证

# src/model/train_model.py
from src.model.tssplit_plus import TimeSeriesSplitPlus
from lightgbm import LGBMRegressor

def train_regressor(X, y):
    model = LGBMRegressor(
        n_estimators=100,
        learning_rate=0.1,
        num_leaves=31,
        random_state=42
    )
    
    # 使用增强版时间序列分割
    tscv = TimeSeriesSplitPlus(n_splits=3, gap=3, min_train_size=7)
    
    # 计算交叉验证得分
    cv_scores = cross_val_score(
        model, X, y, 
        cv=tscv, 
        scoring="neg_mean_absolute_error",
        n_jobs=-1
    )
    
    print(f"MAE CV Scores: {(-cv_scores).round(3)}")
    print(f"Mean MAE: {(-cv_scores.mean()):.3f} ± {cv_scores.std():.3f}")
    
    # 在全量训练集上拟合最终模型
    model.fit(X, y)
    return model

# 执行
X = df[["sales_7d_by_product", "penetration_rate"]]
y = df["actual_amount"]  # 目标变量
model = train_regressor(X, y)

输出示例：

MAE CV Scores: [28.452 29.103 27.887]
Mean MAE: 28.481 ± 0.502

4.6 评估归因：生成四维诊断报告

# src/evaluation/generate_report.py
from src.evaluation.report_generator import generate_evaluation_report

# 划分训练/测试集（按时间）
split_point = int(len(X) * 0.8)
X_train, X_test = X.iloc[:split_point], X.iloc[split_point:]
y_train, y_test = y.iloc[:split_point], y.iloc[split_point:]

model.fit(X_train, y_train)
y_pred = model.predict(X_test)

report_path = generate_evaluation_report(
    model=model,
    X_test=X_test,
    y_test=y_test,
    feature_names=["sales_7d_by_product", "penetration_rate"],
    task_type="regression",
    output_dir="reports/"
)
print(f"报告已生成：{report_path}")

打开 reports/regression_diagnosis.pdf ，你会看到：

• 全局MAE=27.9，低于行业基准30
• 分群分析显示：在“CAT-001”品类下MAE仅18.2，但在“CAT-005”（生鲜）下高达41.5——提示需为生鲜品类单独建模
• bad case列表中，第3条显示“预测299元，实际1299元”，查看原始数据发现该订单含5件商品，但特征中未体现“订单商品数”，需补充特征

4.7 模型部署：打包为可执行Bundle

# src/deploy/save_bundle.py
from src.deploy.bundle_saver import save_model_bundle

save_model_bundle(
    model=model,
    preprocessor=preprocessor,  # 包含StandardScaler等
    feature_config={
        "sales_7d_by_product": {"type": "rolling_mean", "window": 7},
        "penetration_rate": {"type": "ratio", "numerator": "actual_amount"}
    },
    schema_path="schema.yaml",
    requirements_path="requirements.txt",
    output_dir="model_bundle/"
)

生成的 model_bundle/ 目录结构：

model_bundle/
├── model.pkl
├── preprocessor.pkl
├── feature_config.json
├── schema.yaml
├── requirements.txt
└── Dockerfile  # 内置推理API服务

部署命令：

cd model_bundle
docker build -t sales-predictor .
docker run -p 8000:8000 sales-predictor
# 调用API
curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"order_date":"2023-06-01","product_id":"PROD-001"}'

5. 常见问题与排查技巧实录：那些文档里不会写的实战经验

5.1 问题速查表：高频故障与根因定位

现象	可能根因	排查命令/步骤	解决方案
Pipeline在 clean_data 阶段报 TypeError: cannot convert datatime64 to datetime	order_date 列含非法字符串（如"2023-01-01 00:00:00.000"与"2023-01-01"混存）	df["order_date"].apply(type).value_counts()	在 validate_and_load_data 中增加 infer_datetime_format=True 参数
特征构造后 X 中出现 inf 或 -inf	比率特征分母为0（如某品类总销量为0）	np.isinf(X).sum().sum() + X[np.isinf(X).any(axis=1)]	在比率计算前加 np.where(denominator==0, np.nan, numerator/denominator)
交叉验证时 ValueError: Found array with 0 sample(s)	TimeSeriesSplitPlus 的 min_train_size 设得过大，首折无足够数据	print(f"数据总行数：{len(X)}, min_train_size：{min_train_size}")	将 min_train_size 设为 max(7, int(len(X)*0.1)) ，动态计算
模型预测结果全是 nan	StandardScaler 在训练时遇到全NaN列， scale_ 属性为 nan	preprocessor.named_steps['scaler'].scale_	在 build_features 中增加 df = df.replace([np.inf, -np.inf], np.nan)
评估报告中MAPE显示 inf	预测目标含0值，且预测值非0（0值分母导致除零）	y_test[y_test==0].count()	改用SMAPE： 2 * np.abs(y_true - y_pred) / (np.abs(y_true) + np.abs(y_pred))

5.2 那些必须写进Checklist的“隐形坑”

• 时间特征陷阱 ：不要用 pd.to_datetime(df["order_date"]).dt.dayofweek ，因为周一=0，周日=6，模型会误认为“周日比周一高6倍”。正确做法是 pd.get_dummies(df["order_date"].dt.day_name(), prefix="day") ，生成7个布尔列。

• 类别特征陷阱 ： OneHotEncoder 默认 handle_unknown="error" ，但线上新出现的 category_id 会直接报错。必须设为 handle_unknown="infrequent_if_exist" ，并将低频类别（出现<10次）合并为 other 。

• 内存泄漏陷阱 ： pandas.read_csv 读取大文件时，若指定 dtype={"user_id": "category"} ，会显著降低内存占用。实测10GB订单表，内存从24GB降至3.2GB。

• 随机种子陷阱 ： LGBMRegressor(random_state=42) 只固定模型内部随机性，但 TimeSeriesSplitPlus 的分割是确定性的，无需额外设种子。真正需要设种子的是 train_test_split （仅用于调试）。

5.3 性能优化三板斧：让Pipeline快10倍

1. 列式存储加速 ：将清洗后的数据存为Parquet而非CSV。 df.to_parquet("data/clean.parquet", engine="pyarrow", compression="snappy") ，读取速度提升5-8倍，且支持按列读取。

2. 特征缓存机制 ：在 build_features.py 开头加入：

   from joblib import Memory
   memory = Memory(location=".cache", verbose=0)
   @memory.cache
   def build_sales_features_cached(df):
       return build_sales_features(df)
   

   同一数据输入，第二次调用直接返回缓存结果，跳过全部计算。

3. 并行化粒度控制 ： cross_val_score 的 n_jobs=-1 会启动过多进程，反而因IPC开销变慢。实测在32核机器上，设 n_jobs=8 最佳。用 psutil.cpu_count(logical=False) 动态获取物理核心数。

5.4 业务方沟通话术：如何把技术细节翻译成业务语言

• 当业务方问“为什么不用深度学习”：
  “深度学习像一架喷气式飞机，起飞需要3公里跑道（海量数据）和专业塔台（GPU集群）。我们现在只有200米跑道（10万行数据），用螺旋桨飞机（LightGBM）10分钟就能起飞，且飞行员（我们的工程师）全程可控。等跑道扩建完成，再换飞机不迟。”

• 当业务方质疑“MAE 28元太高”：
  “当前人工预测MAE是45元，我们提升了38%。这28元误差中，22元来自生鲜品类（易腐品需求波动大），6元来自新品（无历史数据）。下一步，我们将生鲜和新品拆分成两个子模型，目标MAE压到15元。”

• 当业务方要求“立刻上线”：
  “可以，但需明确：上线的是V1.0基线版，它保证不比人工预测差。我们同时启动V1.1优化，重点解决生鲜品类误差，两周后交付。您希望V1.0先覆盖全部品类，还是先在华东区试点？”

5.5 我的个人体会：Pipeline的价值不在“自动化”，而在“可协商性”

这套Basic Pipeline我用了八年，最大的收获不是省了多少时间，而是 把技术决策变成了可协商的业务对话 。以前，算法工程师说“模型效果不好”，业务方听不懂；现在，大家围着四维诊断报告，指着“CAT-005品类MAE 41.5”讨论：“是不是生鲜仓配时效太差，导致销量预测失真？”——问题从“模型不行”变成了“我们要