# 26人工智能技术导论

**Repository Path**: chwang1986/intro2AI

## Basic Information

- **Project Name**: 26人工智能技术导论
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 39
- **Created**: 2026-03-31
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## AI Classroom Hub：人工智能算法导论教学平台

AI Classroom Hub 是为高校《人工智能算法导论》课程设计的基于 Streamlit 的多页面教学协作平台。  
目标是同时服务教师课堂演示与学生个人成长记录，让同一份代码仓库在每一届学生手中迭代发展。

### 平台面向的典型场景

- **课堂互动演示（教师端）**：实时展示机器学习与神经网络的核心算法、可视化训练过程与参数影响。
- **学生作品展示墙**：每位学生拥有独立的页面文件，集中展示个人项目、实验结果与学习反思。
- **学习进度打卡与记录**：记录每周学习内容、完成情况和思考。
- **数据集 / 模型训练实验平台**：上传数据集、选择基础模型、查看训练结果与可视化。

---

## 项目结构

建议的目录结构如下（本仓库已按此逐步搭建）：

```text
ai-classroom-hub/
├── app.py                  # 主页入口，展示课程信息与导航
├── pages/
│   ├── 01_演示中心.py       # 教师端：算法演示与数据可视化（主导航）
│   ├── 02_作品展示墙.py     # 汇总所有学生子页面入口
│   ├── 03_打卡记录.py       # 学生学习进度打卡（待扩展）
│   ├── 04_实验平台.py       # 数据集上传与模型训练可视化（待扩展）
│   └── students/
│       ├── student_模板.py  # 学生个人页面模板
│       └── ...              # 每位学生的独立页面文件
├── data/
│   ├── checkins.json        # 打卡数据（JSON）
│   └── datasets/            # 上传的数据集
├── utils/
│   ├── helpers.py           # 公共工具函数
│   ├── sandbox.py           # 学生代码沙箱执行
│   └── record.py            # 学生运行记录的读写（预留）
├── requirements.txt
└── README.md
```

---

## 本地快速启动

### 1. 安装依赖

建议使用 Python 3.9+ 版本。先创建虚拟环境（可选，但推荐）：

```bash
python -m venv .venv
.\.venv\Scripts\activate  # Windows PowerShell
# 或 source .venv/bin/activate  # macOS / Linux
```

安装依赖：

```bash
pip install -r requirements.txt
```

### 2. 运行 Streamlit 应用

在项目根目录下执行：

```bash
streamlit run app.py
```

浏览器中会自动打开本地地址，看到课程主页，并可以从左侧多页面导航访问“演示中心”“作品展示墙”等页面。

---

## 面向教师：如何使用本项目

- 在课堂上，通过 `streamlit run app.py` 启动本项目，投影展示：
  - 在 **“演示中心”** 页面中演示线性回归、K-Means、决策树 / 随机森林、神经网络等基础算法；
  - 利用页面中的参数滑块调节超参数，让学生直观看到模型效果的变化；
  - 演示“学生可编辑代码区”，现场修改部分核心代码并运行，帮助学生理解算法细节。
- 在 **“作品展示墙”** 页面中，引导学生查看彼此的项目与学习记录，形成可视化“班级成长档案”。
- 后续可以逐步完善 “打卡记录” 和 “实验平台” 两个模块，用于收集学习打卡和模型训练实验结果。

---

## 面向学生：协作规范（基于 Gitee）

> 本项目推荐托管在 Gitee。以下流程以“教师已有一个主仓库”为前提。

1. **Fork 主仓库**
   - 打开教师提供的 Gitee 仓库地址，点击 `Fork` 到自己的 Gitee 账号。

2. **克隆到本地**
   - 在自己电脑上克隆 Fork 后的仓库：
   ```bash
   git clone <你的仓库地址>
   cd ai-classroom-hub
   ```

3. **基于模板创建个人页面**
   - 在 `pages/students/` 目录下，复制模板文件 `student_模板.py`，重命名为：
     - `student_你的姓名.py` 或 `student_学号.py`
   - 打开你的文件，按照模板中的提示填写：
     - 姓名、学号
     - 个人项目标题与简介
     - 每周学习日志（例如第几周学了什么、掌握情况、自我反思）
     - （可选）插入图表、图片、链接到你的 Gitee / GitHub 仓库。

4. **本地运行自测**
   - 确认自己页面可以在本地成功运行：
   ```bash
   streamlit run app.py
   ```
   - 在侧边栏或“作品展示墙”内，检查能否看到自己的页面与内容。

5. **提交到远程仓库**
   - 将你的修改提交到自己 Fork 的仓库：
   ```bash
   git add .
   git commit -m "添加个人学生页面：<你的姓名或学号>"
   git push origin main  # 或当前分支
   ```

6. **向教师主仓库发起 Pull Request**
   - 在 Gitee 打开你的仓库页面，点击“创建 Pull Request”。
   - 标题建议使用格式：
     - `[学生页面] 张三 - 第1次提交`
   - 描述中简单说明本次主要修改内容，例如：
     - “新增个人页面，包含第 1-2 周学习日志和一个线性回归实验。”

7. **等待教师审核合并**
   - 教师合并 PR 后，你的页面就会出现在主仓库的“作品展示墙”中，供全班同学学习交流。

---

## 页面功能概览

### 1. 主页 `app.py`

- 显示课程名称、授课教师、学期信息。
- 提供到以下模块的导航卡片：
  - 演示中心
  - 作品展示墙
  - 打卡记录
  - 实验平台
- 公告栏：后续可从 JSON 文件读取，便于教师直接修改文件发布通知。

### 2. 演示中心（`pages/01_演示中心.py`）

- 作为算法演示的“总览页”，列出：
  - 线性回归 / 逻辑回归
  - K-Means 聚类
  - 决策树与随机森林
  - 神经网络入门
- 每个算法演示页面包含：
  - 参数滑块 / 选择框（例如学习率、迭代次数、聚类数等）
  - 关键代码展示与可编辑区域（使用 Streamlit 文本框 + 安全沙箱执行）
  - 结果图表与评估指标（准确率、MSE 等）。

> 后续可以将具体算法演示拆分为更多子页面，例如 `pages/demos/线性回归.py` 等。

### 3. 作品展示墙（`pages/02_作品展示墙.py`）

- 自动扫描 `pages/students/` 目录，加载所有符合约定的学生页面 / 元数据。
- 每位学生以卡片形式展示：
  - 姓名
  - 学号
  - 项目标题
  - 一句话简介
- 支持点击跳转到对应学生子页面，查看详情。

### 4. 打卡记录模块（`pages/03_打卡记录.py`）

- 功能规划：
  - 学生输入姓名、本周主题、完成情况与反思。
  - 将打卡记录写入 `data/checkins.json`。
  - 汇总展示为表格或“热力图”（横轴周次、纵轴学生）。
- 当前实现：页面结构与基础表单框架，具体可视化可逐步完善。

### 5. 实验平台（`pages/04_实验平台.py`）

- 功能规划：
  - 支持上传 CSV 数据集。
  - 自动展示基本统计信息（`describe()`、缺失值、分布直方图等）。
  - 提供线性回归 / KNN / 随机森林等基础模型进行训练与评估。
- 当前实现：页面结构与占位说明，为后续实验内容预留入口。

---

## 学生个人页面模板说明（`pages/students/student_模板.py`）

模板中会包含以下变量，学生只需按注释提示填写：

```python
STUDENT_NAME = "你的姓名"
STUDENT_ID   = "学号"
PROJECT_TITLE = "项目名称"
PROJECT_DESC  = "项目一句话描述"
WEEK_LOGS     = [
    {"week": 1, "topic": "线性回归", "done": True,  "note": "理解了梯度下降"},
    {"week": 2, "topic": "决策树",   "done": False, "note": ""},
]
```

页面会根据上述信息自动渲染：
- 个人信息与简短介绍。
- 学习周志时间线。
- （可选）插入图片、图表或外部链接。

---

## 后续扩展建议

- 为演示中心增加“学生代码沙箱”功能，允许学生在前端安全修改部分算法代码并运行。
- 在 `utils/record.py` 中实现“学生运行记录”的读写，在页面底部展示每个学生的历史运行结果。
- 为每个算法演示页面添加“思考题”和“参考阅读链接”，引导学生在课后自学。
- 在 Gitee 仓库中使用 Issue / PR 模板，对学生提交进行更加规范化的管理。

如果你是本课程的学生，欢迎在理解本 README 的基础上，先从填写 `student_模板.py` 开始你的 AI 学习之旅。😊