acoustic_algo_scheduler/docs/水声算法全协议集成与调度平台 - 技术实施方案文档.md

# 水声算法全协议集成与调度平台 - 技术实施方案文档
文档信息
项目	内容
文档版本	V1.0
编写日期	2026.01
适用范围	软件研发、模块开发、技术实现、测试部署
研发团队	2-3 人，核心技术栈 Python
一、技术方案总体设计
1.1 设计理念
基于 **“轻量化、插件化、标准化、低耦合”** 核心设计理念，贴合微型研发团队能力，优先采用 Python 生态成熟技术，同时融合 C/C++ 高性能计算优势，打造 “上层 Python 调度交互 + 底层 C/C++ 高性能计算” 的混合技术栈，实现多语言算法统一适配，同时预留工业级拓展接口。
1.2 整体架构
采用分层式 + 插件化架构设计，分为用户交互层、核心调度层、桥接插件层、算法层、数据层五层，所有层之间通过标准化协议对接，低耦合、可插拔，便于开发、维护与拓展。
plaintext
用户交互层（Web界面）←→核心调度层（标准化内核）←→桥接插件层（语言专属）←→算法层（标准/自研，多语言）
                                        ↓
                                  数据层（标准化中间数据）
1.2.1 各层核心职责
用户交互层：基于 Streamlit 实现 Web 可视化界面，负责算法上传、接口配置、流程组合、异常展示、日志查看等客户操作，为客户提供零代码交互体验；
核心调度层：软件核心内核，负责标准化中间数据管理、算法流程调度、接口实时校验、全流程容错、日志记录，是所有功能的调度中枢；
桥接插件层：包含 Python/MATLAB/C/C++ 语言专属桥接插件，负责跨语言数据转换、算法调用、编译封装，屏蔽语言差异，对上层暴露标准化接口；
算法层：包含官方标准算法库与客户自定义算法库，所有算法均为黑盒化插件，遵循标准化接口协议；
数据层：以 WaterSoundData 为核心，负责全流程数据的存储、流转与管理，同时包含日志、报告、模板等持久化数据的存储。
1.3 核心设计原则
标准化：定义统一的标准化中间数据格式、黑盒插件协议、跨语言数据转换协议，所有模块均遵循标准化协议对接；
插件化：桥接插件、预处理算子、算法黑盒均为可插拔式设计，新增 / 修改 / 删除不影响核心内核；
低耦合：各层之间、模块之间通过标准化接口对接，无直接代码依赖，便于单独开发、测试与迭代；
轻量化：优先采用 Python 轻量开源库，避免重型框架，保证客户侧部署零成本、运行低资源；
容错性：全流程融入容错设计，从配置到执行层层校验、兜底，保证系统稳定性；
可拓展：预留算法语言、预处理算子、功能模块的拓展接口，支持后续快速升级，同时预留 C++/Qt 工业级拓展接口，无技术断层。
二、核心技术选型
2.1 开发语言
主开发语言：Python3.8+（团队核心技术栈，开发效率高，生态丰富，跨平台，轻量）；
辅助语言：C/C++（仅用于 C/C++ 算法编译为动态链接库，无需自研业务代码）。
2.2 核心技术栈与第三方库
按功能模块梳理核心技术 / 库，均为工业级成熟方案，无前沿未验证技术，降低研发风险：
功能模块	核心技术 / 第三方库	核心作用
用户交互层	Streamlit	极简开发 Web 可视化界面，支持下拉、拖拽、实时校验、日志展示，无需前端开发
核心调度层	Python 原生 OOP、dataclasses、logging、json	实现标准化中间数据定义、流程调度、实时校验、结构化日志、数据持久化
桥接插件层	Python：原生调用
MATLAB：matlab.engine、oct2py
C/C++：ctypes、cffi	跨语言数据转换、算法调用，oct2py 为 MATLAB 无授权兜底，ctypes/cffi 实现 C/C++ 库加载
C/C++ 编译模块	MinGW/GCC、Python subprocess/os/glob	自动检测编译器、生成编译脚本，将 C/C++ 文件编译为跨平台动态链接库
数据处理模块	NumPy、SciPy	水声算法核心数据处理，与现有水声算法代码无缝兼容，实现数组、矩阵操作
性能优化模块	Python multiprocessing、mmap（内存映射）	实现非依赖型算法并行调度、大体积数据分块处理、内存级高性能数据传递
数据持久化模块	Python 原生文件操作（.npy/.mat/.bin/.json/.pdf/Excel）	实现算法版本、模板、日志、报告、数据的存储与导出，无需复杂数据库
报告生成模块	reportlab、pandas	实现检测报告、对比报告的生成与导出（PDF/Excel 格式）
2.3 技术栈优势
研发效率高：Python 生态成熟，Streamlit 快速实现 Web 界面，无需前端 / 后端分离开发，2-3 人团队 1-2 周可完成核心功能开发；
客户侧零成本：跨平台免编译，仅需 Python 运行环境，轻量依赖一键安装，拷贝即可运行；
低耦合可拓展：插件化设计，新增功能 / 算法语言仅需开发对应插件，无需重构核心代码；
性能有保障：融合 C/C++ 高性能计算优势，内存映射实现无损耗数据传递，满足水声算法处理需求；
维护成本低：Python 代码简洁可读性强，模块化设计，团队可互相维护，客户问题可快速定位解决。
三、核心模块技术实现
3.1 标准化中间数据模块（数据层核心）
3.1.1 数据定义
基于 Python dataclasses定义WaterSoundData类，作为全流程唯一数据交换标准，包含基础数据、过程数据、结果数据、元信息四大类字段，支持动态扩展字段，适配个性化需求：
python
from dataclasses import dataclass
import numpy as np
from typing import Dict, Optional, List

@dataclass
class WaterSoundData:
    # 基础原始数据
    raw_data: np.ndarray          # 原始声呐数据
    sample_rate: float            # 采样率
    collect_time: str             # 数据采集时间
    sea_env: Dict = None          # 海洋环境参数（声速、温度、盐度等）
    # 处理过程数据
    clean_data: Optional[np.ndarray] = None  # 清洗后数据
    denoised_data: Optional[np.ndarray] = None# 降噪后数据
    stft_data: Optional[np.ndarray] = None   # STFT时频数据
    feat_data: Optional[np.ndarray] = None   # 特征数组
    # 结果数据
    final_result: Optional[np.ndarray] = None# 最终处理结果
    core_index: Dict = None        # 核心指标（信噪比、数据完整性等）
    vis_data: Dict = None          # 可视化数据
    # 元信息
    status: str = "init"           # 数据状态：init/processing/finished/error
    error_info: str = ""           # 错误信息
    log: List[Dict] = None         # 执行日志
    algo_version: Dict = None      # 算法版本记录
3.1.2 核心方法
为 WaterSoundData 类实现数据更新、日志添加、错误记录、数据保存 / 加载等核心方法，支持全流程数据的动态管理与溯源。
3.2 桥接插件层实现
采用插件化工厂模式，为每种语言开发独立的桥接插件，核心实现数据转换与算法调用两大功能，对外暴露统一的call_algo方法，核心调度层无需感知语言差异。
3.2.1 Python 桥接插件（最简）
直接调用 Python 函数，实现标准化数据与 Python 算法输入输出的映射，核心代码示例：
python
class PythonBridge:
    def __init__(self, algo_func, input_mapping, output_mapping):
        self.algo_func = algo_func  # Python算法核心函数
        self.input_mapping = input_mapping  # 输入映射关系
        self.output_mapping = output_mapping# 输出映射关系

    def call_algo(self, water_data: WaterSoundData) -> WaterSoundData:
        # 提取标准化输入并映射
        algo_input = [getattr(water_data, k) for k in self.input_mapping.values()]
        # 调用算法
        algo_output = self.algo_func(*algo_input)
        # 输出映射回标准化数据
        for k, v in zip(self.output_mapping.keys(), algo_output):
            setattr(water_data, k, v)
        return water_data
3.2.2 MATLAB 桥接插件
基于matlab.engine/oct2py实现，自动完成 numpy 数组与 MATLAB 矩阵的转换，核心实现引擎自动管理、数据转换、容错兜底：
调用前自动检测 MATLAB 环境，有则用matlab.engine，无则切换oct2py；
实现 numpy.ndarray ↔ matlab.double/oct2py.Array 的无损转换；
引擎调用失败则切换为.mat文件桥接模式，通过文件实现数据传递。
3.2.3 C/C++ 桥接插件
核心实现C/C++ 文件编译与动态链接库调用两大功能，同时完成 numpy 数组与 C/C++ 指针 / 数组的高性能转换：
自动编译：检测客户编译器，自动生成编译脚本，将 C/C++ 文件编译为.dll（Windows）/.so（Linux）/.dylib（macOS）；
库加载：通过ctypes加载动态链接库，绑定核心函数；
数据转换：采用内存映射实现 numpy 数组与 C/C++ 指针的直接映射，无数据拷贝，保证高性能；
参数传递：自动传递数组长度、维度等信息，保证 C/C++ 算法正确执行。
3.3 核心调度层实现
核心调度层是软件的 “大脑”，负责接口校验、流程调度、容错处理、日志记录，基于状态机模式实现算法流程的自动化调度，核心流程：
流程解析：解析客户拖拽的流程 / 文字指令生成的流程，得到算法黑盒列表与执行顺序；
全局校验：校验算法之间的接口衔接性，生成校验报告；
初始化：初始化 WaterSoundData，加载输入数据；
按序调度：遍历算法黑盒列表，依次调用对应桥接插件的call_algo方法，传递 WaterSoundData；
容错处理：若某算法调用失败，触发容错机制（隔离 / 兜底），记录错误信息，继续调度后续算法；
结果处理：所有算法执行完成后，生成处理结果与报告，更新 WaterSoundData 状态为finished。
3.3.1 实时校验模块实现
基于规则引擎实现接口配置的实时校验，将 5 类校验规则封装为独立的校验函数，配置操作触发时实时调用，返回校验结果与错误信息，核心示例：
python
def check_field_exist(water_data, field_name, pre_algo_list):
    """字段存在性校验"""
    if hasattr(water_data, field_name):
        if getattr(water_data, field_name) is not None:
            return True, ""
    # 校验前序算法是否能生成该字段
    field_algo_map = {"stft_data": "STFT", "denoised_data": "Denoise"}
    if field_name in field_algo_map and field_algo_map[field_name] not in pre_algo_list:
        return False, f"该字段未生成，前序流程需添加{field_algo_map[field_name]}算法"
    return False, f"字段{field_name}不存在或未初始化"
所有校验函数通过统一的校验入口调用，若有任意一个校验失败，弹窗提示并禁止保存配置。
3.3.2 容错处理模块实现
基于异常捕获 + 策略模式实现三层容错，将不同的容错策略封装为独立的函数，根据错误类型自动触发对应策略：
配置阶段：校验函数返回 False 则触发拦截策略，禁止保存；
转换阶段：数据转换异常则触发自动修复策略（维度展平、类型转换等），修复后继续执行；
执行阶段：算法调用异常则触发隔离策略/兜底策略，根据算法重要性自动选择，核心示例：
python
def fault_tolerance(water_data, algo_black_box, error_type, error_info):
    """容错处理主函数"""
    water_data.error_info = error_info
    water_data.log.append({"step": algo_black_box.name, "error": error_type, "info": error_info})
    # 核心算法，触发兜底策略
    if algo_black_box.is_core:
        water_data.log.append({"step": algo_black_box.name, "action": "启用兜底标准算法"})
        core_algo = get_standard_algo(algo_black_box.func_type)  # 获取同功能标准算法
        return core_algo.call_algo(water_data)
    # 非核心算法，触发隔离策略
    else:
        water_data.log.append({"step": algo_black_box.name, "action": "算法隔离，继续执行后续流程"})
        water_data.status = "part_error"
        return water_data
3.4 用户交互层实现
基于Streamlit实现 Web 可视化界面，无需前端开发，纯 Python 代码实现所有交互功能，核心设计原则：简洁直观、功能分区、操作引导，界面分为算法库管理、接口配置、流程调度、海试模式、异常中心、日志报告六大功能区，核心实现：
算法上传：通过st.file_uploader实现文件上传，支持多文件 / 压缩包，配合输入框获取算法名称、核心函数名等信息；
接口配置：通过st.selectbox实现字段下拉选择，st.button实现预处理算子添加，实时调用校验函数，st.error实现错误提示；
流程组合：通过st.columns+st.drag_and_drop实现算法拖拽排序，生成流程列表；
执行调度：通过st.button触发调度函数，st.progress实现进度条，st.text实现实时日志展示；
异常中心：通过st.expander实现异常信息折叠展示，配合st.button实现一键修复；
日志报告：通过st.dataframe展示日志，st.download_button实现日志 / 报告导出。
Streamlit 实现的界面支持本地离线运行，无需搭建服务器，客户启动命令仅需：streamlit run main.py，操作极简。
3.5 海试专属模块实现
基于核心调度层做轻量化定制，隐藏复杂配置功能，仅保留核心操作，核心实现：
模式切换：通过 Web 界面一键切换 “科研模式 / 海试模式”，海试模式下仅显示 “数据上传、一键检测、报告导出” 三个核心模块；
专属流程：内置海试数据质量检测流程模板，无需客户配置，直接调用；
快速执行：关闭并行调度、非核心日志记录等功能，优化资源占用，提升执行速度；
简洁报告：定制海试专属检测报告，突出核心指标、检测结论、处理建议，支持 PDF/Excel 快速导出。
四、研发与部署计划
4.1 研发计划（2-3 人团队，总周期 3 周，分阶段执行）
阶段 1：核心框架开发（第 1 周）
完成标准化中间数据模块、核心调度层、Python/MATLAB 桥接插件开发；
完成基础 Web 界面（算法库管理、简单接口配置）开发；
实现单语言算法的上传、调用、执行核心流程。
阶段 2：功能完善（第 2 周）
完成 C/C++ 桥接插件、自动编译模块开发，支持 C/C++ 算法上传与调用；
完成接口配置实时校验、容错处理模块开发；
完成流程调度、文字指令解析功能开发；
完善 Web 界面，实现流程拖拽、异常展示、日志记录功能。
阶段 3：优化与测试（第 3 周）
完成海试专属模块、报告生成模块开发；
完成性能优化（分块处理、并行调度、内存映射）；
进行全功能测试、性能测试、稳定性测试，修复 bug；
完成用户操作手册、技术文档编写，打包产品。
4.2 测试计划
分单元测试、集成测试、系统测试、客户试用测试四个阶段，由研发团队自行完成，贴合微型团队特点：
单元测试：各模块开发完成后，编写单元测试用例，测试核心函数的正确性；
集成测试：各模块集成后，测试模块之间的对接是否正常，跨语言算法调用是否稳定；
系统测试：按需求文档验收标准，测试全功能、性能、稳定性、易用性；
客户试用测试：邀请 2-3 家目标客户试用，收集反馈，修复问题，优化体验。
4.3 部署与交付计划
4.3.1 产品打包
核心代码：保留纯 Python 脚本，方便后续升级与定制；
便携包：通过pyinstaller将核心代码打包为单文件可执行程序（Windows/.exe、Linux/.bin、macOS/.app），客户无需安装 Python，双击即可运行；
配套文件：包含用户操作手册、技术支持联系方式、一键安装依赖脚本。
4.3.2 客户侧部署
客户侧部署零配置、零成本，两种部署方式：
脚本运行：客户安装 Python3.8+，解压产品包，运行install_deps.py一键安装依赖，再运行streamlit run main.py启动软件；
可执行程序运行：直接解压便携包，双击可执行程序即可启动，无需安装任何环境。
4.3.3 交付物
软件产品包（脚本版 + 便携版）；
《用户操作手册》（图文版，含操作步骤、常见问题解决）；
《技术支持手册》（含联系方式、问题反馈流程）；
算法示例包（含官方标准算法、多语言算法示例）。
五、长远技术迭代与拓展
5.1 短期迭代（0-6 个月）
基于客户反馈优化 Web 界面体验，完善预处理算子库，新增水声行业专属预处理算子；
支持更多算法语言（如 Fortran/Julia），仅需开发对应桥接插件；
优化 C/C++ 编译与调用逻辑，提升高性能计算效率；
增加算法参数可视化调参功能，支持客户在 Web 界面直接修改算法参数。
5.2 中期迭代（6-18 个月）
增加团队协作功能，支持多用户共享算法库、模板，实现权限管理；
增加GPU 加速支持，对接 CUDA，实现大体积数据 GPU 加速处理；
优化数据处理模块，支持更多水声行业数据格式；
开发远程技术支持模块，实现日志远程上传、问题快速定位。
5.3 长期拓展（18 + 个月，工业级方向）
基于现有标准化协议，实现向 C++/Qt 工业级系统的平滑拓展，核心步骤：
基于 C++ 重构核心调度层，复用现有 WaterSoundData 标准化数据定义，保证数据互通；
将现有 Python 桥接插件移植为 C++ 版本，支持多语言算法调用；
基于 Qt 开发工业级可视化界面，支持硬件对接（声呐采集卡、FPGA、GPU）；
形成 **“Python 轻量化科研工具”+“C++/Qt 工业级系统”** 双产品体系，实现科研与工程的无缝衔接。
六、风险评估与应对措施
风险类型	具体风险	应对措施
技术风险	C/C++ 跨平台编译兼容性问题	统一采用 MinGW/GCC 编译器，生成跨平台动态链接库，增加编译失败兜底方案
技术风险	MATLAB 无授权导致调用失败	集成 oct2py 开源库，自动检测 MATLAB 环境，无授权则自动切换 oct2py 兜底
性能风险	大体积数据处理效率低	实现自动分块处理、内存映射、并行调度，优化数据转换逻辑，无拷贝传递
研发风险	团队人员少，研发进度滞后	采用模块化开发，优先实现核心功能，非核心功能可后期迭代；合理分配任务，聚焦核心模块
客户风险	客户操作习惯不适应，上手困难	编写详细的图文操作手册，界面增加操作引导弹窗，提供 1v1 技术支持与操作培训
客户风险	客户自研算法复杂，适配失败	提供极简代码扩展方式，增加自定义预处理插件，同时提供专业的算法适配技术支持
七、质量保障
代码质量：遵循 Python PEP8 编码规范，添加详细的代码注释，核心函数编写文档字符串，保证代码可读性与可维护性；
测试覆盖：单元测试覆盖核心函数，集成测试覆盖模块对接，系统测试覆盖全功能，测试用例包含正常场景与异常场景；
文档完善：编写完整的需求文档、技术实施方案文档、用户操作手册、技术支持手册，保证研发、测试、交付、使用全流程有文档可依；
持续优化：基于客户反馈，建立 bug 修复与功能迭代机制，定期发布小版本更新，提升软件质量与体验。
八、总结
本技术实施方案基于 Python 生态，融合 C/C++ 高性能计算优势，采用分层式 + 插件化架构设计，贴合 2-3 人微型水声算法团队的研发能力与节奏，能快速实现软件的开发、测试与部署。方案既满足当前目标客户（高校 / 研究所 / 海试）的轻量化、零门槛、多语言适配核心需求，又预留了长远的工业级拓展接口，实现 “科研工具→工业级系统” 的平滑迭代。
软件的核心价值并非技术栈本身，而是通过标准化、插件化、容错化的设计，为水声算法研发人员解决工程适配痛点，让客户聚焦算法本身，同时为公司打造水声算法调度领域的差异化竞争力，支撑商业长远发展。