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

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

本层把化工 AI 的模型框架改造为**模板化形态**：固定主干网络 + 可配置超参；
Model Recipe 插件注册；FeatureSpec 声明式特征；所有可变量外置为 **JSON
超参包**，同一框架切换行业模板仅改此包（零改码）。

## 模块清单（EPIC #5 子任务，全部合入）

| 模块 | 对应 issue | PRD 5.3 模型 | 说明 |
|------|-----------|-------------|------|
| `model_recipe` | #34 | ③ Model Recipe 插件接口与样例协议 | 配方（Recipe）不可变对象、主干工厂注册表、样例协议、超参包校验 |
| `feature_spec` | #35 | ③ FeatureSpec 声明式特征定义引擎 | 特征 DSL 解析（窗口/算子/引用）、校验/物化/算子注册 |
| `quality_forecast` | #36 | ③ ①质量预测模板化（固定主干+配方加载） | gbdt/dnn 主干 + 配方，Accuracy ≥ 90% 验收 |
| `anomaly_detection` | #37 | ③ ③异常检测模板化 | iforest/lof 主干 + 配方（阈值策略/召回/误报验收） |
| `cross_process_optimizer` | #38 | ③ 跨工序寻优模板化 | 决策变量/目标/约束声明式规格 + 求解器注册（grid/analytic/random） |
| `hyperparam` | #39 | ③ 超参包 JSON Schema 校验器 | 超参包加载 + 逐条校验报告 |
| `pipeline` | #40 | ③ 训练/推理流水线编排 | 声明式配置驱动 Step/Estimator 编排，训练/评估/预测 |
| `template_registry` | #41 | ③ 模型模板注册/加载/版本机制 | 多版本 + dev/staging/prod 阶段 + 提升/回滚 + 审计 |
| `template_poc` | #42 | ③ 模型框架模板化 PoC（真实数据验证·降 RISK） | Ti+树脂真实场景端到端验证 R1/R2/R3 |

## 命名空间约定

各模型模块（quality_forecast / anomaly_detection / cross_process_optimizer /
template_registry / template_poc）为**独立命名空间**，经
`from . import ...` 挂载到 `model_framework`，避免同名符号
（`Recipe` / `BACKBONES` / `Stage` 等）互相覆盖：

```python
from model_framework.quality_forecast import Recipe          # 质量预测配方
from model_framework.anomaly_detection import Recipe         # 异常检测配方
from model_framework.template_registry import Stage          # 模板阶段
```

顶层 `model_framework` 仅 re-export 无冲突符号（hyperparam / feature_spec /
model_recipe）。零外部强依赖：无 numpy/sklearn 时各模块退化到 stub 实现仍可加载与校验。

## 快速开始

```bash
# 全部单测（core/model-framework 目录下）
python -m unittest discover -s tests -v

# 资产冒烟校验（模块可导入 + 顶层符号 + 样例配方 + PoC R1/R2/R3）
python _sanity_check.py
```

超参包 JSON 结构见 PRD 5.3「超参包 JSON 完整示例」与 `samples/` 下
（quality-forecast / anomaly-detection / cross-process-opt 各含 Ti 与树脂两套配方）。