醒源 lumen · 核心模型算法技术规范与接口文档
标准生产版本 V2.0 • 适用于算法工程师、后端研发与医学团队
1. 🌐 跨平台穿戴设备健康数据采集全景表 (iOS vs. Android / 华为)
醒源 lumen 架构全面支持 iOS (Apple HealthKit) 与 Android (Health Connect / 华为 Health Kit) 双平台健康中枢。下表详细列出了系统通过两个原生健康框架所能够采集到的全量体征与作息指标映射（紫色高亮行代表当前精力预测与 OSA 筛查模型核心依赖指标）：
| 数据分类 | 指标名称与含义 | 系统当前状态 | iOS 标识符 (Apple HealthKit) | Android 标识符 (Health Connect / 华为 Health) | 采集单位 | 对算法与模型的生理意义 |
|---|---|---|---|---|---|---|
| 睡眠与呼吸 | 睡眠分期结构 (Sleep Stages) | ✅ 核心计算中 | sleepAnalysis (REM/Deep/Core/Awake) |
SleepSession (REM/Deep/Light/Awake) |
分钟 (min) | 评估睡眠效率、深睡比例、REM比例与睡眠周期完整度 |
| 睡眠与呼吸 | 呼吸频率 (Respiratory Rate) | ✅ 核心计算中 | respiratoryRate |
RespiratoryRate |
breaths/min | 评估夜间通气状况与 OSA 呼吸暂停/过缓风险 |
| 睡眠与呼吸 | 夜间呼吸紊乱指数 (Breathing Disturbances) | 📦 预留采集中 | breathingDisturbances (iOS 18+) |
BreathingDisturbances (华为/Garmin) |
次/小时 (AHI) | 夜间呼吸异常直观量化，用于 OSA 临床等级预警 |
| 心血管与自主神经 | 心率变异性 (HRV SDNN / RMSSD) | ✅ 核心计算中 | heartRateVariabilitySDNN |
HeartRateVariabilityRmssd / Sdnn |
毫秒 (ms) | 核心指标：评估自主神经平衡（交感/副交感神经活性）与压力恢复 |
| 心血管与自主神经 | 静息心率 (Resting Heart Rate) | ✅ 核心计算中 | restingHeartRate |
RestingHeartRate |
bpm (次/分) | 核心指标：基础代谢水平、心血管负荷与过度疲劳预警 |
| 心血管与自主神经 | 连续心率 (Continuous Heart Rate) | ✅ 核心计算中 | heartRate |
HeartRate |
bpm (次/分) | 日间/夜间心率实时波动折线与静息区间锚定 |
| 心血管与自主神经 | 步行心率均值 (Walking HR Average) | 📦 预留采集中 | walkingHeartRateAverage |
HeartRate (过滤运动状态) |
bpm (次/分) | 日常轻度活动下的心血管适应性 |
| 心血管与自主神经 | 一分钟心率恢复 (HR Recovery) | 📦 预留采集中 | heartRateRecoveryOneMinute |
HeartRate (运动后差值导出) |
bpm (次/分) | 评估副交感神经重激活速度与心肺恢复效率 |
| 心血管与自主神经 | 血氧饱和度 (SpO₂ / Oxygen Saturation) | ✅ 核心计算中 | oxygenSaturation |
OxygenSaturation |
% (百分比) | 核心指标：监测夜间低氧 Nadir 与血氧下降指数 (ODI) |
| 体温与节律 | 睡眠手腕/皮肤温度 (Wrist Temperature) | 📦 预留采集中 | appleWristTemperature (iOS 16+) |
BodyTemperature / 皮肤温度 (华为/Garmin) |
°C / 偏离度 | 评估昼夜体温节律 (C过程) 相位移动与免疫/生理周期起伏 |
| 体温与节律 | 身体体温 (Body Temperature) | 📦 预留采集中 | bodyTemperature |
BodyTemperature |
°C | 监测体温异常与基础代谢起伏 |
| 体温与节律 | 户外日照暴露时长 (Time in Daylight) | 📦 预留采集中 | timeInDaylight (iOS 17+) |
AmbientLight / 日照时间记录 |
分钟 (min) | 评估自然光对松果体褪黑素抑制及昼夜节律重置的调控效果 |
| 活动与体力代谢 | 每日步数 (Step Count) | 📦 预留采集中 | stepCount |
Steps |
步 (steps) | 基础日间物理活动量评估 |
| 活动与体力代谢 | 活动消耗卡路里 (Active Energy) | 📦 预留采集中 | activeEnergyBurned |
ActiveCaloriesBurned |
kcal (千卡) | 评估日间运动/工作体力消耗与 S 过程睡眠压力累积 |
| 活动与体力代谢 | 基础代谢卡路里 (Basal Energy) | 📦 预留采集中 | basalEnergyBurned |
BasalMetabolicRate |
kcal (千卡) | 评估人体静息基础能量维持消耗 |
| 活动与体力代谢 | 步行/跑步距离 (Distance) | 📦 预留采集中 | distanceWalkingRunning |
Distance |
米 (m) | 位移与有氧训练量 |
| 活动与体力代谢 | 爬楼层数 (Flights Climbed) | 📦 预留采集中 | flightsClimbed |
FloorsClimbed |
层 (floors) | 垂直抗阻活动与心肺爆发力消耗 |
| 活动与体力代谢 | 最大摄氧量 (VO₂ Max) | 📦 预留采集中 | vo2Max |
Vo2Max |
mL/(kg·min) | 评估心肺耐力上限与长期体能储备基线 |
| 活动与体力代谢 | 运动训练记录 (Workouts / Exercise) | 📦 预留采集中 | HKWorkout |
ExerciseSession |
类型 / 时长 | 识别高强度运动，修正当晚睡眠恢复模型与次日精力预估 |
| 步态与生物力学 | 步态与步行速度 (Walking Speed & Step Length) | 📦 预留采集中 | walkingSpeed, walkingStepLength |
WalkingSpeed |
m/s, cm | 评估身体衰老、神经肌肉疲劳与中枢神经系统状态 |
| 步态与生物力学 | 步态不对称性 (Walking Asymmetry) | 📦 预留采集中 | walkingAsymmetryPercentage |
仅部分设备支持 | % (百分比) | 评估下肢疲劳、运动损伤或姿态异常 |
| 环境与声学 | 环境噪音暴露 (Environmental Audio Exposure) | 📦 预留采集中 | environmentalAudioExposure |
分贝传感器 / 麦克风采样 | dBA (分贝) | 分析睡眠环境声级噪音对夜间交感觉醒的干扰 |
| 形态与基础 | 身高 / 体重 / BMI (Body Mass Index) | ✅ 核心计算中 | height, bodyMass, bodyMassIndex |
Height, Weight, BodyFat |
cm, kg, kg/m² | 用于计算基础代谢及 STOP-Bang (BMI > 35) OSA 风险初筛 |
2. 系统算法流转与数据融合架构
醒源 lumen 算法中枢采用“穿戴设备采样 $\rightarrow$ 动态基线计算 $\rightarrow$ 核心算法评估 $\rightarrow$ LLM 报告生成”的链式架构：
┌─────────────────────────────────────────────────────────────────────────┐
│ 📱 穿戴设备 / 健康应用传感器 │
│ Apple Watch (HealthKit) / Android (Health Connect / 华为 / 小米健康) │
└─────────────────────────────────────────────────────────────────────────┘
│ (上传 Raw Samples)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 📉 2. 动态基线学习 (baseline.py) │
│ · 结合 PhysioNet / NHANES 人群先验与 14-180 天滑动窗口 │
│ · 输出用户个性化体征均值 (Mean) 与标准差 (Std) │
└─────────────────────────────────────────────────────────────────────────┘
│
┌─────────────────┴─────────────────┐
▼ ▼
┌───────────────────────────────────┐ ┌───────────────────────────────────┐
│ ⚡ 1. 精力预测算法 (algorithm.py) │ │ 🩺 3. OSA 临床筛查 (osa.py) │
│ · Z-Score 标准化 + 缺项动态重分 │ │ · STOP-Bang 8 项问卷主观分 │
│ · 双过程 (C过程节律+S过程压力) │ │ · 夜间低氧/觉醒风暴主客观交叉校验│
│ · 醒时精力起伏曲线 (07:00~23:00 醒时区间)与 Peak 时段 │ │ · 三级风险评估与就医建议 │
└───────────────────────────────────┘ └───────────────────────────────────┘
│ │
└─────────────────┬─────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 🤖 4. LLM 智能诊断解读报告 (llm.py) │
│ · 融合体征、PVT 反应时、精力预测分与 OSA 预警 │
│ · 智能生成 <200 字温和积极、非诊断性每日健康指导与改善建议 │
└─────────────────────────────────────────────────────────────────────────┘
2. ⚡ 精力预测算法 (Energy Prediction Algorithm)
基于睡眠科学中的**双过程模型 (Two-Process Model of Sleep Regulation)**，结合个体体征在 Z-Score 标准化偏离度下的加权融合：
加权综合评分公式 (Weighted Formula):
Score_raw = (w1 * Z_hrv + w2 * Z_sleep + w3 * Z_pvt + w4 * (-Z_rhr) + w5 * SpO2_norm) / ∑ w_active
24 小时昼夜节律 C 过程公式 (Circadian Process C):
C(t) = 50 + 15 * sin( 2π * (t - t_wake - 2) / 24 )
Score_raw = (w1 * Z_hrv + w2 * Z_sleep + w3 * Z_pvt + w4 * (-Z_rhr) + w5 * SpO2_norm) / ∑ w_active
24 小时昼夜节律 C 过程公式 (Circadian Process C):
C(t) = 50 + 15 * sin( 2π * (t - t_wake - 2) / 24 )
2.2 输入数据结构 (EnergyInput)
| 字段名 | 数据类型 | 单位 / 范例 | 含义说明 | 缺项重分逻辑 |
|---|---|---|---|---|
hrv_sdnn | float | ms (如 55.2) | 昨夜睡眠期间 HRV SDNN 均值 | 扣除 w_hrv，自动权重归一化 |
sleep_efficiency | float | 0.0 ~ 1.0 (如 0.88) | 昨夜睡眠效率 | 扣除 w_sleep，自动重分 |
rhr | float | bpm (如 62.0) | 昨夜静息心率均值 (反向参数) | 扣除 w_rhr，自动重分 |
spo2_mean | float | % (如 98.5) | 昨夜平均血氧饱和度 | 扣除 w_spo2，自动重分 |
pvt_score | float | ms (如 320.0) | 今日 PVT 敏捷度测验平均反应时 | 扣除 w_pvt，自动重分 |
pvt_lapses | int | 次 (如 1) | 今日 PVT 走神次数 (>500ms) | 每增加 1 次扣除 5 分 |
2.3 输出数据结构 (EnergyOutput)
| 字段名 | 数据类型 | 输出示例 | 含义与应用 |
|---|---|---|---|
overall_score | float | 78.5 | 综合精力得分 (0.0 ~ 100.0) |
energy_level | str | "normal" | 判定等级: high (≥85), normal (60-84), low (40-59), poor (<40) |
hourly_scores | List[Dict] | [{"hour": 7, "score": 68.2}, ...] | 24 小时起伏折线图点数据 |
peak_hours | List[int] | [10, 11] | 今日精力最充沛的最佳工作时段 |
trough_hours | List[int] | [14, 15] | 今日精力最低谷的休息/小憩时段 |
3. 📉 动态基线学习算法 (Progressive Baseline Learning)
针对首日佩戴数据缺乏问题，结合 PhysioNet / NHANES 人群先验，随佩戴天数增加渐进式演进至 95% 置信度的个人滑动窗口基线。
3.1 渐进式置信度演进过程
· D0 (首日): 匹配同年龄/性别群体先验 (置信度 60%)
· D1~D3: 渐进基线建立 (置信度 70% ~ 80%)
· D7: 7 天基线构建 (置信度 90%)
· D14+: 14 天完整滑动基线构筑 (最高置信度 95%)
· D1~D3: 渐进基线建立 (置信度 70% ~ 80%)
· D7: 7 天基线构建 (置信度 90%)
· D14+: 14 天完整滑动基线构筑 (最高置信度 95%)
3.2 人群先验匹配矩阵 (PhysioNet / NHANES Cohorts)
| 性别/年龄段 | HRV 均值 (SDNN) | HRV 标准差 | RHR 均值 (bpm) | 睡眠效率 | SpO₂ 均值 |
|---|---|---|---|---|---|
| 男性 <30岁 (male_young) | 52.0 ms | 12.0 ms | 62.0 bpm | 88.0% | 97.5% |
| 男性 30-45岁 (male_mid) | 44.0 ms | 10.0 ms | 65.0 bpm | 85.0% | 97.0% |
| 女性 30-45岁 (female_mid) | 46.0 ms | 11.0 ms | 66.0 bpm | 86.0% | 97.2% |
| 长者 60+ (elder) | 28.0 ms | 6.0 ms | 70.0 bpm | 80.0% | 96.2% |
4. 🩺 OSA 睡眠呼吸暂停临床筛查与双向校准矩阵
结合 STOP-Bang 8 项问卷主观分与夜间 Apple Watch 体征（夜间低氧 Nadir 与交感觉醒 AAI）进行双向交叉校验：
4.1 主客观双向校准矩阵 (Calibration Matrix)
| 问卷初筛风险 | 夜间客观体征三维校验 (血氧 ODI / 心率骤升 / HRV 觉醒) | 校准后最终 OSA 风险评级 | 临床解释与诊断建议 |
|---|---|---|---|
| 低风险 (0-2分) | ODI < 5 且 AAI < 5 (全三维体征正常) | 低风险 (Low Risk) | 主客观强一致，夜间气道通畅，无窒息觉醒。 |
| 低风险 (0-2分) | 最低血氧 < 90% 或 AAI 异常 (交感窒息风暴) | 升级为中风险 (Medium Risk) | 🚨 警惕隐匿型 OSA！ 设备捕捉到夜间低氧，提示潜在低通气。 |
| 低风险 (0-2分) | 最低血氧 < 85% (严重夜间低氧) | 强制判定为高风险 (High Risk) | 🚨 严重低氧血症！ 捕捉到严重缺氧事件，建议行 PSG 检查。 |
5. 🤖 LLM 智能诊断解读报告
基于通义千问 qwen3-7b-instruct 大语言模型生成每日健康短评：
System Prompt 边界约束:
1. 字数严格限制在 200 字以内；
2. 口吻温和积极，不过度渲染负面与焦虑；
3. 严禁作出确诊性医疗诊断；
4. 提供 1~2 条具体的今日行动建议与 `_fallback_report()` 降级兜底。
1. 字数严格限制在 200 字以内；
2. 口吻温和积极，不过度渲染负面与焦虑；
3. 严禁作出确诊性医疗诊断；
4. 提供 1~2 条具体的今日行动建议与 `_fallback_report()` 降级兜底。
6. 📱 穿戴设备原始数据采集字段字典
sample_type 标识符 | 含义说明 | 标准物理单位 | 正常参考范围 | 采集传感器 |
|---|---|---|---|---|
hrv_sdnn | 心率变异性 SDNN | ms | 30.0 ~ 100.0 ms | Apple Watch / 智能手环 PPG |
resting_heart_rate | 静息心率 RHR | bpm | 50 ~ 80 bpm | Apple Watch / 智能手环 |
oxygen_saturation | 血氧饱和度 SpO₂ | % (或 0.0~1.0) | 95% ~ 100% | 脉搏血氧传感器 |
sleep_stage | 睡眠分期 | stage_enum | 1:浅睡 2:深睡 3:REM | 睡眠检测算法引擎 |