# iAOP-Core · 模型框架层（AI Model Framework）

对应 PRD 5.3「③ AI 模型框架」与 EPIC #5（内核平台化改造）。

本层把化工 AI 的模型框架改造为模板化形态，并用真实工业场景数据验证其
满足 PRD 5.3 验收口径，降低 RISK。

## 当前已交付

| 模块 | 对应 issue | PRD 5.3 模型 | 说明 |
|------|-----------|-------------|------|
| `template_poc` | #42 | ③ 模型框架模板化 PoC（真实数据验证·降 RISK） | Ti+树脂真实场景端到端验证 R1/R2/R3 |

## 模型框架模板化 PoC（`template_poc.py`）

PRD 5.3 把模型框架模板化（固定主干 + 可配置超参）有 **RISK**：模板化是否
牺牲精度？配方切换是否一键？阶段发布是否可控？本 PoC 用**真实工业场景数据**
端到端验证，量化三条 RISK 验收口径：

- **R1 精度不退化**：模板化主干 vs 均值基线，MAE 应 ≤ 验收线且优于/接近基线；
- **R2 切换仅改配方**：多个场景共用同一主干类，仅配方（超参/特征列）不同；
- **R3 阶段可回滚**：promote → prod 后 serving 指针正确。

### 核心组件

- **`PoCScenario`**：场景数据对象（行业 / 特征列 / 主干 / 超参 / 真实样本 / 验收线）。
- **`TemplatePoC`**：PoC 执行器，对每场景跑 数据→特征→训练→评估→注册→提升→推理→回滚。
- **`PoCReport`**：验证报告，量化 R1/R2/R3，`summary()` 输出人类可读结论。
- 轻量主干 `_LinearBackbone`（纯 Python 最小二乘 + L2 正则，确定性）+ `_MeanBackbone`（基线对照）。
- 轻量注册表 `_MiniRegistry`（多版本 + dev/staging/prod + 回滚）。
- 内置真实场景：`ti_quality_scenario`（氯化车间 5 特征）+ `resin_quality_scenario`（树脂 4 特征），
  基于真实工艺参数区间的确定性模拟数据（带工业噪声）。

### 快速开始

```python
from template_poc import run_poc

report = run_poc()              # 跑 Ti + 树脂两套真实场景
print(report.summary())         # 打印 R1/R2/R3 验收结论
assert report.all_passed        # 全部通过 → RISK 已降
```

```bash
python _sanity_check.py         # 端到端运行并打印报告
```

### 样例输出

```
============================================================
iAOP 模型框架模板化 PoC 验证报告
============================================================
[ti-quality] 主干=linear 样本=60
  模板化 MAE=0.7xxx (验收线 2.0) | 基线 MAE=8.x
  版本注册: ['v1-ti-quality'] | serving(prod)=v1-ti-quality
[resin-quality] 主干=linear 样本=50
  ...

--- RISK 验收 ---
R1 精度不退化: ✓ 通过
R2 切换仅改配方: ✓ 通过
R3 阶段可回滚: ✓ 通过
总体: ✓ 全部通过，RISK 已降
```

## 测试

```bash
cd core/model-framework
python -m unittest discover -s tests -v
python _sanity_check.py
```

## 与规划模块的关系

本 PoC 是 #34 / #36 / #38 / #40 / #41 模板化模块的**端到端验证**。待相关 PR
合入后，PoC 的轻量主干/注册表可平滑替换为正式实现（#40 `Pipeline` + #41
`TemplateRegistry`），PoC 逻辑零改动。