init: RAG 知识库服务初始提交

- 后端 API（Flask + Gunicorn） - RAG 引擎（混合检索 + 云端 Reranker + 引用溯源） - 文档解析（MinerU + 多格式支持） - Docker 生产部署配置 - 排除前端项目、敏感配置、模型文件
2026-06-04 17:35:27 +08:00
commit 100d1a06eb
158 changed files with 64534 additions and 0 deletions
--- a/docs/测试指南.md
+++ b/docs/测试指南.md
@@ -0,0 +1,565 @@
+# 测试指南
+
+> **文档类型**: 测试指南
+> **创建日期**: 2026-04-05
+> **最后更新**: 2026-04-13
+> **文档总数**: 21个测试文档
+
+---
+
+## 一、测试文档清单
+
+### 1.1 文档目录结构
+
+```
+documents/
+├── public/          # 公开文档 - 所有人可见（包括未登录用户）
+│   ├── 公司简介.txt
+│   ├── 产品手册.pdf
+│   ├── 产品手册.txt
+│   ├── 员工手册.txt
+│   ├── 组织架构.xlsx
+│   ├── 组织架构说明.txt
+│   └── 常见问题.txt
+│
+├── internal/        # 内部文档 - 登录用户可见
+│   ├── 差旅管理办法.txt
+│   ├── 请假制度.docx
+│   ├── 信息安全管理制度.pdf
+│   ├── 项目管理制度.xlsx
+│   └── 会议纪要_2024Q1.txt
+│
+├── confidential/    # 机密文档 - 管理层及以上可见
+│   ├── 财务报表_2024.pdf
+│   ├── 薪酬制度.docx
+│   ├── 合同台账.xlsx
+│   ├── 战略规划.txt
+│   └── 人员名册.txt
+│
+└── secret/          # 绝密文档 - 仅管理员可见
+    ├── 董事会决议.pdf
+    ├── 并购方案.docx
+    ├── 股权结构.xlsx
+    └── 核心技术机密.txt
+```
+
+### 1.2 文档格式分布
+
+| 格式 | 数量 | 测试目的 |
+|------|------|---------|
+| TXT | 10个 | 测试纯文本解析、编码识别 |
+| PDF | 4个 | 测试PDF解析、表格提取、中文字体 |
+| DOCX | 3个 | 测试Word解析、标题样式、表格处理 |
+| XLSX | 4个 | 测试Excel解析、多工作表、单元格数据 |
+
+### 1.3 权限级别
+
+| 目录 | 权限级别 | 可见角色 |
+|------|---------|---------|
+| public | public | 所有人（含未登录用户） |
+| internal | internal | user, manager, admin |
+| confidential | confidential | manager, admin |
+| secret | secret | admin only |
+
+---
+
+## 二、测试环境准备
+
+### 2.1 环境检查
+
+```bash
+# 检查 Python 版本
+python --version  # 需要 Python 3.8+
+
+# 检查依赖安装
+pip list | grep -E "chromadb|sentence-transformers|neo4j|flask|jieba"
+
+# 检查模型文件
+ls models/bge-base-zh-v1.5/
+```
+
+### 2.2 启动 Neo4j（用于 Graph RAG）
+
+```bash
+# Docker 启动 Neo4j
+docker run -d --name neo4j \
+  -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/password123 \
+  -v neo4j_data:/data \
+  neo4j:latest
+
+# 等待 Neo4j 启动（约30秒）
+# 访问 http://localhost:7474 验证
+```
+
+### 2.3 配置检查
+
+确保 `config.py` 配置正确：
+```python
+# API配置
+DASHSCOPE_API_KEY = "your-api-key"
+DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+DASHSCOPE_MODEL = "qwen3.5-plus"
+
+# Neo4j配置
+NEO4J_URI = "bolt://localhost:7687"
+NEO4J_USER = "neo4j"
+NEO4J_PASSWORD = "password123"
+USE_GRAPH_RAG = True
+```
+
+---
+
+## 三、测试执行流程
+
+### 3.1 第一阶段：索引构建测试
+
+#### 测试 1.1：向量索引构建
+
+**测试步骤**：
+```bash
+# 清除旧索引
+rm -rf chroma_db/
+
+# 重建向量索引
+python scripts/rebuild_multi_kb.py
+```
+
+**预期结果**：
+- 控制台显示文档加载进度
+- 显示各格式文档解析数量
+- 显示向量构建进度
+- 生成 `chroma_db/` 目录
+
+**验证方法**：
+```python
+import chromadb
+client = chromadb.PersistentClient(path="./chroma_db")
+collection = client.get_collection("knowledge_base")
+print(f"向量数量: {collection.count()}")
+```
+
+#### 测试 1.2：BM25 索引构建
+
+**测试步骤**：
+```bash
+# BM25索引会随向量索引一起构建
+# 检查索引文件
+ls -la bm25_index.pkl
+```
+
+**预期结果**：
+- 生成 `bm25_index.pkl` 文件
+- 文件大小约 1-5 MB
+
+#### 测试 1.3：知识图谱构建
+
+**测试步骤**：
+```bash
+# 构建知识图谱
+python graph_build.py
+```
+
+**预期结果**：
+- 显示实体提取进度
+- 显示关系提取进度
+- 显示图谱存储进度
+- 无错误信息
+
+---
+
+### 3.2 第二阶段：权限控制测试
+
+#### 测试 2.1：未登录用户权限
+
+**测试步骤**：
+```bash
+# 不带 Token 访问
+curl -X POST http://localhost:5001/rag \
+  -H "Content-Type: application/json" \
+  -d '{"message": "公司的产品有哪些？"}'
+```
+
+**预期结果**：
+- 只返回 public 目录下的内容
+- 不返回 internal、confidential、secret 内容
+
+#### 测试 2.2：user 角色权限
+
+**测试步骤**：
+```bash
+# 使用 mock token 登录
+curl -X POST http://localhost:5001/rag \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer mock-token-testuser" \
+  -d '{"message": "差旅费标准是多少？"}'
+```
+
+**预期结果**：
+- 返回 public + internal 目录内容
+- 不返回 confidential、secret 内容
+
+#### 测试 2.3：manager 角色权限
+
+**测试步骤**：
+```bash
+curl -X POST http://localhost:5001/rag \
+  -H "Authorization: Bearer mock-token-manager" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "2024年财务报表显示净利润是多少？"}'
+```
+
+**预期结果**：
+- 返回 public + internal + confidential 内容
+- 正确回答财务相关问题
+- 不返回 secret 目录内容
+
+#### 测试 2.4：admin 角色权限
+
+**测试步骤**：
+```bash
+curl -X POST http://localhost:5001/rag \
+  -H "Authorization: Bearer mock-token-admin" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "董事会决议的并购方案是什么？"}'
+```
+
+**预期结果**：
+- 返回所有目录内容
+- 正确回答涉及绝密信息的问题
+
+---
+
+### 3.3 第三阶段：检索质量测试
+
+#### 测试 3.1：向量语义检索
+
+| 测试问题 | 预期命中文档 | 预期答案关键点 |
+|---------|------------|--------------|
+| 公司有哪些产品？ | 公司简介.txt、产品手册.pdf | 智能数据分析平台、AI知识图谱平台、RAG系统 |
+| 请假需要提前几天申请？ | 请假制度.docx | 1天以内直属上级、3天内部门负责人、7天以上总经理 |
+| 年假有几天？ | 请假制度.docx | 1年5天、5年7天、10年10天、20年15天 |
+
+**测试命令**：
+```bash
+curl -X POST http://localhost:5001/search \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer mock-token-admin" \
+  -d '{"query": "公司有哪些产品？", "top_k": 5}'
+```
+
+#### 测试 3.2：BM25 关键词检索
+
+| 测试关键词 | 预期命中文档 |
+|-----------|------------|
+| 差旅补助 500元 | 差旅管理办法.txt |
+| 年假 15天 | 请假制度.docx |
+| 薪酬 P5 35万 | 薪酬制度.docx |
+
+#### 测试 3.3：混合检索 + Rerank
+
+**测试步骤**：
+```bash
+curl -X POST http://localhost:5001/search \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer mock-token-admin" \
+  -d '{"query": "出差住宿标准是多少？", "top_k": 10}'
+```
+
+**预期结果**：
+- 返回结果包含 rerank_score
+- 结果排序比纯向量检索更准确
+
+#### 测试 3.4：知识图谱检索
+
+| 测试问题 | 预期实体/关系 |
+|---------|-------------|
+| 技术研发中心负责什么？ | 实体：技术研发中心、张明远；关系：负责 |
+| 请假3天需要谁审批？ | 实体：请假、部门负责人；关系：审批 |
+
+**测试命令**：
+```bash
+curl -X POST http://localhost:5001/graph/search \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer mock-token-admin" \
+  -d '{"query": "技术研发中心负责什么？", "depth": 2}'
+```
+
+---
+
+### 3.4 第四阶段：Agentic RAG 测试
+
+#### 测试 4.1：简单问题直接回答
+
+**测试问题**：
+```bash
+curl -X POST http://localhost:5001/rag \
+  -H "Authorization: Bearer mock-token-admin" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "公司的请假制度是什么？"}'
+```
+
+**预期结果**：
+- Agent 决策为 "answer"
+- 直接返回检索结果
+- 无需多轮检索
+
+#### 测试 4.2：查询改写
+
+**测试问题**：
+```bash
+curl -X POST http://localhost:5001/rag \
+  -H "Authorization: Bearer mock-token-admin" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "我想了解关于报销的事情"}'
+```
+
+**预期结果**：
+- Agent 决策为 "rewrite"
+- 查询被改写为更具体的表述
+
+#### 测试 4.3：问题分解
+
+**测试问题**：
+```bash
+curl -X POST http://localhost:5001/rag \
+  -H "Authorization: Bearer mock-token-admin" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "请假和报销的流程分别是什么？"}'
+```
+
+**预期结果**：
+- Agent 决策为 "decompose"
+- 问题被分解为多个子问题
+- 分别检索后合并回答
+
+#### 测试 4.4：多源融合
+
+**测试问题**：
+```bash
+curl -X POST http://localhost:5001/rag \
+  -H "Authorization: Bearer mock-token-admin" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "技术部的组织架构和职责分工是怎样的？"}'
+```
+
+**预期结果**：
+- 同时触发知识库检索和图谱检索
+- 返回结果标注来源类型
+
+---
+
+### 3.5 第五阶段：出题系统测试
+
+#### 测试 5.1：试卷生成
+
+**测试步骤**：
+```bash
+curl -X POST http://localhost:5001/exam/generate \
+  -H "Authorization: Bearer mock-token-admin" \
+  -H "Content-Type: application/json" \
+  -d '{"topic": "公司制度基础", "choice_count": 5, "name": "公司制度测试"}'
+```
+
+**预期结果**：
+- 返回 exam_id
+- 试卷状态为 "draft"
+- 包含选择题、填空题、简答题
+
+#### 测试 5.2：试卷审核
+
+**测试步骤**：
+```bash
+curl -X POST http://localhost:5001/exam/<exam_id>/review \
+  -H "Authorization: Bearer mock-token-admin" \
+  -H "Content-Type: application/json" \
+  -d '{"action": "approve"}'
+```
+
+**预期结果**：
+- 返回 success: true
+- 试卷状态变为 "approved"
+
+#### 测试 5.3：试卷批阅
+
+**测试步骤**：
+```bash
+curl -X POST http://localhost:5001/exam/<exam_id>/grade \
+  -H "Authorization: Bearer mock-token-admin" \
+  -H "Content-Type: application/json" \
+  -d '{"student_name": "测试学生", "answers": {"choice_1": "A", "choice_2": "B"}}'
+```
+
+**预期结果**：
+- 返回批阅报告
+- 包含每题得分和总分
+
+---
+
+### 3.6 第六阶段：API 接口测试
+
+#### 测试 6.1：认证接口
+
+```bash
+# 获取用户信息
+curl http://localhost:5001/auth/me \
+  -H "Authorization: Bearer mock-token-admin"
+```
+
+#### 测试 6.2：会话管理
+
+```bash
+# 创建会话并对话
+curl -X POST http://localhost:5001/chat \
+  -H "Authorization: Bearer mock-token-admin" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "你好", "session_id": "test-001"}'
+
+# 获取会话列表
+curl http://localhost:5001/sessions \
+  -H "Authorization: Bearer mock-token-admin"
+
+# 获取会话历史
+curl http://localhost:5001/history/test-001 \
+  -H "Authorization: Bearer mock-token-admin"
+```
+
+#### 测试 6.3：健康检查
+
+```bash
+curl http://localhost:5001/health
+```
+
+**预期结果**：
+```json
+{
+  "status": "ok",
+  "knowledge_base": "多向量库模式 (按集合提供服务)",
+  "bm25_index": "动态按需加载",
+  "mode": "Agentic RAG"
+}
+```
+
+---
+
+## 四、知识图谱测试要点
+
+### 4.1 实体覆盖
+
+| 实体类型 | 覆盖文档 | 示例实体 |
+|---------|---------|---------|
+| 部门 | 组织架构、员工手册 | 技术研发中心、人力资源部、财务部 |
+| 人员 | 组织架构、人员名册 | 张志远、李明辉、王志强 |
+| 制度 | 员工手册、请假制度、差旅管理办法 | 差旅管理办法、请假制度、信息安全管理制度 |
+| 金额 | 差旅管理办法、财务报表、薪酬制度 | 500元/天、280万元、8-12万元 |
+| 时间 | 请假制度、项目管理制度 | 3个工作日、30天、2024年1月 |
+| 地点 | 公司简介、差旅管理办法 | 北京、上海、深圳 |
+
+### 4.2 关系类型覆盖
+
+| 关系类型 | 覆盖文档 | 示例关系 |
+|---------|---------|---------|
+| 负责 | 组织架构 | 技术研发中心 → 负责 → 技术总监张明远 |
+| 审批 | 请假制度、差旅管理办法 | 请假3天 → 审批 → 部门负责人 |
+| 限额 | 差旅管理办法 | 一线城市住宿 → 限额 → 500元/晚 |
+| 时效 | 请假制度 | 离职申请 → 时效 → 提前30天 |
+
+### 4.3 多跳推理测试点
+
+| 测试问题 | 推理链 | 涉及文档 |
+|---------|--------|---------|
+| 请假5天需要谁审批？ | 5天 > 3天 → 部门负责人 + 人力资源部 + 总经理 | 请假制度.docx |
+| 差旅费超过3000元怎么处理？ | >3000元 → 部门负责人 + 财务部经理审批 | 差旅管理办法.txt |
+| 技术总监的薪酬范围是多少？ | 技术总监 → M4级 → 50-80万元 | 薪酬制度.docx |
+
+---
+
+## 五、测试报告模板
+
+### 5.1 测试执行摘要
+
+| 项目 | 内容 |
+|------|------|
+| 测试日期 | YYYY-MM-DD |
+| 测试人员 | |
+| 测试环境 | |
+| 文档数量 | 21个 |
+| 发现问题数量 | |
+
+### 5.2 测试结果统计
+
+| 测试类型 | 用例数 | 通过 | 失败 | 阻塞 |
+|----------|--------|------|------|------|
+| 索引构建测试 | 3 | | | |
+| 权限控制测试 | 4 | | | |
+| 检索质量测试 | 4 | | | |
+| Agentic RAG测试 | 4 | | | |
+| 出题系统测试 | 3 | | | |
+| API接口测试 | 3 | | | |
+| **总计** | **21** | | | |
+
+### 5.3 问题列表
+
+| 编号 | 测试用例 | 问题描述 | 严重程度 | 状态 |
+|------|----------|----------|----------|------|
+| BUG-001 | | | 高/中/低 | 待修复 |
+
+---
+
+## 六、快速测试命令
+
+```bash
+# 一键索引重建
+python scripts/rebuild_multi_kb.py
+
+# 构建知识图谱
+python graph_build.py
+
+# 启动服务
+python main.py
+
+# 快速测试
+curl http://localhost:5001/health
+```
+
+---
+
+## 七、测试文档生成
+
+测试文档通过脚本 `generate_test_docs.py` 自动生成，支持以下格式：
+
+- **TXT**: 直接文本写入
+- **DOCX**: 使用 `python-docx` 库生成
+- **XLSX**: 使用 `openpyxl` 库生成
+- **PDF**: 使用 `reportlab` 库生成
+
+运行命令：
+```bash
+python generate_test_docs.py
+```
+
+依赖安装：
+```bash
+pip install python-docx openpyxl reportlab
+```
+
+---
+
+## 八、文本量统计
+
+| 目录 | 文件数 | 总字符数 | 总词数(估计) |
+|------|--------|---------|-------------|
+| public | 7 | ~35,000 | ~15,000 |
+| internal | 5 | ~25,000 | ~10,000 |
+| confidential | 5 | ~20,000 | ~8,000 |
+| secret | 4 | ~15,000 | ~6,000 |
+| **合计** | **21** | **~95,000** | **~39,000** |
+
+---
+
+## 九、变更记录
+
+| 日期 | 版本 | 变更内容 |
+|------|------|---------|
+| 2026-04-13 | 2.0 | 合并测试文档清单和测试执行流程 |
+| 2026-04-05 | 1.0 | 初始版本 |