yzexam/doc/ai_question_generation_guide.md

# AI题目生成功能使用指南

## 功能概述

AI题目生成功能是yzexam在线考试系统的一个扩展功能，通过调用AI大模型API（如DeepSeek、OpenRouter等）来自动生成各种类型的题目，包括选择题、简答题和论述题等，以提高教师出题效率，丰富题库内容。

## 功能特性

- 支持生成多种题型：单选题、多选题、简答题、论述题
- 支持"全部题型"选项，一次性生成多种类型的题目
- 支持设置题目数量（1-20题）
- 支持设置题目难度等级：简单、中等、困难
- 支持指定知识点范围生成题目
- 支持指定关键词生成题目（多个关键词用逗号分隔）
- 支持指定题目方向生成题目（理解、应用、分析、综合、评价）
- 支持指定适合学段生成题目（初中、高中、大学、研究生）
- 生成的题目可直接保存到题库中

## 技术架构

### 后端技术栈
- Java + Spring Boot
- OkHttp（用于调用AI API）
- FastJSON（用于JSON处理）
- MyBatis（用于数据库操作）

### 前端技术栈
- Vue.js 2.x
- Element UI
- Axios

## 部署配置

### 1. 配置AI API密钥

在[application.yml](file:///Volumes/macData/code/yzexam/examapi/ruoyi-admin/src/main/resources/application.yml)中配置AI API相关信息：

```yaml
# AI题目生成配置
ai:
  # DeepSeek API配置
  api-url: https://api.deepseek.com/v1/chat/completions
  model-name: deepseek-chat
  api-key: ${AI_API_KEY:}
  connect-timeout: 30
  read-timeout: 60
  write-timeout: 30
  
  # OpenRouter API配置
  openrouter:
    api-url: https://openrouter.ai/api/v1/chat/completions
    model-name: deepseek/deepseek-v3-0324-free
    api-key: ${OPENROUTER_API_KEY:}
    enabled: false
```

### 2. 设置环境变量

可以选择使用DeepSeek API或OpenRouter API：

使用DeepSeek API：
```bash
export AI_API_KEY="your_deepseek_api_key_here"
```

使用OpenRouter API：
```bash
export OPENROUTER_API_KEY="your_openrouter_api_key_here"
```

### 3. 数据库权限配置

运行[ai_question_permissions.sql](file:///Volumes/macData/code/yzexam/doc/ai_question_permissions.sql)脚本，为系统添加AI题目生成功能所需的菜单和权限。

## 使用说明

### 1. 访问AI题目生成功能

1. 登录系统后，进入"题库管理"模块
2. 选择一个题库或创建新题库
3. 点击"AI生成题目"按钮
4. 系统将跳转到AI题目生成页面

### 2. 配置生成参数

在AI题目生成页面中，配置以下参数：

- **题目类型**：选择要生成的题目类型（单选题、多选题、简答题、论述题或全部题型）
- **题目数量**：输入要生成的题目数量（1-20题）
- **知识点范围**：输入题目涉及的知识点范围
- **关键词**：输入与题目相关的关键词（多个关键词用逗号分隔）
- **难易程度**：选择题目的难度等级（简单、中等、困难）
- **题目方向**：选择题目的考查方向（理解、应用、分析、综合、评价）
- **适合学段**：选择题目适合的学段（初中、高中、大学、研究生）

### 3. 生成题目

点击"生成题目"按钮，系统将调用AI API生成指定类型的题目，并在页面中显示生成结果。

### 4. 保存题目

生成题目后，可以点击"保存到题库"按钮将题目保存到当前题库中。

## API接口说明

### 1. 生成选择题
```
POST /ai/questions/choice
Content-Type: application/json

{
  "knowledgePoint": "马克思主义基本原理",
  "keywords": "唯物主义,辩证法,实践",
  "difficulty": "medium",
  "direction": "comprehension",
  "gradeLevel": "college",
  "multiple": false
}
```

### 2. 生成简答题
```
POST /ai/questions/short-answer
Content-Type: application/json

{
  "knowledgePoint": "社会主义核心价值观",
  "keywords": "爱国,敬业,诚信,友善",
  "difficulty": "medium",
  "direction": "application",
  "gradeLevel": "college"
}
```

### 3. 生成论述题
```
POST /ai/questions/essay
Content-Type: application/json

{
  "knowledgePoint": "新时代党的建设",
  "keywords": "全面从严治党,反腐倡康,制度建设",
  "difficulty": "hard",
  "direction": "evaluation",
  "gradeLevel": "postgraduate"
}
```

### 4. 批量生成题目
```
POST /ai/questions/batch
Content-Type: application/json

{
  "questionType": "choice",
  "count": 5,
  "knowledgePoint": "马克思主义基本原理",
  "keywords": "唯物主义,辩证法,实践",
  "difficulty": "medium",
  "direction": "comprehension",
  "gradeLevel": "college",
  "multiple": false
}
```

### 5. 保存AI生成的题目
```
POST /ai/questions/save
Content-Type: application/json

{
  "questions": [...], // AI生成的题目列表
  "bankCode": "题库代码"
}
```

## 安全注意事项

1. API密钥应妥善保管，不要硬编码在代码中
2. 建议通过环境变量或配置中心管理API密钥
3. 实际部署时应添加身份验证和权限控制
4. 添加API调用频率限制，防止滥用

## 常见问题

### 1. 生成题目失败

可能原因：
- API密钥配置错误
- 网络连接问题
- AI API服务不可用

解决方案：
- 检查API密钥是否正确配置
- 检查网络连接是否正常
- 确认AI API服务是否可用

### 2. 保存题目失败

可能原因：
- 题库代码不正确
- 数据库连接问题
- 权限不足

解决方案：
- 检查题库代码是否正确
- 检查数据库连接是否正常
- 确认用户是否有保存题目的权限

## 扩展建议

1. 添加题目质量评估功能
2. 实现题目去重机制
3. 添加题目版本管理
4. 支持批量生成题目
5. 添加题目审核流程
6. 实现题目分类管理
7. 添加题目搜索功能
8. 支持题目导出为不同格式