heatsink-forced-mlp 是一款专为风冷散热器（Heat Sink）设计的 AI 代理模型：3 步安装、1 行 Python 代码，即可同时输出底板热阻r_base_k_w、风道压降pressure_drop_pa，以及带 95% 置信上界的热阻估计值，让你几分钟内完成散热方案的快速筛选。本教程带你从零跑通第一个预测。

🧊 什么是 heatsink-forced-mlp？

一句话概括：输入散热器几何、材料与工况参数，毫秒级返回热阻与压降。

• 模型结构：bench_mlp（4 层 × 128 宽，SiLU 激活），在 13 维输入上对数域训练
• 训练数据：HeatSink Sizer 物理引擎的 6000 次求解（Teertstra 复合平行板换热 + 3D 有限体积基底导热 + 发展流压降）
• 精度：900 个留出测试设计中，热阻平均绝对误差仅0.71%，压降1.04%
• 可信度：95% 置信上界实测覆盖率95.78%，信任审查结论APPROVED（评分 1.00）

📄 完整模型卡：model_card.json · 项目说明：README.md

🚀 快速开始：3 步安装

第 1 步：准备 Python 环境

任意平台均可，建议 Python 3.9+（已安装 pip）。

第 2 步：一行命令安装 pinneapple 库

pip install "pinneapple @ git+https://github.com/PINNeAPPle-Labs/PINNeAPPle"

模型权重在首次load时自动下载并做 SHA-256 校验，无需手动管理文件。

第 3 步：1 行代码输出热阻、压降与 95% 置信上界

import pinneapple as pp model = pp.zoo.load("heatsink_forced_mlp") # 权重自动校验 inputs = {"base_width_mm": 44.7278, "base_depth_mm": 138.196, "base_thickness_mm": 3.54108, "n_fins": 15.0, "fin_thickness_mm": 0.81635, "fin_height_mm": 15.0093, "k_w_mk": 183.817, "source_width_mm": 13.5681, "source_depth_mm": 21.6939, "t_ambient_c": 27.7717, "air_velocity_m_s": 4.20166, "power_w": 297.703} out = model.predict(inputs) # ← 核心就这一行 print({k: round(float(v[0]), 6) for k, v in out.items()}) # {'r_base_k_w': 0.882924, 'pressure_drop_pa': 66.151017, 'r_base_upper95_k_w': 0.901249}

三个输出一次到手：热阻约0.883 K/W、压降约66.15 Pa、95% 置信上界0.901 K/W。输入超出有效范围时，predict会主动发出警告。

📥 输入参数速查表（12 项）

完整定义见 README.md 与 model_card.json。

📤 3 个输出怎么读？

其中 95% 置信上界的含义是：有 95% 的把握，真实热阻不会超过该值——做裕量设计时可直接引用它。

📄 官方示例（含参考值与审查结论pass/APPROVED）：example.json

✅ 适用范围与已知限制

• 适用工况：风道内（无旁通）层流/发展流强制对流
• 旁通风道：实际散热器若存在旁通，风速会损失 20–50%，需先修正风速
• 精度口径：对流关联式典型误差 ±15%；模型对物理引擎的平均误差 <1%
• 定位：快速筛选工具，定型设计建议再用物理引擎复核

详见 README.md。

📦 仓库文件一览

如需本地获取全部文件，可克隆仓库：

git clone https://gitcode.com/hf_mirrors/PINNeAPPle-Labs/heatsink-forced-mlp

💡 常见问题（FAQ）

Q：想用 ONNX 部署怎么办？model.onnx 已内置前后处理（与 PyTorch 最大偏差 1.8e-06），配合 onnxruntime 即可推理，列序为 12 个物理输入：

import numpy as np, onnxruntime as ort session = ort.InferenceSession("model.onnx") x = np.array([[44.7278, 138.196, 3.54108, 15.0, 0.81635, 15.0093, 183.817, 13.5681, 21.6939, 27.7717, 4.20166, 297.703]], np.float32) print(dict(zip([o.name for o in session.get_outputs()], session.run(None, {"x": x}))))

⚠️ 注意：有效范围与物理检查不包含在 ONNX 图内，需自行判断输入区间。

Q：预测结果可信吗？用pp.zoo.query_checks(model, inputs)做逐次查询信任检查（示例返回pass）；pp.zoo.validate(model)可复现全部模型卡指标（结论APPROVED）。

Q：输入超出有效范围会怎样？模型会发出警告，结果仅供参考，建议把参数拉回上表范围内再评估。