Merge PR #112/#113 (feat #71 无监督模型 + #72 告警规则，与 #70 特征工程联合)

2026-08-05 08:21:41 +08:00
parent 234a476ec0
commit a0b21866fe
8 changed files with 1261 additions and 3 deletions
@@ -0,0 +1,356 @@
+# -*- coding: utf-8 -*-
+"""炉层杂质预警 · 预警规则与阈值设定引擎（Issue #72 / PRD 5.3 ③）。
+
+PRD 5.3 ③ / 场景 A（line 80）：异常检测模型触发 → 驾驶舱红色告警 + LLM 生成
+"原因+处置建议" → 值班长确认。本模块把"行业知识"——**预警分级 + 阈值 + 处置 SOP**——
+外置为模板配置（PRD line 152/171：阈值外置 JSON，行业工程师在配置台维护），引擎
+按规则评估特征向量产出带 severity 的 Alert。
+
+设计要点
+--------
+1. **声明式 AlertRule**：每条规则声明 ``id`` + ``severity``（P0/P1/P2）+ ``condition``
+   （特征名 + 比较运算 + 阈值）+ ``sop``（处置 SOP 引用，供 LLM 报警解释/驾驶舱展示）。
+2. **severity 三级**（PRD line 333：关键告警不直接联动执行机构，高利害人工确认）：
+   - ``P0``（critical）：红色告警，立即人工确认 + 紧急处置；
+   - ``P1``（warning）：黄色告警，加强监控 + 预备处置；
+   - ``P2``（info）：提示，记录跟踪。
+3. **规则引擎**：``AlertRuleEngine.evaluate`` 对一个特征向量评估全部规则，返回命中的
+   Alert 列表（取最高 severity 为主告警）；可与 #70/#71 组合（特征向量/异常分数均可作为
+   condition 输入）。
+4. **零依赖 YAML 子集解析**（对齐 data-bus / rag-kb / #70），阈值外置模板资产。
+"""
+from __future__ import annotations
+
+import math
+import os
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable, Dict, List, Optional, Sequence, Tuple
+
+NAN = float("nan")
+
+
+class AlertSeverity(str, Enum):
+    """预警严重度三级（PRD line 80 红色告警 / line 333 关键告警人工确认）。"""
+
+    P0 = "P0"   # critical：红色，立即人工确认 + 紧急处置
+    P1 = "P1"   # warning：黄色，加强监控 + 预备处置
+    P2 = "P2"   # info：提示，记录跟踪
+
+    @property
+    def label(self) -> str:
+        return {AlertSeverity.P0: "严重", AlertSeverity.P1: "警告",
+                AlertSeverity.P2: "提示"}[self]
+
+    @property
+    def rank(self) -> int:
+        """排序权重，越大越严重（用于取主告警）。"""
+        return {AlertSeverity.P0: 3, AlertSeverity.P1: 2, AlertSeverity.P2: 1}[self]
+
+
+# 比较运算符注册表（condition.op 取值）
+OPS: Dict[str, Callable[[float, float], bool]] = {
+    ">": lambda a, b: a > b,
+    ">=": lambda a, b: a >= b,
+    "<": lambda a, b: a < b,
+    "<=": lambda a, b: a <= b,
+    "==": lambda a, b: a == b,
+}
+
+
+def _is_num(x: object) -> bool:
+    return isinstance(x, (int, float)) and not (isinstance(x, float) and math.isnan(x))
+
+
+@dataclass
+class AlertCondition:
+    """单条触发条件：特征名 + 比较运算 + 阈值。"""
+
+    feature: str
+    op: str
+    threshold: float
+
+    def __post_init__(self) -> None:
+        if self.op not in OPS:
+            raise ValueError(f"未知比较运算 {self.op!r}（应为 {sorted(OPS)}）")
+
+    def matches(self, values: Dict[str, float]) -> bool:
+        v = values.get(self.feature)
+        if not _is_num(v):
+            return False
+        return OPS[self.op](float(v), self.threshold)
+
+
+@dataclass
+class AlertRule:
+    """声明式预警规则（模板配置中的一行规则声明）。
+
+    Attributes:
+        id: 规则 id（稳定标识，供驾驶舱/审计引用）。
+        severity: 严重度（P0/P1/P2）。
+        conditions: 触发条件列表（AND 语义：全部满足才命中）。
+        message: 告警文案（驾驶舱展示）。
+        sop: 处置 SOP 引用（PRD 场景A：LLM 报警解释 + 值班长确认）。
+    """
+
+    id: str
+    severity: AlertSeverity
+    conditions: List[AlertCondition]
+    message: str = ""
+    sop: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.id:
+            raise ValueError("AlertRule.id 不能为空")
+        if not self.conditions:
+            raise ValueError(f"规则 {self.id!r} 至少需要 1 条 condition")
+
+    def matches(self, values: Dict[str, float]) -> bool:
+        return all(c.matches(values) for c in self.conditions)
+
+    def describe(self) -> str:
+        conds = " 且 ".join(f"{c.feature}{c.op}{c.threshold}" for c in self.conditions)
+        return f"[{self.severity.value}] {self.id}: {conds}"
+
+
+@dataclass
+class Alert:
+    """一次预警命中（规则 + 触发时的特征快照）。"""
+
+    rule_id: str
+    severity: AlertSeverity
+    message: str
+    sop: str
+    timestamp: float
+    snapshot: Dict[str, float] = field(default_factory=dict)
+
+
+class AlertRuleEngine:
+    """预警规则引擎：评估特征向量，产出带 severity 的 Alert 列表。
+
+    换行业只改模板配置（AlertRule 列表），引擎零改动（PRD line 152/171）。
+
+    用法::
+
+        engine = AlertRuleEngine(rules)
+        alerts = engine.evaluate(timestamp=100, values={"炉温_ema5": 920.0})
+        if alerts:
+            primary = engine.primary_alert(alerts)   # 取最高 severity
+    """
+
+    def __init__(self, rules: Sequence[AlertRule]):
+        if not rules:
+            raise ValueError("AlertRuleEngine 至少需要 1 条规则")
+        ids = set()
+        for r in rules:
+            if r.id in ids:
+                raise ValueError(f"规则 id 重复：{r.id!r}")
+            ids.add(r.id)
+        self.rules: List[AlertRule] = list(rules)
+
+    @classmethod
+    def from_template_config(cls, path: str) -> "AlertRuleEngine":
+        return cls(load_alert_rules_config(path).rules)
+
+    def evaluate(self, timestamp: float,
+                 values: Dict[str, float]) -> List[Alert]:
+        """评估一个特征向量，返回全部命中规则的 Alert（按 severity 降序）。"""
+        hits: List[Alert] = []
+        for rule in self.rules:
+            if rule.matches(values):
+                hits.append(Alert(
+                    rule_id=rule.id, severity=rule.severity,
+                    message=rule.message, sop=rule.sop,
+                    timestamp=timestamp, snapshot=dict(values),
+                ))
+        hits.sort(key=lambda a: a.severity.rank, reverse=True)
+        return hits
+
+    def primary_alert(self, alerts: Sequence[Alert]) -> Optional[Alert]:
+        """取最高 severity 的主告警（驾驶舱红色告警）。无命中返回 None。"""
+        return alerts[0] if alerts else None
+
+
+# ---------------------------------------------------------------------------
+# 模板配置（零依赖 YAML 子集解析，对齐 #70 / data-bus / rag-kb）
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AlertRulesTemplateConfig:
+    """模板预警规则配置：模板元信息 + AlertRule 列表。"""
+
+    template: str
+    version: str
+    rules: List[AlertRule]
+    description: str = ""
+
+
+def _parse_scalar(text: str) -> str:
+    t = text.split(" #", 1)[0].strip()
+    if len(t) >= 2 and t[0] == t[-1] and t[0] in ("'", '"'):
+        return t[1:-1]
+    return t
+
+
+def _parse_flow_value(text: str):
+    """解析 ``key: value`` 右侧的值，支持行内 flow map ``{k: v, k: v}``。
+
+    其余（标量 / 引号串）退化为 :func:`_parse_scalar`。flow map 用于
+    ``conditions: [{feature: x, op: ">", threshold: 900.0}]`` 这种紧凑声明。
+    """
+    t = text.split(" #", 1)[0].strip()
+    if t.startswith("{") and t.endswith("}"):
+        inner = t[1:-1].strip()
+        out: Dict[str, object] = {}
+        if not inner:
+            return out
+        for part in inner.split(","):
+            if ":" not in part:
+                raise ValueError(f"flow map 项不是键值对：{part!r}")
+            k, _, v = part.partition(":")
+            out[k.strip()] = _parse_scalar(v)
+        return out
+    return _parse_scalar(text)
+
+
+def _strip_comments(lines: List[str]) -> List[Tuple[str, int]]:
+    out = []
+    for i, ln in enumerate(lines):
+        s = ln.strip()
+        if not s or s.startswith("#"):
+            continue
+        out.append((ln, i + 1))
+    return out
+
+
+def _parse_node(lines: List[Tuple[str, int]], i: int, indent: int):
+    text, _ = lines[i]
+    if text.lstrip(" ").startswith("- "):
+        items: List[object] = []
+        while i < len(lines):
+            t, no = lines[i]
+            stripped = t.lstrip(" ")
+            if not stripped.startswith("- "):
+                break
+            lead_j = len(t) - len(t.lstrip(" "))
+            if lead_j != indent:
+                break
+            item_text = stripped[2:].strip()
+            if not item_text:
+                raise ValueError(f"alerts.yaml 第 {no} 行：list 项为空")
+            # 行内 flow map（{k: v, ...}）优先用 _parse_flow_value，避免被
+            # 下方「含 : 即 map 项」分支误判（flow map 也含 :）。
+            if item_text.startswith("{") and item_text.endswith("}"):
+                items.append(_parse_flow_value(item_text))
+                i += 1
+            elif ":" in item_text:
+                map_indent = len(t) - len(t.lstrip(" ")) + 2
+                lines[i] = (" " * map_indent + item_text, no)
+                v, i = _parse_node(lines, i, map_indent)
+                items.append(v)
+            else:
+                items.append(_parse_flow_value(item_text))
+                i += 1
+        return items, i
+    result: Dict[str, object] = {}
+    while i < len(lines):
+        t, no = lines[i]
+        lead_j = len(t) - len(t.lstrip(" "))
+        if lead_j < indent or t.lstrip(" ").startswith("- "):
+            break
+        if lead_j > indent:
+            raise ValueError(f"alerts.yaml 第 {no} 行缩进异常")
+        if ":" not in t:
+            raise ValueError(f"alerts.yaml 第 {no} 行不是合法键值对：{t!r}")
+        key, _, rest = t.partition(":")
+        key = key.strip()
+        rest = rest.strip()
+        if rest:
+            result[key] = _parse_flow_value(rest)
+            i += 1
+            continue
+        if i + 1 >= len(lines):
+            raise ValueError(f"alerts.yaml 第 {no} 行 {key!r} 缺少值")
+        sub_indent = len(lines[i + 1][0]) - len(lines[i + 1][0].lstrip(" "))
+        if sub_indent <= indent:
+            raise ValueError(f"alerts.yaml 第 {no} 行 {key!r} 缺少值（无嵌套）")
+        v, i = _parse_node(lines, i + 1, sub_indent)
+        result[key] = v
+    return result, i
+
+
+def _load_yaml_text(text: str) -> Dict[str, object]:
+    lines = _strip_comments(text.splitlines())
+    if not lines:
+        return {}
+    top_indent = len(lines[0][0]) - len(lines[0][0].lstrip(" "))
+    value, next_i = _parse_node(lines, 0, top_indent)
+    if not isinstance(value, dict):
+        raise ValueError("alerts.yaml 顶层必须是 map")
+    if next_i < len(lines):
+        raise ValueError(f"alerts.yaml 第 {lines[next_i][1]} 行：顶层存在多个节点")
+    return value
+
+
+def load_alert_rules_config(path: str) -> AlertRulesTemplateConfig:
+    """从模板预警规则 YAML 资产加载配置。
+
+    期望结构（详见 ``config/alert_rules.template.yaml``）::
+
+        template: ti-cl4
+        version: 1.0.0
+        rules:
+          - id: bed_temp_critical
+            severity: P0
+            message: 炉温超上限，立即降流减料
+            sop: SOP-CL-001
+            conditions:
+              - {feature: 炉温_ema5, op: ">", threshold: 900.0}
+    """
+    with open(path, "r", encoding="utf-8") as fh:
+        data = _load_yaml_text(fh.read())
+
+    template = str(data.get("template", "")).strip()
+    if not template:
+        raise ValueError("alerts.yaml 缺少 template 字段")
+    version = str(data.get("version", "1.0.0")).strip() or "1.0.0"
+    description = str(data.get("description", "")).strip()
+
+    raw_rules = data.get("rules") or []
+    if not isinstance(raw_rules, list):
+        raise ValueError("alerts.yaml rules 必须是 list")
+    rules: List[AlertRule] = []
+    for idx, item in enumerate(raw_rules):
+        if not isinstance(item, dict):
+            raise ValueError(f"alerts.yaml rules[{idx}] 必须是 map")
+        rid = str(item.get("id", "")).strip()
+        sev_name = str(item.get("severity", "")).strip().upper()
+        sev_map = {s.value: s for s in AlertSeverity}
+        if sev_name not in sev_map:
+            raise ValueError(
+                f"alerts.yaml rules[{idx}] 未知 severity {sev_name!r}"
+                f"（应为 {sorted(sev_map)}）")
+        message = str(item.get("message", "")).strip()
+        sop = str(item.get("sop", "")).strip()
+        raw_conds = item.get("conditions") or []
+        if not isinstance(raw_conds, list):
+            raise ValueError(f"alerts.yaml rules[{idx}] conditions 必须是 list")
+        conds: List[AlertCondition] = []
+        for ci, c in enumerate(raw_conds):
+            if not isinstance(c, dict):
+                raise ValueError(f"alerts.yaml rules[{idx}].conditions[{ci}] 必须是 map")
+            feature = str(c.get("feature", "")).strip()
+            op = str(c.get("op", "")).strip()
+            if op not in OPS:
+                raise ValueError(
+                    f"alerts.yaml rules[{idx}].conditions[{ci}] 未知 op {op!r}")
+            try:
+                threshold = float(c.get("threshold"))
+            except (TypeError, ValueError) as exc:
+                raise ValueError(
+                    f"alerts.yaml rules[{idx}].conditions[{ci}] threshold 不是数值") from exc
+            conds.append(AlertCondition(feature=feature, op=op, threshold=threshold))
+        rules.append(AlertRule(id=rid, severity=sev_map[sev_name],
+                               conditions=conds, message=message, sop=sop))
+    return AlertRulesTemplateConfig(template=template, version=version,
+                                    rules=rules, description=description)