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主干自动 退化为纯 Pythonstub（均值预测），保证边缘/离线/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
使用
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，切换模板仅改超参包，模型代码
零改动」。
测试
cd core/model-framework/tests
python -m unittest test_model_recipe # 30 个用例
cd core/model-framework
python _sanity_check.py # 端到端 sanity