stresslens-full-project

StressLens 可穿戴压力监测原型

本项目是一个“前后端 + 机器学习”的原型系统，用于演示基于腕带传感器（仿 Empatica E4 风格）的压力监测流程。它包含：

• 前端（Vite + React + TypeScript + Tailwind）：展示实时压力判定、概率、程度与生理指标，并呈现 AI 分析与健康建议
• 后端（FastAPI）：接收原始传感器数据，完成预处理与特征提取，加载已训练模型进行压力推理，并调用大模型生成建议
• 研究原型（Streamlit 仪表板）：完整的数据生成/加载、预处理、特征工程、模型训练与评估（LOSO），用于学术演示

重要提示：这是一个学术原型，侧重监测与决策支持演示，不是临床诊断工具。

---

目录结构

• 根目录（D:\stresslens-wesad-prototype-main）
  • main_api.py：后端 API 服务入口，提供 /predict 接口
  • llm_advisor.py：大模型建议生成器，从 .env 读取 Key/模型/地址
  • .env：本地开发环境变量（LLM_API_KEY、LLM_BASE_URL、LLM_MODEL）
  • stress_model_brain.pkl：已训练好的模型工件，供后端加载
  • health/health：前端工程（Vite + React + TS + Tailwind）
  • stresslens-wesad-prototype-main：研究原型（Streamlit 仪表板 + ML 管线）

前端（health/health）

• 主要文件：
  • package.json：依赖与脚本（dev/build/lint/preview）
  • vite.config.ts：Vite 配置（React 插件 + Babel React Compiler）
  • tsconfig.*.json：TypeScript 编译配置（应用与 Node 环境）
  • tailwind.config.js / postcss.config.js：样式与构建
  • index.html / src/main.tsx / src/App.tsx：页面入口与主界面
• 功能要点：
  • 每 10 秒向后端 /predict 发送 4Hz、约 60 秒窗口的模拟数据
  • 展示压力判定（Stress/Non-Stress）、概率、程度（正常/轻度/中度/重度）
  • 展示 EDA/BVP/TEMP/ACC 等生理指标，并呈现 AI 的中文分析与建议

后端 API（根目录）

• main_api.py：
  • 接收原始 JSON 传感器数据（字段：BVP、EDA、TEMP、ACC_x、ACC_y、ACC_z）
  • 计算 ACC_magnitude，进行信号清理（Butterworth 低通等）与“基准化”
  • 分窗（默认 60s，50% 重叠）、统计特征提取，加载模型进行推理
  • 根据概率划分压力程度，生成人类可读的指标报告与调用大模型生成建议
  • 默认端口示例：8001（可根据需要调整）
• llm_advisor.py：
  • 将压力推理结果与生理指标格式化为提示词，调用 LLM 输出 “【状态分析】/【健康建议】” 两段内容
  • 从 .env 读取 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL，支持开箱即用

研究原型（stresslens-wesad-prototype-main）

• app.py（Streamlit 仪表板）：
  • 多标签页：原始信号、预处理流程、窗口推理、压力片段汇总、LOSO 评估与特征重要性
  • 既支持真实 WESAD 数据（放入 wesad_data），也支持合成数据（默认）
• data_generator.py / preprocessing.py / feature_extraction.py / model.py：
  • 数据加载/生成、信号清理与标准化、滑窗特征工程、随机森林训练与评估（LOSO）
• train_offline.py / train_stepped.py：
  • 使用真实 WESAD 数据离线训练，生成 stress_model_brain.pkl 工件

数据集（wesad_data）压缩包

---

快速运行

1. 启动后端（FastAPI）

确保根目录下已有 stress_model_brain.pkl（若无可先按“训练模型”生成）。

# 在项目根目录
python .\\main_api.py
# 默认在 8001 端口监听；可修改代码中的 uvicorn.run 端口

2. 启动前端（Vite）

cd .\\health\\health
npm install
npm run dev
# 浏览器访问提示地址（默认 http://localhost:5173/），前端会请求后端 http://localhost:8001/predict

/predict 接口说明

POST http://localhost:8001/predict

请求体（示例，4Hz≈260 点，约 65 秒）：

{
  "data": [
    { "BVP": 72.0, "EDA": 2.1, "TEMP": 34.1, "ACC_x": 0.01, "ACC_y": 0.01, "ACC_z": 0.99 },
    ...
  ]
}

返回体（关键信息）：

• stress_analysis：prediction（Stress/Non-Stress）、probability（概率字符串）、confidence、stress_level（正常/轻度/中度/重度）
• metrics_report：人类可读的生理指标汇总（EDA/BVP/TEMP/ACC）
• ai_advice：LLM 输出的 “【状态分析】/【健康建议】”

注意：

• 实时预测使用“稳定基准值”归一化而非局部 Z-score，避免每窗均值为 0、方差为 1 导致强度变化不可识别。
• 若未配置 LLM 的 API Key，ai_advice 会提示无法提供个性化建议。

---

训练模型（生成 stress_model_brain.pkl）

前置：在 stresslens-wesad-prototype-main/wesad_data/ 放入真实 WESAD 受试者文件（例如 S2/S2.pkl、S3/S3.pkl 等）。

离线训练：

python .\\train_offline.py
# 完成后会在根目录生成 stress_model_brain.pkl

分步训练（内存受限时）：

python .\\train_stepped.py
# 逐个受试者提取特征，全部完成后合并训练并生成 stress_model_brain.pkl

---

配置与安全

• .env 用于本地开发，包含敏感密钥（LLM_API_KEY 等），请勿提交到公共仓库或外泄。
• 前端请求地址默认为 http://localhost:8001/predict，若调整后端端口或部署地址，请同步修改前端代码（src/App.tsx）。
• 这是教学/研究演示，真实部署还需考虑：设备佩戴一致性、运动伪迹、环境变化、数据隐私与安全、观测与标注的可靠性等。

---

常见问题

• 前端看不到建议：检查后端是否启动、端口是否一致；确认 .env 已配置有效的 LLM Key。
• /predict 返回数据不足：确保发送的数据至少覆盖一个 60 秒窗口；默认采样率按 4Hz 处理。
• 研究原型无真实数据：默认会使用合成数据；若需要真实 WESAD，请将受试者 S*/S*.pkl 放入 wesad_data/。

---

版权与致谢

• 数据与方法参考：WESAD（Schmidt et al., 2018），以及常见穿戴式压力检测文献的统计特征方法。
• 仪表板与代码为课程 COMP8230（Macquarie University）学术原型的一部分，仅供教学与研究演示。