从“卡死”到“跑通”：WMS机器学习全流程实战排坑记

摘要：在出版行业WMS智能调度项目中，我们搭建了一套基于LightGBM的销量预测模型。然而，在实际落地过程中，从特征工程、模型训练到预测评估，每一步都踩了无数"坑"：变量缺失、表不存在、日期类型错误、ORA-00942、DPI-1015数组溢出、训练集为空、MAPE爆炸......本文逐一记录这些问题的现象、原因及解决方法，并总结出可复用的排查思路。读完本文，你将学会如何快速定位并解决类似问题，让机器学习项目真正跑起来。

---

一、背景与目标

我们正在为仓库构建托盘任务智能调度系统，核心是通过机器学习预测SKU月均销量，为出库口决策提供依据。技术栈：Oracle 11g（远程备库）+ Python 3.9 + LightGBM + 报表库本地表。

整体流程：

1. 特征工程：从销售日汇总表和库存月末快照表构建特征表 WMS_ML_FEATURES。
2. 模型训练：训练托数和件数两个回归模型。
3. 预测：为下个月生成销量预测，写入 WMS_ML_FORECAST_TUO。
4. 评估：对比预测与实际销量，计算误差指标。

然而，在一天之内，我们先后遇到了十几个报错，几乎每个环节都卡住。以下是详细的排坑记录。

---

二、问题与解决逐条记录

阶段一：特征工程（feature_engineering.py）

问题1：ImportError: cannot import name 'PROGRESS_INTERVAL' from 'config'

• 现象 ：运行 python3 feature_engineering.py 时，提示缺少 PROGRESS_INTERVAL。

• 原因 ：config.py 中没有定义特征工程进度输出间隔和历史窗口天数。

• 解决 ：在 config.py 末尾添加：

  PROGRESS_INTERVAL = 5000
  HISTORY_WINDOW = 365

问题2：ORA-00942: table or view does not exist（LOCAL_ITEM_ATTR 表缺失）

• 现象 ：执行 fetch_item_attributes() 时，提示表不存在。
• 原因 ：特征工程需要读取商品属性（每托件数、分类、首次上架日期等），但本地表 LOCAL_ITEM_ATTR 未创建。
• 解决 ：创建表 WMS_ITEM_ATTR（或原名 LOCAL_ITEM_ATTR），并每日从远程库同步数据。关键字段：item_id, supportcode_quantity, class4, first_sale_date。

问题3：AttributeError: 'numpy.datetime64' object has no attribute 'month'

• 现象 ：在 add_labels() 函数中，month_start.month 报错。

• 原因 ：feature_df['begin_month'].unique() 返回的是 numpy.datetime64 类型，不能直接使用 .month 属性。

• 解决 ：在循环开始时转换类型：

  month_start = pd.Timestamp(month)

  并手动计算 next_month（避免使用自定义的 add_months 函数）。

问题4：DPI-1015: array size of 264601 is too large

• 现象 ：写入特征表时，df.to_sql 抛出 oracledb.exceptions.DatabaseError。

• 原因：pandas 默认一次性提交全部数据（26万行），超出 Oracle 数组大小限制。

• 解决 ：修改 db_utils.py 中的 to_sql 方法，增加 chunksize=1000 分批写入，并指定 dtype 映射避免字符串列被误转为 CLOB。

  def to_sql(self, df, table, if_exists='append', index=False, chunksize=1000):
      dtype = {col: types.VARCHAR(4000) for col in df.select_dtypes('object').columns}
      df.to_sql(table.upper(), self.engine, if_exists=if_exists,
                index=index, chunksize=chunksize, dtype=dtype)

问题5：SettingWithCopyWarning 警告

• 现象 ：A value is trying to be set on a copy of a slice from a DataFrame.
• 原因 ：X = feature_df[ALL_FEATURES] 返回的是视图，修改视图中的列会触发警告。
• 解决 ：改为深拷贝 X = feature_df[ALL_FEATURES].copy()，或使用 .loc 赋值。

---

阶段二：模型训练（train_model.py）

问题6：ImportError: cannot import name 'LABEL_COL' from 'config'

• 现象：训练脚本无法导入标签列名。
• 原因 ：config.py 中标签列定义为 LABEL_TUO 和 LABEL_QTY，而脚本试图导入 LABEL_COL。
• 解决：修改导入，分别使用两个标签，并调整后续代码。

问题7：训练集为空（Train size: 0, Test size: 114）

• 现象 ：ValueError: Input data must be 2 dimensional and non empty.
• 原因 ：特征表只有4个月数据，而 prepare_train_test 默认最后3个月作为测试集，导致训练集为空。
• 解决 ：将 test_months 改为1，或扩大特征表时间范围。暂时修改调用参数：prepare_train_test(df, test_months=1)。

问题8：ValueError: DataFrame.dtypes for data must be int, float or bool

• 现象 ：Did not expect the data types in the following fields: publisher_code, category_code

• 原因：LightGBM 要求特征全为数值类型，但类别列是字符串。

• 解决 ：在 load_data() 中将类别列转为 category 类型：

  for col in CATEGORICAL_FEATURES:
      if col in df.columns:
          df[col] = df[col].astype('category')

问题9：FileNotFoundError: No such file or directory: './models/monthly_sales_predictor_tuo.lgb'

• 现象：模型训练成功后保存文件时报错。
• 原因 ：models 目录不存在。
• 解决 ：mkdir -p /home/xinhua/wms_ml/models

---

阶段三：预测（predict.py）

问题10：cannot import name 'MODEL_PATH' from 'config'

• 现象：预测脚本无法导入模型路径。
• 原因 ：config.py 中定义了 MODEL_PATH_TUO 和 MODEL_PATH_QTY，而非单一的 MODEL_PATH。
• 解决：分别导入并加载两个模型。

问题11：预测月份不合理（预测2026年6月）

• 现象 ：脚本使用 add_months(datetime.today().replace(day=1), 1) 计算下个月，但2026年5月的销售历史尚未发生，导致特征依赖未来数据。
• 原因：业务上应预测下一个自然月，但当前时间点是5月初，预测6月需要5月的销售数据（未发生）。
• 解决 ：手动将目标月份改为 datetime(2026, 5, 1)，确保使用已有的库存快照（2026-04-30）和历史销售（截止2026-04-30）。

---

阶段四：评估（evaluate_model.py）

问题12：MAPE 爆炸（837316302366179968.0%）

• 现象：评估输出的 MAPE 异常巨大。

• 原因：大量 SKU 实际销量为 0，模型预测值非零，导致百分比无限大。

• 解决 ：过滤实际销量小于阈值（如 min_actual_tuo=0.5）的样本，并增加对称平均绝对百分比误差（SMAPE）指标。

  def smape(y_true, y_pred):
      denominator = (np.abs(y_true) + np.abs(y_pred)) / 2
      diff = np.abs(y_true - y_pred) / denominator
      diff[denominator == 0] = 0
      return np.mean(diff) * 100

问题13：NameError: name 'np' is not defined

• 现象 ：smape 函数中使用 np 但未导入。
• 解决 ：在脚本开头添加 import numpy as np。

---

阶段五：环境与配置

问题14：ORA-00942 反复出现（表不存在）

• 现象 ：多次提示 WMS_SALES_DAILY_AGG 或 INV_MONTH_END_SUMMARY 等表不存在。
• 原因：报表库中缺少对应的本地表，或表名大小写不一致（Oracle 默认大写，Python 中使用大写表名）。
• 解决：逐一创建缺失的表，并确认 SQL 中表名与数据库一致（大写）。

问题15：库存历史数据缺失

• 现象：评估结果中库存特征全为0，导致模型效果差（MAE=3.197，SMAPE=68%）。
• 原因：库存备份只保留了最近两个月，无法获取2022-2025年的库存快照。
• 解决 ：若远程库有历史库存明细，执行存储过程 sp_backfill_inv_hist 回填；否则只能等待未来积累数据后重训。

---

三、关键经验与教训

1. 配置文件要完整 ：所有常量（表名、路径、精度、窗口大小）都应在 config.py 中集中定义，避免散落各处。
2. 表存在性检查 ：每次运行前，确认本地表已创建，且字段符合预期。可以编写一个 check_tables() 函数自动验证。
3. 数据类型要谨慎 ：numpy.datetime64 与 datetime 不通用，pandas 的 category 类型是 LightGBM 处理类别特征的最佳方式。
4. 分批写入是王道 ：Oracle 对单次批量大小有限制，必须使用 chunksize。
5. 评估指标要稳健：实际销量存在大量0值时，用 SMAPE 替代 MAPE，或过滤低销量样本。
6. 历史库存是基石：没有库存特征，模型的准确率会大打折扣；应尽早推动库存数据备份和回填。
7. 日志与警告 ：SettingWithCopyWarning 虽不影响结果，但表明确实存在复制/视图混淆，应养成使用 .copy() 的习惯。

---

四、后续优化方向

1. 补充历史库存数据：如果远程库有2022-2025年的库存明细，回填后重新训练，模型效果将显著提升。
2. 扩大训练集：目前只有484条标签非零样本，需构建更多月份的特征（如2022-2025年）。
3. 超参数调优 ：使用网格搜索或贝叶斯优化，调整 num_leaves, learning_rate 等参数。
4. 特征工程增强：增加滞后特征、节假日标识等，进一步提升预测能力。
5. 自动化调度：将特征工程、训练、预测、评估全部纳入 crontab 或 Airflow，实现全自动流水线。

---

五、结语

这一天我们几乎遇到了所有可能出现的"坑"，但每一次报错都让我们对系统的理解更深一层。希望这篇文章能帮助后来的同学少走弯路。记住：跑通流程只是第一步，持续优化才是真正的挑战。

如果你也正在构建类似的系统，欢迎留言交流。

👉 点击关注我，更新后第一时间收到推送！