133 lines
3.4 KiB
Markdown
133 lines
3.4 KiB
Markdown
# 文档模块需求文档
|
||
|
||
## 1. 模块定位
|
||
|
||
Documents 模块负责文件上传、文件管理、文本抽取和知识库入库入口。
|
||
|
||
该模块是复试题快速适配的关键模块。拿到题目材料后，用户需要能快速上传文档，并让 Agent 在对话中使用这些文档。
|
||
|
||
## 2. 模块目标
|
||
|
||
- 支持上传题目材料和知识库文件。
|
||
- 保存文件元数据。
|
||
- 支持按场景关联文件。
|
||
- 提供文档入库入口。
|
||
- 为 Agent Core 的 RAG 模块提供文件内容。
|
||
|
||
## 3. 职责边界
|
||
|
||
### 3.1 负责
|
||
|
||
- 文件上传页面。
|
||
- 文件保存。
|
||
- 文件元数据记录。
|
||
- 文件与场景关联。
|
||
- 文本抽取入口。
|
||
- 触发 RAG 入库。
|
||
|
||
### 3.2 不负责
|
||
|
||
- 不负责具体向量检索算法。
|
||
- 不负责 embedding 生成细节。
|
||
- 不负责 Agent 对话编排。
|
||
- 不负责模型回答。
|
||
|
||
## 4. 支持文件类型
|
||
|
||
V1 必须支持：
|
||
|
||
| 类型 | 扩展名 | 说明 |
|
||
|---|---|---|
|
||
| 文本文档 | `.txt` | 第一优先级，最稳定 |
|
||
| Markdown | `.md` | 适合准备知识库和规则 |
|
||
| PDF | `.pdf` | 复试常见材料格式，V1 抽取纯文本 |
|
||
| Word | `.docx` | 复试常见材料格式，V1 抽取段落文本 |
|
||
|
||
后续增强：
|
||
|
||
| 类型 | 扩展名 | 说明 |
|
||
|---|---|---|
|
||
| Excel | `.xlsx` | 后续可作为业务数据源或结构化表格导入 |
|
||
|
||
## 5. 数据模型需求
|
||
|
||
建议模型：`UploadedDocument`
|
||
|
||
字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | int | 主键 |
|
||
| `scenario_id` | string | 关联场景 ID |
|
||
| `original_name` | string | 原始文件名 |
|
||
| `file` | FileField | Django FileField 相对路径，不保存用户本机绝对路径 |
|
||
| `file_type` | string | 文件类型 |
|
||
| `size` | int | 文件大小 |
|
||
| `status` | string | `uploaded` / `indexed` / `failed` |
|
||
| `error_message` | text | 入库失败原因 |
|
||
| `created_at` | datetime | 上传时间 |
|
||
| `updated_at` | datetime | 更新时间 |
|
||
|
||
## 6. 页面需求
|
||
|
||
### 6.1 文件上传页
|
||
|
||
路径：`/documents/upload/`
|
||
|
||
页面元素：
|
||
|
||
- 场景选择下拉框。
|
||
- 文件选择按钮。
|
||
- 上传按钮。
|
||
- 支持类型提示。
|
||
- 上传结果提示。
|
||
|
||
### 6.2 文件列表页
|
||
|
||
路径：`/documents/`
|
||
|
||
展示内容：
|
||
|
||
- 文件名。
|
||
- 所属场景。
|
||
- 文件类型。
|
||
- 文件大小。
|
||
- 入库状态。
|
||
- 上传时间。
|
||
- 入库按钮。
|
||
|
||
## 7. RAG 入库流程
|
||
|
||
用户上传文件后，可以手动触发入库。
|
||
|
||
流程：
|
||
|
||
1. 用户上传文件。
|
||
2. 系统保存文件和元数据。
|
||
3. 用户点击入库按钮。
|
||
4. Documents 模块读取文件文本。
|
||
5. 调用 `agent_core.rag.ingest`。
|
||
6. 入库成功后更新状态为 `indexed`。
|
||
7. 入库失败后更新状态为 `failed` 并保存错误信息。
|
||
|
||
## 8. 文本抽取需求
|
||
|
||
V1 文本抽取策略：
|
||
|
||
- `.txt`：按 UTF-8 读取，失败时尝试系统默认编码。
|
||
- `.md`：按 UTF-8 读取，保留标题和正文。
|
||
- `.pdf`：抽取纯文本，不要求 OCR、表格还原和复杂版式理解。
|
||
- `.docx`：抽取段落、标题和普通表格文本，不要求完整保留 Word 样式。
|
||
|
||
入库失败后的文档允许重新触发入库。重新入库前需要清理或覆盖同一 `document_id` 对应的旧 chunk，避免重复检索。
|
||
|
||
## 9. 验收标准
|
||
|
||
- 可以上传 `.txt`、`.md`、`.pdf`、`.docx` 文件。
|
||
- 上传后可以在文件列表看到记录。
|
||
- 文件可以关联到指定场景。
|
||
- 可以触发文件入库。
|
||
- 入库成功后状态变为 `indexed`。
|
||
- 入库失败时页面能显示失败原因。
|
||
- 入库失败的文档可以重新入库。
|