NeuroFlow 将公开 EEG 数据、信号质量控制、分类模型、实时推理服务和浏览器可视化整合为一套可复现的脑机接口研究原型。
版本：v3.0。 本项目用于研究、教学和工程验证，不用于医疗诊断、治疗决策或高风险设备控制。
| 模块 | 实现内容 |
|---|---|
| 数据 | PhysioNet EEG Motor Movement/Imagery，5 位被试、64 通道、160 Hz |
| 质量控制 | 平坦/异常通道、振幅阈值、工频噪声、标签平衡、C3/Cz/C4 功率谱 |
| 模型 | 手工 CSP、手工 LDA、scikit-learn 基线、PyTorch EEGNet |
| 评估 | Runs 4+8 训练、Run 12 测试，按运行划分数据 |
| 实时服务 | FastAPI、REST、WebSocket、100 ms 数据包、4 秒推理窗口 |
| 前端与存储 | Canvas 波形、质量报告、模型对比、系统指标、SQLite 实验记录 |
| 数据源扩展 | PhysioNet 回放、模拟设备协议、LSL/厂商 SDK 适配接口 |
| 工程支持 | Docker、OpenAPI、P50/P95/P99 延迟、25 项测试、GitHub Actions |
flowchart LR
A["PhysioNet EDF<br/>或 EEG 硬件"] --> B["可插拔 EEGSource"]
B --> C["质量控制<br/>PSD / 振幅 / 噪声"]
B --> D["MNE 预处理<br/>8–30 Hz / 4 s Epoch"]
D --> E1["CSP + LDA"]
D --> E2["EEGNet"]
E1 --> F["FastAPI 推理服务"]
E2 --> F
F --> G["WebSocket 实时波形"]
F --> H["REST / OpenAPI"]
F --> I["SQLite 实验记录"]
G --> J["浏览器仪表盘"]
H --> J
I --> J
组件职责和数据流见 系统架构。
实验协议：每位被试使用 Runs 4+8 训练，Run 12 独立测试，信号采用 8–30 Hz 带通滤波。
| 模型 | Mean Accuracy | Mean Macro-F1 |
|---|---|---|
| CSP + LDA | 60.00% | 55.29% |
| EEGNet | 50.67% | 37.31% |
在当前小样本跨运行设置下，CSP + LDA 的结果高于 EEGNet。该结果仅适用于当前数据和实验协议；跨被试泛化仍需通过更多被试、重复实验和置信区间验证。
服务启动后可访问以下页面：
| 页面 | 地址 | 主要内容 |
|---|---|---|
| 实时推理 | http://127.0.0.1:8020/ |
数据源切换、设备状态、实时波形和预测 |
| 数据质量 | http://127.0.0.1:8020/quality |
被试质量报告、PSD 和 SQLite 实验记录 |
| 模型对比 | http://127.0.0.1:8020/static/real.html |
CSP+LDA 与 EEGNet 结果 |
| 系统信息 | http://127.0.0.1:8020/system |
组件架构、运行环境和延迟指标 |
| API 文档 | http://127.0.0.1:8020/docs |
Swagger/OpenAPI 接口 |
页面操作步骤见 使用手册。
git clone <repository-url>
cd NeuroFlow
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\run_fullstack.ps1首次请求真实数据时，MNE 会将公开 EDF 下载到本地 data/。该目录不会提交到 Git。
docker build -t neuroflow .
docker run --rm -p 8020:8020 neuroflow$env:PYTHONPATH="backend"
$env:_MNE_FAKE_HOME_DIR="$PWD\data\mne-config"
$env:MPLCONFIGDIR="$PWD\data\matplotlib-config"
.\.venv\Scripts\python.exe -m unittest discover -s tests -v当前测试数量：25。
| 协议 | 路径 | 说明 |
|---|---|---|
| GET | /api/health |
服务状态和版本 |
| GET | /api/sources |
EEG 数据源目录 |
| GET | /api/benchmark |
5 被试模型结果 |
| GET | /api/quality/{subject} |
单被试质量报告与 PSD |
| GET | /api/experiments |
SQLite 实验记录 |
| GET | /api/system/metrics |
推理延迟与运行环境 |
| WS | /ws/stream?source=... |
EEG 数据包、设备状态和预测结果 |
NeuroFlow/
├── backend/app/ # 信号处理、模型、API、WebSocket、SQLite
├── frontend/ # Canvas 仪表盘
├── scripts/ # 数据下载、训练和基准测试
├── tests/ # 单元测试与接口测试
├── docs/ # 使用、架构、算法和硬件说明
├── outputs/ # 可复现实验摘要
├── models/ # JSON 训练摘要（不提交模型权重）
├── Dockerfile
└── run_fullstack.ps1
physionet_replay：公开 EEG 的伪实时回放。mock_hardware：使用公开 EEG 模拟设备数据包、时间戳和状态。lsl_hardware：接口已规划，尚未连接真实设备。
模拟设备只用于验证传输协议。现有模型基于 64 通道 PhysioNet 数据训练，接入不同通道或采样率的设备后需要重新校准和训练。参见 硬件接入。
- 真实 EEG、质量控制和模型对照
- REST、WebSocket、SQLite 和浏览器仪表盘
- 多被试基准与推理延迟
- 可插拔数据源与模拟设备协议
- 跨被试验证、bootstrap 置信区间和统计检验
- LSL/厂商 SDK 设备适配器
- 校准流程、模型注册与版本管理
- 页面截图和运行视频
- 本项目是研究原型，不是医疗器械。
- “实时”指离线数据分块回放；未连接硬件时不代表真实采集。
- 质量规则是启发式检查，不构成临床判断。
- 当前结果来自 5 位被试，不能代表普遍人群性能。
- 不应使用自制、未隔离的电路直接连接人体。
提交问题或改动前请阅读 CONTRIBUTING.md。