450 lines
8.7 KiB
Markdown
450 lines
8.7 KiB
Markdown
# 知识库页面后端接口清单
|
||
|
||
本文对应前端页面：[RagStoresPage.vue](frontend/src/pages/rag/RagStoresPage.vue) 和 [RagDocumentsPage.vue](frontend/src/pages/rag/RagDocumentsPage.vue)。
|
||
|
||
## 1. 页面目标
|
||
|
||
知识库页面采用：
|
||
|
||
- 顶部 4 张全局统计卡片
|
||
- 左侧知识库名称搜索与列表
|
||
- 右侧当前知识库详情
|
||
- 当前知识库级别操作：编辑、批量导入文件、重建索引
|
||
|
||
因此接口拆成 `全局概览`、`知识库列表/详情`、`文档管理`、`后续索引动作` 四组。
|
||
|
||
## 2. 本批已实现并已用于前端联调的接口
|
||
|
||
### 2.1 查询全部知识库
|
||
|
||
- `POST /api/rag/store/list`
|
||
|
||
当前返回类型：
|
||
|
||
- `RequestResult<List<RagStoreResponse>>`
|
||
|
||
当前字段：
|
||
|
||
- `id`
|
||
- `storeCode`
|
||
- `storeName`
|
||
- `description`
|
||
- `status`
|
||
- `remark`
|
||
|
||
对应代码：
|
||
|
||
- `src/main/java/com/bruce/rag/controller/RagStoreController.java`
|
||
- `src/main/java/com/bruce/rag/dto/response/RagStoreResponse.java`
|
||
|
||
### 2.2 按条件查询知识库
|
||
|
||
- `POST /api/rag/store/query`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"storeCode": "PROD_DOC",
|
||
"storeName": "产品制度",
|
||
"status": "ENABLED"
|
||
}
|
||
```
|
||
|
||
当前支持字段：
|
||
|
||
- `storeCode`
|
||
- `storeName`
|
||
- `status`
|
||
|
||
对应代码：
|
||
|
||
- `src/main/java/com/bruce/rag/dto/request/RagStoreQueryRequest.java`
|
||
|
||
### 2.3 查询知识库详情
|
||
|
||
- `GET /api/rag/store/detail?id={id}`
|
||
|
||
返回类型：
|
||
|
||
- `RequestResult<RagStoreResponse>`
|
||
|
||
### 2.4 新增或修改知识库
|
||
|
||
- `POST /api/rag/store/save`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"storeCode": "PROD_DOC",
|
||
"storeName": "产品制度库",
|
||
"description": "产品制度、业务规范、流程材料",
|
||
"status": "启用",
|
||
"remark": "核心制度库"
|
||
}
|
||
```
|
||
|
||
返回类型：
|
||
|
||
- `RequestResult<Boolean>`
|
||
|
||
说明：
|
||
|
||
- `id` 为空时新增
|
||
- `id` 不为空时修改
|
||
|
||
### 2.5 删除知识库
|
||
|
||
- `POST /api/rag/store/delete?id={id}`
|
||
|
||
返回类型：
|
||
|
||
- `RequestResult<Boolean>`
|
||
|
||
### 2.6 知识库总览统计
|
||
|
||
- `GET /api/rag/store/overview`
|
||
|
||
返回类型：
|
||
|
||
- `RequestResult<RagStoreOverviewResponse>`
|
||
|
||
字段：
|
||
|
||
- `totalStores`
|
||
- `totalDocuments`
|
||
- `totalChunks`（当前为 `null`，待切片入库后统计）
|
||
- `retrievableStores`
|
||
|
||
### 2.7 知识库文档概览
|
||
|
||
- `GET /api/rag/store/documentOverview?storeId={storeId}`
|
||
|
||
返回类型：
|
||
|
||
- `RequestResult<RagStoreDocumentOverviewResponse>`
|
||
|
||
字段：
|
||
|
||
- `storeId`
|
||
- `storeName`
|
||
- `documentCount`
|
||
- `enabledDocumentCount`
|
||
- `parsedDocumentCount`
|
||
- `indexedDocumentCount`
|
||
- `lastUploadTime`
|
||
|
||
## 3. 当前文档管理接口
|
||
|
||
### 3.1 查询全部知识文档
|
||
|
||
- `POST /api/rag/documents/list`
|
||
|
||
### 3.2 按条件查询知识文档
|
||
|
||
- `POST /api/rag/documents/query`
|
||
|
||
当前可用于按 `storeId` 查询当前知识库下文档。
|
||
|
||
对应代码：
|
||
|
||
- `src/main/java/com/bruce/rag/controller/RagDocumentController.java`
|
||
- `src/main/java/com/bruce/rag/dto/request/RagDocumentQueryRequest.java`
|
||
|
||
### 3.3 查询知识文档详情
|
||
|
||
- `GET /api/rag/documents/detail?id={id}`
|
||
|
||
### 3.4 新增或修改知识文档
|
||
|
||
- `POST /api/rag/documents/save`
|
||
|
||
### 3.5 删除知识文档
|
||
|
||
- `POST /api/rag/documents/delete?id={id}`
|
||
|
||
### 3.6 批量上传文档到知识库
|
||
|
||
- `POST /api/rag/documents/batchUpload`
|
||
|
||
请求类型：
|
||
|
||
- `multipart/form-data`
|
||
|
||
表单字段：
|
||
|
||
- `storeId`：知识库 ID
|
||
- `sourceType`：默认为 `RAG`
|
||
- `files`：文件数组
|
||
- `documentSummary`：可选，批量设置文档摘要
|
||
- `remark`：可选
|
||
|
||
当前行为：
|
||
|
||
- 逐个调用附件上传服务，写入 `sys_attachment`
|
||
- 自动创建 `rag_document`
|
||
- 新文档默认 `parseStatus=UPLOADED`、`indexStatus=PENDING`、`enabled=true`
|
||
|
||
### 3.7 批量解析知识文档
|
||
|
||
- `POST /api/rag/documents/parse`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"documentIds": [1, 2]
|
||
}
|
||
```
|
||
|
||
当前行为：
|
||
|
||
- 根据附件后缀或 content type 选择 Tika 解析器
|
||
- 解析结果写入 `rag_document_parse_result`
|
||
- 解析成功后更新 `parseStatus=PARSED`
|
||
- 解析失败后更新 `parseStatus=FAILED` 和 `errorMessage`
|
||
|
||
### 3.8 批量切片知识文档
|
||
|
||
- `POST /api/rag/documents/chunk`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"documentIds": [1, 2],
|
||
"chunkStrategy": 1,
|
||
"chunkSize": 800,
|
||
"chunkOverlap": 120,
|
||
"delimiter": "。"
|
||
}
|
||
```
|
||
|
||
当前行为：
|
||
|
||
- `chunkStrategy` 使用 `RagChunkStrategyEnum` 的整型枚举值，例如 `1` 表示固定长度切片，`5` 表示按分隔符切片。
|
||
- 只处理已经存在解析快照的文档。
|
||
- 按策略生成 `rag_chunk`，写入前会替换该文档已有切片。
|
||
- 当前尚未调用 Embedding 模型写入 `rag_chunk_embedding`。
|
||
|
||
## 4. 下一批建议补充的接口
|
||
|
||
当前已有接口能支撑知识库、文档、上传、解析和手动切片入口。下一批建议聚焦向量索引、模型配置和任务化。
|
||
|
||
### 4.1 知识库列表查询增强版
|
||
|
||
- `POST /api/rag/store/manage/query`
|
||
|
||
用途：
|
||
|
||
- 左侧知识库列表
|
||
|
||
相比当前 `/query`，建议直接返回列表页需要的摘要字段，避免前端再额外聚合文档数据。
|
||
|
||
请求体建议：
|
||
|
||
```json
|
||
{
|
||
"storeName": "FAQ"
|
||
}
|
||
```
|
||
|
||
返回建议：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": [
|
||
{
|
||
"id": 2,
|
||
"storeCode": "FAQ",
|
||
"storeName": "FAQ知识库",
|
||
"description": "常见问题知识沉淀",
|
||
"status": "ENABLED",
|
||
"documentCount": 58,
|
||
"chunkCount": 920,
|
||
"indexStatus": "PROCESSING",
|
||
"retrievable": true,
|
||
"updateTime": "2026-05-21 11:12:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
建议响应 DTO：
|
||
|
||
- `RagStoreManageListResponse`
|
||
|
||
字段建议：
|
||
|
||
- `id`
|
||
- `storeCode`
|
||
- `storeName`
|
||
- `description`
|
||
- `status`
|
||
- `documentCount`
|
||
- `chunkCount`
|
||
- `indexStatus`
|
||
- `retrievable`
|
||
- `updateTime`
|
||
|
||
### 4.2 查询单个知识库详情增强版
|
||
|
||
- `GET /api/rag/store/detailPlus?id={id}`
|
||
|
||
用途：
|
||
|
||
- 右侧详情区
|
||
|
||
返回建议：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": {
|
||
"id": 1,
|
||
"storeCode": "PROD_DOC",
|
||
"storeName": "产品制度库",
|
||
"description": "产品制度、业务规范、流程材料",
|
||
"status": "ENABLED",
|
||
"createTime": "2026-05-03 10:20:00",
|
||
"updateTime": "2026-05-21 16:40:00",
|
||
"documentCount": 126,
|
||
"parseSuccessCount": 120,
|
||
"parseFailedCount": 6,
|
||
"chunkCount": 3800,
|
||
"lastUploadTime": "2026-05-21 15:32:00",
|
||
"lastIndexTime": "2026-05-21 15:48:00",
|
||
"retrievalMode": "HYBRID",
|
||
"embeddingModel": "bge-large-zh",
|
||
"chunkSize": 500,
|
||
"chunkOverlap": 100,
|
||
"topK": 5,
|
||
"retrievable": true
|
||
}
|
||
}
|
||
```
|
||
|
||
建议响应 DTO：
|
||
|
||
- `RagStoreDetailResponse`
|
||
|
||
### 4.3 发起当前知识库重建索引
|
||
|
||
- `POST /api/rag/store/reindex?storeId={id}`
|
||
|
||
用途：
|
||
|
||
- 右侧“重建索引”按钮
|
||
|
||
请求体建议：
|
||
|
||
```json
|
||
{
|
||
"force": true
|
||
}
|
||
```
|
||
|
||
返回建议：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": {
|
||
"taskId": 1002,
|
||
"storeId": 1,
|
||
"status": "PROCESSING"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.4 查询当前知识库最近任务
|
||
|
||
- `GET /api/rag/store/tasks?storeId={id}&limit=10`
|
||
|
||
用途：
|
||
|
||
- 右侧“最近任务”区
|
||
|
||
返回建议：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": [
|
||
{
|
||
"id": 1002,
|
||
"taskType": "REINDEX",
|
||
"summary": "全库索引刷新",
|
||
"status": "PROCESSING",
|
||
"startedAt": "2026-05-21 16:00:00"
|
||
},
|
||
{
|
||
"id": 1001,
|
||
"taskType": "IMPORT",
|
||
"summary": "12 个文件，制度文档增量导入",
|
||
"status": "SUCCESS",
|
||
"startedAt": "2026-05-21 15:20:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
建议响应 DTO：
|
||
|
||
- `RagStoreTaskResponse`
|
||
|
||
## 5. 这页前后端最小联调顺序
|
||
|
||
当前知识库页和知识文档页已经接入基础接口。下一步联调顺序建议：
|
||
|
||
1. 完成向量入库：
|
||
- `POST /api/rag/documents/chunk` 生成 `rag_chunk`
|
||
- 通过模型网关调用 Embedding 并写入 `rag_chunk_embedding`
|
||
|
||
2. 完成索引入口：
|
||
- `POST /api/rag/documents/index`
|
||
- `POST /api/rag/store/reindex`
|
||
|
||
3. 再补任务查询：
|
||
- `GET /api/rag/store/tasks`
|
||
- `GET /api/rag/documents/tasks`
|
||
|
||
## 6. 当前前端实现说明
|
||
|
||
当前前端已经接入：
|
||
|
||
- 统计卡片：`/api/rag/store/overview`
|
||
- 左侧列表：`/api/rag/store/query`
|
||
- 右侧详情：`/api/rag/store/detail`
|
||
- 文档概览：`/api/rag/store/documentOverview`
|
||
- 批量上传：`/api/rag/documents/batchUpload`
|
||
- 知识文档列表：`/api/rag/documents/query`
|
||
- 批量解析：`/api/rag/documents/parse`
|
||
- 批量切片：`/api/rag/documents/chunk`
|
||
|
||
仍待后端补齐后再联调：
|
||
|
||
- 重建索引
|
||
- 最近任务
|
||
- 模型服务商与 Embedding 模型配置
|
||
- 检索配置
|
||
- 检索测试/召回预览
|
||
|
||
## 7. 与 Agent 调试链路的关联
|
||
|
||
当前 RAG 切片与向量数据已经被 Agent 调试页直接消费：
|
||
|
||
- Agent 调试接口 `POST /api/agents/{agentId}/chat` 在 `ragEnabled=true` 时会读取 `rag_chunk_embedding` 进行 TopK 召回。
|
||
- 若未完成切片向量化，Agent 调试会返回“未召回到可用知识切片”。
|
||
|
||
关联文档：
|
||
|
||
- [Agent 页面后端接口清单](agent-page-apis.md)
|