已经实现的冷机节能体检、冷机群控优化、COP/功率模型拟合、设备配置、Excel 报告、Vue 前端后的结构。 ## 项目截图# 冷机节能算法项目框架结构与功能模块设计 ## 1. 项目总体定位 当前项目是一个面向冷站的算法型工程项目核心目标是 1. 读取冷站历史运行数据。 2. 进行数据质量诊断。 3. 拟合冷机 COP 模型和功率模型。 4. 基于设备铭牌参数、设备拓扑、历史工况执行冷机群控优化。 5. 输出三页节能体检报告和 Excel 明细报告。 6. 支持后续扩展为实时冷机群控优化接口。 整体上可以理解为 text 冷站历史数据 / 实时数据 ↓ 数据清洗与质量诊断 ↓ 冷机性能模型拟合 ↓ 设备参数 拓扑配置 ↓ 冷机群控优化器 ↓ 节能体检报告 / 优化控制建议 / 结果入库 --- ## 2. 当前项目目录结构 当前项目已经基本形成了类似 Spring Boot 的分层结构 text pyomo_chiller/ main.py # FastAPI 应用入口启动接口服务和静态页面服务 controller/ # 接口层接收请求、参数校验、返回响应 integration_controller.py # 汇总路由入口 history_evaluation_controller.py equipment_controller.py chiller_cop_controller.py telemetry_controller.py result_query_controller.py common.py service/ # 业务服务层组织业务流程 history_evaluation_service.py # 冷站节能体检、历史数据评估、Excel 报告生成 chiller_group_control_service.py # 实时群控优化业务编排 chiller_cop_fit_service.py # 冷机 COP / 功率模型拟合与质量评估 algorithm/ # 算法层数学模型、优化器、预测模型 optimizer/ chiller_optimizer.py # 冷机组合枚举 泵塔频率优化 Pyomo/IPOPT 求解 prediction/ models/ # 历史负荷预测模型文件 mapper/ # 数据访问层SQLite 表读写 sqlite_mapper.py domain/ # 领域模型 / Schema chiller_schema.py config/ # 配置层 settings.py # 路径、数据库、运行模式、优化并发等配置 chiller_params.py # 默认设备参数、环境约束、求解器参数 logging_config.py tasks/ # 定时任务 scheduler.py # 定时群控、定时 COP 拟合任务 thingsboard/ # 前端与 ThingsBoard 相关资源 vue2/ # Vue2 前端工程源码 html/ # Vue 打包后的静态页面由 FastAPI 托管 data/ # 数据文件、模型文件、SQL、报告输出 haikou/ sql/ cop_models/ history_evaluations/ docs/ # 项目文档、设计说明、用户手册、截图 tests/ # 单脚本验证、算法实验、历史原型 scripts/ # 构建、部署、批处理脚本 utils/ # 通用工具函数 --- ## 3. 分层设计说明 ### 3.1 main.py应用启动层 职责 - 创建 FastAPI 应用。 - 注册接口路由。 - 配置跨域。 - 托管前端静态页面。 - 启动 Uvicorn 服务。 当前入口逻辑 text main.py ↓ 注册 integration_controller ↓ 挂载 /html 静态页面 ↓ 浏览器访问 http://127.0.0.1:8003/html/ 这个设计适合后续打包成 EXE 用户运行 EXE 后同时启动接口服务和前端页面服务不需要单独部署 Nginx。 --- ## 4. Controller 接口层设计 controller 层类似 Spring Boot 的 Controller负责接口暴露不应该写复杂算法逻辑。 ### 4.1 integration_controller.py 统一集成路由入口。 职责 - 把多个子 Controller 路由统一挂到 /integration 下。 - 对外提供一个完整的集成接口入口。 当前整合内容包括 text telemetry_router equipment_router chiller_cop_router history_evaluation_router result_query_router ### 4.2 history_evaluation_controller.py 历史节能体检接口。 主要功能 - 下载历史数据 Excel 模板。 - 上传历史 Excel 并生成三页体检报告。 - 上传历史 Excel 并生成 Excel 明细报告。 - 下载已经生成的 Excel 报告。 - 处理上传文件、Sheet 参数、样本数参数等。 对应前端 text 冷站节能体检页面 - 生成三页体检报告 - 下载历史数据 Excel 模板 - 下载 Excel 明细报告 ### 4.3 equipment_controller.py 设备配置接口。 主要功能 - 读取设备铭牌参数。 - 保存设备铭牌参数。 - 初始化默认设备参数。 - 读取设备拓扑配置。 - 保存设备拓扑配置。 - 初始化默认拓扑配置。 对应前端 text 设备铭牌参数配置 设备拓扑配置 ### 4.4 chiller_cop_controller.py 冷机性能模型接口。 主要功能 - 执行冷机 COP / 功率模型拟合。 - 校验历史样本质量。 - 查询最新冷机 COP 系数和功率模型系数。 对应功能 text 冷机性能画像 COP 曲面 功率曲面 ### 4.5 telemetry_controller.py 遥测数据接口。 主要功能 - 写入未来天气数据。 - 查询未来天气数据。 - 写入负荷训练原始数据。 - 查询负荷训练数据。 这个模块更多是为实时系统、ThingsBoard 接入、负荷预测准备的。 ### 4.6 result_query_controller.py 结果查询接口。 主要功能 - 查询群控优化结果。 - 查询控制指令结果。 - 给前端或 ThingsBoard 查询历史优化结果使用。 --- ## 5. Service 业务服务层设计 service 是当前项目最重要的业务编排层。 它不直接暴露接口也不应该只做数据库读写而是负责把数据、配置、算法和报告串起来。 --- ### 5.1 history_evaluation_service.py 这是当前冷机节能体检工具的核心服务。 主要职责 text 历史 Excel 数据 ↓ 字段识别与标准化 ↓ 过滤空值、/、关键字段缺失行 ↓ 数据质量评估 ↓ COP / 功率模型拟合 ↓ 逐行调用优化器 ↓ 生成三页体检报告数据 ↓ 生成 Excel 明细报告 核心功能模块 | 模块 | 功能 | | --- | --- | | 字段别名识别 | 兼容不同 Excel 列名 | | 数据过滤 | 排除空值、/、关键字段缺失数据 | | 历史工况参数构造 | 将 Excel 行数据转成优化器参数 | | 历史行优化计算 | 对每条有效历史工况调用优化器 | | 并发优化 | 多行历史数据并发计算提高报告生成速度 | | 数据质量评分 | 生成数据可信度、WARN/FAIL | | 节能潜力计算 | 原始功率 vs 优化功率 | | 管理摘要生成 | 给 Excel 报告添加首页摘要 | | Excel 报告输出 | 输出明细、汇总、管理摘要等 Sheet | 它是“冷站节能体检工具”的主业务服务。 --- ### 5.2 chiller_cop_fit_service.py 冷机性能建模服务。 当前已经从单 COP 模型升级为双模型 text 模型 ACOP f(PLR, T_chw_s, T_cw_in, ...) 用于展示、解释、曲面查看 模型 BPower f(load, PLR, T_chw_s, T_cw_in, ...) 用于优化器真实计算冷机功率 主要功能 | 功能 | 说明 | | --- | --- | | 冷机识别 | 从历史数据中识别 chiller1、chiller2 等 | | 样本提取 | 提取每台冷机有效运行样本 | | 负荷率识别 | 判断负荷率是 0~1 还是 0~100 | | COP 拟合 | 拟合 COP 曲面 | | 功率拟合 | 拟合冷机功率模型 | | R2 / RMSE 评价 | 判断模型是否可靠 | | 曲线诊断 | 判断 COP 曲线是否异常、峰值 PLR 是否合理 | | 系数入库 | 保存最新 COP / Power 模型参数 | | 模型读取 | 给优化器和前端曲面展示使用 | 这个模块决定冷机性能画像和优化器功率计算的可靠性。 --- ### 5.3 chiller_group_control_service.py 实时冷机群控业务服务。 主要职责 text 读取最新实时工况 ↓ 读取设备铭牌参数 ↓ 读取设备拓扑配置 ↓ 读取最新冷机功率模型参数 ↓ 构造优化器输入参数 ↓ 调用 chiller_optimizer.optimize() ↓ 保存优化结果和控制指令 主要功能 | 功能 | 说明 | | --- | --- | | 实时冷负荷计算 | 根据冷冻水流量和供回水温差计算实时冷负荷 | | 参数装配 | 合并默认参数、数据库参数、拓扑参数、模型参数 | | 拓扑应用 | 将 equipment_topology 转换成优化器可用结构 | | 优化调用 | 调用冷机群控优化器 | | 结果压缩 | 去掉过大的 skipped_combinations 等内容 | | 结果入库 | 保存优化汇总和设备级控制指令 | | 默认参数初始化 | 初始化 equipment_specs 和 topology | 这个模块是未来做在线群控策略的核心入口。 --- ## 6. Algorithm 算法层设计 算法层只负责数学模型和计算不关心接口、Excel、数据库、前端。 --- ### 6.1 algorithm/optimizer/chiller_optimizer.py 冷机群控优化器。 当前核心逻辑 text 输入 - 实时冷负荷 demand - 冷机参数 - 冷冻泵参数 - 冷却泵参数 - 冷却塔参数 - 设备拓扑 - 环境约束 - 冷机功率模型参数 处理 1. 枚举冷机启停组合 2. 判断组合容量是否满足负荷 3. 根据拓扑枚举可用泵塔组合 4. 进行泵塔组合剪枝 5. 检查冷冻水侧能量平衡可行性 6. 检查冷却塔温度关系可行性 7. 使用 Pyomo 建立优化模型 8. 使用 IPOPT 求解 9. 选择总功率最低的方案 输出 - active_chillers - allocation - total_power - power_detail - control - commands - system_cop 优化目标 text minimize: P_total P_chillers P_chw_pumps P_cw_pumps P_towers 主要约束 | 约束 | 说明 | | --- | --- | | 冷机最小/最大负荷 | 每台冷机不能低于最小负荷不能高于最大负荷 | | 总负荷平衡 | 所有运行冷机负荷之和等于当前冷负荷 | | 冷冻水侧能量平衡 | demand Cp × F_chw × ΔT_chw | | 冷却侧能量平衡 | 冷却侧带走冷负荷 冷机耗功 | | 泵频率上下限 | 冷冻泵、冷却泵频率不能越界 | | 冷却塔频率上下限 | 冷却塔频率不能越界 | | 冷却塔出水温度关系 | 根据湿球温度、approach、塔频率估算冷却水进冷机温度 | | 温度边界 | 冷冻水供回水、冷却水进出水温度上下限 | 当前优化器已经支持 - 超过 4 台冷机的扩展。 - 多冷机组合枚举。 - 多冷冻泵、多冷却泵、多冷却塔。 - 公共母管共享泵组/塔组。 - 设备拓扑配置。 - 泵塔组合剪枝。 - IPOPT 求解参数配置。 - 历史报告批量优化加速。 --- ## 7. Mapper 数据访问层设计 ### 7.1 mapper/sqlite_mapper.py 当前项目使用 SQLite 作为本地数据存储。 主要职责 | 功能 | 对应数据 | | --- | --- | | 表读写 | 通用 read_table / write_table | | 表结构维护 | ensure_table_columns、迁移字段 | | 原始训练数据 | load_training_raw | | 未来天气数据 | future_weather_samples | | 实时控制输入 | control_inputs | | 设备铭牌参数 | equipment_specs | | 设备拓扑 | equipment_topology | | COP / Power 模型参数 | chiller_cop_coefficients | | 优化结果 | control_optimization_results | | 控制指令 | control_dispatch_results | 数据库核心表建议如下 text equipment_specs # 设备铭牌参数、环境约束、求解器配置 equipment_topology # 冷机与泵塔绑定关系 chiller_cop_coefficients # 冷机 COP / Power 模型系数 control_inputs # 实时工况输入 control_optimization_results # 优化结果汇总 control_dispatch_results # 设备级控制指令 load_training_raw # 负荷预测训练原始数据 future_weather_samples # 未来天气样本 --- ## 8. Config 配置层设计 ### 8.1 config/settings.py 负责项目运行级配置。 典型配置 | 配置 | 说明 | | --- | --- | | 数据库路径 | SQLite 文件位置 | | 报告输出路径 | 历史体检报告保存目录 | | IPOPT 路径 | ipopt.exe 所在路径 | | APP_MODE | online / offline | | HISTORY_OPTIMIZATION_WORKERS | 历史报告优化并发数 | | 文件上传限制 | 防止上传过大 Excel | | 定时任务配置 | COP 拟合、群控执行周期 | ### 8.2 config/chiller_params.py 默认算法参数配置。 主要包括 - 默认冷机参数。 - 默认冷冻泵参数。 - 默认冷却泵参数。 - 默认冷却塔参数。 - 默认环境约束。 - 默认求解器配置。 - 设备参数兜底值。 实际运行时数据库中的 equipment_specs 会覆盖默认参数。 --- ## 9. Tasks 定时任务层设计 ### 9.1 tasks/scheduler.py 定时任务模块。 当前规划任务 | 任务 | 说明 | | --- | --- | | scheduled_group_control_task | 定时执行实时群控优化 | | scheduled_chiller_cop_fit_task | 定时根据历史数据重新拟合 COP / Power 模型 | | start_scheduler | 启动调度器 | | stop_scheduler | 停止调度器 | 目标闭环 text 历史数据持续入库 ↓ 定时拟合冷机模型 ↓ 模型参数写入数据库 ↓ 实时优化时读取最新模型 ↓ 生成控制建议 ↓ 优化结果入库 --- ## 10. 前端模块设计 当前前端位于 text thingsboard/vue2/ 打包后输出到 text thingsboard/html/ 由 FastAPI 托管 text http://127.0.0.1:8003/html/ ### 10.1 当前主要页面 | 页面 | 功能 | | --- | --- | | 1数据是否可信 | 展示数据质量、可信度、WARN/FAIL、设备数据质量 | | 2钱浪费在哪里 | 展示平均节电功率、节能率、月节省、年节省、冷机性能线索 | | 3怎么优化 | 展示下一步动作、代表性优化样本、试运行建议 | | 冷机性能画像 | 展示 COP 曲面和功率曲面 | | 设备铭牌参数配置 | 维护设备容量、功率、流量、频率、环境约束 | | 设备拓扑配置 | 维护冷机允许绑定的泵塔关系 | ### 10.2 前端技术设计 text Vue2 ↓ axios 封装接口请求 ↓ 调用 FastAPI /integration 接口 ↓ 展示报告、配置、曲面图 --- ## 11. 核心业务流程设计 ### 11.1 历史节能体检流程 text 用户上传 Excel ↓ history_evaluation_controller ↓ history_evaluation_service ↓ 标准化字段、过滤无效行 ↓ chiller_cop_fit_service 拟合 COP / Power 模型 ↓ 逐行构造历史工况优化参数 ↓ chiller_optimizer.optimize() ↓ 汇总原始功率、优化功率、节能率 ↓ 生成三页报告数据 ↓ 生成 Excel 明细报告 ↓ 前端展示 / 用户下载 ### 11.2 实时群控优化流程 text 实时工况数据入库 ↓ 定时任务触发 ↓ chiller_group_control_service ↓ 读取最新工况 ↓ 读取 equipment_specs ↓ 读取 equipment_topology ↓ 读取最新 Power 模型参数 ↓ 构造 optimizer 参数 ↓ chiller_optimizer.optimize() ↓ 保存优化结果和设备指令 ↓ ThingsBoard / 前端查询结果 ### 11.3 冷机模型拟合流程 text 读取历史运行数据 ↓ 识别冷机编号 ↓ 提取每台冷机有效样本 ↓ 计算 PLR、COP、Power、温度特征 ↓ 拟合 COP 模型 ↓ 拟合 Power 模型 ↓ 计算 R2、RMSE、峰值 PLR、异常诊断 ↓ 保存模型系数 ↓ 前端曲面展示 / 优化器调用 --- ## 12. 当前项目的核心模块边界 后续继续保持这个边界 text controller 只做接口、参数、文件上传下载、响应封装。 service 做业务流程编排比如生成报告、执行群控、模型拟合。 algorithm 只做算法计算不直接读数据库不直接处理 HTTP。 mapper 只做数据库读写不写业务判断。 config 放默认参数、路径、运行模式、求解器配置。 tasks 放定时任务入口不写复杂业务。 一句话 text Controller 调 Service Service 调 Mapper 和 Algorithm Algorithm 只返回计算结果 Mapper 只负责数据持久化。 --- ## 13. 当前项目后续拆分 当前项目已经能用但后续如果继续工程化逐步拆成以下服务文件 text service/ history_evaluation_service.py # 保留历史体检主流程 report_generation_service.py # 可新增三页报告和 Excel 报告生成 equipment_config_service.py # 可新增设备参数、拓扑配置业务 chiller_model_service.py # 可新增COP / Power 模型管理 chiller_group_control_service.py # 保留实时群控主流程 algorithm/ optimizer/ chiller_optimizer.py # 保留优化器 topology_enumerator.py # 可新增设备组合枚举 feasibility_checker.py # 可新增可行性检查 power_model.py # 可新增冷机功率模型计算 mapper/ sqlite_mapper.py # 当前可以先保留 equipment_mapper.py # 后续可拆 model_coeff_mapper.py # 后续可拆 result_mapper.py # 后续可拆 短期不必强行拆太细。当前最重要的是让 text 冷机节能体检工具 ↓ 模型拟合 ↓ 优化计算 ↓ 报告输出
