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

使用

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

5.1 KiB Raw Blame History Unescape Escape