ShopTRAINING/data/multi_model_feature_strategy.md

多模型自适应特征选择系统设计方案

版本: 1.0 日期: 2025-07-25 作者: Roo

1. 概述

本文档旨在为现有销售预测系统设计一套全新的数据处理管道。该方案的核心目标是，在接入包含丰富预处理特征的新数据集（old_5shops_50skus.parquet）后，能够根据不同算法模型的特性，为其智能地、动态地选择最优的特征子集进行训练，从而最大限度地发挥各算法的潜力。

现有系统的问题在于其特征工程逻辑是硬编码在代码中的，无法利用新数据集中已经预处理好的海量特征。本方案将彻底重塑此数据管道，从“实时计算少量特征”模式转变为“按需选择海量预处理特征”模式。

2. 核心设计思想：特征选择注册表

我们将引入“特征选择注册表（Feature Selection Registry）”的设计模式。此模式取代了过去在代码中硬编码特征列表或通过JSON配置选择特征的做法。

其核心优势在于：

• 尊重现有成果：完全基于您提供的 data/old_5shops_50skus-据结构字典.md 中的特征进行工作，不引入额外的特征创造，专注于特征选择。
• 算法为本：为系统中的每一种算法模型（mLSTM, Transformer, TCN, XGBoost, KAN, CNN-BiLSTM-Attention）量身定制一个专属的特征选择函数。
• 高度解耦：每个模型的特征选择逻辑都封装在自己的函数中，修改一个模型的特征策略不会影响其他任何模型，便于维护和迭代。
• 清晰高效：每个函数的职责单一且明确——从所有可用特征中，为特定算法挑选出最合适的特征列表。

3. 架构设计与工作流程

新的数据处理流程将遵循以下步骤：

graph TD
    subgraph "API请求"
        A[POST /api/training <br> {model_type: 'mlstm'}]
    end

    subgraph "核心逻辑 (predictor.py)"
        A --> B{train_model(model_type='mlstm')};
        B --> C[1. 加载完整的Parquet数据 -> df];
        C --> D[2. 调用 get_feature_list_for_model('mlstm', df.columns)];
    end

    subgraph "特征选择模块 (feature_selection.py)"
        D --> E{Feature Selection Registry};
        E -- "model_type is 'mlstm'" --> F[调用 select_features_for_mlstm(df.columns)];
        F --> G["返回mLSTM的<br>专属特征列表"];
    end

    subgraph "训练与模型层"
        G & C --> H{mLSTM Trainer};
        H -- "使用df和专属特征列表" --> I[准备数据并训练];
        I --> J([models/mlstm_model.pth]);
    end

    J --> K[返回结果] --> B --> L[API响应] --> A;

    style F fill:#cce5ff,stroke:#004085,stroke-width:2px,stroke-dasharray: 5 5
    style E fill:#f5c6cb,stroke:#721c24,stroke-width:2px

4. 各算法特征选择策略详解

以下是为全部六种算法模型设计的专属特征选择策略。所有策略都基于 data/old_5shops_50skus-据结构字典.md 中的特征。

算法模型	模型类型	核心策略	推荐特征集
mLSTM	序列模型 (RNN)	捕捉时序依赖	select_features_for_mlstm: 核心指标 + 短期滚动 + 静态上下文
Transformer	序列模型 (Attention)	捕捉长距离依赖	select_features_for_transformer: mLSTM基础上 + 中长期滚动
TCN	序列模型 (CNN)	捕捉多尺度模式	select_features_for_tcn: 与Transformer类似，提供丰富特征
CNN-BiLSTM-Attn	序列模型 (Hybrid)	自学习局部模式	select_features_for_hybrid: 核心指标 + 中长期滚动 + 静态特征
XGBoost	表格模型 (Tree)	挖掘特征组合	select_features_for_xgboost: 最全特征集，将时序转为静态
KAN	表格模型 (Function)	拟合复杂关系	select_features_for_kan: 与XGBoost相同，最全特征集

5. 实施计划与代码改造点

步骤1：创建新的数据加载器

• 文件: server/utils/new_data_loader.py
• 函数: load_new_data(path)
• 任务:
  1. 使用 pandas.read_parquet() 读取数据。
  2. 将 subbh 重命名为 store_id。
  3. 将 hh 重命名为 product_id。
  4. 将 kdrq 转换为 datetime 类型。
  5. 返回处理后的DataFrame。

步骤2：实现特征选择注册表

• 文件: server/utils/feature_selection.py
• 任务:
  1. 为上述六种算法分别创建一个专属的特征选择函数，如 select_features_for_mlstm(all_columns)。每个函数接收所有列名作为输入，返回一个特征列表。
  2. 创建一个字典 FEATURE_SELECTION_REGISTRY，将模型类型字符串映射到对应的选择函数。
  3. 创建一个主调用函数 get_feature_list_for_model(model_type, all_columns)，它会查询注册表并调用正确的函数。

步骤3：重构核心预测器

• 文件: server/core/predictor.py
• 类: PharmacyPredictor
• 方法: train_model
• 任务:
  1. 修改方法签名，移除所有与旧特征工程相关的参数。
  2. 方法内部流程改为： a. 调用 new_data_loader.load_new_data() 加载数据。 b. 调用 feature_selection.get_feature_list_for_model() 获取当前模型专属的特征列表。 c. 将加载的完整DataFrame和获取的特征列表传递给相应的训练器。

步骤4：统一并简化所有训练器

• 文件: server/trainers/*.py
• 任务:
  1. 修改所有训练函数的签名，使其接收一个DataFrame和一张特征列表作为输入。
  2. 移除训练器内部所有的数据加载和特征选择逻辑。
  3. 训练器内部的数据准备部分，将直接使用传入的特征列表从DataFrame中提取 X，并使用 net_sales_quantity 作为 y。
  4. 对于需要3D输入的序列模型，在此处完成从2D到3D的数据塑形。

步骤5：API层适应性修改

• 文件: server/api.py
• 路由: /api/training (POST)
• 任务:
  1. 简化请求体，核心参数为 model_type 和训练目标（如product_id）。
  2. 移除所有与旧特征工程相关的参数传递。

6. 总结

本方案提供了一个清晰、健壮且可扩展的架构。它不仅解决了当前新数据接入的问题，更通过引入“特征选择注册表”机制，为未来添加新模型或优化现有模型特征策略打下了坚实的基础。整个系统将变得更加智能和高效。

开发者指南：算法自适应特征选择系统

1. 概述

本文档旨在为开发者阐述本项目中实现的“算法自适应特征选择系统”的核心设计、工作原理以及如何进行扩展。

在本次重构之前，所有模型都使用一套固定的、硬编码的特征列表。这种“一刀切”的方法无法发挥某些模型（如XGBoost）处理高维数据的优势，也可能为另一些模型（如CNN）引入不必要的噪声。

新的特征选择系统解决了这个问题。其核心思想是：为系统中的每一种算法模型，提供一个专属的、可配置的特征选择策略。

2. 核心模块

所有相关的逻辑都集中在以下一个文件中：

• server/utils/feature_selection.py

这个文件包含了两个核心部分：

1. 特征选择函数: 一系列 select_features_for_[model_name] 格式的函数。
2. 特征选择注册表: 一个名为 FEATURE_SELECTION_REGISTRY 的字典，它将模型名称映射到对应的特征选择函数。

3. 现有模型特征策略详解

系统当前支持以下模型的专属特征策略：

模型名称	对应函数	核心策略
mlstm	select_features_for_mlstm	基础+短期: 提供核心时序指标、日期、生命周期、短期滚动特征和静态上下文特征。
transformer	select_features_for_transformer	基础+多尺度: 在mLSTM基础上，增加中长期滚动特征，让注意力机制筛选。
tcn	select_features_for_tcn	基础+多尺度: 与Transformer策略相同，为卷积网络提供多尺度信息。
cnn_bilstm_attention	select_features_for_hybrid	宏观背景: 提供核心指标和中长期背景特征，让CNN层自行学习短期模式。
xgboost	select_features_for_xgboost	最大化信息: 提供除ID和未来信息外的几乎所有特征，让树模型自行挖掘关系。
kan / optimized_kan	select_features_for_kan	最大化信息: 与XGBoost策略相同，为模型提供最全面的信息。

4. 如何为新模型添加特征策略

为新的算法模型（例如，my_new_model）添加一个专属的特征选择策略非常简单，只需三步：

第一步：创建新的特征选择函数

在 server/utils/feature_selection.py 文件中，仿照现有函数，创建一个新的函数。函数接收一个包含数据源所有列名的列表 all_columns，并返回一个您挑选出的特征列表。

# 在 server/utils/feature_selection.py 中添加

def select_features_for_my_new_model(all_columns):
    """
    为我的新模型挑选特征。
    策略: [在这里写下您的策略描述]
    """
    my_feature_list = [
        'net_sales_quantity', # 目标本身作为特征
        'is_holiday',         # 一个日期特征
        'brand_encoded'       # 一个商品静态特征
        # ... 在这里添加您选择的所有特征
    ]
    
    # 确保返回的特征在数据源中真实存在
    return [col for col in my_feature_list if col in all_columns]

第二步：注册您的新函数

在同一个文件的底部，找到 FEATURE_SELECTION_REGISTRY 字典，将您的新模型名称和您刚刚创建的函数关联起来。

# 在 server/utils/feature_selection.py 中修改

FEATURE_SELECTION_REGISTRY = {
    'mlstm': select_features_for_mlstm,
    'transformer': select_features_for_transformer,
    'tcn': select_features_for_tcn,
    'xgboost': select_features_for_xgboost,
    'kan': select_features_for_kan,
    'cnn_bilstm_attention': select_features_for_hybrid,
    'optimized_kan': select_features_for_kan,
    
    # --- 在这里添加您的新模型 ---
    'my_new_model': select_features_for_my_new_model
}

第三步：完成！

就这样！现在，当您通过API请求训练一个类型为 my_new_model 的模型时，系统会自动调用 select_features_for_my_new_model 函数，并将返回的特征列表传递给训练器。

5. 数据管道流程概览

为了加深理解，这里是整个流程的简要概览：

1. API请求: 用户请求训练一个特定类型的模型（e.g., model_type: "transformer"）。
2. 核心预测器 (predictor.py):
   • 加载完整的数据集。
   • 调用 get_feature_list_for_model("transformer", all_columns)。
3. 特征选择器 (feature_selection.py):
   • get_feature_list_for_model 在注册表中查找 "transformer"。
   • 找到并调用 select_features_for_transformer() 函数。
   • 该函数返回一个为Transformer量身定制的特征列表。
4. 核心预测器 (predictor.py):
   • 接收到特征列表。
   • 将完整的数据集和定制的特征列表一同传递给 transformer_trainer.py。
5. 训练器 (transformer_trainer.py):
   • 使用传入的特征列表从数据集中提取出 X 和 y。
   • 开始后续的标准化数据准备和模型训练。

这个设计将特征工程的“策略”部分与模型训练的“执行”部分完全解耦，使系统更加灵活和可维护。