a3aa6cbcf3
- generate-smart 的 requested_types 可能包含值为0的题型（AI分析结果） - actual_types 仅包含实际生成数量大于0的题型 - 文档已通过生产服务器三端点实测验证
768 lines
22 KiB
Markdown
768 lines
22 KiB
Markdown
# 出题批卷系统设计
|
||
|
||
> **文档类型**: 系统设计文档 & 后端对接手册
|
||
> **创建日期**: 2026-04-10
|
||
> **最后更新**: 2026-06-22
|
||
> **版本**: 3.0
|
||
> **状态**: 已实施
|
||
|
||
---
|
||
|
||
## 一、系统概述
|
||
|
||
### 1.1 定位
|
||
|
||
出题批卷系统是 RAG 知识库服务的扩展模块（`exam_pkg`），负责基于知识库文档自动生成题目和自动批阅。RAG 服务只负责出题和批题的无状态计算，题目的存储、审核、状态管理由后端服务负责。
|
||
|
||
### 1.2 职责边界
|
||
|
||
| 职责 | RAG 服务 | 后端服务 |
|
||
|------|----------|----------|
|
||
| 题目生成 | 基于文档生成题目 + 溯源 | 审核入库 + 状态管理 |
|
||
| 题目批阅 | 逐题评分 + 反馈 | 汇总报告 + 成绩存储 |
|
||
| 题目存储 | 无状态，不存储 | MySQL 持久化 |
|
||
|
||
### 1.3 模块结构
|
||
|
||
```
|
||
exam_pkg/
|
||
├── generator.py # 出题引擎（v2管线：章节分组→知识点提取→精准出题→去重补题）
|
||
├── grader.py # 批阅引擎（客观题精确匹配 + 填空题模糊匹配 + 主观题LLM评分）
|
||
├── manager.py # 编排层（检索切片→调用引擎→组装返回）
|
||
├── api.py # Flask Blueprint（exam_bp, url_prefix=/exam）
|
||
└── local_db.py # 本地题库缓存（SQLite，辅助功能）
|
||
```
|
||
|
||
### 1.4 服务信息
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 服务地址 | `http://<host>:5001` |
|
||
| URL前缀 | `/exam` |
|
||
| 健康检查 | `GET /exam/health` |
|
||
| 运行模式 | gunicorn + gthread (2 workers) |
|
||
|
||
---
|
||
|
||
## 二、统一响应格式
|
||
|
||
所有接口返回统一 JSON 信封：
|
||
|
||
### 2.1 成功响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"status": "success",
|
||
"status_code": 2020,
|
||
"message": "出题成功",
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
### 2.2 失败响应
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"status": "failed",
|
||
"error_code": "MISSING_PARAMS",
|
||
"status_code": 4000,
|
||
"message": "缺少 file_path 或 collection 参数"
|
||
}
|
||
```
|
||
|
||
### 2.3 业务状态码
|
||
|
||
| 状态码 | 常量名 | 说明 |
|
||
|--------|--------|------|
|
||
| 2020 | EXAM_SUCCESS | 出题成功 |
|
||
| 2021 | GRADE_SUCCESS | 批阅完成 |
|
||
| 4000 | BAD_REQUEST | 请求参数错误 |
|
||
| 4001 | UNAUTHORIZED | 未授权 |
|
||
| 4002 | FORBIDDEN | 权限不足 |
|
||
| 5020 | EXAM_ERROR | 出题失败 |
|
||
| 5021 | GRADE_ERROR | 批阅失败 |
|
||
|
||
---
|
||
|
||
## 三、API 接口
|
||
|
||
### 3.1 POST /exam/generate — 参数出题
|
||
|
||
根据指定的题型和数量，基于文档内容生成题目。
|
||
|
||
#### 请求体
|
||
|
||
```json
|
||
{
|
||
"file_path": "public_kb/产品手册.pdf",
|
||
"collection": "public_kb",
|
||
"question_types": {
|
||
"single_choice": 3,
|
||
"multiple_choice": 2,
|
||
"true_false": 2,
|
||
"fill_blank": 2,
|
||
"subjective": 1
|
||
},
|
||
"difficulty": 3,
|
||
"exclude_stems": ["已有题目的题干1", "已有题目的题干2"],
|
||
"request_id": "uuid-optional",
|
||
"options": {
|
||
"include_explanation": true,
|
||
"max_source_chunks": 50
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 请求参数说明
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `file_path` | string | 是 | — | 文件路径（向量库内相对路径） |
|
||
| `collection` | string | 是 | — | 向量库名称 |
|
||
| `question_types` | object | 是 | — | 题型及数量，见下方合法值 |
|
||
| `difficulty` | int | 否 | 3 | 难度等级 1-5 |
|
||
| `exclude_stems` | string[] | 否 | — | 排除已有题干（跨调用去重），最多100条 |
|
||
| `request_id` | string | 否 | — | 幂等性标识，原样返回 |
|
||
| `options.include_explanation` | bool | 否 | true | 是否生成答案解析 |
|
||
| `options.max_source_chunks` | int | 否 | 50 | 最大检索切片数 |
|
||
|
||
**question_types 合法键值**：`single_choice`、`multiple_choice`、`true_false`、`fill_blank`、`subjective`。值为非负整数，总题数上限 **20**。
|
||
|
||
#### 成功响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"status": "success",
|
||
"status_code": 2020,
|
||
"message": "出题成功",
|
||
"data": {
|
||
"success": true,
|
||
"request_id": "uuid",
|
||
"questions": [ ... ],
|
||
"total": 10,
|
||
"requested_types": {"single_choice": 3, "fill_blank": 2},
|
||
"actual_types": {"single_choice": 3, "fill_blank": 2},
|
||
"source_chunks_used": 15,
|
||
"warnings": ["fill_blank: 请求 3 道，实际生成 2 道"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**data 字段说明**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `success` | bool | 是否成功 |
|
||
| `request_id` | string/null | 请求标识原样返回 |
|
||
| `questions` | array | 题目列表，结构见第四章 |
|
||
| `total` | int | 实际生成题数 |
|
||
| `requested_types` | object | 请求的题型和数量 |
|
||
| `actual_types` | object | 实际生成的题型和数量 |
|
||
| `source_chunks_used` | int | 使用的文档切片数 |
|
||
| `warnings` | string[] | 警告信息（可选，某题型实际生成少于请求时出现） |
|
||
|
||
---
|
||
|
||
### 3.2 POST /exam/generate-smart — AI 智能出题
|
||
|
||
AI 自动分析文档内容，决定题型和数量后生成题目。与 `/exam/generate` 的区别是**不需要传 question_types**。
|
||
|
||
#### 请求体
|
||
|
||
```json
|
||
{
|
||
"file_path": "public_kb/产品手册.pdf",
|
||
"collection": "public_kb",
|
||
"difficulty": 3,
|
||
"max_total": 20,
|
||
"exclude_stems": ["已有题目的题干1"],
|
||
"request_id": "uuid-optional",
|
||
"options": {}
|
||
}
|
||
```
|
||
|
||
#### 请求参数说明
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `file_path` | string | 是 | — | 文件路径 |
|
||
| `collection` | string | 是 | — | 向量库名称 |
|
||
| `difficulty` | int | 否 | 3 | 难度等级 1-5 |
|
||
| `max_total` | int | 否 | — | AI出题总数上限（正整数）。**不传则不限制** |
|
||
| `exclude_stems` | string[] | 否 | — | 排除已有题干 |
|
||
| `request_id` | string | 否 | — | 幂等性标识 |
|
||
| `options` | object | 否 | {} | 同 /exam/generate |
|
||
|
||
#### 成功响应
|
||
|
||
与 `/exam/generate` 格式相同，`data` 中额外包含 `ai_analysis` 字段：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"status": "success",
|
||
"status_code": 2020,
|
||
"message": "AI 智能出题成功",
|
||
"data": {
|
||
"success": true,
|
||
"request_id": "uuid",
|
||
"questions": [ ... ],
|
||
"total": 15,
|
||
"requested_types": {"single_choice": 8, "true_false": 4, "fill_blank": 3},
|
||
"actual_types": {"single_choice": 8, "true_false": 4, "fill_blank": 3},
|
||
"source_chunks_used": 30,
|
||
"ai_analysis": {
|
||
"total_knowledge_points": 54,
|
||
"question_types": {"single_choice": 8, "true_false": 4, "fill_blank": 3},
|
||
"suitable_types": ["single_choice", "true_false", "fill_blank"],
|
||
"reason": "文档涵盖大量概念性内容..."
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**ai_analysis 字段说明**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `total_knowledge_points` | int | AI 提取的知识点总数 |
|
||
| `question_types` | object | AI 推荐的题型和数量 |
|
||
| `suitable_types` | string[] | 适合该文档的题型列表 |
|
||
| `reason` | string | AI 的分析说明 |
|
||
|
||
> **注意**：`requested_types` 来自 AI 分析结果（与 `ai_analysis.question_types` 一致），可能包含值为 0 的题型（表示 AI 认为该题型不适合当前文档）。`actual_types` 仅包含实际生成数量大于 0 的题型。
|
||
|
||
---
|
||
|
||
### 3.3 POST /exam/grade — 批题接口
|
||
|
||
逐题批阅并返回评分结果。支持 5 种题型混合批阅。
|
||
|
||
#### 请求体
|
||
|
||
```json
|
||
{
|
||
"request_id": "uuid-optional",
|
||
"answers": [
|
||
{
|
||
"question_id": "uuid-001",
|
||
"question_type": "single_choice",
|
||
"content": {"answer": "B"},
|
||
"student_answer": "A",
|
||
"max_score": 2
|
||
},
|
||
{
|
||
"question_id": "uuid-002",
|
||
"question_type": "multiple_choice",
|
||
"content": {"answer": ["A", "C"]},
|
||
"student_answer": ["A", "B"],
|
||
"max_score": 3
|
||
},
|
||
{
|
||
"question_id": "uuid-003",
|
||
"question_type": "true_false",
|
||
"content": {"answer": "对"},
|
||
"student_answer": "错",
|
||
"max_score": 2
|
||
},
|
||
{
|
||
"question_id": "uuid-004",
|
||
"question_type": "fill_blank",
|
||
"content": {"answer": [["答案1", "同义词"], ["答案2"]]},
|
||
"student_answer": ["学生答案1", "学生答案2"],
|
||
"max_score": 4
|
||
},
|
||
{
|
||
"question_id": "uuid-005",
|
||
"question_type": "subjective",
|
||
"content": {
|
||
"stem": "简述...",
|
||
"data": {"scoring_points": [{"point": "要点1", "weight": 0.5}, {"point": "要点2", "weight": 0.5}]},
|
||
"answer": "参考范文..."
|
||
},
|
||
"student_answer": "学生作答内容...",
|
||
"max_score": 10
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 请求参数说明
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `request_id` | string | 否 | 幂等性标识 |
|
||
| `answers` | array | 是 | 答案列表，每项结构见下方 |
|
||
|
||
**answers 每道题的字段**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `question_id` | string | 是 | 题目唯一标识 |
|
||
| `question_type` | string | 是 | 题型，合法值同 question_types 键名 |
|
||
| `content` | object | 是 | 题目内容（与出题接口返回的 content 结构一致，后端可直接透传） |
|
||
| `student_answer` | any | 是 | 学生答案（类型随题型变化） |
|
||
| `max_score` | number | 否 | 该题满分，默认：客观题2/填空4/主观10 |
|
||
|
||
**各题型 content 和 student_answer 格式**：
|
||
|
||
| 题型 | content.answer | student_answer |
|
||
|------|---------------|----------------|
|
||
| single_choice | `"B"` | `"A"` |
|
||
| multiple_choice | `["A", "C"]` | `["A", "B"]` |
|
||
| true_false | `"对"` 或 `"错"` | `"对"` 或 `"错"` |
|
||
| fill_blank | `[["答案1", "同义词"], ["答案2"]]` 每空一个数组（含可接受同义词） | `["学生答案1", "学生答案2"]` |
|
||
| subjective | 参考范文字符串 | 学生作答字符串 |
|
||
|
||
> **content 透传说明**：`content` 字段的结构与出题接口返回的 `questions[].content` 完全一致。后端在存储题目时保存整个 `content` 对象，批题时原样传入即可。
|
||
|
||
#### 成功响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"status": "success",
|
||
"status_code": 2021,
|
||
"message": "批阅完成",
|
||
"data": {
|
||
"success": true,
|
||
"request_id": "uuid",
|
||
"results": [ ... ],
|
||
"total_score": 10.5,
|
||
"total_max_score": 21.0,
|
||
"score_rate": 50.0
|
||
}
|
||
}
|
||
```
|
||
|
||
**data 顶层字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `success` | bool | 是否成功 |
|
||
| `request_id` | string/null | 请求标识 |
|
||
| `results` | array | 逐题评分结果（顺序与输入一致） |
|
||
| `total_score` | float | 总得分（保留1位小数） |
|
||
| `total_max_score` | float | 总满分 |
|
||
| `score_rate` | float | 得分率百分比（保留1位小数） |
|
||
|
||
---
|
||
|
||
### 3.4 GET /exam/health — 健康检查
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"service": "exam-api",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、题目数据结构
|
||
|
||
每道题（`questions` 数组中的元素）的完整结构：
|
||
|
||
```json
|
||
{
|
||
"question_type": "single_choice",
|
||
"difficulty": 3,
|
||
"content": {
|
||
"stem": "根据XX制度，以下哪项是正确的？",
|
||
"data": {
|
||
"options": [
|
||
{"key": "A", "content": "选项A内容"},
|
||
{"key": "B", "content": "选项B内容"},
|
||
{"key": "C", "content": "选项C内容"},
|
||
{"key": "D", "content": "选项D内容"}
|
||
]
|
||
},
|
||
"answer": "B",
|
||
"explanation": "根据XX制度第3条规定..."
|
||
},
|
||
"source_trace": {
|
||
"document_name": "public_kb/产品手册.pdf",
|
||
"chunk_ids": ["chunk_001", "chunk_002"],
|
||
"page_numbers": [3, 5],
|
||
"sources": [
|
||
{
|
||
"chunk_id": "chunk_001",
|
||
"page": 3,
|
||
"section": "第三章 管理制度",
|
||
"snippet": "原文相关片段前200字符..."
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.1 字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `question_type` | string | 题型标识 |
|
||
| `difficulty` | int | 难度 1-5 |
|
||
| `content.stem` | string | 题干文本 |
|
||
| `content.data` | object | 题型相关数据（见下方） |
|
||
| `content.answer` | any | 正确答案（类型随题型变化） |
|
||
| `content.explanation` | string | 答案解析（可选） |
|
||
| `source_trace` | object | 溯源信息 |
|
||
|
||
### 4.2 各题型 content 差异
|
||
|
||
**单选题 (single_choice)**：
|
||
```json
|
||
{
|
||
"content": {
|
||
"stem": "以下哪项是正确的？",
|
||
"data": {
|
||
"options": [
|
||
{"key": "A", "content": "..."},
|
||
{"key": "B", "content": "..."},
|
||
{"key": "C", "content": "..."},
|
||
{"key": "D", "content": "..."}
|
||
]
|
||
},
|
||
"answer": "B",
|
||
"explanation": "..."
|
||
}
|
||
}
|
||
```
|
||
|
||
**多选题 (multiple_choice)**：
|
||
```json
|
||
{
|
||
"content": {
|
||
"stem": "以下哪些是正确的？（多选）",
|
||
"data": {
|
||
"options": [
|
||
{"key": "A", "content": "..."},
|
||
{"key": "B", "content": "..."},
|
||
{"key": "C", "content": "..."},
|
||
{"key": "D", "content": "..."}
|
||
]
|
||
},
|
||
"answer": ["A", "C"],
|
||
"explanation": "..."
|
||
}
|
||
}
|
||
```
|
||
|
||
**判断题 (true_false)**：
|
||
```json
|
||
{
|
||
"content": {
|
||
"stem": "公司数据应定期备份（判断对错）",
|
||
"data": {},
|
||
"answer": "对",
|
||
"explanation": "..."
|
||
}
|
||
}
|
||
```
|
||
|
||
**填空题 (fill_blank)**：
|
||
```json
|
||
{
|
||
"content": {
|
||
"stem": "公司财务报表应在每季度结束后______天内提交。",
|
||
"data": {
|
||
"blank_count": 1
|
||
},
|
||
"answer": [["15", "十五日"]],
|
||
"explanation": "..."
|
||
}
|
||
}
|
||
```
|
||
|
||
> `answer` 格式为二维数组：外层对应每空，内层为该空的可接受答案列表（第一个为标准答案，其余为同义词/等价答案）。
|
||
|
||
**主观题 (subjective)**：
|
||
```json
|
||
{
|
||
"content": {
|
||
"stem": "简述公司数据安全的三道防线。",
|
||
"data": {
|
||
"scoring_points": [
|
||
{"point": "技术防线（防火墙、加密、访问控制）", "weight": 0.4},
|
||
{"point": "制度防线（安全规定、审批流程）", "weight": 0.3},
|
||
{"point": "人员防线（安全培训、意识教育）", "weight": 0.3}
|
||
]
|
||
},
|
||
"answer": "公司数据安全的三道防线包括：1.技术防线...",
|
||
"explanation": "..."
|
||
}
|
||
}
|
||
```
|
||
|
||
> `scoring_points[].weight` 为该评分要点的权重（0-1），批题时 LLM 按要点逐项评分。
|
||
|
||
### 4.3 溯源信息 (source_trace)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `document_name` | string | 来源文件名 |
|
||
| `chunk_ids` | string[] | 来源切片 ID 列表 |
|
||
| `page_numbers` | int[] | 来源页码（已排序去重） |
|
||
| `sources` | object[] | 详细来源信息 |
|
||
| `sources[].chunk_id` | string | 切片 ID |
|
||
| `sources[].page` | int/null | 页码 |
|
||
| `sources[].section` | string | 所属章节标题 |
|
||
| `sources[].snippet` | string | 来源切片前 200 字符 |
|
||
|
||
---
|
||
|
||
## 五、批题结果数据结构
|
||
|
||
`results` 数组中每道题的评分结果，结构因题型而异：
|
||
|
||
### 5.1 客观题 (single_choice / multiple_choice / true_false)
|
||
|
||
```json
|
||
{
|
||
"question_id": "uuid-001",
|
||
"score": 2,
|
||
"max_score": 2,
|
||
"grading_status": "success",
|
||
"details": {
|
||
"correct": true,
|
||
"student_answer": "B",
|
||
"correct_answer": "B",
|
||
"feedback": "正确！"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 填空题 (fill_blank)
|
||
|
||
```json
|
||
{
|
||
"question_id": "uuid-004",
|
||
"score": 2.0,
|
||
"max_score": 4,
|
||
"grading_status": "success",
|
||
"details": {
|
||
"blank_scores": [2.0, 0],
|
||
"total_blanks": 2,
|
||
"correct_blanks": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
> 填空题支持部分给分。`blank_scores` 为每空得分，支持模糊匹配（编辑距离容错 + 标点归一化）。
|
||
|
||
### 5.3 主观题 (subjective)
|
||
|
||
```json
|
||
{
|
||
"question_id": "uuid-005",
|
||
"score": 7.5,
|
||
"max_score": 10,
|
||
"grading_status": "success",
|
||
"details": {
|
||
"scoring_breakdown": [
|
||
{
|
||
"point": "技术防线",
|
||
"weight": 0.4,
|
||
"achieved": 0.9,
|
||
"comment": "表述准确，覆盖了主要技术手段"
|
||
},
|
||
{
|
||
"point": "制度防线",
|
||
"weight": 0.3,
|
||
"achieved": 0.5,
|
||
"comment": "提到了审批流程但缺少具体制度名称"
|
||
},
|
||
{
|
||
"point": "人员防线",
|
||
"weight": 0.3,
|
||
"achieved": 0.8,
|
||
"comment": "安全培训和意识教育均有涉及"
|
||
}
|
||
],
|
||
"highlights": ["技术防线表述全面"],
|
||
"shortcomings": ["制度防线描述不够具体"],
|
||
"overall_feedback": "整体回答较好，建议补充制度层面的具体规定。"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.4 批阅失败（兜底）
|
||
|
||
```json
|
||
{
|
||
"question_id": "uuid-005",
|
||
"score": 0,
|
||
"max_score": 10,
|
||
"grading_status": "failed",
|
||
"details": {
|
||
"error": "LLM 调用超时"
|
||
}
|
||
}
|
||
```
|
||
|
||
> 单题批阅失败不影响其他题目，失败题目得 0 分。
|
||
|
||
### 5.5 grading_status 取值
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `success` | 评分成功 |
|
||
| `failed` | 评分失败（LLM超时/解析异常），score 为 0 |
|
||
|
||
---
|
||
|
||
## 六、出题管线内部逻辑（供参考）
|
||
|
||
v2 出题管线分四个阶段：
|
||
|
||
**Phase 1 — 章节分组**：检索文档切片，按章节标题聚类，构建文档结构概览。
|
||
|
||
**Phase 2 — 知识点提取**：逐章节调用 LLM 提取知识点列表。每次 LLM 调用间隔 1 秒防限流。
|
||
|
||
**Phase 3 — 精准出题**：按知识点 + 题型分配方案，逐知识点调用 LLM 生成题目。支持 429 限流自动重试（指数退避 1s→2s→4s）。
|
||
|
||
**Phase 4 — 后处理**：
|
||
- 四层去重：题干精确去重 → 语义相似度去重 → 知识点均衡 → 跨调用去重（exclude_stems）
|
||
- 补题机制：某知识点出题失败时自动从其他知识点补题，补题与已有题干交叉去重
|
||
|
||
---
|
||
|
||
## 七、批阅逻辑说明（供参考）
|
||
|
||
| 题型 | 批阅方式 | 匹配策略 |
|
||
|------|----------|----------|
|
||
| single_choice | 精确匹配 | 大小写不敏感 |
|
||
| multiple_choice | 精确匹配 | 全部选对才给分 |
|
||
| true_false | 精确匹配 | 完全一致 |
|
||
| fill_blank | 模糊匹配 | 标点归一化 + 编辑距离容错（>=4字符允许<=2差异） |
|
||
| subjective | LLM 评分 | 按 scoring_points 逐项评分，支持并发批阅 |
|
||
|
||
---
|
||
|
||
## 八、后端对接指南
|
||
|
||
### 8.1 出题 → 存储 → 批题的典型流程
|
||
|
||
```
|
||
1. 后端调用 POST /exam/generate 或 /exam/generate-smart
|
||
↓
|
||
2. RAG 返回 questions 数组
|
||
↓
|
||
3. 后端将 questions 存入 MySQL（保存完整 content 对象和 source_trace）
|
||
↓
|
||
4. 学生答题后，后端组装 answers 数组
|
||
- 将存储的 content 对象直接透传到 answers[].content
|
||
- 填入 student_answer 和 max_score
|
||
↓
|
||
5. 后端调用 POST /exam/grade
|
||
↓
|
||
6. RAG 返回 results 数组，后端存储评分结果
|
||
```
|
||
|
||
### 8.2 后端存储建议
|
||
|
||
题目表建议至少存储以下字段：
|
||
|
||
| 字段 | 来源 | 说明 |
|
||
|------|------|------|
|
||
| `question_id` | 后端自行分配 UUID | 出题接口不返回 ID，由后端分配 |
|
||
| `question_type` | `questions[].question_type` | 题型标识 |
|
||
| `difficulty` | `questions[].difficulty` | 难度 |
|
||
| `content` | `questions[].content` | 完整 JSON 存储（含 stem/data/answer/explanation） |
|
||
| `source_trace` | `questions[].source_trace` | 溯源 JSON |
|
||
| `source_file` | 请求参数 `file_path` | 来源文件 |
|
||
| `collection` | 请求参数 `collection` | 来源向量库 |
|
||
|
||
### 8.3 调用示例 (curl)
|
||
|
||
**参数出题**：
|
||
```bash
|
||
curl -X POST http://<host>:5001/exam/generate \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"file_path": "public_kb/产品手册.pdf",
|
||
"collection": "public_kb",
|
||
"question_types": {"single_choice": 3, "true_false": 2},
|
||
"difficulty": 3
|
||
}'
|
||
```
|
||
|
||
**AI 智能出题（限制20题）**：
|
||
```bash
|
||
curl -X POST http://<host>:5001/exam/generate-smart \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"file_path": "public_kb/产品手册.pdf",
|
||
"collection": "public_kb",
|
||
"max_total": 20
|
||
}'
|
||
```
|
||
|
||
**批题**：
|
||
```bash
|
||
curl -X POST http://<host>:5001/exam/grade \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"answers": [
|
||
{
|
||
"question_id": "q-001",
|
||
"question_type": "single_choice",
|
||
"content": {"answer": "B"},
|
||
"student_answer": "B",
|
||
"max_score": 2
|
||
}
|
||
]
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 九、性能参考
|
||
|
||
| 操作 | 预估耗时 | 说明 |
|
||
|------|----------|------|
|
||
| 参数出题（5题） | 60-90s | 主要耗时在多次 LLM 调用 |
|
||
| AI 智能出题（20题） | 3-5min | 含 AI 分析 + 多次 LLM 调用 |
|
||
| 批题（10题混合） | 15-30s | 主观题 LLM 评分较慢 |
|
||
| 批题（纯客观题） | 1-3s | 无需 LLM，纯匹配 |
|
||
|
||
> 耗时受 LLM 响应速度影响较大。使用推理模型（如 mimo-v2.5）时已自动关闭推理链以提速。
|
||
|
||
---
|
||
|
||
## 十、错误码汇总
|
||
|
||
| HTTP 状态码 | error_code | 场景 |
|
||
|------------|------------|------|
|
||
| 400 | MISSING_PARAMS | 缺少必填参数 |
|
||
| 400 | INVALID_PARAMS | 参数格式或值无效 |
|
||
| 500 | EXAM_ERROR | 出题过程异常 |
|
||
| 500 | GRADE_ERROR | 批阅过程异常 |
|
||
|
||
---
|
||
|
||
## 十一、注意事项
|
||
|
||
1. **题目 ID**：出题接口不生成 ID，由后端在存储时分配 UUID。
|
||
2. **总题数上限**：`/exam/generate` 单次请求不超过 20 题；`/exam/generate-smart` 通过 `max_total` 参数控制。
|
||
3. **排除题干**：`exclude_stems` 最多 100 条，用于跨批次去重。后端可在多轮出题时将前批题干传入。
|
||
4. **填空题答案**：格式为二维数组 `[["标准答案", "同义词"], ...]`，批题时支持模糊匹配。
|
||
5. **主观题评分**：依赖 LLM，存在一定非确定性。同一答案多次评分可能有小幅波动。
|
||
6. **同步阻塞**：所有接口为同步阻塞模式，请求直到完成后才返回。请后端设置合理的请求超时（建议 5 分钟以上）。
|
||
|
||
---
|
||
|
||
## 十二、变更记录
|
||
|
||
| 日期 | 版本 | 变更内容 |
|
||
|------|------|---------|
|
||
| 2026-06-22 | 3.0 | 全面重写：对接 v2 管线，更新为实际 API 格式（5种题型、统一响应、generate-smart、max_total） |
|
||
| 2026-06-04 | 2.1 | 更新模块结构 |
|
||
| 2026-04-13 | 2.0 | 合并出题批卷功能改造计划 |
|
||
| 2026-04-12 | 1.2 | 新增最小字段输入格式 |
|
||
| 2026-04-10 | 1.0 | 初始版本 |
|