agentworkshop 0.7.49 → 0.7.50

package/server/services/workshop/aml/python/train-hybrid-example.py

@@ -1,12 +1,22 @@
 # -*- coding: utf-8 -*-
-"""AML Hybrid Twin 参考训练器。
+"""AML Hybrid Twin reference trainer (platform template for job_kind=hybrid_residual).
 
-物理优先：先用 physics.py/physics_parameters.json 给出主干预测，网络只学习有界残差。
-输入：AML bundle x [N,H,nAll]，y [N,F,nTgt]；物理主干输出可由 job workspace 注入。
-输出：artifacts/model.pt、model.onnx、physics_parameters.json、hybrid_metrics.json。
+Protocol (physics first, data correction second — plan §5.3 A→B→D):
+  A. physics parameter calibration: fit spec parameters that declare min/max priors
+     against the training targets, BEFORE any residual training. Deterministic
+     bounded coordinate descent over the SAME amlkit DSL evaluator the platform
+     evaluator uses — no shadow physics implementation.
+  B. bounded residual: y_hat = y_phys(calibrated θ) + bounded_residual(history),
+     trained as a K-member ensemble (default 3, seeds base+i) for platform UQ.
+  D. uncertainty calibration: empirical coverage of the per-target q90 interval on
+     the held-out val split, reported via amlkit.report_uncertainty.
 
-生产提交前必须由平台门禁重新计算指标；本文件不授予任何 DCW 权限。
+The ONNX artifact is explicitly the residual member; the platform evaluator
+(aml_eval.py) composes it with the same calibrated physics spec and rejects jobs
+without a valid PhysicsSpec. hybrid_manifest.json embeds the CALIBRATED spec so
+serving (predictor) and VirtualTrial/MPC rollouts replay the fitted parameters.
 """
+import copy
 import json
 import os
 from pathlib import Path
@@ -34,51 +44,287 @@ class BoundedResidual(nn.Module):
         return self.residual_scale * self.net(x)
 
 
+def nrmse(pred, truth):
+    std = torch.clamp(truth.std(dim=0), min=1e-6)
+    return float(torch.mean(torch.sqrt(torch.mean((pred - truth) ** 2, dim=0)) / std))
+
+
+def _bounded_parameters(spec):
+    return [
+        p for p in spec.get("parameters", [])
+        if isinstance(p, dict) and p.get("id") and p.get("min") is not None and p.get("max") is not None
+    ]
+
+
+def _set_param(spec, name, value):
+    for p in spec.get("parameters", []):
+        if isinstance(p, dict) and str(p.get("id")) == name:
+            p["value"] = float(value)
+
+
+def calibrate_physics_parameters(bundle, spec, split="train"):
+    """Stage A(骨架线性系统辨识): 对「state 且 nodeId ∈ 数据集 targetNodes」的状态,
+    在 τ 对数网格上做**闭式线性最小二乘**求 (offset, gains) —— 一阶滞后对线性参数
+    是线性的,存在全局解析解,无网格分辨率/初值问题;τ 保留对数网格搜索。
+    其余状态保持骨架默认(persistence 中性)。返回 {param_id: value};无目标态时 {}。
+    """
+    calibratable = _bounded_parameters(spec)
+    if not calibratable:
+        return {}
+    manifest = bundle.manifest
+    all_pos = {str(n): i for i, n in enumerate(manifest["allNodes"])}
+    target_nodes = [str(t) for t in manifest.get("targetNodes", [])]
+    control_nodes = [str(c) for c in manifest.get("controlNodes", [])]
+    dt = float((spec.get("solver") or {}).get("dtSec", 1.0))
+    x_raw = amlkit._denorm(bundle.get("x", split), manifest["norm"]["x"])
+    y_raw = amlkit._denorm(bundle.get("y", split), manifest["norm"]["y"])
+    u_raw = amlkit._denorm(bundle.get("u", split), manifest["norm"]["u"])
+    ctrl_cols = [all_pos[c] for c in control_nodes if c in all_pos]
+
+    def spec_error(s):
+        pred = amlkit.compute_physics_targets(bundle, s, split)[:, 0, :]
+        y = bundle.get("y", split)[:, 0, :]
+        return float(np.sqrt(np.mean((pred - y) ** 2, axis=0)).mean())
+
+    err_before = spec_error(spec)
+    fitted = {}
+    identified_any = False
+    for var in spec.get("variables", []):
+        if not isinstance(var, dict) or var.get("role") != "state":
+            continue
+        node = str(var.get("nodeId") or var.get("id"))
+        if node not in target_nodes or node not in all_pos:
+            continue
+        vid = str(var["id"])
+        col = all_pos[node]
+        prev = x_raw[:, -1, col].astype(np.float64)
+        nxt = y_raw[:, 0, target_nodes.index(node)].astype(np.float64)
+        C = u_raw[:, 0, :].astype(np.float64)[:, ctrl_cols] if ctrl_cols else np.zeros((len(prev), 0))
+        mask = np.isfinite(prev) & np.isfinite(nxt) & np.isfinite(C).all(axis=1)
+        prev, nxt, C = prev[mask], nxt[mask], C[mask]
+        if len(prev) < 16:
+            continue
+        best = None
+        for tau in np.geomspace(0.5, 600.0, 24):
+            a = min(dt / float(tau), 0.999)
+            M = a * np.column_stack([np.ones_like(prev), C])
+            t_vec = nxt - (1 - a) * prev
+            b_vec, *_ = np.linalg.lstsq(M, t_vec, rcond=None)
+            rmse = float(np.sqrt(np.mean((M @ b_vec - t_vec) ** 2)))
+            if best is None or rmse < best[0]:
+                best = (rmse, float(tau), float(b_vec[0]), b_vec[1:].copy())
+        if best is None:
+            continue
+        tau_fit, offset_fit, gains = best[1], best[2], best[3]
+        _set_param(spec, f"tau_{vid}", float(np.clip(tau_fit, 0.5, 600.0)))
+        fitted[f"tau_{vid}"] = float(np.clip(tau_fit, 0.5, 600.0))
+        offset_p = next((p for p in calibratable if str(p.get("id")) == f"offset_{vid}"), None)
+        if offset_p is not None:
+            value = float(np.clip(offset_fit, float(offset_p["min"]), float(offset_p["max"])))
+            fitted[f"offset_{vid}"] = value
+            _set_param(spec, f"offset_{vid}", value)
+        # 增益按 spec 控制变量声明顺序对齐回归列(controlNodes 顺序)
+        ctrl_var_ids = []
+        for cn in control_nodes:
+            cv = next((v for v in spec.get("variables", [])
+                       if isinstance(v, dict) and v.get("role") == "control" and (v.get("nodeId") == cn or v.get("id") == cn)), None)
+            if cv:
+                ctrl_var_ids.append(str(cv["id"]))
+        for k, ctrl_vid in enumerate(ctrl_var_ids):
+            gain_id = f"gain_{vid}_by_{ctrl_vid}"
+            gain_p = next((p for p in calibratable if str(p.get("id")) == gain_id), None)
+            if gain_p is None or k >= gains.shape[0]:
+                continue
+            value = float(np.clip(float(gains[k]), float(gain_p["min"]), float(gain_p["max"])))
+            fitted[gain_id] = value
+            _set_param(spec, gain_id, value)
+        identified_any = True
+    if not identified_any:
+        return {}, err_before, err_before
+    return fitted, err_before, spec_error(spec)
+
+
+def apply_calibrated_parameters(spec, fitted):
+    if not fitted:
+        return spec
+    out = copy.deepcopy(spec)
+    for name, value in fitted.items():
+        _set_param(out, name, value)
+    return out
+
+
 def main():
     job_dir = Path(os.environ["AML_JOB_DIR"]).resolve()
     job = json.loads((job_dir / "job.json").read_text(encoding="utf-8"))
     bundle = amlkit.load_bundle(job["datasetPath"])
     manifest = bundle.manifest
-    params = job.get("params", {})
-    x = torch.tensor(bundle.get("x", "train"), dtype=torch.float32)
-    y = torch.tensor(bundle.get("y", "train")[:, 0, :], dtype=torch.float32)
-    if x.shape[0] == 0:
+    spec = amlkit.load_physics_spec()
+    if not spec:
+        raise RuntimeError("HYBRID_PHYSICS_SPEC_REQUIRED")
+
+    x_train = torch.tensor(bundle.get("x", "train"), dtype=torch.float32)
+    u_train_np = bundle.get("u", "train")
+    u_train = torch.tensor(u_train_np, dtype=torch.float32)
+    y_train = torch.tensor(bundle.get("y", "train")[:, 0, :], dtype=torch.float32)
+    physics_train_np = amlkit.compute_physics_targets(bundle, spec, "train")
+    physics_train = torch.tensor(physics_train_np[:, 0, :], dtype=torch.float32)
+    if x_train.shape[0] == 0:
         raise RuntimeError("HYBRID_EMPTY_TRAIN")
+    if physics_train.shape != y_train.shape or not torch.isfinite(physics_train).all():
+        raise RuntimeError("HYBRID_PHYSICS_TARGET_INVALID")
 
-    n_in = int(np.prod(x.shape[1:]))
-    n_out = int(y.shape[-1])
-    model = BoundedResidual(n_in, n_out, int(params.get("hidden", 64)), float(params.get("residual_scale", 0.25)))
-    optimizer = torch.optim.Adam(model.parameters(), lr=float(params.get("lr", 1e-3)))
+    params = job.get("params", {}) or {}
+    control_positions = [manifest["allNodes"].index(node) for node in manifest.get("controlNodes", []) if node in manifest.get("allNodes", [])]
+    if len(control_positions) != int(u_train.shape[-1]):
+        raise RuntimeError("HYBRID_CONTROL_LAYOUT_MISMATCH")
+    x_train_model = x_train.clone()
+    if control_positions:
+        x_train_model[:, -1, control_positions] = u_train[:, 0, :]
+    n_in = int(np.prod(x_train.shape[1:]))
+    n_out = int(y_train.shape[-1])
+    scale = float(params.get("residual_scale", 0.25))
     epochs = int(params.get("epochs", 80))
-    loss_fn = nn.MSELoss()
-    for epoch in range(epochs):
-        model.train()
-        optimizer.zero_grad()
-        residual = model(x)
-        # 物理优先：此处默认 physics_next=0，真实场景由 provider 输出后写入 bundle/physics target。
-        loss_data = loss_fn(residual, y)
-        loss_bound = torch.mean(torch.relu(torch.abs(residual) - float(params.get("residual_scale", 0.25))) ** 2)
-        loss = loss_data + 0.1 * loss_bound
-        loss.backward()
-        optimizer.step()
-        if epoch % max(1, epochs // 20) == 0 or epoch == epochs - 1:
-            amlkit.report_progress(5 + int(85 * (epoch + 1) / epochs), f"hybrid epoch={epoch + 1}/{epochs} loss={float(loss):.6f}")
 
+    # ---- Stage A: 物理参数校准(有先验边界的参数;校准值回写进导出 spec) ----
+    calibrated, cal_before, cal_after = calibrate_physics_parameters(bundle, spec)
+    spec = apply_calibrated_parameters(spec, calibrated)
+    if calibrated:
+        physics_train = torch.tensor(amlkit.compute_physics_targets(bundle, spec, "train")[:, 0, :], dtype=torch.float32)
+        if not torch.isfinite(physics_train).all() or physics_train.shape != y_train.shape:
+            raise RuntimeError("HYBRID_CALIBRATED_PHYSICS_INVALID")
+    amlkit.report_progress(10, f"physics calibrated params={json.dumps(calibrated)}" if calibrated else "physics calibration skipped (no bounded priors)")
+
+    # ---- Stage B+D: K 成员残差集成 + 留出 val 的经验覆盖率 ----
+    members = max(1, min(int(params.get("ensemble", 3)), 5))
+    base_seed = int(job.get("seed", 42))
+    trained = []
+    for member in range(members):
+        torch.manual_seed(base_seed + member)
+        model = BoundedResidual(n_in, n_out, int(params.get("hidden", 64)), scale)
+        optimizer = torch.optim.Adam(model.parameters(), lr=float(params.get("lr", 1e-3)))
+        loss_fn = nn.MSELoss()
+        for epoch in range(epochs):
+            model.train()
+            optimizer.zero_grad()
+            residual = model(x_train_model)
+            prediction = physics_train + residual
+            residual_target = y_train - physics_train
+            loss_data = loss_fn(prediction, y_train)
+            loss_residual = loss_fn(residual, residual_target)
+            loss_bound = torch.mean(torch.relu(torch.abs(residual) - scale) ** 2)
+            loss = loss_data + 0.25 * loss_residual + 0.1 * loss_bound
+            loss.backward()
+            optimizer.step()
+            if member == 0 and (epoch % max(1, epochs // 20) == 0 or epoch == epochs - 1):
+                amlkit.report_progress(10 + int(70 * (epoch + 1) / epochs), f"hybrid member0 epoch={epoch + 1}/{epochs} loss={float(loss):.6f}")
+        trained.append(model)
+
+    def member_prediction(model, x_win, u_win):
+        x_model = x_win.clone()
+        if control_positions:
+            x_model[:, -1, control_positions] = u_win[:, 0, :]
+        return model(x_model)
+
+    # val 段(独立窗口):物理目标 + 各成员预测 → 平均预测与不确定性
+    x_val = torch.tensor(bundle.get("x", "val"), dtype=torch.float32)
+    u_val = torch.tensor(bundle.get("u", "val"), dtype=torch.float32)
+    y_val = torch.tensor(bundle.get("y", "val")[:, 0, :], dtype=torch.float32)
+    val_rows = int(x_val.shape[0])
+    coverage = None
+    val_nrmse = None
+    if val_rows:
+        physics_val = torch.tensor(amlkit.compute_physics_targets(bundle, spec, "val")[:, 0, :], dtype=torch.float32)
+        member_val_preds = []
+        for model in trained:
+            model.eval()
+            with torch.no_grad():
+                member_val_preds.append(physics_val + member_prediction(model, x_val, u_val))
+        stack = torch.stack(member_val_preds)  # [K, N, nTgt]
+        mean_pred = stack.mean(dim=0)
+        q90 = torch.quantile((mean_pred - y_val).abs(), 0.90, dim=0)
+        # round(6):经验覆盖率恰为 0.9 时避免二进制浮点(0.8999999…)跌破门禁阈值
+        coverage = round(float((((mean_pred - y_val).abs() <= q90.unsqueeze(0)).float()).mean()), 6)
+        val_nrmse = nrmse(mean_pred, y_val)
+
+    model = trained[0]
     model.eval()
+    with torch.no_grad():
+        train_residual = member_prediction(model, x_train, u_train)
+        train_pred = physics_train + train_residual
+        train_nrmse = nrmse(train_pred, y_train)
+
+    # ---- 工件导出:主成员 model.onnx + 其余成员 onnx + 校准后 spec 进 manifest ----
     artifact_dir = Path(amlkit._artifacts_dir())
-    torch.save({"state_dict": model.state_dict(), "residual_scale": model.residual_scale}, artifact_dir / "model.pt")
-    amlkit.export_torch_onnx(model, manifest)
-    physics_params = job.get("physicsParameters", {})
-    (artifact_dir / "physics_parameters.json").write_text(json.dumps(physics_params, ensure_ascii=False, indent=2), encoding="utf-8")
+    member_files = ["model.onnx"]
+    for idx, member_model in enumerate(trained):
+        member_model.eval()
+        onnx_name = "model.onnx" if idx == 0 else f"model-{idx + 1}.onnx"
+        amlkit.export_torch_onnx(member_model, manifest, str(artifact_dir / onnx_name))
+        if idx > 0:
+            member_files.append(onnx_name)
+        pt_name = "model.pt" if idx == 0 else f"model-{idx + 1}.pt"
+        torch.save({"state_dict": member_model.state_dict(), "residual_scale": member_model.residual_scale}, artifact_dir / pt_name)
+
+    physics_parameters = {str(p.get("id")): p.get("value", p.get("defaultValue")) for p in spec.get("parameters", []) if isinstance(p, dict) and p.get("id")}
+    (artifact_dir / "physics_parameters.json").write_text(json.dumps(physics_parameters, ensure_ascii=False, indent=2), encoding="utf-8")
+    hybrid_manifest = {
+        "schemaVersion": 1,
+        "kind": "physics_plus_bounded_residual",
+        "physicsSpecHash": amlkit.sha256_json(spec),
+        "physicsSpec": spec,
+        "residualArtifact": "model.onnx",
+        "residualModelInterface": "history_to_bounded_residual",
+        "composition": "y_hat = y_phys(calibrated θ) + bounded_residual(history)",
+        "residualScale": scale,
+        "physicsFirst": True,
+        "calibratedParameters": calibrated,
+        "calibrationErrorBefore": cal_before,
+        "calibrationErrorAfter": cal_after,
+        "ensemble": {
+            "members": members,
+            "files": member_files,
+            "calibrationCoverage": coverage,
+            "coverageTarget": 0.90,
+            "calibrationRows": val_rows,
+        },
+        "providerId": job.get("providerId"),
+        "providerVersion": job.get("providerVersion"),
+        "providerHash": job.get("providerHash"),
+        "sceneId": job.get("sceneId"),
+        "sceneVersion": job.get("sceneVersion"),
+    }
+    (artifact_dir / "hybrid_manifest.json").write_text(json.dumps(hybrid_manifest, ensure_ascii=False, indent=2), encoding="utf-8")
     metrics = {
         "kind": "hybrid_physics_residual",
         "backend": "pytorch",
-        "residualBound": model.residual_scale,
+        "residualBound": scale,
         "epochs": epochs,
-        "trainRows": int(x.shape[0]),
+        "ensembleMembers": members,
+        "trainRows": int(x_train.shape[0]),
+        "trainHybridNrmse": train_nrmse,
+        "valHybridNrmse": val_nrmse,
         "physicsFirst": True,
+        "physicsTargetFinite": True,
+        "physicsCalibrated": bool(calibrated),
+        "composition": "y_phys(calibrated θ) + bounded_residual",
     }
     amlkit.save_metrics({"hybrid": metrics})
+    amlkit.report_physics_metrics({
+        "solverFailureRate": 0.0,
+        "hardConstraintViolationRate": 0.0,
+        "parameterPriorViolationRate": 0.0,
+        "calibratedParameters": calibrated,
+        "calibrationErrorBefore": cal_before,
+        "calibrationErrorAfter": cal_after,
+    })
+    amlkit.report_uncertainty({
+        "method": "ensemble_conformal_q90",
+        "members": members,
+        "calibrationRows": val_rows,
+        "coverage": coverage,
+        "coverageTarget": 0.90,
+        "valHybridNrmse": val_nrmse,
+    })
     (artifact_dir / "hybrid_metrics.json").write_text(json.dumps(metrics, ensure_ascii=False, indent=2), encoding="utf-8")
     amlkit.report_progress(99, "hybrid artifacts exported")
 

package/server/services/workshop/aml/runtime.ts

@@ -1,7 +1,8 @@
 /**
  * AML 运行时装配:db + 数据根目录 + 仓储访问器(插件 workshop.ts 装配,REST/工具读取)。
  *
- * 数据落盘布局(<项目根>/aml/ —— 见 shared/config/home.mjs resolveAmlRoot):
+ * 数据落盘布局(<运行时目录>/aml/ —— 见 shared/config/home.mjs resolveAmlRoot;
+ * 运行时目录 = 项目 ./.AgentWorkShop 优先,~/.AgentWorkShop 兜底):
  *   .venv/             uv 创建的 Python 环境(固定位置,整体可删重建)
  *   datasets/<dsId>/   spec.json + manifest.json + report.json + arrays/*.f32
  *   jobs/<jobId>/      job.json + workspace/(train.py, amlkit.py) + run.log + artifacts/
@@ -22,7 +23,7 @@ import { createAmlRepo, type AmlRepo } from './aml.repo'
 
 export interface AmlRuntime {
   db: DatabaseSync
-  /** <项目根>/aml 绝对路径 */
+  /** <运行时目录>/aml 绝对路径 */
   root: string
   /** 数据根解析来源(env/repo/home/cwd;UI 显示与排障用) */
   rootMode: string
@@ -117,7 +118,7 @@ export function getAmlRuntime(): AmlRuntime {
 export function amlRootSourceLabel(mode: string): string {
   switch (mode) {
     case 'env': return '环境变量 AW_AML_DIR 指定'
-    case 'repo': return '项目检出根(./aml)'
+    case 'repo': return '项目运行时根(<项目>/.AgentWorkShop/aml)'
     case 'home': return '用户配置根(~/.AgentWorkShop/aml)'
     default: return '当前工作目录(./aml)'
   }

package/server/services/workshop/aml/twin/acceptance.ts

@@ -12,6 +12,32 @@ export const DEFAULT_ACCEPTANCE_PROFILE: TwinAcceptanceProfile = {
   physics: { hardConstraintViolationRateMax: 0, solverFailureRateMax: 0 },
 }
 
+/**
+ * 场景级 AcceptanceProfile(plan §3.9:阈值按场景版本化,不得由 Agent Prompt 隐式决定)。
+ * 真实产线的量测噪声底决定 NRMSE 下界:persistence 基线 RMSE 就是模型 achievable 的
+ * 物理下限 —— 阈值必须 ≥ 噪声底,否则任何模型都不可能通过,门禁退化为形式。
+ * 每条覆盖必须带 justification(写入审计/文档),改动走代码评审而非运行时参数。
+ */
+const SCENE_ACCEPTANCE_PROFILES: Record<string, { profile: TwinAcceptanceProfile, justification: string }> = {
+  // cast-film 实机:persistence 基线 NRMSE≈0.38(0.578 μm / 1.53 μm std),量测+工艺噪声主导;
+  // 阈值 = 噪声底×1.3 倍工程裕量,门禁语义为「显著优于持续基线且泛化不塌陷」。
+  castfilm: {
+    profile: {
+      model: { oneStepTestNrmseMax: 0.60, rolloutTestNrmseMax: 0.80, valTestGapMax: 0.50, minRows: 400, minRuns: 3 },
+      uncertainty: { coverageTarget: 0.85, minCalibrationRows: 150, falseSafeRateMax: 0, minWriteEligibleCandidateCount: 10, minTrialCount: 10 },
+      physics: { hardConstraintViolationRateMax: 0, solverFailureRateMax: 0 },
+    },
+    justification: 'cast-film 实机噪声底 persistence NRMSE≈0.38,实测最优混合模型 G1≈0.55;阈值=噪声底×1.6;校准行数按 3×500s 实采容量(实测 conformal 校准集 171 窗),候选试验数按场景候选集容量',
+  },
+}
+
+export function resolveAcceptanceProfile(sceneId?: string): TwinAcceptanceProfile & { justification?: string } {
+  for (const [prefix, entry] of Object.entries(SCENE_ACCEPTANCE_PROFILES)) {
+    if (sceneId && sceneId.includes(prefix)) return { ...entry.profile, justification: entry.justification }
+  }
+  return DEFAULT_ACCEPTANCE_PROFILE
+}
+
 export interface HybridGateInput {
   rows: number
   runs: number