Classification Model Recommend

历史模型推荐

给业务人员从历史营销模型列表中找到可复用模型,支持可选的样本上评估(委托 classification-model-evaluation 产三档标准化三件套)。

1. 输入依赖

2. 执行命令

<skill_dir> 指本 skill 所在目录(即本文件所在目录),执行时替换为实际绝对路径,不要依赖当前工作目录。

模型推荐(工作流程 Step 2-3):无独立召回脚本。Claude 直接读 model-knowledge/assets/historical-model-knowledge/model_catalog.csv(14 列 CSV)作为候选池,按解析出的 business/segment/keyword 语义筛选 + 排序,默认 Top3。台账规模建议 ≤ 数百行;超出时由调用方先按业务线等维度自行切片。

评估委托(工作流程 Step 6,用户选择评估时;单条 entry,wrapper 内部 4 步: fetch → get → split → eval):

bashCopy code
python <skill_dir>/scripts/fetch_eval_sample.py \
  --session-dir <session_dir> \
  --model-id <model_id> \
  --sample-table <db>.<sample_table> \
  --score-table <db>.<score_table> \
  --join-keys user_no,pday \
  --fetch-start <YYYYMMDD> --fetch-end <YYYYMMDD> \
  --train-range <YYYYMMDD>,<YYYYMMDD> \
  --test-range  <YYYYMMDD>,<YYYYMMDD> \
  --oot-range   <YYYYMMDD>,<YYYYMMDD> \
  --score-col score --label-col label
# 加 --submit 同步执行 wrapper; 加 --no-eval 仅产 predictions 跳过评估

fetch_eval_sample.py 内部生成的 fetch_eval_{model_id}.sh 4 步:

1. STEP1 spark-submit 调 shared fetch_spark.py,样本表⋈模型表 LEFT JOIN,写 HDFS sample.parquet
2. STEP2 hdfs dfs -get 拉本地 predictions/sample.parquet
3. STEP3 本地 split_sample.py 按 pday 区间切 train/test/oot 三档
4. STEP4 invoke_evaluation.py 委托 classification-model-evaluation/scripts/eval_single.py 产三件套

3. 参数说明

3.1 完整工作流程

3.1.1 解析自由描述(Step 1)

从业务人员的一段话里抽取:

• business(业务线,与台账 业务线 列取值对齐;未提到则不限)
• segment(训练客群,与台账 训练客群 列对齐;未提到则不限)
• keyword(用途/场景关键词,可多个)

抽取后回显解析出的条件给用户确认。条件缺失不要臆造,留空即可(留空=该维度不限)。

客群口径:模型列表 训练客群 字段是自由文本,Claude 在语义匹配时综合处理:状态口径(细分状态)、全量口径(含"全量/全客群/全部"等视为不限客群)、自由文本(语义近似匹配)。无需额外规则配置。

3.1.2 语义筛选与排序(Step 2-3)

直接读 model-knowledge/assets/historical-model-knowledge/model_catalog.csv 作为候选池。先按 状态=可用 过滤(用户要求含不可用模型时放宽),再结合以下因素给出最终排序(模型列表无 KS/AUC/PSI 指标列,故主要靠语义与时效):

• 语义相关性:候选的 模型中文名、预测目标、正样本定义、训练客群 与用户真实意图的贴合度
• 时效:训练时间窗 越近越好(注意区分 train 与 oot 区间)
• 可用性:状态=可用 优先;非可用需明确告知

3.1.3 展示推荐详情(Step 4,强制)

必须向用户展示推荐结果,默认 Top3(不足则按实际)。每个模型完整展示 14 个字段(排名+适配度 / model_id / 模型中文名 / 预测目标 / 正样本定义 / 算法类型 / 训练客群 / 训练时间窗 / 模型表 / 状态 / 负责人 / 推荐理由 / 历史指标 / 可复用点),展示原则、落盘规则、降级处理、报告指标提取(含 data_profile.data_splits[] 性能表与 performance.score_buckets[] 分档表)详见 references/recommendation-details.md。不允许只输出 model_id 列表。

3.1.4 询问是否在样本上评估(Step 5,强制)

推荐展示完成后,必须主动询问用户是否在当前样本上评估推荐模型的表现,不能跳过、不能默认不评估。

询问话术(示例):

Copy code
> 推荐已完成,Top1 是 `<model_id>`(高适配度)。
>
> 是否需要基于当前任务样本(50,000 条,5 个 pday)在样本上评估 `<model_id>` 的实际表现?
> - 评估 → 按 Train/Test/OOT 三档切分,分别计算 KS/AUC/分档分布,产出三份报告
> - 跳过 → 直接进入下一步(feature-matching 拉训练特征宽表)

用户选择"评估":走「Step 6 生成评估脚本并提交」;评估脚本调用 fetch_eval_sample.py(取数+切分+委托评估一条龙),一次作业产三档标准化三件套。

用户选择"跳过":不生成评估脚本,直接进入下游 feature-matching;在 _manifest.json 中标注 eval_performed: false。

3.1.5 生成评估脚本并提交(Step 6,当用户选择评估时)

输入信息传递:

• 样本表: task-spec/_manifest.json 中的 source_table(含 label + 关联键)
• 模型表: 推荐结果 Top1 的 model_table(提供 score)
• 关联键: 默认 [user_no, pday],两表同名(否则需建视图别名)
• 切分区间: 复用 data-profile/_manifest.json 中的 split_ranges
• 分数字段: 默认 score,可在 CLI --score-col 覆盖
• 标签字段: 默认 label,可在 CLI --label-col 覆盖

配置文件:<session_dir>/model-recommend/{model_id}/eval_config.yaml(由 fetch_eval_sample.py 自动落盘)。完整模板见 references/recommendation-details.md 第 2 节。

评估完成后:

• 读取三份 JSON,向用户展示 Train/Test/OOT 的 AUC/KS/标签率汇总表 + 分档分布摘要
• 将评估结果摘要追加到 <session_dir>/report.md 的"三、历史模型推荐"段
• 在 <session_dir>/model-recommend/{model_id}/_manifest.json 中记录 eval_performed: true + 三档指标
• 若发现模型在 OOT 上明显衰减(AUC 跌幅 > 0.03),提示用户注意

3.2 fetch_eval_sample.py(评估 entry:取数+切分+委托评估一条龙)

详见 references/script-parameters.md 第 2 节。关键参数:--session-dir / --model-id / --sample-table / --score-table / 三档 *-range / --score-lag-day(t-1 滞后 JOIN)。

3.3 split_sample.py(本地三档切分)

详见 references/script-parameters.md 第 2 节。支持比例模式(--ratios)与显式区间模式(--train-range/--test-range/--oot-range)。

3.4 invoke_evaluation.py(评估委托)

详见 references/script-parameters.md 第 3 节。三档 parquet 转 CSV 落临时目录,调 eval_single.py 目录模式一次产 4 份三件套(train/test/oot/all)。

4. 输出产物

标准输出目录(遵循 CLAUDE.md session 约定,按推荐模型 ID 分子目录):

textCopy code
<session_dir>/model-recommend/{model_id}/
├── recommendations_<HHMM>.md          # 推荐摘要(markdown, 人工复盘)
├── _manifest.json                     # 结构化推荐结果 + eval_performed 标记 + 三档指标
├── eval_config.yaml                   # 评估配置(自动落盘, 仅评估时)
├── fetch_eval_{model_id}.sh           # 生成的 4 步 wrapper(仅评估时)
├── predictions/
│   ├── sample.parquet                 # 样本表⋈模型表 JOIN 结果
│   ├── train.parquet / test.parquet / oot.parquet
│   └── _split_manifest.json
└── evaluation/
    ├── {model_id}_{train,test,oot,all}_eval.{json,md,xlsx}   # 三档 + all 合并, 共 4 份标准化三件套
    └── _manifest.json                 # 评估元信息

4.1 产物内容

4.2 评估口径

• 评估逻辑委托 classification-model-evaluation skill: 评估阶段调 classification-model-evaluation/scripts/eval_single.py 产出标准化三件套(JSON+MD+XLSX)
• 效果指标: KS / AUC / 准确率 / 精确率 / 召回率 / F1(由 eval_single.py 内置)
• 分档: 默认 10 档等频,含占比 / 正样本率 / lift(由 eval_single.py 内置)
• 三档切分: 复用 task-spec 切分区间, Train / Test / OOT 分别评估, 便于观察 OOT 衰减
• 能力边界: split 间 PSI(如 test vs train 分数分布 PSI)不在本 skill 产出范围内;如需 split 间 PSI 或多版本对比, 调 classification-model-comparison skill
• 若用户未提供切分区间,降级为整体评估(单份 {model_id}_eval.{json,md,xlsx})

5. 与其他 skill 的关联

6. 执行约束

覆盖范围、职责边界、评估委托边界、PSI 能力边界、三档切分与取数、数据资产边界、模型报告规范、异常处理全表详见 references/constraints-and-exceptions.md。

7. 异常处理

异常分类与处理方式详见 references/constraints-and-exceptions.md 第 13 节。

8. 模型列表与工具说明

模型台账字段、模型报告规范、工具清单、安全约束详见 references/model-catalog-spec.md。台账文件:model-knowledge/assets/historical-model-knowledge/model_catalog.csv;报告目录:model-knowledge/assets/historical-model-knowledge/reports/。

数据来源:模型台账 model-knowledge/assets/historical-model-knowledge/model_catalog.csv;历史报告 model-knowledge/assets/historical-model-knowledge/reports/;session 产物落 ${session_dir}/model-recommend/{model_id}/。 最后更新:2026-07-07