jhzhang/rag
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 同步项目状态

Browse Source 
- main.py: 去掉 emoji 避免 GBK 编码崩溃
- docs/curl测试手册.md: 更新模型名和测试日期
- docs/代码审查报告_2026-06-05.md: 删除过期报告
- docs/main分支独有功能说明.md: 新增
- docs/出题系统逻辑.md: 新增
This commit is contained in:
lacerate551
2026-06-19 15:25:57 +08:00
parent 95f3b99064
commit 858ee40e5b
5 changed files with 1029 additions and 526 deletions
Download Patch File Download Diff File Expand all files Collapse all files

685
docs/curl测试手册.md
View File

@@ -2,9 +2,9 @@
> 基于 `后端对接规范.md`，所有 curl 命令均在生产模式 (`APP_ENV=prod`) 下验证通过。
>
> 测试日期：2026-06-04 | 生产服务器：`47.116.16.222` | 服务地址：`http://127.0.0.1:5001`
> 测试日期：2026-06-10（最近更新）| 生产服务器：`47.116.16.222` | 服务地址：`http://127.0.0.1:5001`
>
> 当前部署模型：`qwen-plus`（DashScope）| 嵌入模型：`bge-base-zh-v1.5`（本地 CPU）| Rerank：`qwen3-rerank`（DashScope 云端 API）
> 当前部署模型：`qwen-turbo`（DashScope）| 嵌入模型：`bge-base-zh-v1.5`（本地 CPU）| Rerank：`qwen3-rerank`（DashScope 云端 API）
## 目录
@@ -23,6 +23,8 @@
- [13. 报告服务](#13-报告服务)
- [14. 知识库路由](#14-知识库路由)
- [15. 异步任务查询](#15-异步任务查询)
- [16. 认证系统](#16-认证系统)
- [17. 其他端点](#17-其他端点)
- [附录. 已知问题](#附录-已知问题)
---
@@ -281,11 +283,19 @@ curl -s http://localhost:5001/collections
"department": "",
"description": "",
"display_name": "dept_1_kb",
"document_count": 800,
"document_count": 500,
"name": "dept_1_kb"
},
{
"created_at": "2026-06-10T03:04:20.619279",
"department": "",
"description": "",
"display_name": "resources",
"document_count": 0,
"name": "resources"
}
],
"total": 9
"total": 3
}
```
@@ -382,15 +392,15 @@ curl -s "http://localhost:5001/collections/public_kb/documents"
"collection": "public_kb",
"documents": [
{
"chunks": 105,
"source": "1.docx"
"chunks": 69,
"source": "3.txt"
},
{
"chunks": 39,
"source": "三峡公报_1-15页.pdf"
"chunks": 12,
"source": "1.txt"
}
],
"total": 9
"total": 10
}
```
@@ -580,27 +590,25 @@ curl -s -X POST http://localhost:5001/documents/upload \
**响应示例**：
```json
{
"data": {
"file": {
"collection": "public_kb",
"filename": "test.txt",
"path": "public_kb/test.txt",
"size": 18,
"replaced": false
},
"sync_status": "已保存，向量化任务已启动",
"task_id": "a1b2c3d4e5f6"
},
"message": "文件上传成功，已保存，向量化任务已启动",
"success": true,
"status": "success",
"status_code": 2002,
"success": true
"message": "文件上传成功，已保存并添加到向量库",
"data": {
"file": {
"filename": "test.txt",
"collection": "public_kb",
"path": "public_kb/test.txt",
"size": 18
},
"sync_status": "已保存并添加到向量库"
}
}
```
> **异步说明**：文件保存为同步操作，向量化在后台线程异步执行。响应中的 `task_id` 可用于轮询向量化进度（`GET /tasks/<task_id>`）。
> **说明**：文件保存和向量化均为同步操作，响应时文件已处理完成。不包含 `task_id` 字段（异步任务系统仅 main 分支可用）。
>
> **同名文件处理**：上传同名文件时，旧版本的切片会被自动清理后覆盖（`replaced: true`），不会生成时间戳后缀文件。
> **同名文件处理**：上传同名文件时，旧版本的切片会被自动清理后覆盖，不会生成时间戳后缀文件。
**验证结果**：✅ 通过
@@ -622,25 +630,24 @@ curl -s -X POST http://localhost:5001/documents/batch-upload \
**响应示例**：
```json
{
"data": {
"results": [
{"filename": "file1.txt", "path": "public_kb/file1.txt", "status": "success", "replaced": false},
{"filename": "file2.txt", "path": "public_kb/file2.txt", "status": "success", "replaced": false}
],
"success_count": 2,
"total": 2,
"task_id": "b2c3d4e5f6a1"
},
"message": "批量上传完成，成功 2/2 个文件",
"success": true,
"status": "success",
"status_code": 2003,
"success": true
"message": "批量上传完成，成功 2/2 个文件",
"data": {
"total": 2,
"success_count": 2,
"results": [
{"filename": "file1.txt", "path": "public_kb/file1.txt", "status": "success"},
{"filename": "file2.txt", "path": "public_kb/file2.txt", "status": "success"}
]
}
}
```
> **异步说明**：批量上传成功后自动触发后台向量化任务。`task_id` 可用于轮询向量化进度（`GET /tasks/<task_id>`）。若无成功上传的文件则不返回 `task_id`。
> **说明**：批量上传为同步操作，响应时所有文件已处理完成。不包含 `task_id` 字段（异步任务系统仅 main 分支可用）。
>
> **同名文件处理**：与单文件上传相同，批量上传中遇到同名文件也会自动覆盖旧版本（`replaced: true`）。
> **同名文件处理**：与单文件上传相同，批量上传中遇到同名文件也会自动覆盖旧版本。
**验证结果**：✅ 通过
@@ -899,22 +906,27 @@ curl -s -X POST http://localhost:5001/sync \
**响应示例**：
```json
{
"data": {
"task_id": "c3d4e5f6a1b2",
"message": "同步任务已启动，通过 GET /tasks/c3d4e5f6a1b2 查询进度"
},
"message": "同步任务已启动",
"success": true,
"status": "success",
"status_code": 2010,
"success": true
"message": "同步完成",
"data": {
"result": {
"documents_processed": 20,
"documents_added": 3,
"documents_modified": 2,
"documents_deleted": 0,
"errors": []
}
}
}
```
> **⚠️ 异步变更**：此接口已从同步改为异步。不再直接返回同步结果，而是返回 `task_id`。后端需通过 `GET /tasks/<task_id>` 轮询任务状态，直到 `status` 为 `completed` 或 `failed`。
> **说明**：此接口为**同步操作**，请求会阻塞直到同步完成（可能需要较长时间）。响应中 `data.result` 包含完整的同步结果。不包含 `task_id` 字段（异步任务系统仅 main 分支可用）。
>
> **冲突检测**：如果已有同步任务正在运行，返回 HTTP 409：
> ```json
> {"error": "TASK_RUNNING", "message": "同步任务正在执行中 (task_id: xxx)，请等待完成"}
> {"error": "TASK_RUNNING", "message": "同步任务正在执行中，请等待完成"}
> ```
**验证结果**：✅ 通过
@@ -1368,6 +1380,22 @@ curl -s -X POST "http://localhost:5001/faq/suggestions/6/reject" \
---
### POST /faq/\<id\>/approve
直接批准 FAQ（非从建议列表）。
```bash
curl -s -X POST "http://localhost:5001/faq/1/approve" \
-H "Content-Type: application/json" \
-d '{}'
```
> **注意**：此端点与 `POST /faq/suggestions/<id>/approve` 不同，后者用于审批用户提交的 FAQ 建议。
**验证结果**：✅ 通过（路由存在）
---
## 11. 出题系统
### 出题架构说明（v2）
@@ -1461,56 +1489,48 @@ curl -s -X POST http://localhost:5001/exam/generate \
**响应示例**：
```json
{
"data": {
"task_id": "d4e5f6a1b2c3",
"message": "出题任务已启动 (10题)，通过 GET /tasks/d4e5f6a1b2c3 查询结果"
},
"message": "出题任务已启动",
"success": true,
"status": "success",
"status_code": 2020,
"success": true
}
```
> **⚠️ 异步变更**：此接口已从同步改为异步。响应仅返回 `task_id`，后端需通过 `GET /tasks/<task_id>` 轮询任务状态。任务完成后，`result` 字段包含完整出题结果（格式见下方说明）。
**轮询结果（GET /tasks/\<task_id\> 完成后的 result 字段）**：
```json
{
"questions": [
{
"content": {
"stem": "重购率的定义是下列哪一项？",
"answer": "B",
"data": {
"options": [
{"content": "选项A内容", "key": "A"},
{"content": "品规连续两周订货客户数/上周订货客户数*100%", "key": "B"}
]
"message": "出题成功",
"data": {
"questions": [
{
"content": {
"stem": "重购率的定义是下列哪一项？",
"answer": "B",
"data": {
"options": [
{"content": "选项A内容", "key": "A"},
{"content": "品规连续两周订货客户数/上周订货客户数*100%", "key": "B"}
]
},
"explanation": "重购率的定义是..."
},
"explanation": "重购率的定义是..."
},
"difficulty": 3,
"question_type": "single_choice",
"source_trace": {
"chunk_ids": ["1.docx_76"],
"document_name": "public_kb/1.docx",
"page_numbers": [1],
"sources": [...]
"difficulty": 3,
"question_type": "single_choice",
"source_trace": {
"chunk_ids": ["1.docx_76"],
"document_name": "public_kb/1.docx",
"page_numbers": [1],
"sources": [...]
}
}
}
],
"request_id": null,
"source_chunks_used": 15,
"success": true,
"total": 10,
"requested_types": {"single_choice": 5, "true_false": 3, "fill_blank": 2},
"actual_types": {"single_choice": 5, "true_false": 3, "fill_blank": 2},
"warnings": []
],
"request_id": null,
"source_chunks_used": 15,
"success": true,
"total": 10,
"requested_types": {"single_choice": 5, "true_false": 3, "fill_blank": 2},
"actual_types": {"single_choice": 5, "true_false": 3, "fill_blank": 2},
"warnings": []
}
}
```
> **说明**：`warnings` 字段在某题型实际生成数量少于请求数量时返回提示信息。
> **说明**：此接口为**同步操作**，请求会阻塞直到出题完成（通常需要 30-60 秒）。响应中 `data` 直接包含完整出题结果。不包含 `task_id` 字段（异步任务系统仅 main 分支可用）。
>
> **注意**：`warnings` 字段在某题型实际生成数量少于请求数量时返回提示信息。
**验证结果**：✅ 通过（2026-06-05）
@@ -1542,42 +1562,34 @@ curl -s -X POST http://localhost:5001/exam/generate-smart \
**响应示例**：
```json
{
"data": {
"task_id": "e5f6a1b2c3d4",
"message": "AI 智能出题任务已启动，通过 GET /tasks/e5f6a1b2c3d4 查询结果"
},
"message": "AI 智能出题任务已启动",
"success": true,
"status": "success",
"status_code": 2020,
"success": true
}
```
> **⚠️ 异步变更**：此接口已从同步改为异步。响应仅返回 `task_id`，后端需通过 `GET /tasks/<task_id>` 轮询任务状态。任务完成后，`result` 字段包含完整出题结果（含 `ai_analysis` 字段）。
**轮询结果（GET /tasks/\<task_id\> 完成后的 result 字段）**：
```json
{
"ai_analysis": {
"total_knowledge_points": 21,
"suitable_types": ["single_choice", "multiple_choice", "true_false", "subjective"],
"question_types": {
"single_choice": 8,
"multiple_choice": 6,
"true_false": 4,
"fill_blank": 0,
"subjective": 3
"message": "AI 智能出题成功",
"data": {
"ai_analysis": {
"total_knowledge_points": 21,
"suitable_types": ["single_choice", "multiple_choice", "true_false", "subjective"],
"question_types": {
"single_choice": 8,
"multiple_choice": 6,
"true_false": 4,
"fill_blank": 0,
"subjective": 3
},
"reason": "文档包含21个知识点，涵盖术语定义、流程步骤、数值标准..."
},
"reason": "文档包含21个知识点，涵盖术语定义、流程步骤、数值标准..."
},
"questions": [...],
"request_id": null,
"source_chunks_used": 15,
"success": true,
"total": 16
"questions": [...],
"request_id": null,
"source_chunks_used": 15,
"success": true,
"total": 16
}
}
```
> **说明**：此接口为**同步操作**，请求会阻塞直到出题完成。响应中 `data` 直接包含完整出题结果（含 `ai_analysis` 字段）。不包含 `task_id` 字段（异步任务系统仅 main 分支可用）。
**注意事项**：
- 实际出题数量 ≤ min(文档知识点数, AI 推荐数量)
- 如果文档知识点较少，生成的题目数量会相应减少
@@ -1626,44 +1638,36 @@ curl -s -X POST http://localhost:5001/exam/grade \
**响应示例**：
```json
{
"data": {
"task_id": "f6a1b2c3d4e5",
"message": "批阅任务已启动 (1题)，通过 GET /tasks/f6a1b2c3d4e5 查询结果"
},
"message": "批阅任务已启动",
"success": true,
"status": "success",
"status_code": 2021,
"success": true
}
```
> **⚠️ 异步变更**：此接口已从同步改为异步。响应仅返回 `task_id`，后端需通过 `GET /tasks/<task_id>` 轮询任务状态。任务完成后，`result` 字段包含完整批阅结果（格式见下方说明）。
**轮询结果（GET /tasks/\<task_id\> 完成后的 result 字段）**：
```json
{
"request_id": null,
"results": [
{
"question_id": "q1",
"score": 2,
"max_score": 2,
"grading_status": "success",
"details": {
"correct": true,
"student_answer": "B",
"correct_answer": "B",
"feedback": "正确！"
"message": "批阅完成",
"data": {
"request_id": null,
"results": [
{
"question_id": "q1",
"score": 2,
"max_score": 2,
"grading_status": "success",
"details": {
"correct": true,
"student_answer": "B",
"correct_answer": "B",
"feedback": "正确！"
}
}
}
],
"score_rate": 100.0,
"success": true,
"total_max_score": 2,
"total_score": 2
],
"score_rate": 100.0,
"success": true,
"total_max_score": 2,
"total_score": 2
}
}
```
> **说明**：此接口为**同步操作**，响应中 `data` 直接包含完整批阅结果。不包含 `task_id` 字段（异步任务系统仅 main 分支可用）。
**`grading_status` 取值说明**：
- `success`：评分成功
- `failed`：评分失败（主观题 LLM 解析失败或超时），此时 `details` 包含 `error` 字段
@@ -1842,16 +1846,16 @@ curl -s -X POST http://localhost:5001/kb/route \
```json
{
"intent": {
"confidence": 0.95,
"confidence": 1.0,
"department": null,
"is_general": true,
"keywords": [],
"reason": "LLM 意图分析"
},
"query": "三峡工程",
"query": "test",
"target_collections": ["public_kb"],
"user_department": "",
"user_role": "user"
"user_department": "开发部",
"user_role": "admin"
}
```
@@ -1861,188 +1865,154 @@ curl -s -X POST http://localhost:5001/kb/route \
## 15. 异步任务查询
> 所有异步操作（同步、重建索引、上传向量化、出题、批阅）返回的 `task_id` 均可通过以下接口查询进度。
### GET /tasks
获取任务列表。
```bash
curl -s http://localhost:5001/tasks
```
**查询参数**：
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `status` | string | ❌ | 过滤状态：`pending` / `running` / `completed` / `failed` |
| `type` | string | ❌ | 过滤类型：`sync` / `reindex` / `upload` / `batch_upload` / `exam_generate` / `exam_grade` |
| `limit` | int | ❌ | 返回数量限制（默认 50） |
**响应示例**：
```json
{
"data": {
"tasks": [
{
"task_id": "a1b2c3d4e5f6",
"type": "sync",
"description": "文档同步",
"status": "running",
"progress": 45.0,
"current": 9,
"total": 20,
"stage": "处理文件",
"message": "已处理: 产品手册.pdf",
"created_at": "2026-06-05T10:30:00"
}
],
"total": 1
},
"message": "查询成功",
"status": "success",
"status_code": 2000,
"success": true
}
```
**验证结果**：✅ 通过
---
### GET /tasks/\<task_id\>
获取单个任务状态（JSON 轮询接口）。
**后端组推荐使用此接口轮询任务进度，建议间隔 1-2 秒。**
```bash
curl -s http://localhost:5001/tasks/a1b2c3d4e5f6
```
**响应示例（运行中）**：
```json
{
"data": {
"task_id": "a1b2c3d4e5f6",
"type": "sync",
"description": "文档同步",
"status": "running",
"progress": 45.0,
"current": 9,
"total": 20,
"stage": "处理文件",
"message": "已处理: 产品手册.pdf",
"created_at": "2026-06-05T10:30:00",
"started_at": "2026-06-05T10:30:01"
},
"message": "查询成功",
"status": "success",
"status_code": 2000,
"success": true
}
```
**响应示例（已完成）**：
```json
{
"data": {
"task_id": "a1b2c3d4e5f6",
"type": "sync",
"description": "文档同步",
"status": "completed",
"progress": 100.0,
"current": 20,
"total": 20,
"stage": "完成",
"message": "同步完成",
"created_at": "2026-06-05T10:30:00",
"started_at": "2026-06-05T10:30:01",
"completed_at": "2026-06-05T10:30:15",
"duration_ms": 14000,
"result": {
"documents_processed": 20,
"documents_added": 3,
"documents_modified": 2,
"documents_deleted": 0,
"errors": []
}
},
"message": "查询成功",
"status": "success",
"status_code": 2000,
"success": true
}
```
> **任务状态**：
> - `pending`：已创建，等待执行
> - `running`：正在执行
> - `completed`：执行完成，`result` 字段包含完整结果
> - `failed`：执行失败，`error` 字段包含错误信息
> **⚠️ 生产服务器（server-release）不支持**：异步任务系统（`/tasks` 系列端点）仅存在于 main 分支。当前生产服务器的上传、同步、出题、批阅接口均为**同步操作**，直接返回结果，无需轮询。
>
> **轮询建议**：间隔 1-2 秒，当 `status` 为 `completed` 或 `failed` 时停止轮询。
> 如果后续升级到 main 分支版本，以下接口将可用：
>
> | 端点 | 方法 | 说明 |
> |------|------|------|
> | `/tasks` | GET | 获取任务列表（支持 status/type/limit 过滤） |
> | `/tasks/<task_id>` | GET | 获取单个任务状态（JSON 轮询） |
> | `/tasks/<task_id>/progress` | GET | SSE 流式任务进度推送 |
> | `/tasks/stats` | GET | 获取任务统计信息 |
>
> **任务状态**：`pending` → `running` → `completed` / `failed`
**验证结果**：✅ 通过
**验证结果**：❌ 路由不存在（404）— 符合 server-release 预期行为
---
### GET /tasks/\<task_id\>/progress
## 16. 认证系统
SSE 流式任务进度推送（dev-ui 前端推荐使用）。
### POST /auth/login
用户登录。
```bash
curl -s -N http://localhost:5001/tasks/a1b2c3d4e5f6/progress
echo '{"username":"admin","password":"xxx"}' > /tmp/login.json
curl -s -X POST http://localhost:5001/auth/login \
-H "Content-Type: application/json" \
-d @/tmp/login.json
```
**SSE 事件序列**：
```
data: {"type": "start", "data": {"stage": "扫描文档"}}
data: {"type": "progress", "data": {"progress": 10.0, "current": 2, "total": 20, "stage": "处理文件", "message": "已处理: file1.pdf"}}
data: {"type": "progress", "data": {"progress": 25.0, "current": 5, "total": 20, "stage": "处理文件", "message": "已处理: file2.docx"}}
data: {"type": "complete", "data": {"task_id": "a1b2c3d4e5f6", "status": "completed", "result": {...}}}
```
> **SSE 事件类型**：
> - `start`：任务开始
> - `progress`：进度更新（包含 progress/current/total/stage/message）
> - `complete`：任务完成（data 为完整任务详情，含 result）
> - `error`：任务失败（data 包含 message 错误信息）
> - 每 1 秒发送一次 `: heartbeat` 保活
**验证结果**：✅ 通过
---
### GET /tasks/stats
获取任务统计信息。
```bash
curl -s http://localhost:5001/tasks/stats
```
**响应示例**：
**响应示例**（失败）：
```json
{
"data": {
"total": 5,
"by_status": {"running": 1, "completed": 3, "failed": 1},
"by_type": {"sync": 2, "exam_generate": 2, "upload": 1}
},
"message": "查询成功",
"status": "success",
"status_code": 2000,
"success": true
}
{"error": "用户名或密码错误"}
```
**验证结果**：✅ 通过（参数校验正常）
---
### GET /auth/me
获取当前用户信息。
```bash
curl -s http://localhost:5001/auth/me
```
---
### GET /auth/users
获取用户列表。
```bash
curl -s http://localhost:5001/auth/users
```
---
### PUT /auth/users/\<user_id\>
修改用户信息。
```bash
echo '{"role":"user"}' > /tmp/update_user.json
curl -s -X PUT "http://localhost:5001/auth/users/test-user" \
-H "Content-Type: application/json" \
-d @/tmp/update_user.json
```
---
### POST /auth/change-password
修改密码。
```bash
echo '{"old_password":"old","new_password":"new"}' > /tmp/changepw.json
curl -s -X POST http://localhost:5001/auth/change-password \
-H "Content-Type: application/json" \
-d @/tmp/changepw.json
```
---
## 17. 其他端点
### GET /documents/\<path\>/raw
下载文档原始文件。
```bash
curl -s -o output.docx "http://localhost:5001/documents/public_kb%2F1.docx/raw"
```
**响应**：返回原始文件（HTTP 200）
**验证结果**：✅ 通过
---
### DELETE /chunks/batch
批量删除切片。
```bash
echo '{"chunk_ids":["file.txt_text_0","file.txt_text_1"],"collection":"public_kb"}' > /tmp/batch_del.json
curl -s -X DELETE http://localhost:5001/chunks/batch \
-H "Content-Type: application/json" \
-d @/tmp/batch_del.json
```
---
### GET /stats
获取系统统计信息。
```bash
curl -s http://localhost:5001/stats
```
**验证结果**：❌ HTTP 500（`KeyError: 'SESSION_MANAGER'`，见已知问题 #2）
---
### POST /collections/sync-vlm-cache
同步 VLM 缓存。
```bash
curl -s -X POST http://localhost:5001/collections/sync-vlm-cache
```
---
### POST /collections/\<kb_name\>/reindex
重构向量库索引（异步任务）。
```bash
curl -s -X POST "http://localhost:5001/collections/public_kb/reindex"
```
> **说明**：清除哈希记录并触发全量同步。
---
## 附录. 已知问题
### 1. /rag 接口 collections 参数
@@ -2059,33 +2029,63 @@ curl -s http://localhost:5001/tasks/stats
{"message": "问题", "collections": ["dept_tech"], "chat_history": []}
```
### 2. /stats 接口 500 错误
**问题**：`GET /stats` 返回 HTTP 500，日志显示 `KeyError: 'SESSION_MANAGER'`。
**原因**：该端点依赖 `SESSION_MANAGER` 配置项，但 server-release 分支未注册会话管理器。
**状态**：已知缺陷，不影响其他接口正常使用。
### 3. /tasks 系列端点不存在
**问题**：`GET /tasks`、`GET /tasks/<id>`、`GET /tasks/<id>/progress`、`GET /tasks/stats` 均返回 HTTP 404。
**原因**：异步任务系统仅存在于 main 分支，server-release 保持同步操作模式。上传、同步、出题、批阅接口直接返回结果，无需轮询。
**影响**：无 — 这是预期行为，所有操作均为同步完成。
### 4. /documents/sync 与 /sync 的区别
**问题**：服务器上存在两个同步触发端点，行为略有不同。
| 端点 | 说明 |
|------|------|
| `POST /sync` | 主同步接口，扫描并同步所有知识库 |
| `POST /documents/sync` | 文档级同步接口，需要额外参数 |
**建议**：使用 `POST /sync` 触发手动同步。
---
## 测试覆盖统计
> 2026-06-04 生产服务器测试结果（47.116.16.222，云端 Reranker + MMR 文本相似度）
> 2026-06-10 生产服务器测试结果（47.116.16.222，云端 Reranker + MMR 文本相似度）
| 分类 | 总数 | 通过 | 超时/异常 | 备注 |
|------|------|------|-----------|------|
| 分类 | 总数 | 通过 | 异常 | 备注 |
|------|------|------|------|------|
| 健康检查 | 1 | 1 | 0 | ✅ 0.002s |
| 问答接口 | 2 | 2 | 0 | ✅ /rag 流式 12-14s |
| 问答接口 | 2 | 2 | 0 | ✅ /rag 流式，/chat 正常 |
| 检索接口 | 1 | 1 | 0 | ✅ /search 0.58-1.53s |
| 向量库管理 | 3 | 3 | 0 | ✅ |
| 文档管理 | 1 | 1 | 0 | ✅ |
| 同步服务 | 3 | 3 | 0 | ✅ |
| 反馈系统 | 4 | 4 | 0 | ✅ |
| FAQ 管理 | 2 | 2 | 0 | ✅ |
| 出题系统 | 1 | 1 | 0 | ✅ |
| 图片服务 | 2 | 2 | 0 | ✅ |
| 报告服务 | 2 | 2 | 0 | ✅ |
| 知识库路由 | 1 | 1 | 0 | ✅ |
| **总计** | **23** | **23** | **0** | **全部通过** |
| 向量库管理 | 3 | 3 | 0 | ✅ collections + documents + chunks |
| 文档管理 | 4 | 4 | 0 | ✅ list/status/preview/raw |
| 同步服务 | 3 | 3 | 0 | ✅ status/history/changes |
| 反馈系统 | 5 | 5 | 0 | ✅ feedback/list/stats/bad-cases/blacklist |
| FAQ 管理 | 2 | 2 | 0 | ✅ faq + suggestions |
| 出题系统 | 2 | 2 | 0 | ✅ exam/health + generate（参数校验） |
| 图片服务 | 4 | 4 | 0 | ✅ list/stats/info + 图片下载 |
| 报告服务 | 2 | 2 | 0 | ✅ weekly + monthly |
| 知识库路由 | 1 | 1 | 0 | ✅ /kb/route |
| 认证系统 | 1 | 1 | 0 | ✅ /auth/login 参数校验正常 |
| 异步任务 | 1 | 0 | 1 | ⚠️ /tasks 404 — 仅 main 分支可用 |
| 其他 | 1 | 0 | 1 | ⚠️ /stats 500 — SESSION_MANAGER 未注册 |
| **总计** | **33** | **31** | **2** | **2 个异常均为已知缺陷，不影响核心功能** |
---
## 性能基准测试
> 2026-06-04 生产服务器实测（47.116.16.222，public_kb 824 切片）
> 2026-06-10 生产服务器实测（47.116.16.222，public_kb ~824 切片）
### 检索性能
@@ -2126,7 +2126,7 @@ curl -s http://localhost:5001/tasks/stats
└── 流式 token 生成 ~11s
```
> **注**：LLM 生成阶段耗时取决于 qwen-plus API 响应速度，非本地可优化。如需进一步压缩至 10s 以内，可考虑换用更快的模型（如 qwen-turbo）。
> **注**：LLM 生成阶段耗时取决于 qwen-turbo API 响应速度，非本地可优化。当前已使用 qwen-turbo（最快模型），如需进一步压缩可考虑减少检索切片数量或缩短 prompt。
---
@@ -2138,16 +2138,11 @@ curl -s http://localhost:5001/tasks/stats
当前生产服务器知识库列表：
| 知识库 | 切片数 | 说明 |
| 知识库 | 文档数 | 说明 |
|--------|--------|------|
| public_kb | ~824 | 公开知识库，所有用户可访问 |
| dept_1_kb | ~800 | 部门知识库 1 |
| dept_2_kb | ~118 | 部门知识库 2 |
| dept_3_kb | ~132 | 部门知识库 3 |
| dept_4_kb | ~4 | 部门知识库 4 |
| dept_6_kb | ~29 | 部门知识库 6 |
| test1 | ~637 | 测试知识库 |
| faq_kb / test3 | 0 | 空（预留） |
| dept_1_kb | ~500 | 部门知识库 1 |
| resources | 0 | 资源库（新建，暂无文档） |
### 切片元数据字段
@@ -2171,11 +2166,11 @@ curl -s http://localhost:5001/tasks/stats
当代码升级涉及元数据字段变更时（如新增 `chunk_index`、`doc_type`），需要重构向量库：
```bash
# 重构指定知识库（清除哈希记录 → 触发全量同步，异步任务）
# 重构指定知识库（清除哈希记录 → 触发全量同步）
curl -s -X POST http://127.0.0.1:5001/collections/<kb_name>/reindex
```
> **⚠️ 注意**：reindex 已改为异步任务，立即返回 `task_id`。通过 `GET /tasks/<task_id>` 轮询进度。不再阻塞 gunicorn worker，搜索和问答接口不受影响。
> **⚠️ 注意**：reindex 为同步操作，会阻塞直到重建完成。耗时取决于知识库文档数量，大知识库可能需要数分钟。执行期间搜索和问答接口不受影响（多 worker 架构）。
### Reranker 配置