# smart-class-back

**Repository Path**: bytesc/smart-class-back

## Basic Information

- **Project Name**: smart-class-back
- **Description**: ✨ 一种基于代码生成的大语言模型 (LLM) 智能体，实现班级自主管理小程序 A code-generation-based LLM agent for autonomous class management mini-programs.✨一个基于大语言模型（LLM）的智能班级管理小程序，通过代码生成和函数调用实现多智能体协同，支持自然语言交互、成绩预测、统计分析、可视化图表等功能。创新点包括函数
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: http://www.bytesc.top
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-02-07
- **Last Updated**: 2025-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# smart class

✨ **一种基于代码生成的大语言模型 (LLM) 智能体，实现班级自主管理小程序**

一个基于大语言模型（LLM）的智能班级管理小程序，通过代码生成和函数调用实现多智能体协同，支持自然语言交互、成绩预测、统计分析、可视化图表等功能。创新点包括函数依赖图、智能体反问机制和动态知识库集成，系统采用Django和FastAPI混合架构，兼顾开发效率与高并发性能，为班级管理提供智能化解决方案。

🚩[English Readme](./README.en.md)

[📺演示视频 ./demo_video_480.mp4](./demo_video_480.mp4) 

[📝相关论文 ./paper.pdf](./paper.pdf)

### 相关项目
- [基于代码生成和函数调用(function call)的大语言模型(LLM)智能体 https://github.com/bytesc/data-copilot-functions](https://github.com/bytesc/data-copilot-functions)
- [基于大语言模型 (LLM) 的<u>**可解释型**</u>自然语言数据库查询系统 (RAG) https://github.com/bytesc/data-copilot-steps](https://github.com/bytesc/data-copilot-steps)
- [基于大语言模型 (LLM)和并发预测模型的自然语言数据库查询系统 (RAG) (https://github.com/bytesc/data-copilot-v2](https://github.com/bytesc/data-copilot-v2)

配套前端项目链接
- github: [https://github.com/bytesc/smart-class-front](https://github.com/bytesc/smart-class-front)
- gitee: [https://gitee.com/bytesc/smart-class-front](https://gitee.com/bytesc/smart-class-front)


🚩[个人网站：www.bytesc.top](http://www.bytesc.top)

🔔 如有项目相关问题，欢迎在本项目提出`issue`，我一般会在 24 小时内回复。

## 功能简介

- 1, 基于代码生成的大语言模型智能体(AI Agent)。
- 2, 实现智能体对用户的反问，解决用户提问模糊、不完整的情况。
- 3, 智能体可以访问动态知识库，调用检索增强生成模块(RAG)，结合背景知识解决问题
- 4, 智能体支持灵活的自定义函数调用(function call)和思维链(COT)
- 5, 实现多智能体的合作调用
- 6, 智能体实现智能绘制多种统计图表
- 7, 智能体实现基于机器学习的智能成绩预测 
- 8, 能够处理大语言模型表现不稳定等异常情况
- 9, 支持 `openai` 格式(如 `glm` ,`deepseek`, `qwen`)的 api 接口

## 项目背景
目前，大学生的班级信息管理主要通过微信群进行发布，但是群里的相关文件很容易过期，大量的聊天记录容易干扰学生学习，无法实现智能组建学习小组、个人成绩预测等功能。为了方便学生及时了解学校各类政策、实时了解自己的学习情况，增强学生的学习自觉性和主动性，同时为了帮助班导师更好地进行班级管理，提高工作效率，开发一款全面、高效的班级自主管理小程序具有一定的现实意义。


## 创新点
- 基于代码生成的智能体(Agent)支持灵活的自定义函数调用(function call)和思维链(COT)
- 引入函数依赖图(Function Graph)的概念，实现自定义函数调用
- 引入智能体函数(Agent as Function)的概念，实现多智能体(Agent)的合作调用
- 实现智能体(Agent)对用户的反问，解决用户提问模糊、不完整的情况
- 包含输出断言和异常处理，能够处理大语言模型表现不稳定等异常情况
- 系统架构兼顾了Django的开发高效与结构统一和FastAPI的高并发性能与功能敏捷

## 技术路线

### AI agent 

基本程序流水线图：

![](./readme_static/流程图1.png)

![](./readme_static/流程图2.png)

基本流程：
1. **Question**: 用户自然语言问题提问
2. **RAG**: 通过检索增强生成(RAG)获取背景知识
3. **Function Selection**: LLM 根据函数基本信息选择多个函数，通过函数依赖图(Function Graph)获得可用函数列表和详细注释（函数包括非智能体函数(Custum Function)和调用其它智能体的函数(Agent as Function)，实现多智能体协同）
4. **Function Calls Chain**: LLM 根据函数列表和详细注释，生成调用多个函数的 python 代码并执行
5. **Result Review**: LLM 回顾总结整个流程，评估问题是否解决，没有解决则反问用户，使其澄清问题或者提供更多信息



### 系统架构

系统架构图：

![](./readme_static/a1.png)

FastAPI 搭建用户后端，Django 搭建管理端，模型-视图-控制器(MVC)与领域驱动设计(DDD)相结合的系统设计，实现了数据库结构定义与增删改查的分离，用户后端与管理端的解耦，Django 高效搭建管理端和 FastAPI 的高并发性能结合，兼顾了Django的开发高效与结构统一和FastAPI的高并发性能与功能敏捷。


## 界面展示

### 智能助手(AI Agent)

知识库的检索增强生成(RAG)，智能解答问题，支持连续对话

![](./readme_static/r1.png)

数据库查询，统计计算和图表绘制，统计分析，可视化

![](./readme_static/r2.png)

原理：函数调用链(Function Call Chain)和智能体函数(Agent as Function)，实现多智能体协同原理示例

![](./readme_static/f1.png)

如果对智能绘图不满意，生成自定义交互式绘图工具链接

![](./readme_static/w10.png)
![](./readme_static/w11.png)

用户提供信息不足以完成任务时，反问用户使其补充信息(Result Review)

![](./readme_static/r3.png)

调用自定义的学生成绩预测模型

![](./readme_static/r4.png)

原理：函数依赖图(Function Graph)和非智能体函数(Custom Functions)原理示例

![](./readme_static/f2.png)


### 用户端(微信小程序)

用户登录，注册，修改密码

![](./readme_static/w1.png)

切换班级页面，菜单页面，用户信息

![](./readme_static/w2.png)

管理端实现用户的批量导入导出

![](./readme_static/w3.png)

班级通讯录和站内消息

![](./readme_static/w4.png)

成绩统计和可视化

![](./readme_static/w5.png)

基于机器学习的成绩智能预测，班级智能分组

![](./readme_static/w6.png)

学校政策与班级公告

![](./readme_static/w7.png)

配套前端项目链接
- github: [https://github.com/bytesc/smart-class-front](https://github.com/bytesc/smart-class-front)
- gitee: [https://gitee.com/bytesc/smart-class-front](https://gitee.com/bytesc/smart-class-front)

示例问题
```txt
计算机专业核心课程有哪些

我的大学物理会挂科吗
我是张伟

查询计211的每个同学的平均成绩，画出前三名的成绩对比图
```

### 管理端

基于 Django-admin 和 simple-ui 的管理端

![](./readme_static/g1.png)


## 如何使用

### 安装依赖

python 版本 3.10

```bash
pip install -r requirement-1.txt
pip install -r requirement-2.txt
```

### 管理端(django-server)

这是管理端，使用 Django 支持管理端的高效搭建和数据库结构管理
```bash
cd ./django-server
```

#### 配置文件

`mysite/settings.py` 77行附近
```python
# 填写数据库信息
# Database
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "NAME": "smart_class2",
        "USER": "root",
        "PASSWORD": "123456",
        "HOST": "127.0.0.1",
        "PORT": "3306",
    }
}
```

#### 运行

首次运行创建数据库内容，新建超级管理员
```bash
# 初始化数据库内容
python manage.py makemigrations
python manage.py migrate
# 新建超级管理员
python manage.py createsuperuser
python manage.py runserver
```

运行
```bash
python manage.py runserver 0.0.0.0:8000
```

浏览器输入连接，打开管理端 [http://127.0.0.1:8000/](http://127.0.0.1:8000/)


### 用户后端(fastapi-server)

这是用户后端，使用 FastAPI 支持高并发请求
```bash
cd ./fastapi-server
```

#### 配置文件

`config.yaml`
```yml
server_port: 8001 
server_host: "0.0.0.0"  

# 填写数据库连接
mysql: "mysql+pymysql://root:123456@localhost:3306/smart_class2"

# ai-agent server
agent_url: "http://127.0.0.1:8003/ask-agent/"
```

#### 数据库

运行`sql`文件，添加触发器和存储过程，初始化数据库。
可用通过命令行，数据库终端等方式运行。
```bash
mysql -u root -p -P 3306 smart_class2 < ./sql/trigger_and_procedure.sql
```

#### 生成密钥对

运行 `api/utils/rsa/rsa.py` 生成 RSA 密钥对用于 token 签发
```bash
cd ./api/utils/rsa/
python rsa.py
```


#### 配置微信小程序

如果前端不使用微信小程序，跳过这一步

新建文件：`api/utils/openid/appid.txt` 和 `api/utils/openid/secret.txt`
其中分别填写微信小程序的`secret`和`appid`

获取途径：[微信公众平台](https://mp.weixin.qq.com/)


#### 运行

```bash
python ./main.py
```

### 大语言模型智能体(AI Agent)服务(ai-server)

大语言模型智能体(AI Agent)服务，实现以自然语言的方式操作系统，是本项目的核心创新点所在。
```bash
cd ./ai-server
```

#### 配置文件

`config.yaml`
```yml
# config
server_port: 8003
server_host: "0.0.0.0"
# 填写数据库连接
mysql: "mysql+pymysql://root:123456@localhost:3306/smart_class2"

# 本机ip/域名:server_port
static_path: "http://127.0.0.1:8003/"

# 是否启用智能体回答 review 功能
ans_review: "false"
# true/false
```

#### 大语言模型配置

`config.yaml`
```yml
model_name: "qwen-max"
    # glm-4
    # deepseek-chat
    # qwen-max
  
model_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    # https://open.bigmodel.cn/api/paas/v4/
    # https://api.deepseek.com/v1/
    # https://dashscope.aliyuncs.com/compatible-mode/v1
```


新建文件：`agent\utils\llm_access\api_key_openai.txt` 在其中填写`api-key`

`api-key`获取链接：
- 阿里云:[https://bailian.console.aliyun.com/](https://bailian.console.aliyun.com/)
- deepseek:[https://api-docs.deepseek.com/](https://api-docs.deepseek.com/)
- glm:[https://open.bigmodel.cn/](https://open.bigmodel.cn/)


#### 检索增强生成(RAG)配置

如果不需要 rag 

`config.yaml` 的 `rag_model_path` 为空字符串即可
```yml
rag_model_path: ""
```

如果需要 rag 

`config.yaml` 填写词嵌入模型的保存路径（绝对路径）
```yml
rag_model_path: "D:/IDLE/big/RAG/models/text2vec-base-multilingual/"
# https://huggingface.co/shibing624/text2vec-base-multilingual/tree/main
# https://hf-mirror.com/shibing624/text2vec-base-multilingual/tree/main
```

模型在 `huggingface` 或者其镜像网站下载
- [https://huggingface.co/shibing624/text2vec-base-multilingual/tree/main](https://huggingface.co/shibing624/text2vec-base-multilingual/tree/main)
- [https://hf-mirror.com/shibing624/text2vec-base-multilingual/tree/main](https://hf-mirror.com/shibing624/text2vec-base-multilingual/tree/main)

词嵌入模型文件夹结构
```bash
├─text2vec-base-multilingual
│      config.json
│      eval_results.txt
│      gitattributes
│      model.safetensors
│      modules.json
│      pytorch_model.bin
│      README.md
│      sentence_bert_config.json
│      special_tokens_map.json
│      tokenizer.json
│      tokenizer_config.json
│      unigram.json
```

#### 运行

```bash
python ./main.py
```



# 开源许可证

此翻译版本仅供参考，以 LICENSE 文件中的英文版本为准

MIT 开源许可证：

版权所有 (c) 2025 bytesc

特此授权，免费向任何获得本软件及相关文档文件（以下简称“软件”）副本的人提供使用、复制、修改、合并、出版、发行、再许可和/或销售软件的权利，但须遵守以下条件：

上述版权声明和本许可声明应包含在所有副本或实质性部分中。

本软件按“原样”提供，不作任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性。在任何情况下，作者或版权持有人均不对因使用本软件而产生的任何索赔、损害或其他责任负责，无论是在合同、侵权或其他方面。