model-training-config

⚙️ 本技能遵循公共运行环境契约（最高优先级，先于本文其余内容执行）： 详见 _shared/env-contract.md，执行前先读它。

模型训练配置生成器（QuantMind）

把「用户想要什么模型」翻译成前端模型训练页可以一键导入的配置文件。 本技能不调用训练 API（纯文件生成 + 本地/容器内校验）；生成物交给用户在前端点导入。

• 事实源（若可读源码）：electron/src/pages/training/trainingUtils.tsx、 electron/src/pages/training/__tests__/trainingConfigFile.test.ts
• 字段全表：references/schema.md
• 因子家族与选因子：references/factor-families.md
• 可直接导入的演示：templates/

0. 交付物与导入方式

• 交付一个 .yml 文件（内容可为 YAML，也可为 JSON —— 导入用的 js-yaml 认 JSON）。 文件名建议 模型训练配置_<名称>_<YYYYMMDD>.yml。
• 前端导入路径：模型训练页 → 右上角「导入配置」→ 选择文件 → 预览 → 确认。 文件选择器只接受 .yml / .yaml / .txt，不要用 .json 扩展名。
• 导入会整体覆盖当前表单；市场/因子源会自动切换（见 §4）。

1. 文件骨架（照抄结构，再改值）

schema_version: 1                                  # 固定 1
kind: quantmind-model-training-config              # 固定值
exported_at: "2026-09-22T00:00:00.000Z"            # 元数据
market: CN                                         # CN|HK|US|CRYPTO|FUTURES
factor_source: l1_l2_factors                       # 可选：QuantDB 直读源
factor_catalog_version: qdb-cn-l1_l2_factors-xxxx  # 可选：仅作版本提示
factor_filter:
  enabled: true
  n_top: 80
  ic_threshold: 0.01
  icir_threshold: 0.15
  correlation_threshold: 0.9
configuration:
  displayName: MY_MODEL_T5
  displayNameMode: manual                          # auto|manual
  selectedFeatures: [mom_ret_20d, vol_std_20, ...] # 非空、去重、禁止标签字段
  timePeriods:
    train: ["2018-01-02", "2023-06-18"]
    val:   ["2023-06-26", "2025-01-21"]
    test:  ["2025-01-28", "2026-08-28"]
  target: { mode: return, horizonDays: 5 }
  params:
    model_type: lightgbm                           # 13 选 1
    # …见 references/schema.md 的白名单键
  context:
    initialCapital: 1000000
    benchmark: SH000300                            # CN=SH000300 HK=HSI US=SPX CRYPTO=BTC FUTURES=CL.FUT
    commissionRate: 0.00025
    slippage: 0.0005
    dealPrice: open                                # open|close
    market: CN
    industry_as_feature: false
  wfa: { enabled: false, strategy: rolling, nWindows: 4, trainYears: 3, valMonths: 12, stepMonths: 12 }

2. 生成工作流（按序执行）

1. 收集需求：市场？预测周期 T+N？模型类型？偏因子方向（动量/微观结构/基本面…）？ 训练/验证/测试时间范围？股票池？若用户没说，用 §3 的默认值并在交付时说明所选默认。
2. 定市场与因子源：CN/HK/US/FUTURES/CRYPTO 是 QuantDB 直读市场。 要 L2 微观特征就 l1_l2_factors；只要日频用 l1_factors；纯高频用 l2_factors。
3. 选因子：按 references/factor-families.md 的 recipe 挑 40~120 个，家族均衡；优先用其中列出的 key（已在本地目录验证）。
4. 定时间切分：三段都要，且 train_end < val_start、val_end < test_start； 间隔 ≥ horizonDays + 1 天，否则后端会把 val/test 起点悄悄后移。
5. 定模型与超参：树模型给 learning_rate/num_leaves/max_depth/...；DL 给 dl_*。 多模型 Stacking 才写 model_types（≥2）+ ensemble_method: stacking。
6. 组装：按 §1 骨架填值，context.market 与顶层 market 保持一致。
7. 自检（必做）：跑 §6 的校验脚本，error 清零、warning 逐条确认后再交付。
8. 交付：把文件给用户，并附「导入后要检查什么」（§4）。

3. 常用默认值（用户未指定时）

项	默认
时间切分（T+5）	train 2018-01-02~2023-06-18 / val 2023-06-26~2025-01-21 / test 2025-01-28~2026-08-28
时间切分（T+3）	同上，但 val 起 2023-06-23、test 起 2025-01-26（满足 gap≥4）
factor_filter	enabled:true, n_top:80, ic:0.01, icir:0.15, corr:0.9
LightGBM 稳健档	lr 0.01 / num_leaves 15 / max_depth 6 / min_data 500 / l1 2 / l2 5 / ff 0.5 / bag 0.7 / rounds 3000 / es 100
基准	CN SH000300、HK HSI、US SPX、CRYPTO BTC、FUTURES CL.FUT

4. 导入后前端会做什么（务必转告用户）

1. 校验通过后弹预览：会标出「当前目录缺失的特征 / 市场变化 / 目录版本变化」。
2. 确认后整体覆盖表单；不在当前因子目录里的特征会被丢弃。
3. factor_catalog_version 只是提示，实际训练用页面当前已发布版本，不是回放旧版本。
4. QuantDB 直读市场还需满足「目录已发布 + 数据覆盖就绪 + 训练节点就绪」，否则「开始训练」按钮不可用。
5. 若日期间隔不足 horizon+1，后端会自动平移 val/test 起点并在 system_notices 提示。

5. 演示配置（可直接导入）

文件	场景
templates/cn-l1l2-t5-lightgbm.yml	CN / L1L2 / T+5 / LightGBM 稳健档（推荐起手）
templates/cn-l1l2-t3-lightgbm.yml	CN / L1L2 / T+3 / LightGBM 基线（与上一份同特征，做周期对照）
templates/cn-l1l2-t5-gru.yml	CN / L1L2 / T+5 / GRU 深度学习
templates/hk-t5-lightgbm.yml	HK / T+5 / LightGBM 跨市场
templates/quantmind-training-L1L2-ICIR-100-T5.yml	CN / ICIR 优选 100 特征 / T+5 / LGB 重正则（大 preset）

改这些文件比重头写更稳：它们已通过校验脚本、且特征 key 全部存在于本地目录。 仓库根目录另有两个规模更大的成品 preset（quantmind-training-L1L2-120-*.yml）可作参考。

6. 校验脚本（交付前必跑）

纯标准库优先（JSON 可无需依赖；YAML 需 PyYAML）：

# 本地直接跑（本机有 PyYAML 时）
python3 skills/model-training-config/scripts/validate_training_config.py <你的配置.yml>

# 无 PyYAML 时进容器跑（env-contract §2）
docker cp <你的配置.yml> quantmind:/tmp/cfg.yml
docker cp skills/model-training-config/scripts/validate_training_config.py quantmind:/tmp/
docker exec -w /app quantmind python3 /tmp/validate_training_config.py /tmp/cfg.yml

脚本检查：kind/schema_version、市场、日期顺序、horizon+1 间隔、模型类型白名单、 params 未知键、factor_filter 钳制区间、标签字段混入、factor_source 与直读市场一致性。 退出码 0=通过（可含 warning）、1=有 error。error 必须清零；warning 要逐条判断是否符合预期。

7. 相关技能

• [[model-train-infer-backtest-report]] — 提交训练/推理/回测/出报告（本技能只负责「生成可导入的配置」）。
• [[quantmind-operations]] — 平台运营总指南（训练 5 步流程、模型管理）。
• [[quantdb-fields]] — 字段单位与口径速查（选因子前必读）。
• [[quantdb-data-structure]] — QuantDB 目录/分区/代码格式。

8. 常见问题

现象	处理
导入报「不是受支持的 QuantMind 模型训练配置文件」	kind / schema_version 写错
导入报「训练、验证、测试时间段必须按先后顺序」	改成 train_end < val_start、val_end < test_start
导入报「配置中的模型类型不受支持」	model_type 不在 13 种里
导入后特征少了很多	不在当前目录的 key 被过滤；对照预览提示换用存在的 key
超参没生效	用了非白名单键（如 lgb_learning_rate），被静默丢弃；改用共享键
训练时 val/test 起点和配置不一致	间隔 < horizon+1，后端自动平移
Start 按钮灰着	直读市场目录未发布/覆盖未就绪，或训练节点未就绪
文件选择器看不到文件	扩展名不是 .yml/.yaml/.txt