# SleepFocus-AI：从睡眠数据预测认知表现的机器学习评估框架

> 一个端到端的机器学习研究项目，探索如何通过睡眠和生活方式数据预测次日认知表现，同时深入分析模型泄漏风险与可解释性，最终部署为可交互的研究原型。

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-06-15T01:16:00.000Z
- 最近活动: 2026-06-15T01:18:11.205Z
- 热度: 146.0
- 关键词: machine learning, sleep analysis, cognitive performance, SHAP, explainable AI, data leakage, FastAPI, responsible AI, regression, health informatics
- 页面链接: https://www.zingnex.cn/forum/thread/sleepfocus-ai
- Canonical: https://www.zingnex.cn/forum/thread/sleepfocus-ai
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：NguyenThanhHaii
- 来源平台：github
- 原始标题：SleepFocus-AI
- 原始链接：https://github.com/NguyenThanhHaii/SleepFocus-AI
- 来源发布时间/更新时间：2026-06-15T01:16:00Z

## 原作者与来源\n\n- **原作者/维护者**: NguyenThanhHaii\n- **来源平台**: GitHub\n- **原始标题**: SleepFocus-AI: Evaluation of Machine Learning Models in Predicting Cognitive Performance from Sleep Data and Lifestyle\n- **原始链接**: https://github.com/NguyenThanhHaii/SleepFocus-AI\n- **发布时间**: 2026年6月15日\n\n---\n\n## 项目概述\n\nSleepFocus-AI 是一个学术性的机器学习研究原型，旨在通过睡眠和生活方式相关数据来估算次日的认知表现得分。该项目不仅关注预测准确性，更深入探讨了机器学习工程中的关键问题：数据泄漏、模型可解释性以及负责任的AI部署。\n\n项目的核心研究问题是：**机器学习模型能否以准确、可解释且适合部署的方式，从睡眠和生活方式数据中估算认知表现？**\n\n值得注意的是，该项目明确声明其非医疗性质——它不能用于诊断睡眠障碍、提供医疗建议或替代专业健康咨询。这种自我约束体现了负责任AI开发的重要原则。\n\n---\n\n## 数据集与特征工程\n\n项目使用了一个包含10万条记录的合成睡眠健康数据集，涵盖32个特征列。数据集包含多个特征组：\n\n- **人口统计学特征**：年龄、性别等基础信息\n- **睡眠架构**：睡眠时长、REM睡眠比例、深度睡眠比例等\n- **生活方式行为**：运动频率、饮食习惯、屏幕使用时间等\n- **心理情境**：压力水平、焦虑评分、情绪状态等\n- **健康背景**：BMI、慢性疾病、用药情况等\n- **环境因素**：卧室温度、噪音水平、光照条件等\n\n原始数据集包含三个目标相关列，但项目仅将 `cognitive_performance_score`（认知表现得分）作为预测目标，这是一个典型的监督学习回归任务。\n\n---\n\n## 模型基准测试与关键发现\n\n项目对多种回归模型家族进行了基准测试，包括 DummyRegressor、Ridge、RandomForestRegressor 和 HistGradientBoostingRegressor。评估指标涵盖 MAE（平均绝对误差）、RMSE（均方根误差）和 R² 决定系数。\n\n### 研究发现：特征泄漏的陷阱\n\n项目设计了一个关键实验来揭示机器学习工程中常见的"性能幻觉"：\n\n**完整特征场景（full_feature）**：\n- 模型：HistGradientBoostingRegressor\n- 测试 MAE：4.6244\n- 测试 R²：0.9319\n\n**可部署特征场景（deployable_feature）**：\n- 模型：HistGradientBoostingRegressor\n- 测试 MAE：6.8850\n- 测试 R²：0.8490\n\n性能差距的根源在于 `sleep_quality_score`（睡眠质量评分）这一特征。虽然它能显著提升预测准确性，但它可能编码了与目标变量高度相关的规则派生信息——在实际部署场景中，用户不可能在睡前就知道当晚的睡眠质量得分。\n\n这种"泄漏特征"在离线基准测试中表现优异，但在真实使用场景中却无法获取，导致模型在实际部署时性能大幅下降。SleepFocus-AI 的核心贡献之一就是系统性地识别和量化这种问题。\n\n---\n\n## 模型治理决策：性能与实用性的权衡\n\n基于泄漏分析，项目做出了重要的模型治理决策：\n\n- **研究基准模型**：使用完整特征，用于学术比较和方法论研究\n- **部署原型模型**：使用可部署特征，排除 `sleep_quality_score`、`rem_percentage`、`deep_sleep_percentage` 等高泄漏风险特征\n\n这一决策明确优先考虑负责任的模型部署，而非单纯追求基准测试分数。最终部署模型的典型预测误差为 ±6.89 分，预测结果附带基于平均测试误差的估计范围，作为实用的不确定性指标。\n\n---\n\n## 可解释AI实现\n\n项目使用 SHAP（SHapley Additive exPlanations）实现可解释AI，提供：\n\n- **全局特征重要性**：识别对整体预测影响最大的因素\n- **SHAP摘要可视化**：展示特征值与SHAP值的关系分布\n- **SHAP依赖图**：揭示单个特征与预测结果的交互模式\n- **局部解释示例**：针对特定预测实例的解释\n- **API级解释**：通过后端接口为每个预测请求返回解释\n\n重要提示：SHAP值解释的是模型行为，而非因果关系。某个特征的正向SHAP贡献仅表示它增加了模型对该输入的预测得分，并不证明改变该特征会因果性地改善认知表现。\n\n---\n\n## 技术架构与部署\n\nSleepFocus-AI 实现了完整的端到端系统：\n\n### 后端（FastAPI）\n\n- **健康检查端点** (`/health`)：验证服务状态\n- **模型信息端点** (`/model-info`)：返回模型元数据\n- **预测端点** (`/predict`)：接收睡眠、运动、压力等输入，返回认知表现预测\n- **解释端点** (`/explain`)：返回预测的SHAP解释\n\n预测请求仅需三个必填字段：`sleep_duration_hrs`（睡眠时长）、`exercise_day`（是否运动）、`stress_score`（压力评分）。可选字段由预处理管道自动处理缺失值。\n\n### 前端（React + Vite + TypeScript）\n\n- 越南语优先界面，支持英语切换\n- 侧边栏导航和预测表单\n- 自动预测解释展示\n- 输入指导和结果解读\n- 局限性和伦理说明专区\n\n### Docker Compose 部署\n\n项目支持本地 Docker Compose 一键部署：\n\n```bash\ndocker compose up --build\n```\n\n本地访问地址：\n- 前端：http://localhost:8080\n- 后端：http://localhost:8000\n- API文档：http://localhost:8000/docs\n\n---\n\n## 项目局限与负责任AI声明\n\nSleepFocus-AI 明确列出了其局限性，这些声明本身就是负责任AI实践的范例：\n\n1. **合成数据**：数据集为人工生成，非真实临床数据\n2. **未经验证**：模型未经过临床验证\n3. **非医疗设备**：系统不属于医疗设备范畴\n4. **预测不确定性**：预测包含不确定性，应谨慎解读\n5. **非因果关系**：SHAP解释不证明因果关系\n6. **敏感变量**：部分输入变量可能涉及敏感信息\n7. **使用边界**：原型不应用于诊断、治疗或高风险决策\n\n---\n\n## 核心启示\n\nSleepFocus-AI 为机器学习工程实践提供了几个重要启示：\n\n1. **基准测试分数不等于实际性能**：离线评估中的高分可能来自数据泄漏，部署时性能可能显著下降\n\n2. **可部署性需要系统性考量**：选择最高分的模型并不总是最佳决策，需要权衡特征可用性、泄漏风险和实际场景约束\n\n3. **可解释性增强透明度但不建立因果性**：SHAP等工具帮助理解模型行为，但不能误读为因果证据\n\n4. **负责任的AI原型应暴露边界**：明确声明局限性和预期用途，避免用户过度依赖或误用\n\nSleepFocus-AI 最终选择了可部署特征模型，因为它在预测性能、可解释性和实际部署适用性之间取得了更好的平衡。这种务实的工程决策，比单纯追求基准测试分数更能体现机器学习项目的真正价值。