基于fastapi和h5的ai智能脑机接口数据分析平台的设计与实现

一、整体架构概述

该系统采用前后端分离架构，基于 FastAPI 构建后端服务，前端采用原生 HTML/CSS/JavaScript 开发，核心实现 EEG（脑电波）和 HRV（心率变异性）数据的上传、分析、AI 解读及报告生成功能。
前端界面如图

架构分层

层级	技术栈	核心功能
前端层	HTML/CSS/JS + Font Awesome	数据上传、功能选择、结果展示、报告下载
后端层	FastAPI + 异步处理	接口提供、文件解析、数据预处理
算法层	NumPy/SciPy/PyWavelets	EEG 特征提取、信号滤波、时域 / 频域分析
AI 层	通义千问 API	智能分析报告生成、多维度解读
输出层	python-docx	Word 格式报告生成与下载

二、后端架构详解（FastAPI）

1. 项目结构与核心模块

├── 基础配置模块          # FastAPI初始化、跨域配置、API密钥管理
├── EEG业务处理模块       # 文件读取、数据解析、特征提取、滤波、报告生成
├── HRV业务处理模块       # Excel解析、数据清洗、预处理
├── AI调用模块           # 通义千问API调用、提示词工程
├── 联合分析模块         # EEG+HRV数据融合分析
├── 报告生成模块         # Word文档生成、样式配置
└── API接口模块          # 各功能接口定义

2. 核心模块详解

1. 基础配置模块

# FastAPI实例化
app = fastapi.FastAPI(
    title="脑机接口数据分析",
    description="基于阿里云通义千问的脑机接口数据分析api",
    version="1.0.0",
    max_request_body_size=10 * 1024 * 1024  # 10MB请求限制
)

# 跨域配置
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 生产环境需指定具体域名
    allow_credentials=False,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 通义千问API密钥配置
api_key = os.getenv("DASHSCOPE_API_KEY")
dashscope.api_key = api_key

2. EEG 业务处理模块

核心功能链：文件读取 → 数据解析 → 信号滤波 → 特征提取 → 报告生成

• 文件读取：read_eeg_content() - 清洗原始文本数据，统一换行符
• 数据解析：parse_eeg_data() - 解析 A/B 通道数据，转换为 NumPy 数组
• 信号滤波：preprocess_eeg() - 基线漂移去除 + 50Hz 陷波滤波 + 带通滤波
• 特征提取：extract_eeg_features()
• 时域特征：均值、标准差、偏度、峰度、过零率等
• 频域特征：功率谱密度（PSD）、经典频段功率（δ/θ/α/β/γ）
• 时频特征：小波熵、小波能量
• 报告生成：generate_eeg_report() - 结构化特征报告，含临床解读

3. HRV 业务处理模块

• 文件解析：read_fake_excel() - 支持.xls/.xlsx 格式，自动识别文件类型
• 数据预处理：data_preprocess() - 列名标准化、时间格式转换、缺失值处理

4. AI 调用模块

• 提示词工程：choose_function()/generate_prompt() - 针对不同分析类型定制提示词
• API 调用：call_qianfan_ai()/generate_hrv_report() - 封装通义千问 API 调用

5. 核心接口定义

接口路径	请求方法	功能	请求参数
/eeg/analyze	POST	EEG 数据分析	file (.txt) + function (分析类型)
/hrv/analyze	POST	HRV 数据分析	file (.xls/.xlsx) + function (分析类型)
/both/analyze	POST	联合分析	eeg_file + hrv_file + background
/report	POST	生成 Word 报告	content + name

3. 异步处理优化

所有耗时操作（文件处理、AI 调用、报告生成）均使用asyncio.to_thread()实现异步处理：

# 异步调用同步函数
eeg_report = await asyncio.to_thread(analyze_data, content)
output = await asyncio.to_thread(call_qianfan_ai, eeg_report, function)

三、前端架构详解

1. 页面结构

头部：

eeg(脑电波)分析部分：

hrv(心率变异率)分析部分：

联合分析部分：

报告生成部分(生成word)：

├── 头部区域          # Logo + 系统标题
├── EEG分析模块       # 文件上传 + 功能选择 + 结果展示
├── HRV分析模块       # 文件上传 + 功能选择 + 结果展示
├── 联合分析模块      # 文件状态 + 背景信息 + 联合分析 + 报告生成
└── 通用样式/脚本     # 样式配置 + 通用函数

2. 核心功能模块

1. 文件上传模块

• 支持拖拽 / 点击上传
• 文件格式校验（EEG:.txt，HRV:.xls/.xlsx）
• 文件大小限制（100MB）
• 上传状态展示

// EEG文件选择处理
function handleEEGFileSelect(e) {
    const file = e.target.files[0];
    if (!file) return;
    
    // 格式校验
    if (!file.name.endsWith('.txt') && file.type !== 'text/plain') {
        alert('请上传TXT格式的EEG文件！');
        return;
    }
    
    // 大小校验
    if (file.size > 100 * 1024 * 1024) {
        alert('文件大小不能超过100MB！');
        return;
    }
    
    // 保存文件对象，更新UI
    eegSelectedFile = file;
    // ...
}

2. 功能选择模块

• 卡片式功能选择
• 选中状态可视化
• 按钮状态联动（未选择 / 未上传时禁用）
  上传前：
  
  上传后：
  

3. 数据分析模块

• 加载状态展示（Spinner 动画）
  

• 异步接口调用

• 结果格式化渲染
  

• 错误处理

// EEG分析请求处理
async function handleEEGAnalyze() {
    // 显示加载动画
    eegEl.loading.classList.add('show');
    
    try {
        // 构建FormData
        const formData = new FormData();
        formData.append('file', eegSelectedFile); 
        formData.append('function', currentFunction); 

        // 调用API
        const response = await fetch(eegBaseUrl, {
            method: 'POST',
            body: formData
        });
        
        // 处理响应
        const result1 = await response.json();
        const result = result1.output;
        
        // 渲染结果
        renderFormattedResult(result, eegEl.resultContent);
    } catch (error) {
        // 错误处理
        eegEl.resultContent.innerHTML = `<div style="color: red;">分析失败：${error.message}</div>`;
    } finally {
        // 隐藏加载动画
        eegEl.loading.classList.remove('show');
    }
}

4. 报告生成与下载模块

• 姓名输入校验

• 异步调用报告生成接口
  报告示例（小黑子版）：
  

• Blob 文件流处理

• 浏览器下载触发

async function handleDownloadReport() {
    // 校验输入
    const userName = nameInput.value.trim();
    if (!userName) {
        alert('请先输入报告对应的姓名！');
        return;
    }
    
    try {
        // 构建FormData
        const formData = new FormData();
        formData.append('name', userName);
        formData.append('content', analysisCache.combine);

        // 调用报告生成接口
        const res = await fetch(report_baseurl, {
            method: 'POST',
            body: formData,
        });

        // 处理文件下载
        const blob = await res.blob();
        const a = document.createElement('a');
        a.href = URL.createObjectURL(blob);
        a.download = `${userName}综合评估报告.docx`;
        a.click();
        
        // 清理资源
        URL.revokeObjectURL(a.href);
    } catch (error) {
        alert(`报告下载失败：${error.message}`);
    }
}

3. 通用工具函数

• formatFileSize() - 文件大小格式化（Bytes→KB/MB/GB）
• renderFormattedResult() - 分析结果格式化渲染
• renderReportContent() - 报告内容专用渲染

四、关键技术亮点

1. 信号处理技术

• EEG 滤波链：基线漂移去除（0.1Hz 高通）→ 50Hz 陷波滤波 → 0.5-50Hz 带通滤波
• 特征提取：结合时域、频域、时频域多维度特征
• 小波分析：基于 db4 小波基的多尺度分解，计算小波熵

2. AI 提示词工程

针对不同分析场景定制专业化提示词，确保 AI 输出符合医疗 / 分析规范：

1. EEG 特征分析
2. 脑功能与认知评估
3. 大脑优缺点分析
4. 性格分析
   HRV 压力 / 情绪 / 社交分析
   联合分析（EEG+HRV）
5. 异步处理优化
   后端：所有 CPU/IO 密集型操作通过asyncio.to_thread()异步执行
   前端：使用async/await处理 API 请求，避免页面阻塞
6. 文档生成技术
   基于 python-docx 实现 Word 文档动态生成
   自定义样式：字体、行距、页眉、标题层级
   流式输出：通过BytesIO实现内存文档生成，支持直接下载

五、系统交互流程

1. 用户上传EEG/HRV文件 → 前端校验格式/大小
2. 用户选择分析功能 → 前端更新按钮状态
3. 用户点击分析 → 前端显示加载动画，调用后端API
4. 后端接收文件 → 解析/预处理/特征提取 → 调用AI生成分析报告
5. 后端返回分析结果 → 前端格式化展示
6. （联合分析）用户输入背景信息 → 后端融合EEG+HRV数据 → AI生成综合报告
7. 用户生成报告 → 后端生成Word文档 → 前端触发下载  

六、扩展性与可维护性

1. 模块化设计

各功能模块解耦，便于单独维护 / 升级
提示词与业务逻辑分离，便于调整 AI 输出风格

2. 异常处理

后端：完善的异常捕获与 HTTP 状态码返回
前端：友好的错误提示，加载状态管理

3. 配置化管理

API 密钥通过环境变量配置
文件格式 / 大小限制可配置
AI 模型参数（temperature/top_p/max_tokens）可调整

4. 兼容性

前端：响应式设计，适配移动端 / 桌面端
后端：支持多种文件格式（.txt/.xls/.xlsx）
字符编码：统一使用 UTF-8，避免中文乱码
该架构兼顾了专业性（脑电信号处理）、智能化（AI 分析）和易用性（前端交互），同时保持了良好的扩展性和可维护性。

最后，如果觉得项目有意思的话，就赏点小鱼干吧喵