个性化考试系统

💻 系统要求

硬件要求

#### 环境配置（参考） - CPU: Kunpeng-920处理器 - 存储: 196GB总容量（建议至少100GB可用空间用于模型文件和Docker镜像） - NPU: 昇腾910B2 NPU

安装依赖（使用国内镜像源，速度更快）

由于torch torch-npu torchaudio torchvision vllm vllm-ascend这几个包已经在docker中存在，安装是可能造成版本冲突，故不在requirements.txt中申明

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

#### 步骤3: 迁移数据到数据库

使用迁移脚本将JSON格式转换为数据库格式：

主要依赖第三方开源软件

本项目基于以下优秀的开源项目构建，我们感谢所有开源贡献者的工作。

（版本信息基于 requirements.txt）：

• Gradio (5.49.1, Apache 2.0) - 用于构建交互式Web界面
• PyTorch (2.5.1, BSD 3-Clause) - 深度学习框架
• torch-npu (2.5.1.post1, Apache 2.0) - 昇腾NPU支持
• Transformers (4.53.2, Apache 2.0) - Hugging Face 模型库
• vLLM (0.9.2, Apache 2.0) - 高性能LLM推理引擎
• vllm-ascend (0.9.2rc1, Apache 2.0) - vLLM昇腾支持
• NumPy (1.26.4, BSD 3-Clause) - 数值计算库
• NetworkX (3.5, BSD 3-Clause) - 图论和网络分析
• Plotly (6.4.0, MIT) - 交互式数据可视化
• FastAPI (0.117.1, MIT) - 高性能Web API框架
• Accelerate (1.10.1, Apache 2.0) - 模型加速库

第三方依赖许可证

本项目使用的第三方依赖许可证类型主要是商业友好的：

完整的开源软件清单和许可证信息请参考：

• 📋 LICENSE - 项目代码的许可证
• 📄 NOTICE - 开源软件声明文件
• 📦 requirements.txt - Python 依赖清单

部署环境

创建容器

```bash

启动 Docker 容器并挂载 NPU 设备

docker run -dit --net=host \ --name docker_person_exam \ --device /dev/davinci2 \ --device /dev/davinci_manager \ --device /dev/devmm_svm \ --device /dev/hisi_hdc \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \ -v /etc/ascend_install.info:/etc/ascend_install.info \ -v /opt/pangu:/opt/pangu \ -v /home:/home \ quay.io/ascend/cann:pangu-8.1.rc1-910b-py3.11 ```

安装Hugging Face CLI（如果未安装）

curl -LsSf https://hf.co/cli/install.sh | bash

Q: 必须使用Docker吗？

A: 是的，本项目使用Docker容器化部署。Docker提供了更好的环境隔离和依赖管理，无需手动配置Python虚拟环境。

Q: 如何进行远程SSH部署？

A: 远程SSH部署步骤： 1. 使用SSH密钥连接到远程服务器：ssh -i .cursor/liqinsi_key liqinsi@1.95.160.102 2. 上传代码到服务器的 /home/liqinsi/Documents/project/PersonalExam 目录 3. 创建容器（参考"创建容器"章节，容器名: docker_person_exam） 4. 复制代码到容器内：docker cp /home/liqinsi/Documents/project/PersonalExam/. docker_person_exam:/app/ 5. 进入容器：docker exec -it docker_person_exam /bin/bash 6. 安装依赖：cd /app && pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple 7. 在容器内运行：cd /app/education && python main.py

注意: 数据库文件存储在 education/data/education_system.db，建议通过volume挂载持久化。

方式2: 使用默认位置下载

运行迁移脚本，初始化系统数据库

python migrate_to_database.py ```

注意: - 系统首次启动时会自动创建默认用户账号，也可直接修改初始化脚本： - 学生账号: student_001 / 123456 - 教师账号: teacher / admin123 - 后续添加题目可以通过UI界面进行（见使用指南中的"题库管理"部分）

6. 启动系统

默认模型路径（通过环境变量配置）： - 盘古7B模型: 通过 PANGU_MODEL_PATH 环境变量配置，默认 /opt/pangu/openPangu-Embedded-7B-V1.1 - BGE嵌入模型: 通过 BGE_MODEL_PATH 环境变量配置 - 本地开发环境默认值: education/models/bge-small-zh-v1.5 - Docker容器环境默认值: /app/education/models/bge-small-zh-v1.5 - 如果未设置环境变量，将使用上述默认路径

启动步骤:

```bash

进入运行中的容器

docker exec -it docker_person_exam /bin/bash cd /app/education

启动系统

python main.py ```

注意: 如果之前没有安装依赖，请先执行步骤5中的依赖安装命令。

重要提示: - 初次运行构建知识图谱需要一定时间，请耐心等待 - 服务将会运行在: http://localhost:7860（默认端口） - 如果要修改端口，请在 education/config.py 中修改 UI_CONFIG['port'] 的值，或通过环境变量 GRADIO_SERVER_PORT 设置 - 确保机器已经开放相应端口，如果是云服务器还需要在安全组中设置

📖 使用指南

使用说明

重要: 使用本项目时，必须遵守以下许可证要求：

1. 项目代码许可证 (BSL 1.1): - 非商业使用：允许个人、教育、研究用途 - 商业使用：需要获得授权许可

2. OpenPangu模型许可证: 必须遵守OPENPANGU MODEL LICENSE AGREEMENT VERSION 1.0的所有条款 - 必须包含OpenPangu的归属声明 - 必须包含许可证通知 - 遵守OpenPangu商标使用规定 - 不能在欧盟境内使用

1. 第三方开源软件: 请遵守所有相关开源软件的许可证条款

详细信息请参考： - 项目许可证: LICENSE - 开源软件声明: NOTICE - 各项目的官方文档

Q: 容器启动失败怎么办？

A: 检查以下几点： 1. 查看容器日志：docker logs personal-exam 2. 确认端口7860未被占用（本地部署） 3. 确认NPU设备正确挂载（如果使用NPU） 4. 确认模型文件路径正确 5. 远程部署时，确认所有volume挂载路径存在且可访问

下载到项目 models 目录，与配置文件中的默认路径一致

hf download BAAI/bge-small-zh-v1.5 --local-dir /app/education/models/bge-small-zh-v1.5

下载后需要配置 BGE_MODEL_PATH 环境变量指向实际路径

hf download BAAI/bge-small-zh-v1.5 ```

应该包含模型权重文件（如 .bin, .safetensors 等）和配置文件（config.json, tokenizer.json 等）

设置环境变量（根据实际路径调整）

export PANGU_MODEL_PATH=/opt/pangu/openPangu-Embedded-7B-V1.1

⚙️ 配置说明

主要配置项

配置文件: education/config.py

```python

模型配置

PANGU_MODEL_CONFIG = { "max_new_tokens": 32768, "temperature": 0.7, "top_p": 0.9, "device": "npu", }

智能出题配置

SMART_QUESTION_CONFIG = { "default_question_count": 10, "weak_threshold": 0.4, # 薄弱点阈值 "weak_point_focus_ratio": 0.7, # 薄弱点题目比例 "rebuild_kg": False, # 是否强制重建知识图谱 "use_kg_rag": True, # 是否使用知识图谱RAG "kg_rag_top_k": 5, # 知识图谱RAG返回的候选题目数量 }

UI配置

UI_CONFIG = { "port": 7860, "share": False, "server_name": "0.0.0.0" }

日志配置

LOGGING_CONFIG = { "level": "INFO", "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s", "log_file": "logs/system.log" } ```

数据库配置

数据库文件路径在 main.py 中配置，默认路径为： - 数据库文件: education/data/education_system.db - 知识图谱缓存: education/data/knowledge_graph.pkl - 知识图谱哈希: education/data/kg_hash.txt

数据库会自动创建，包含以下表： - users: 用户表（学生和教师） - questions: 题目表 - student_states: 学生状态表（BKT参数） - answer_records: 答题记录表

环境变量

可以通过环境变量覆盖配置：

export PANGU_MODEL_PATH="/path/to/pangu/model"
export BGE_MODEL_PATH="/path/to/bge/model"
export GRADIO_SERVER_PORT=7860  # 修改UI端口

3. 下载bge-small-zh-v1.5模型

模型地址：https://huggingface.co/BAAI/bge-small-zh-v1.5

```bash curl -LsSf https://hf.co/cli/install.sh | bash # Make sure the hf CLI is installed

4. 下载OpenPangu-Embedded-7B-V1.1模型

重要提示：OpenPangu模型采用 OPENPANGU MODEL LICENSE AGREEMENT VERSION 1.0 许可证，使用前请仔细阅读并遵守许可协议条款。

模型地址：https://huggingface.co/FreedomIntelligence/openPangu-Embedded-7B-V1.1

```bash

创建模型目录

mkdir -p /opt/pangu

下载模型到指定目录

hf download FreedomIntelligence/openPangu-Embedded-7B-V1.1 --local-dir /opt/pangu/openPangu-Embedded-7B-V1.1

**验证模型文件**：

检查模型文件是否存在

ls -lh /opt/pangu/openPangu-Embedded-7B-V1.1/

OpenPangu模型许可证

本项目使用了OpenPangu模型（openPanGu-Embedded-7B-V1.1）。OpenPangu是由华为技术有限公司（Huawei Technologies Co., Ltd.）发布的大型语言模型。

OpenPangu模型采用 OPENPANGU MODEL LICENSE AGREEMENT VERSION 1.0 许可证

使用OpenPangu模型时，必须遵守OPENPANGU MODEL LICENSE AGREEMENT VERSION 1.0的所有条款和条件，包括： - 地理限制：不能在欧盟境内使用 - 归属声明：必须包含OpenPangu的归属声明 - 许可证通知：必须包含许可证副本或链接

有关详细信息，请参阅： - OpenPangu 7B模型 (Hugging Face): https://huggingface.co/FreedomIntelligence/openPangu-Embedded-7B-V1.1 - OpenPangu官方仓库: https://ai.gitcode.com/ascend-tribe/openpangu-embedded-7b-model

AI 模型

本项目使用的 AI 模型：

• OpenPangu模型 (openPanGu-Embedded-7B-V1.1)
• 来源: 华为技术有限公司 (Huawei Technologies Co., Ltd.)
• 许可证: OPENPANGU MODEL LICENSE AGREEMENT VERSION 1.0
• 参考: https://huggingface.co/FreedomIntelligence/openPangu-Embedded-7B-V1.1
• 重要: 本项目使用OpenPangu模型，需遵守OPENPANGU MODEL LICENSE AGREEMENT VERSION 1.0许可协议

• BGE-small-zh-v1.5
• 来源: 北京智源人工智能研究院 (BAAI)
• 许可证: Apache 2.0
• 参考: https://github.com/FlagOpen/FlagEmbedding

Q: 如何修改模型路径？

A: 有三种方式： 1. 在Dockerfile中配置（构建时） 2. 通过环境变量配置（运行时） 3. 挂载配置文件（运行时）

❓ 常见问题