FaceRest：本地智能疲劳状态助手

FaceRest 是一个面向学习、办公和日常使用场景的本地化疲劳状态分析系统。系统通过摄像头、图片或视频获取视觉线索，综合分析眼部闭合、张口事件和连续变化趋势，输出清晰的状态等级、风险解释与调整建议；同时接入本地 Qwen 模型，支持围绕检测结果进行自然语言对话。

本项目仅提供视觉状态参考和健康建议，不替代医学诊断。系统默认在本机处理图像，原始图片和摄像头画面不会写入数据库。

项目特点

多入口检测：支持实时摄像头、单张图片和视频分析。
连续状态评估：以一段时间内的视觉线索变化为依据，减少单帧误判。
可解释结果：展示疲劳评分、状态等级、闭眼比例、张口事件等依据。
本地 AI 对话：支持快速模式和专家模式，可结合当前检测结果、场所和用户描述生成建议。
数据闭环：登录、检测记录、对话会话、消息、模型版本和训练记录统一保存到 MySQL。
可视化管理：提供检测记录、对话历史、数据大屏和个人中心等页面。

技术架构

前端（Vue 3 + Vite）
        │ HTTP / JSON
Java 业务后端（Spring Boot） ─── MySQL
        │ HTTP / JSON
Python AI 服务（FastAPI）
        ├── 视觉分析：人脸关键点、眼部/嘴部线索、图片与视频推理
        └── 本地 Qwen：对话生成、快速/专家模式、LoRA 适配器

目录说明

目录	作用
`前端/`	Vue 页面、路由、摄像头交互、检测结果、AI 对话和数据大屏
`后端/`	Java Spring Boot 业务接口、登录注册、权限校验和数据库访问
`Py端/`	FastAPI AI 服务、视觉推理、连续疲劳评估、Qwen 调用和训练脚本
`千问模型/`	本地基础模型说明、LoRA 适配器和训练配置（模型权重默认不提交）
`视觉模型/`	人脸关键点模型和视觉分类模型（大文件默认不提交）
`数据库/`	MySQL 建表脚本、初始化数据和数据库说明
`运行数据/`	训练日志、服务日志、评估结果和阶段性报告
`项目文档/`	比赛材料、开题报告、性能报告、训练记录和开发日志
`项目工具/`	启动、停止和环境检查脚本
`其他文件/`	参考资料及临时文件

快速启动

方式一：一键启动

在项目根目录双击 启动FaceRest.cmd。脚本会依次启动 Python AI 服务、Java 后端和 Vue 前端。

方式二：分模块启动

# 1. 启动 Python AI 服务（8001）
.\Py端\scripts\run_backend.ps1

# 2. 启动 Java 业务服务（8080）
cd .\后端
mvn spring-boot:run

# 3. 启动 Vue 前端（5173）
cd ..\前端
.\run_web.ps1

启动后访问：http://localhost:5173

停止服务可双击项目根目录的 停止FaceRest.cmd。

环境要求

Windows 10/11
Python 3.10 或更高版本
Node.js 18 或更高版本、npm
Java 17 或更高版本、Maven
MySQL 8.0
可选：支持 CUDA 的 NVIDIA 显卡；CPU 也可以运行，但推理速度较慢

首次使用前请复制 .env.example 为 .env，根据本机模型位置和数据库配置进行修改。模型权重、虚拟环境、前端依赖和原始数据集均通过 .gitignore 排除，不影响代码仓库的正常克隆。

数据库

数据库名称默认为 facrest，建表脚本位于 数据库/。主要数据表包括：

users：用户账户、密码摘要、头像和个人资料；
detection_records：图片、视频和实时检测的状态结果；
detection_metrics：闭眼比例、张口事件、疲劳评分等明细指标；
chat_sessions：AI 对话会话；
chat_messages：会话中的用户问题和模型回答；
model_versions：模型版本与部署状态；
training_runs：训练参数、轮次、损失和评估指标；
user_feedback：用户对检测结果的反馈。

AI 对话与多模态分析

系统内置本地健康助手，用户可以在检测完成后直接提问，也可以从“新建对话”进入独立的健康咨询界面。对话支持快速模式和专家模式：快速模式强调及时反馈，适合查看当前状态和获得简短建议；专家模式会结合检测指标、用户描述和使用场景进行更完整的分析。

健康助手可以回答以下类型的问题：

解释本次疲劳状态、风险等级和主要视觉依据；
根据学习、办公、休息等场景给出状态调整建议；
制定一段时间内的用眼、活动、休息和环境调整计划；
结合用户上传的图片提供面部状态参考；
说明眼镜、光线、姿态和摄像头角度对结果可能造成的影响。

系统会明确区分“视觉线索参考”和“医学诊断”，避免将模型输出误解为医疗结论。图片分析仅提取必要的视觉特征，原始图片不写入业务数据库。

视觉分析流程

前端获取摄像头画面、图片或视频文件，并将数据发送至 Python AI 服务。
Python 服务检测人脸区域和眼、嘴关键点，计算眼部闭合比例、张口幅度及连续帧变化。
连续视频通过时间窗口进行平滑和聚合，降低单帧姿态、眨眼或光线变化带来的误判。
系统根据多项线索生成疲劳评分和状态等级，并返回可解释指标。
前端以状态卡片、评分环、动态轮廓和趋势信息展示结果，用户可以继续向本地 AI 提问。

实时检测页面还提供眼部和嘴部轮廓定位、连续状态变化、检测倒计时和结果动画，帮助用户理解系统正在分析的内容。

数据库设计

系统使用 MySQL 保存业务数据，并通过用户编号和会话编号建立关联：

users 保存账户、密码摘要、昵称、头像和个人资料；
detection_records 保存每次图片、视频或摄像头检测的总体结果；
detection_metrics 保存闭眼比例、张口事件、疲劳评分和分析时长等指标；
chat_sessions 保存每次 AI 对话的标题、模式、来源和时间；
chat_messages 保存用户问题、图片信息、模型回答和生成耗时；
model_versions 保存视觉模型、语言模型和适配器的版本信息；
training_runs 保存模型训练参数、训练轮次、损失和评估指标；
user_feedback 保存用户对检测结果的反馈，便于后续优化模型。

这种设计将账户、检测、指标、对话和模型信息分离管理，既方便数据大屏统计，也便于查询个人历史记录和追踪模型版本。

页面功能

概览

展示最近一次检测状态、本地检测记录数量、服务运行状态和主要功能入口，并提供实时检测、视频分析和图片分析的快捷入口。

实时观察

调用电脑摄像头进行连续帧分析，实时显示面部轮廓、眼部与嘴部线索、疲劳评分和当前风险提示。检测完成后可直接进入 AI 对话获取针对性建议。

图片分析

上传单张图片，系统分析当前画面中的人脸和视觉线索，适合进行快速状态参考。页面支持图片预览、重新选择和结果清理。

视频回顾

上传已有视频，系统按时间顺序分析画面变化，输出总体状态和关键指标，帮助用户了解一段时间内的状态趋势。

新建对话

提供简洁的本地 AI 健康助手界面，支持文字和图片输入、对话持续保存、历史会话恢复以及快速/专家模式切换。

检测记录与对话历史

用户可以按时间、状态和来源查询检测记录，也可以查看、重命名、备注或删除历史内容。对话页面采用独立滚动区域，较长的会话不会影响整体页面布局。

数据大屏

以卡片、趋势图和统计图表展示检测次数、状态分布、平均疲劳评分、常见线索和模型使用情况，为项目演示和系统运行观察提供统一视图。

个人中心

支持修改昵称、头像和登录密码，也可以安全退出当前账户。

技术实现

前端采用 Vue 3 与 Vite 构建，负责页面路由、组件交互、摄像头调用、文件上传、结果可视化和对话体验；Java 后端采用 Spring Boot，负责用户认证、权限校验、检测记录、对话会话、数据大屏统计和 MySQL 事务；Python 端采用 FastAPI，负责视觉推理、连续疲劳评估和本地 Qwen 模型调用。

语言模型采用 Qwen 基础模型结合 LoRA 适配器进行本地部署，回答过程不依赖外部云端接口。视觉服务与业务后端通过 HTTP/JSON 进行通信，前端不直接访问模型文件或数据库，保证系统模块之间职责清晰。

应用场景与价值

FaceRest 可用于学生长时间学习、电脑办公、线上会议、居家休息和日常健康管理等场景。系统不要求用户刻意做出闭眼或张口动作，而是通过短时间自然观察评估当前状态，适合普通用户直接使用。

项目采用本地化处理方式，减少图像上传和隐私泄露风险；通过可解释指标和自然语言建议降低专业使用门槛；通过模块化架构方便后续接入更多视觉模型、健康数据和校园健康管理服务。

运行说明

一键启动

在项目根目录双击 启动FaceRest.cmd，等待 Python AI 服务、Java 后端和 Vue 前端依次启动后，访问 http://localhost:5173。

分模块启动

# 启动 Python AI 服务
.\Py端\scripts\run_backend.ps1

# 启动 Java 业务服务
cd .\后端
mvn spring-boot:run

# 启动 Vue 前端
cd ..\前端
.\run_web.ps1

使用结束后双击 停止FaceRest.cmd，或按照项目文档分别停止服务。首次运行需要安装 Python 依赖、Node.js 依赖、Java/Maven 环境并准备 MySQL 数据库；模型权重和本地配置按照 .env.example 设置即可。

注意事项

检测结果只反映当前画面中的可见线索，不代表医学诊断；
光线不足、遮挡、侧脸、摄像头角度不佳时，结果可能受到影响；
出现明显不适时应优先休息或寻求专业帮助，不应仅依赖系统结果；
建议在光线稳定、面部完整入镜的环境下使用，以获得更稳定的分析结果。