基于学生数据的可视化与发展潜力评估预测

项目介绍

本项目是一个面向学生成绩数据的”分析 + 预测”一体化系统，目标是把一份小规模种子成绩表，加工成可训练、可展示、可预测的完整数据产品。系统以 PySpark + Spark MLlib 作为数据清洗与建模引擎，数据从 docs/学生成绩预测.xlsx 出发，经过扩充、清洗、训练三步流水线后，同时由两套 Web 方案对外服务：Streamlit + Plotly 版主打快速交互，适合课堂演示与探索式分析；FastAPI + ECharts 版采用前后端分离结构，提供一组 JSON API，适合接口化部署与二次集成。

数据方面，系统覆盖 17 个字段：12 个类别特征（性别、国籍、出生地、学段、年级、班级分组、课程、学期、家庭主要沟通人、家长问卷参与、家长满意度、缺勤情况）、4 个行为数值特征（举手次数、学习资源访问次数、公告查看次数、讨论参与次数）以及三分类目标 class_label（低 L / 中 M / 高 H）。最终训练出的随机森林模型在测试集上取得 Accuracy 0.9652、F1 0.9652 的评估结果，并可直接用于在线预测。

项目架构

项目按”脚本流水线 + 双端应用”组织，代码集中在 scripts/、app/、fastapi_app/ 三个目录，全局配置统一收口在根目录 config.py 中——包括 Java/Hadoop 自动探测（Windows 下自动定位 winutils）、Spark 本地模式参数、随机种子（20260228）、字段映射表与所有输入输出路径。

数据处理链路由四个脚本串联，每个脚本的产出即下一个脚本的输入：

step0_generate_dataset.py：读取种子 Excel，按目标样本量有放回抽样，对 4 个数值特征施加正态扰动（噪声标准差取 max(2.0, 0.1σ)，结果裁剪到 0-100），对类别特征以 3% 概率随机替换，生成大样本数据集并同时导出 XLSX 与 CSV；
step1_ingest_and_clean.py：Spark 读入原始数据，完成字段改名、去重、数值列中位数填补、越界裁剪、空类别兜底为 Unknown、过滤非法标签，最终以 Parquet 落盘 data/processed/student_clean.parquet；
step2_train_model.py：构建 Spark ML Pipeline（12 个 StringIndexer + 标签索引 + OneHotEncoder + VectorAssembler + RandomForestClassifier），按 8:2 随机切分训练/测试，评估 Accuracy / Weighted Precision / Weighted Recall / F1，输出模型、指标 JSON 与混淆矩阵 CSV；
step3_visualization.py：用 matplotlib + seaborn 生成 6 张静态图表到 images/，供文档与汇报使用。

应用层上，Streamlit 端以三个标签页组织”可视化大屏 / 筛选查询 / 模型评估与预测”；FastAPI 端提供 GET / 大屏页面（Jinja2 + ECharts 5）与 GET /api/summary、/api/charts、/api/students、/api/model/metrics、POST /api/predict 等接口，并自动生成 /docs 交互文档。scripts/start_services.py 作为跨平台一键启动入口（Windows/macOS/Linux），自动检查 Python 与 Java 环境、缺依赖自动安装、缺数据自动补齐，然后按 --mode all/fastapi/streamlit 拉起对应服务。

核心功能

数据扩充与清洗：从几十行种子表出发，通过固定随机种子（20260228）的有放回抽样 + 数值扰动 + 类别替换生成可调规模（默认 10000 行）的大样本数据；Spark 侧完成去重、中位数填补缺失、0-100 裁剪、类别空值标准化与标签合法性过滤，全流程可复现。
可视化大屏：四张 KPI 卡（学生人数、平均学习活跃度、高成绩占比、低缺勤占比）+ 五类图表——成绩等级分布柱状图、性别占比饼图、各年级学习资源访问均值折线图、行为特征相关性热力图、不同成绩等级行为画像雷达图；Streamlit 版支持侧边栏多选联动筛选，并可在页面内一键将图表导出为 images/*.png。
学生筛选查询：支持性别、学段、年级、课程、缺勤情况多维度筛选，叠加国籍 / 出生地 / 课程关键字检索，分页表格展示，一键导出当前筛选结果 CSV。
模型训练与评估：Spark ML Pipeline 训练随机森林三分类模型（240 棵树、最大深度 12），测试集 603 条样本上 Accuracy 0.9652、F1 0.9652、Weighted Precision 0.9655、Weighted Recall 0.9652，混淆矩阵与各项指标在界面与 /api/model/metrics 中同步展示。
在线预测与发展潜力评估：表单录入 12 个类别选项 + 4 个行为数值（滑杆），实时输出预测成绩等级、各类别概率柱状图与 0-100 发展潜力仪表盘——潜力分由高等级概率折算，75 分以上为”高潜力”、50-75 为”中潜力”、50 以下为”待提升”；预测链路默认走 Spark Pipeline 推理，失败自动降级为基于数据距离的 Pandas 兜底，再失败则使用类别先验的应急兜底，保证功能始终可用。

功能截图

暂无运行截图。

快速上手

推荐使用 Anaconda 创建 Python 3.10+ 环境（项目在 Python 3.12 下验证），并准备 JDK 17（Spark 运行依赖；JDK 21+ 可能触发 getSubject is not supported 报错）。Windows 用户需按 QUICKSTART 配置 winutils.exe 与 HADOOP_HOME，macOS / Linux 无需额外配置：

conda create -n studentviz python=3.12 -y
conda activate studentviz
pip install -r requirements.txt

依赖就绪后，一键启动（推荐显式指定 Anaconda 解释器路径）：

python scripts/start_services.py --mode all --python /opt/anaconda3/bin/python

脚本会按需自动执行数据生成（step0）、清洗（step1）与训练（step2），然后同时拉起两个服务：

Streamlit 大屏：http://localhost:8501
FastAPI 大屏：http://localhost:8000
FastAPI 接口文档：http://localhost:8000/docs

也可以手动分步运行：step0_generate_dataset.py --target-size 10000 → step1_ingest_and_clean.py → step2_train_model.py → step3_visualization.py，最后分别用 streamlit run app/streamlit_app.py 与 uvicorn fastapi_app.main:app --reload --port 8000 启动双端。首次在线预测需要加载 Spark 模型，通常耗时 10-30 秒属正常现象。

总结

项目把”数据扩充 → Spark 清洗 → 随机森林建模 → 双端可视化 → 在线潜力评估”串成一条可一键运行的完整链路，兼具课程设计的教学完整性与工程落地的实用性：固定随机种子让数据生成与模型训练完全可复现；Streamlit 与 FastAPI + ECharts 双方案既满足快速交互演示，也提供了接口化部署的路径；预测接口的 Spark → Pandas → 先验三级降级设计，则让在线推理在不同环境下都能稳定返回结果。

当前模型基于模拟扩充数据训练，Accuracy 0.9652 属于同一分布下的理想水平。后续若接入真实学校的学生档案与过程性行为数据（如课堂互动、作业提交、测验成绩序列），可进一步扩展为时序特征与多分类精细粒度，并把”发展潜力分数”与教学干预建议联动，形成真正可落地的学业预警闭环。