feat(#34): Model Recipe 插件接口与样例协议（PRD 5.3 模型框架配置化/网络结构策略）

2026-08-04 23:03:01 +08:00
parent 4e9d0e60c9
commit 9c07d19f63
6 changed files with 1144 additions and 0 deletions
@@ -0,0 +1,107 @@
+# iAOP-Core · model_framework（③ AI 模型框架 · 配置化重构）
+
+本目录承载 EPIC #5「③ AI 模型框架 配置化重构」（PRD 5.3）的内核模块。PRD 5.3
+要求把"写死在树脂场景"的 4 类模型重构为**可配置模板**，由超参包驱动，核心诉求：
+
+> **固定主干网络 + 可配置超参**为默认；同时提供 **Model Recipe 注册表**，允许
+> 高级行业模板通过声明式 recipe 选择不同网络结构（LSTM 用于时序、GNN 用于跨工序），
+> **新增结构走插件注册而非改内核**。
+
+## 模块一览
+
+| 文件 | Issue | 职责 |
+|------|-------|------|
+| `model_recipe.py` | **#34** | Model Recipe 插件接口与样例协议（**结构层**插件注册表） |
+| `feature_spec.py` | #35（并行 PR） | FeatureSpec 声明式特征定义引擎（**特征层**插件注册表） |
+
+> 注：`feature_spec.py`（#35）与 `model_recipe.py`（#34）是 EPIC #5 下两个并行
+> 子任务，各自独立但理念呼应——#35 在**特征算子**层提供 `register_operator`
+> 插件注册，#34 在**模型结构**层提供 `register_recipe`/`register_backbone`
+> 插件注册，共同构成「特征层 + 结构层」两级插件体系。两个 PR 合入后本 README
+> 会整合两段说明。
+
+---
+
+## `model_recipe.py` — Model Recipe 插件接口（issue #34）
+
+对应 PRD 5.3「网络结构策略 / 模板化技术路径」与 EPIC #5 验收口径：**同一框架
+加载树脂与 Ti 两套 Recipe 均能跑通——切换模板仅改 Recipe，模型代码零改动**。
+
+### 设计要点
+
+* **声明式 Recipe**：`ModelRecipe` 是不可变数据对象（dataclass frozen），描述
+  「用什么网络主干 + 默认超参 + 必需特征」。`to_dict`/`from_dict` 可序列化往返，
+  便于配置台（#62~#67）展示与审计。
+* **两级插件注册**：
+  * `register_backbone(name, factory)` —— 注册网络主干工厂（结构层扩展点）；
+  * `register_recipe(ModelRecipe(...))` —— 注册声明式 Recipe（业务层扩展点）。
+  * 高级行业模板（如自研 GNN）只需 `register_backbone` + `register_recipe` 即可
+    接入内核，**零改码**（对齐 PRD「新增结构走插件注册」）。
+* **统一模型句柄**：所有主干工厂返回 `ModelHandle`（`fit`/`predict`/`to_dict`），
+  使训练/推理流水线（#40）与配置台只面向同一接口编程。
+* **零外部强依赖**：无 sklearn/torch 时，`gbdt`/`dnn`/`lstm`/`gnn` 主干自动
+  退化为纯 Python `stub`（均值预测），保证边缘/离线/CI 环境可加载、注册、构造、
+  （伪）拟合与推理。有 sklearn 时 `gbdt`/`dnn` 自动升级为真实实现。
+* **fail-closed**：未 `fit` 的模型 `predict` 直接抛错，绝不静默返回垃圾值。
+
+### 内置主干（覆盖 PRD 5.3 四类模型模板全部默认结构）
+
+| 主干 | 工厂 | 说明 | 有第三方依赖时 |
+|------|------|------|----------------|
+| `gbdt` | `gbdt_backbone` | 梯度提升回归（质量预测默认） | sklearn `GradientBoostingRegressor` |
+| `dnn` | `dnn_backbone` | 轻量 DNN（异常检测默认） | sklearn `MLPRegressor` |
+| `lstm` | `lstm_backbone` | LSTM 时序（高级模板可选） | 退化为 stub，插件注入真实实现 |
+| `gnn` | `gnn_backbone` | GNN 跨工序（高级模板可选） | 退化为 stub，插件注入真实实现 |
+| `stub` | `stub_backbone` | 纯 Python 均值预测（兜底） | — |
+
+### 内置四类 Recipe（与 PRD 5.3 四类模型模板 1:1 映射）
+
+```
+quality_predict.default    ① 质量预测      backbone=gbdt
+process_optimize.default   ② 工艺优化      backbone=gbdt
+anomaly_detect.default     ③ 异常检测      backbone=dnn
+cross_process.default      ④ 跨工序寻优    backbone=gnn
+```
+
+### 使用
+
+```python
+from model_framework.model_recipe import (
+    build_model, register_recipe, register_backbone, ModelRecipe,
+    validate_hyperparam_pack, load_sample_recipe,
+)
+
+# 1) 用内置 Recipe 构造模型并训练
+m = build_model("quality_predict.default", {"max_depth": 6, "n_estimators": 300})
+m.fit(X_train, y_train)
+pred = m.predict(X_test)
+
+# 2) 插件扩展：自研 GNN 主干，零改码接入
+register_backbone("my-gnn", lambda hp: MyGnnImpl(**hp))
+register_recipe(ModelRecipe(
+    id="cross_process.my_gnn", kind="cross_process", backbone="my-gnn",
+    default_hyperparams={"hidden": 128}, description="自研 GNN",
+))
+m2 = build_model("cross_process.my_gnn")
+
+# 3) 超参包校验（Recipe 视角，与 #39 的 spec 校验互补）
+pack = load_sample_recipe("ti")
+issues = validate_hyperparam_pack(pack)   # [] = 通过
+```
+
+### 样例协议（EPIC #5 验收口径）
+
+`SAMPLE_RECIPES` 内置 `resin`（树脂）与 `ti`（氯化车间/海绵钛）两套超参包样例，
+两者共用同一个 `recipe_id=quality_predict.default`，仅超参不同——直接验证
+「同一框架加载两套 Recipe 均能 build/fit/predict，切换模板仅改超参包，模型代码
+零改动」。
+
+## 测试
+
+```bash
+cd core/model-framework/tests
+python -m unittest test_model_recipe            # 30 个用例
+
+cd core/model-framework
+python _sanity_check.py                          # 端到端 sanity
+```