# scale-ai **Repository Path**: huang-da/scale-ai ## Basic Information - **Project Name**: scale-ai - **Description**: 基于生成式AI的课堂学生参与度智能评价系统 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 3 - **Created**: 2026-06-02 - **Last Updated**: 2026-08-15 ## Categories & Tags **Categories**: ai **Tags**: 课堂评价, 生成式AI, 人工智能 ## README # 基于生成式人工智能的课堂学生参与度智能评价系统 > 基于生成式 AI（Qwen-VL + DeepSeek）的课堂视频多维度学生参与度自动评价系统，支持视频上传、实时分析、历史对比与 HTML 报告导出。 基于生成式人工智能的课堂学生参与度智能评价系统，使用计算机视觉和LLM技术实时分析学生参与度。 [![Gitee](https://gitee.com/huang-da/scale-ai/badge/star.svg)](https://gitee.com/huang-da/scale-ai) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Python 3.9+](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/) [![React 18](https://img.shields.io/badge/React-18-61DAFB.svg)](https://react.dev/) --- ## 📸 系统界面预览 ### 登录页 ![登录页](docs/screenshots/01-login.png) ### 仪表盘首页 ![仪表盘](docs/screenshots/02-dashboard.png) ### 视频管理 ![视频管理](docs/screenshots/03-videos.png) ### 分析中心 ![分析中心](docs/screenshots/04-analysis.png) ### 报告列表 ![报告列表](docs/screenshots/05-reports-list.png) ### 报告详情预览 ![报告详情](docs/screenshots/06-report-detail.png) ### 系统设置 ![系统设置](docs/screenshots/07-settings.png) > 📷 **截图说明**：以上截图需手动截取并保存至 `docs/screenshots/` 目录。启动项目后访问 http://localhost:5173 即可逐项截图。 --- ## ✨ 功能特性 本系统面向高校教师与教育研究者，提供从**视频采集 → AI 自动分析 → 多维度报告**的全流程课堂参与度评价能力。 ### 核心功能 ### 核心功能 - 🎥 **视频管理** - 支持上传、流媒体播放、批量管理教学视频 - 🧪 **智能分析** - 基于Qwen-VL和DeepSeek双模型架构的参与度分析 - 📊 **多维度评价** - SCALE框架五维度评分（专注度、互动度、情绪状态等） - 📈 **数据可视化** - 雷达图、趋势图、热力图等多形式展示 - 🎥 **实时监控** - RTSP摄像头/本地摄像头实时分析 - 📝 **报告生成** - 自动生成HTML格式分析报告 ### 技术亮点 - **双模型架构**：Qwen-VL（视觉分析）+ DeepSeek（文本聚合）分工明确 - **实时分析**：WebSocket实时传输 + Celery异步任务处理 - **100分制评分**：统一评分体系，LLM内部0-1，输出×100 - **历史对比**：多课节数据对比分析 - **多次采样**：每帧3次采样取修剪平均，提高评分稳健性 --- ## 🌟 系统特色 1. **双模型架构**：视觉分析+文本聚合分工明确，Qwen VL负责逐帧评分，DeepSeek负责语义理解和报告生成 2. **实时监控**：支持RTSP摄像头，即时反馈学生参与度数据 3. **历史对比**：多维度数据可视化分析，支持跨课程、跨时间对比 4. **开源共享**：完整代码开放，易于复现和二次开发 5. **AI辅助开发**：完全由WorkBuddy智能体进行需求梳理、技术选型、代码生成、错误排查和文档整理 --- 完整文档请查看 [docs/](docs/) 目录： - **[安装手册](docs/安装手册.md)** - 详细的环境配置和安装步骤 - **[配置手册](docs/配置手册.md)** - 环境变量说明和AI模型配置指南 - **[使用手册](docs/使用手册.md)** - 功能介绍和操作流程说明 - **[分析原理](docs/SCALE-AI%20生成式人工智能分析原理.md)** - 双模型架构和技术原理介绍 --- ## 📚 SCALE-AI 分析框架理论说明 SCALE-AI 框架是一套**面向经典课堂参与度理论的可计算化观测方案**，而非提出新的理论。框架将教育学中成熟的参与度三维度理论扩展为五个可计算观测维度，通过生成式 AI（Qwen-VL 视觉分析 + DeepSeek 文本聚合）实现对课堂视频的自动化参与度评价。 ### 理论基石：Fredricks 等（2004）三维度模型 SCALE 中前三个维度（**S / C / A**）直接对应 Fredricks, Blumenfeld & Paris（2004）在 *Review of Research in Education* 中提出的**学生参与度三维模型**： | SCALE 维度 | Fredricks 对应维度 | 核心定义 | |---|---|---| | **S** 行为参与 | Behavioral Engagement | 学生在课堂中的可观察行为表现 | | **C** 认知参与 | Cognitive Engagement | 学生在学习过程中投入的认知资源深度 | | **A** 情感参与 | Affective Engagement | 学生对课堂活动产生的情感反应 | Fredricks 等指出，传统课堂观察方法依赖人工编码，存在**主观性强、覆盖率低、难以规模化**的问题。SCALE-AI 的核心贡献在于：利用多模态 AI 将这些理论构念转化为**可自动化计算的观测指标**。 --- ### 五维度详解 #### S — 行为参与（Behavioral Engagement） **理论依据**：Fredricks（2004）行为参与子维度，关注可观察的课堂行为。 **AI 可识别的观测指标**： - 视线方向（注视黑板/屏幕 vs. 低头/游离） - 举手频率与主动性 - 笔记行为、身体前倾等参与性动作 - 与教师和同伴的互动行为 **评分逻辑**：基于单位时间窗口内参与性行为的频次与持续时间，归一化至 0–100 分。 --- #### C — 认知参与（Cognitive Engagement） **理论依据**：Fredricks（2004）认知参与子维度，关注学生投入的认知策略深度（浅层学习 vs. 深层学习）。 **AI 可识别的观测指标**： - 面部表情中的困惑/专注/顿悟等认知情感信号 - 互动中的追问行为（追问 = 深层认知参与的标志） - 非言语线索：皱眉（深度思考）、眼神聚焦（注意力集中） - 与教师和同伴讨论时的语言复杂度（需结合 ASR，可选） **评分逻辑**：认知情感信号强度 + 追问/互动深度综合打分，归一化至 0–100 分。 > ⚠️ **方法论说明**：纯视觉分析对认知参与的推断存在固有局限，评分应作为**趋势性参考**而非精确测量，建议结合课后测验数据做三角验证。 --- #### A — 情感参与（Affective Engagement） **理论依据**：Fredricks（2004）情感参与子维度，关注学生对课堂活动的情感反应（积极 / 中性 / 消极）。 **AI 可识别的观测指标**： - 面部表情情感分类（高兴、专注、困惑、厌倦、沮丧、中性） - 情感持续性（积极情感持续 = 高情感参与） - 情感转换模式（频繁消极转换 = 低情感参与） **评分逻辑**：基于 Plutchik 情感模型，将检测到的情感映射为参与度情感分，归一化至 0–100 分。 --- #### L — 社交互动（Social Interaction）★ AI 扩展维度 **理论依据**：不属于 Fredricks 原始三维模型，而是**AI 多模态分析能力的扩展观测维度**，对应课堂中的社交互动参与度。 **AI 可识别的观测指标**： - 与同伴的互动频次（转头、肢体朝向同伴） - 小组活动中的参与度（是否主动参与讨论） - 与教师互动时的社交线索（微笑回应、点头等） - 课堂社交网络的参与程度（是否被同伴主动互动） **评分逻辑**：社交互动行为的频次与质量综合评估，归一化至 0–100 分。 > ★ 此维度是 SCALE 框架的**创新性扩展**，利用 AI 视觉模型对社交互动的识别能力，补充了传统人工观察中难以系统化记录的社交参与维度。 --- #### E — 身体感知参与（Body Perception Participation）★ AI 扩展维度 **理论依据**：不属于 Fredricks 原始三维模型，基于**身体感知理论（Body Perception Theory）**，认为认知过程嵌入在身体与环境的互动中。 **AI 可识别的观测指标**： - 身体姿态参与度（坐姿端正 vs. 趴桌/后仰） - 手势参与（手势表达 = 高身体感知参与） - 空间占位（坐在前排 = 身体感知参与度更高，已有教育学研究支持） - 头部姿态与身体朝向（面向教师 = 高参与） **评分逻辑**：基于人体姿态估计（OpenCV Pose Estimation）提取姿态特征，综合评估身体感知参与度，归一化至 0–100 分。 > ★ 此维度是 SCALE 框架的**第二个创新性扩展**，将身体感知理论引入课堂参与度计算，是传统问卷和观察方法难以系统化测量的维度。 --- ### 框架创新性总结 | 贡献 | 说明 | |---|---| | 理论锚定 | 前三维（S/C/A）严格对应 Fredricks et al. 2004 经典模型，有据可查 | | AI 能力扩展 | 后两维（L/E）利用 AI 多模态感知能力，扩展传统理论的可观测边界 | | 可计算化 | 将理论构念转化为可自动化计算的指标，支持规模化课堂分析 | | 百分制统一 | 五维度统一使用 0–100 分制，便于横向对比与趋势分析 | --- ## 🛠️ 技术栈 ### 后端 - **框架**：FastAPI (Python 3.9+) - **数据库**：SQLite (可扩展PostgreSQL) - **任务队列**：Celery + Redis - **AI模型**： - 帧分析：Qwen-VL Max (阿里云百炼) - 聚合分析：DeepSeek V4 Flash ### 前端 - **框架**：React 18 + TypeScript - **构建工具**：Vite - **UI组件**：MUI (Material-UI) - **图表**：ECharts + Recharts ## 📦 安装部署 ### 环境要求 - Python 3.9+ - Node.js 18+ - Redis (可选，用于Celery) ### 后端部署 ```bash # 1. 克隆项目 git clone https://gitee.com/huang-da/scale-ai.git cd scale-ai/backend # 2. 创建虚拟环境 python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 3. 安装依赖 pip install -r requirements.txt # 4. 配置环境变量 cp .env.example .env # 编辑 .env 文件，填入API Key等配置 # 5. 启动后端 python3 -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8001 ``` ### 前端部署 ```bash # 1. 进入前端目录 cd ../frontend # 2. 安装依赖 npm install # 3. 配置环境变量 cp .env.example .env # 编辑 .env 文件 # 4. 启动开发服务器 unset NODE_OPTIONS && npx vite --host 0.0.0.0 --port 3000 ``` ### Celery Worker (可选) ```bash cd backend python3 -m celery -A backend.app.tasks.analysis_task:celery_app worker --loglevel=info --concurrency=1 ``` ## ⚙️ 配置说明 复制 `.env.example` 为 `.env` 并配置： ```bash # 必需配置 QWEN_VL_API_KEY=your_qwen_api_key # 阿里云百炼API Key DEEPSEEK_API_KEY=your_deepseek_api_key # DeepSeek API Key # 可选配置 SECRET_KEY=your_jwt_secret # JWT密钥 REDIS_URL=redis://localhost:6379/0 # Redis连接（可选） ``` ## 📖 使用指南 ### 1. 注册登录 - 访问 `http://localhost:3000` - 注册账号（默认角色：teacher） - 管理员账号：demo@scale-ai.edu.cn / demo123456 ### 2. 上传视频 - 进入"视频管理"页面 - 上传教学视频（支持MP4、WebM等格式） - 关联课程和课次 ### 3. 启动分析 - 进入"分析中心" - 选择视频，配置分析参数 - 启动分析任务 ### 4. 查看报告 - 分析完成后查看详细报告 - 多维度评分、时间线、关键时段分析 - 导出HTML报告 ### 5. 实时监控（可选） - 配置RTSP摄像头 - 开始实时监控 - 实时查看参与度数据 ## 📊 项目结构 ``` scale-ai/ ├── backend/ # 后端代码 │ ├── app/ │ │ ├── api/ # API路由 │ │ ├── models/ # 数据库模型 │ │ ├── services/ # 业务逻辑 │ │ ├── schemas/ # Pydantic模式 │ │ └── tasks/ # Celery任务 │ └── storage/ # 存储目录 ├── frontend/ # 前端代码 │ ├── src/ │ │ ├── pages/ # 页面组件 │ │ ├── components/ # 公共组件 │ │ ├── api/ # API调用 │ │ └── store/ # 状态管理 │ └── dist/ # 构建输出 ├── README.md # 项目文档 ├── LICENSE # 开源协议 └── .env.example # 环境变量模板 ``` ## 🤝 贡献指南 欢迎提交Issue和Pull Request！ 1. Fork本项目 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 提交Pull Request ## 📝 许可证 本项目采用 MIT License 开源协议，详见 [LICENSE](LICENSE) 文件。 ## 📧 联系方式 - 作者：黄达 - 邮箱：huang-da@qq.com ## 🙏 致谢 - 阿里云百炼 - Qwen-VL Max模型支持 - DeepSeek - DeepSeek V4 Flash模型支持 - FastAPI - 高性能Python Web框架 - React - 前端UI框架 --- **注意**：使用本系统需要自行申请Qwen-VL和DeepSeek的API Key。