# rag-exam-generator

**Repository Path**: MerrySunlight/rag-exam-generator

## Basic Information

- **Project Name**: rag-exam-generator
- **Description**: 基于RAG的考试题生成工具，自动从文档生成高质量试题，支持多格式输入与自定义题型，助力教育智能化。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 本地 RAG 约束式智能评测生成系统

面向课程、培训与网络安全知识库的本地化智能评测生成原型。系统以本地知识库检索约束大语言模型生成，并通过题型、难度、知识类别、审核状态和相似度检查，完成从题目生成到组卷、审核和导出的流程。

> 本仓库仅发布可复现源码。知识材料、题库、向量索引、试卷、日志和账号数据均不会随仓库提供。

## 功能特性

### 知识库管理

- 支持 PDF、DOCX 等文档导入，以及基于段落和句子的自适应分块；
- 使用 ChromaDB 或本地 TF-IDF 存储实现检索增强生成（RAG）；
- 支持本地处理和进度反馈。

### 题库与试卷管理

- 支持单选、多选、判断等题型，以及 Easy、Medium、Hard 难度分级；
- 以知识类别组织题目，基于 TF-IDF 相似度检查减少重复题目；
- 支持管理员、出题人、审核员三级角色；
- 按知识类别和难度比例约束组卷，支持单题重生成；
- 试卷状态按 `Draft → Review → Approved → Exported` 流转，并记录创建、审核与导出时间。

### 导出与安全

- 支持 PDF、JSON、CSV 导出，以及带答案或不带答案的版本；
- 本地部署、会话 Token、密码哈希、字段加密工具、输入与文件路径校验、访问限流；
- 生成结果仅作辅助，必须经过人工审核。

## 系统架构

```text
知识材料 → 文档加载 → 文本切分 → 向量入库 → 检索增强 → 本地 LLM
    → 相似度校验 → 题目入库 → 审核通过 → 组卷编排 → 多格式导出

Streamlit 前端
  ├─ 认证、审计、安全校验与配置
  ├─ 知识库（加载、切分、向量存储、检索）
  ├─ 题库（SQLite、相似度检查）
  ├─ 组卷引擎（生成、去重、编排）
  └─ 导出（PDF、JSON、CSV）
```

默认模型接口兼容本地 Ollama，可通过 `OLLAMA_BASE_URL`、`OLLAMA_MODEL` 和 `OLLAMA_EMBED_MODEL` 配置。未连接模型时，系统保留模板生成路径，不能替代人工审核。

## 快速开始

### 环境要求

- Python 3.9+
- Windows 10+、Linux、macOS、统信 UOS 或麒麟
- 可选：Ollama（用于本地 LLM 推理）

### 1. 配置环境

在仓库根目录复制配置模板：

```powershell
Copy-Item .env.example .env
```

创建虚拟环境并安装依赖：

```powershell
cd exam_generator
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

Linux/macOS 激活命令：

```bash
source .venv/bin/activate
```

### 2. 设置管理员密码并启动

```powershell
$env:EXAM_GENERATOR_ADMIN_PASSWORD = '请替换为长度至少12位的本地强口令'
streamlit run app.py
```

浏览器访问 `http://localhost:8501`。首次启动时，系统会在 `exam_generator/data/` 创建运行数据库和通用知识结构模板。

### 配置项

| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| `OLLAMA_BASE_URL` | Ollama 服务地址 | `http://localhost:11434` |
| `OLLAMA_MODEL` | 文本生成模型 | `qwen2.5:7b` |
| `OLLAMA_EMBED_MODEL` | 向量嵌入模型 | `nomic-embed-text` |
| `EXAM_GENERATOR_ADMIN_PASSWORD` | 管理员初始密码 | 必须手动设置 |

## 使用流程

1. 在“知识库管理”中上传拥有处理授权的 PDF 或 DOCX 材料；
2. 在“组卷配置”中设置题型、难度比例和知识类别数量；
3. 在“试卷管理”中新建试卷，系统检索知识库并生成题目；
4. 审核员检查题目、答案和解析后通过或退回；
5. 审核通过后导出 PDF、JSON 或 CSV。

## 目录结构

```text
.
├── .env.example
├── README.md
├── SECURITY.md
└── exam_generator/
    ├── app.py                 # 应用入口
    ├── auth.py                # 用户认证
    ├── config.py              # 系统配置
    ├── crypto_utils.py        # 加密工具
    ├── security.py            # 安全校验
    ├── knowledge_base/        # 文档加载、切分、向量存储、检索
    ├── question_bank/         # SQLite 题库与相似度检查
    ├── exam_engine/           # 生成、去重、组卷
    ├── export/                # PDF、JSON、CSV 导出
    ├── pages/                 # Streamlit 页面
    ├── docs/                  # 使用、技术、部署文档
    └── data/                  # 本地运行数据（不纳入版本控制）
```

## 常见问题

**没有安装 Ollama 可以使用吗？**  
可以使用模板生成模式，但无法进行 RAG 增强生成。建议安装 Ollama 以获得更好的题目质量。

**如何备份数据？**  
在系统停止运行后复制 `exam_generator/data/` 目录。该目录可能包含数据库和向量索引，请勿提交到公开仓库。

**PDF 中文显示乱码怎么办？**  
请检查系统中文字体库是否正常安装。

**管理员密码忘记了怎么办？**  
仅在确认可以清除本地运行数据时，删除 `exam_generator/data/` 内的运行数据库后重启，并重新设置 `EXAM_GENERATOR_ADMIN_PASSWORD`。此操作会丢失本地数据。

## 数据与使用边界

- 请勿提交版权受限教材、真实题库、个人信息、访问凭据或运行日志；
- 请勿将未获授权的数据上传或复用到公开环境；
- 对网络安全材料，应遵循所属机构的访问控制、保密与数据处理规则。

## 开源说明

公开版已将原有垂直领域配置替换为通用模板，展示本地 RAG、约束式生成、去重、审核状态流转和轻量级数据管理能力。使用者可按自身合规材料调整知识结构。

## 许可证

本项目采用 [MIT License](LICENSE)。