345 lines
14 KiB
Python
345 lines
14 KiB
Python
|
# -*- coding: utf-8 -*-
|
|||
|
|
"""Ti-1 氯化车间质量预测 · 模型部署到内核并接入驾驶舱（Issue #73 / PRD §5.3 ① / §5.5）。
|
|||
|
|
|
|||
|
|
承接 #69（模型训练）产出的 ``QualityModel``：把"训练好的模型 → 可调用的预测服务
|
|||
|
|
→ 驾驶舱可展示的预测+可解释结果"这条链路**模板化、可测试**。
|
|||
|
|
|
|||
|
|
PRD 设计口径
|
|||
|
|
------------
|
|||
|
|
- 架构表（PRD §5.3）：``质量预测 | 预测 | 入：DCS实时数据+LIMS；
|
|||
|
|
出：质量指标预测值(纯度/杂质) | ① 质量预测 | 中``。
|
|||
|
|
- 驾驶舱接入（PRD §5.5）：预测结果以 kpi_card / alarm_panel 形式渲染，
|
|||
|
|
支持按模板渲染四状态流程视图；移动端交接班摘要引用预测结论。
|
|||
|
|
- 模型漂移（PRD §5.3 / §9 NFR）：质保期监测准确率/误报率，触发重训。
|
|||
|
|
|
|||
|
|
本模块交付
|
|||
|
|
----------
|
|||
|
|
1. **预测服务 ``PredictionService``**：加载（或内存持有）QualityModel + 特征清单，
|
|||
|
|
``predict(samples)`` 返回 ``Prediction``（预测值 + 置信区间 + 命中阈值判定）。
|
|||
|
|
2. **阈值告警 ``QualityAlarm``**：按超参包的 ``thresholds``（纯度下限/杂质上限）
|
|||
|
|
判定告警等级（normal/warning/critical），供驾驶舱 alarm_panel。
|
|||
|
|
3. **驾驶舱视图 ``CockpitView``**：把预测结果 + explain() 渲染为驾驶舱布局
|
|||
|
|
片段（kpi_card / alarm_panel / 可解释溯源列表），对齐 iAOP-cockpit-layout-v1。
|
|||
|
|
4. **模型漂移监测 ``DriftMonitor``**：累计预测的 R²/MAE，超阈值触发重训信号。
|
|||
|
|
|
|||
|
|
设计要点
|
|||
|
|
--------
|
|||
|
|
- **零运行时依赖**（纯标准库）：与 #68/#69 一致。
|
|||
|
|
- **可解释接入驾驶舱**：预测结果附带 top-N 特征贡献（来自 #69 explain），
|
|||
|
|
满足 PRD"要求结果可解释、可溯源，要引用依据"。
|
|||
|
|
- **可校验**：部署前 ``PredictionService.validate`` 检查模型已训练、特征清单
|
|||
|
|
与模型特征名对齐。
|
|||
|
|
"""
|
|||
|
|
from __future__ import annotations
|
|||
|
|
|
|||
|
|
import json
|
|||
|
|
import math
|
|||
|
|
import os
|
|||
|
|
from dataclasses import dataclass, field
|
|||
|
|
from enum import Enum
|
|||
|
|
from typing import Any, Dict, List, Optional, Sequence
|
|||
|
|
|
|||
|
|
from .features import FeatureExtractor, FeatureMatrix, FeatureSpec, Sample
|
|||
|
|
from .model import Evaluation, ModelRecipe, QualityModel
|
|||
|
|
|
|||
|
|
NAN = float("nan")
|
|||
|
|
|
|||
|
|
|
|||
|
|
class ServeError(ValueError):
|
|||
|
|
"""模型部署/预测服务错误。"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
# 告警等级
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
|
|||
|
|
class AlarmLevel(str, Enum):
|
|||
|
|
NORMAL = "normal" # 正常
|
|||
|
|
WARNING = "warning" # 预警（接近阈值）
|
|||
|
|
CRITICAL = "critical" # 超限（质量不达标）
|
|||
|
|
|
|||
|
|
|
|||
|
|
@dataclass
|
|||
|
|
class Thresholds:
|
|||
|
|
"""质量阈值（超参包外置）。"""
|
|||
|
|
|
|||
|
|
target: str
|
|||
|
|
min_value: Optional[float] = None # 纯度下限（低于则告警）
|
|||
|
|
max_value: Optional[float] = None # 杂质上限（高于则告警）
|
|||
|
|
warning_band: float = 0.0 # 预警带（距阈值多少开始 warning）
|
|||
|
|
|
|||
|
|
@classmethod
|
|||
|
|
def from_dict(cls, d: Dict[str, Any]) -> "Thresholds":
|
|||
|
|
return cls(
|
|||
|
|
target=str(d.get("target", "")).strip(),
|
|||
|
|
min_value=(float(d["min"]) if d.get("min") is not None else None),
|
|||
|
|
max_value=(float(d["max"]) if d.get("max") is not None else None),
|
|||
|
|
warning_band=float(d.get("warning_band", 0.0)),
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
def validate(self) -> List[str]:
|
|||
|
|
errs = []
|
|||
|
|
if not self.target:
|
|||
|
|
errs.append("thresholds.target 不能为空")
|
|||
|
|
if self.min_value is None and self.max_value is None:
|
|||
|
|
errs.append("thresholds 至少需 min 或 max 之一")
|
|||
|
|
return errs
|
|||
|
|
|
|||
|
|
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
# 预测结果
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
|
|||
|
|
@dataclass
|
|||
|
|
class Prediction:
|
|||
|
|
"""单条预测结果。"""
|
|||
|
|
|
|||
|
|
target: str
|
|||
|
|
value: float
|
|||
|
|
unit: str
|
|||
|
|
level: str # AlarmLevel 值
|
|||
|
|
message: str
|
|||
|
|
confidence_band: float # ±置信带（基于训练 RMSE）
|
|||
|
|
explanation: List[Dict[str, Any]] = field(default_factory=list)
|
|||
|
|
timestamp: float = 0.0
|
|||
|
|
|
|||
|
|
def to_dict(self) -> Dict[str, Any]:
|
|||
|
|
return {
|
|||
|
|
"target": self.target, "value": round(self.value, 4),
|
|||
|
|
"unit": self.unit, "level": self.level, "message": self.message,
|
|||
|
|
"confidence_band": round(self.confidence_band, 4),
|
|||
|
|
"lower": (round(self.value - self.confidence_band, 4)
|
|||
|
|
if not math.isnan(self.value) else None),
|
|||
|
|
"upper": (round(self.value + self.confidence_band, 4)
|
|||
|
|
if not math.isnan(self.value) else None),
|
|||
|
|
"explanation": self.explanation,
|
|||
|
|
"timestamp": self.timestamp,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
# 预测服务
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
|
|||
|
|
class PredictionService:
|
|||
|
|
"""质量预测部署服务：特征抽取 + 模型预测 + 告警判定。"""
|
|||
|
|
|
|||
|
|
def __init__(self, model: QualityModel, extractor: FeatureExtractor,
|
|||
|
|
thresholds: Optional[Thresholds] = None,
|
|||
|
|
*, confidence_rmse: float = 0.0):
|
|||
|
|
self.model = model
|
|||
|
|
self.extractor = extractor
|
|||
|
|
self.thresholds = thresholds
|
|||
|
|
self.confidence_rmse = confidence_rmse # 训练 RMSE，作为置信带
|
|||
|
|
self.validate()
|
|||
|
|
|
|||
|
|
def validate(self) -> None:
|
|||
|
|
errs: List[str] = []
|
|||
|
|
if not self.model.fitted:
|
|||
|
|
errs.append("模型未训练，无法部署")
|
|||
|
|
# 特征清单与模型特征名对齐
|
|||
|
|
model_names = self.model.recipe.feature_names
|
|||
|
|
ext_names = self.extractor.names
|
|||
|
|
if model_names and model_names != ext_names:
|
|||
|
|
errs.append(
|
|||
|
|
f"特征清单与模型特征名不一致: 清单={ext_names} 模型={model_names}")
|
|||
|
|
if self.thresholds:
|
|||
|
|
errs.extend(self.thresholds.validate())
|
|||
|
|
if (self.model.recipe.target
|
|||
|
|
and self.thresholds.target
|
|||
|
|
and self.thresholds.target != self.model.recipe.target):
|
|||
|
|
errs.append(
|
|||
|
|
f"阈值 target({self.thresholds.target}) 与模型 "
|
|||
|
|
f"target({self.model.recipe.target}) 不一致")
|
|||
|
|
if errs:
|
|||
|
|
raise ServeError("部署校验失败:\n " + "\n ".join(errs))
|
|||
|
|
|
|||
|
|
def predict(self, samples: Sequence[Sample]) -> List[Prediction]:
|
|||
|
|
"""对时序样本预测（每个样本时刻一条预测）。"""
|
|||
|
|
matrix: FeatureMatrix = self.extractor.extract(samples)
|
|||
|
|
# 模型特征名顺序（若清单与模型一致，直接用矩阵列）
|
|||
|
|
X = matrix.rows
|
|||
|
|
preds_raw = self.model.predict(X)
|
|||
|
|
explanation = self.model.explain()
|
|||
|
|
out: List[Prediction] = []
|
|||
|
|
# 样本时刻（extract 保留输入顺序）
|
|||
|
|
ts_list = [s.ts for s in sorted(samples, key=lambda s: s.ts)]
|
|||
|
|
for i, raw in enumerate(preds_raw):
|
|||
|
|
level, msg = self._classify(raw)
|
|||
|
|
ts = ts_list[i] if i < len(ts_list) else 0.0
|
|||
|
|
out.append(Prediction(
|
|||
|
|
target=self.model.recipe.target, value=raw,
|
|||
|
|
unit=self.model.recipe.unit, level=level, message=msg,
|
|||
|
|
confidence_band=self.confidence_rmse,
|
|||
|
|
explanation=explanation, timestamp=ts))
|
|||
|
|
return out
|
|||
|
|
|
|||
|
|
def _classify(self, value: float) -> tuple:
|
|||
|
|
"""按阈值判定告警等级。"""
|
|||
|
|
if math.isnan(value) or self.thresholds is None:
|
|||
|
|
return AlarmLevel.NORMAL.value, "无阈值或预测缺失，未判定"
|
|||
|
|
th = self.thresholds
|
|||
|
|
band = th.warning_band
|
|||
|
|
if th.min_value is not None:
|
|||
|
|
if value < th.min_value:
|
|||
|
|
return AlarmLevel.CRITICAL.value, (
|
|||
|
|
f"{th.target}={value:.3f} 低于下限 {th.min_value}")
|
|||
|
|
if value < th.min_value + band:
|
|||
|
|
return AlarmLevel.WARNING.value, (
|
|||
|
|
f"{th.target}={value:.3f} 接近下限 {th.min_value}")
|
|||
|
|
if th.max_value is not None:
|
|||
|
|
if value > th.max_value:
|
|||
|
|
return AlarmLevel.CRITICAL.value, (
|
|||
|
|
f"{th.target}={value:.3f} 超过上限 {th.max_value}")
|
|||
|
|
if value > th.max_value - band:
|
|||
|
|
return AlarmLevel.WARNING.value, (
|
|||
|
|
f"{th.target}={value:.3f} 接近上限 {th.max_value}")
|
|||
|
|
return AlarmLevel.NORMAL.value, f"{th.target}={value:.3f} 达标"
|
|||
|
|
|
|||
|
|
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
# 驾驶舱视图
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
|
|||
|
|
class CockpitView:
|
|||
|
|
"""把预测结果渲染为驾驶舱布局片段（对齐 iAOP-cockpit-layout-v1）。"""
|
|||
|
|
|
|||
|
|
WIDGET_TYPES = {"kpi_card", "alarm_panel", "explanation_list"}
|
|||
|
|
|
|||
|
|
def __init__(self, title: str = "质量预测"):
|
|||
|
|
self.title = title
|
|||
|
|
|
|||
|
|
def render(self, prediction: Prediction,
|
|||
|
|
*, position: Optional[Dict[str, int]] = None) -> Dict[str, Any]:
|
|||
|
|
"""渲染单个预测为 kpi_card + alarm_panel + 可解释溯源列表。"""
|
|||
|
|
pos = position or {"x": 0, "y": 0, "w": 6, "h": 2}
|
|||
|
|
level_color = {
|
|||
|
|
AlarmLevel.NORMAL.value: "green",
|
|||
|
|
AlarmLevel.WARNING.value: "yellow",
|
|||
|
|
AlarmLevel.CRITICAL.value: "red",
|
|||
|
|
}[prediction.level]
|
|||
|
|
# top-3 特征贡献（可溯源）
|
|||
|
|
top = sorted(prediction.explanation,
|
|||
|
|
key=lambda e: e.get("importance", 0), reverse=True)[:3]
|
|||
|
|
return {
|
|||
|
|
"$schema": "iAOP-cockpit-layout-v1",
|
|||
|
|
"title": self.title,
|
|||
|
|
"widgets": [
|
|||
|
|
{
|
|||
|
|
"type": "kpi_card",
|
|||
|
|
"metric": prediction.target,
|
|||
|
|
"label": self.title,
|
|||
|
|
"value": round(prediction.value, 3),
|
|||
|
|
"unit": prediction.unit,
|
|||
|
|
"level": prediction.level,
|
|||
|
|
"color": level_color,
|
|||
|
|
**pos,
|
|||
|
|
"description": prediction.message,
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"type": "alarm_panel",
|
|||
|
|
"metric": prediction.target,
|
|||
|
|
"level": prediction.level,
|
|||
|
|
"message": prediction.message,
|
|||
|
|
"color": level_color,
|
|||
|
|
"x": pos["x"], "y": pos["y"] + pos["h"],
|
|||
|
|
"w": pos["w"], "h": 1,
|
|||
|
|
"description": "质量预测告警面板",
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"type": "explanation_list",
|
|||
|
|
"metric": prediction.target,
|
|||
|
|
"items": top,
|
|||
|
|
"x": pos["x"], "y": pos["y"] + pos["h"] + 1,
|
|||
|
|
"w": pos["w"], "h": 2,
|
|||
|
|
"description": "预测依据（top-3 特征贡献，可溯源）",
|
|||
|
|
},
|
|||
|
|
],
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
# 模型漂移监测
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
|
|||
|
|
class DriftMonitor:
|
|||
|
|
"""累计预测的评估指标，超阈值触发重训信号（PRD §5.3 / §9）。"""
|
|||
|
|
|
|||
|
|
def __init__(self, *, min_r2: float = 0.8, max_mae: float = 1.0):
|
|||
|
|
self.min_r2 = min_r2
|
|||
|
|
self.max_mae = max_mae
|
|||
|
|
self.history: List[Evaluation] = []
|
|||
|
|
|
|||
|
|
def record(self, evaluation: Evaluation) -> None:
|
|||
|
|
self.history.append(evaluation)
|
|||
|
|
|
|||
|
|
def should_retrain(self) -> tuple:
|
|||
|
|
"""最近一次评估是否触发重训。返回 (是否重训, 原因)。"""
|
|||
|
|
if not self.history:
|
|||
|
|
return False, "无评估记录"
|
|||
|
|
last = self.history[-1]
|
|||
|
|
if math.isnan(last.r2):
|
|||
|
|
return True, f"R² 异常（NaN），建议重训"
|
|||
|
|
if last.r2 < self.min_r2:
|
|||
|
|
return True, f"R²={last.r2:.3f} < {self.min_r2}，模型退化"
|
|||
|
|
if last.mae > self.max_mae:
|
|||
|
|
return True, f"MAE={last.mae:.3f} > {self.max_mae}，误差超限"
|
|||
|
|
return False, f"R²={last.r2:.3f} MAE={last.mae:.3f} 达标"
|
|||
|
|
|
|||
|
|
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
# 部署包加载
|
|||
|
|
# ---------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
|
|||
|
|
@dataclass
|
|||
|
|
class DeploymentBundle:
|
|||
|
|
"""模型部署包：模型 + 特征清单 + 阈值 + 置信带，可整体序列化。"""
|
|||
|
|
|
|||
|
|
model: QualityModel
|
|||
|
|
extractor: FeatureExtractor
|
|||
|
|
thresholds: Optional[Thresholds] = None
|
|||
|
|
confidence_rmse: float = 0.0
|
|||
|
|
|
|||
|
|
def to_service(self) -> PredictionService:
|
|||
|
|
return PredictionService(
|
|||
|
|
self.model, self.extractor, self.thresholds,
|
|||
|
|
confidence_rmse=self.confidence_rmse)
|
|||
|
|
|
|||
|
|
def to_dict(self) -> Dict[str, Any]:
|
|||
|
|
return {
|
|||
|
|
"model": self.model.to_dict(),
|
|||
|
|
"feature_specs": [
|
|||
|
|
{"name": s.name, "source": s.source, "transform": s.transform,
|
|||
|
|
"window": s.window, "denominator": s.denominator,
|
|||
|
|
"meaning": s.meaning, "unit": s.unit}
|
|||
|
|
for s in self.extractor.specs],
|
|||
|
|
"thresholds": ({
|
|||
|
|
"target": self.thresholds.target,
|
|||
|
|
"min": self.thresholds.min_value,
|
|||
|
|
"max": self.thresholds.max_value,
|
|||
|
|
"warning_band": self.thresholds.warning_band}
|
|||
|
|
if self.thresholds else None),
|
|||
|
|
"confidence_rmse": self.confidence_rmse,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
@classmethod
|
|||
|
|
def from_dict(cls, d: Dict[str, Any]) -> "DeploymentBundle":
|
|||
|
|
from .features import FeatureSpec as FS
|
|||
|
|
model = QualityModel.from_dict(d["model"])
|
|||
|
|
specs = [FS(name=s["name"], source=s["source"],
|
|||
|
|
transform=s.get("transform", "raw"),
|
|||
|
|
window=float(s.get("window", 60.0)),
|
|||
|
|
denominator=s.get("denominator"),
|
|||
|
|
meaning=s.get("meaning", ""), unit=s.get("unit", ""))
|
|||
|
|
for s in d.get("feature_specs", [])]
|
|||
|
|
ext = FeatureExtractor(specs, strict=False)
|
|||
|
|
th_raw = d.get("thresholds")
|
|||
|
|
th = Thresholds.from_dict(th_raw) if th_raw else None
|
|||
|
|
return cls(model, ext, th, float(d.get("confidence_rmse", 0.0)))
|