docs(agent): 同步 RAG 当前能力文档
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# 知识库页面后端接口清单
|
||||
|
||||
本文对应前端页面：[RagStoresPage.vue](/D:/Code/common_agent/frontend/src/pages/RagStoresPage.vue)
|
||||
本文对应前端页面：[RagStoresPage.vue](frontend/src/pages/rag/RagStoresPage.vue) 和 [RagDocumentsPage.vue](frontend/src/pages/rag/RagDocumentsPage.vue)。
|
||||
|
||||
## 1. 页面目标
|
||||
|
||||
@@ -11,13 +11,13 @@
|
||||
- 右侧当前知识库详情
|
||||
- 当前知识库级别操作：编辑、批量导入文件、重建索引
|
||||
|
||||
因此接口建议拆成 `全局概览`、`知识库列表/详情`、`单库动作` 三组。
|
||||
因此接口拆成 `全局概览`、`知识库列表/详情`、`文档管理`、`后续索引动作` 四组。
|
||||
|
||||
## 2. 本批已实现并已用于前端联调的接口
|
||||
|
||||
### 2.1 查询全部知识库
|
||||
|
||||
- `GET /api/rag/stores`
|
||||
- `POST /api/rag/store/list`
|
||||
|
||||
当前返回类型：
|
||||
|
||||
@@ -34,12 +34,12 @@
|
||||
|
||||
对应代码：
|
||||
|
||||
- [RagStoreController.java](/D:/Code/common_agent/src/main/java/com/bruce/rag/controller/RagStoreController.java)
|
||||
- [RagStoreResponse.java](/D:/Code/common_agent/src/main/java/com/bruce/rag/dto/response/RagStoreResponse.java)
|
||||
- `src/main/java/com/bruce/rag/controller/RagStoreController.java`
|
||||
- `src/main/java/com/bruce/rag/dto/response/RagStoreResponse.java`
|
||||
|
||||
### 2.2 按条件查询知识库
|
||||
|
||||
- `POST /api/rag/stores/query`
|
||||
- `POST /api/rag/store/query`
|
||||
|
||||
请求体：
|
||||
|
||||
@@ -59,11 +59,11 @@
|
||||
|
||||
对应代码：
|
||||
|
||||
- [RagStoreQueryRequest.java](/D:/Code/common_agent/src/main/java/com/bruce/rag/dto/request/RagStoreQueryRequest.java)
|
||||
- `src/main/java/com/bruce/rag/dto/request/RagStoreQueryRequest.java`
|
||||
|
||||
### 2.3 查询知识库详情
|
||||
|
||||
- `GET /api/rag/stores/{id}`
|
||||
- `GET /api/rag/store/detail?id={id}`
|
||||
|
||||
返回类型：
|
||||
|
||||
@@ -71,7 +71,7 @@
|
||||
|
||||
### 2.4 新增或修改知识库
|
||||
|
||||
- `POST /api/rag/stores`
|
||||
- `POST /api/rag/store/save`
|
||||
|
||||
请求体：
|
||||
|
||||
@@ -97,17 +97,50 @@
|
||||
|
||||
### 2.5 删除知识库
|
||||
|
||||
- `DELETE /api/rag/stores/{id}`
|
||||
- `POST /api/rag/store/delete?id={id}`
|
||||
|
||||
返回类型：
|
||||
|
||||
- `RequestResult<Boolean>`
|
||||
|
||||
## 3. 当前项目里已有但本批前端未联调的接口
|
||||
### 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 查询全部知识文档
|
||||
|
||||
- `GET /api/rag/documents`
|
||||
- `POST /api/rag/documents/list`
|
||||
|
||||
### 3.2 按条件查询知识文档
|
||||
|
||||
@@ -117,50 +150,74 @@
|
||||
|
||||
对应代码：
|
||||
|
||||
- [RagDocumentController.java](/D:/Code/common_agent/src/main/java/com/bruce/rag/controller/RagDocumentController.java)
|
||||
- [RagDocumentQueryRequest.java](/D:/Code/common_agent/src/main/java/com/bruce/rag/dto/request/RagDocumentQueryRequest.java)
|
||||
- `src/main/java/com/bruce/rag/controller/RagDocumentController.java`
|
||||
- `src/main/java/com/bruce/rag/dto/request/RagDocumentQueryRequest.java`
|
||||
|
||||
## 4. 下一批建议补充的接口
|
||||
### 3.3 查询知识文档详情
|
||||
|
||||
当前已有接口能支撑最基础的列表查询，但还不足以支撑统计卡片、右侧详情聚合和单库动作。建议补下面几个接口。
|
||||
- `GET /api/rag/documents/detail?id={id}`
|
||||
|
||||
### 4.1 知识库总览统计
|
||||
### 3.4 新增或修改知识文档
|
||||
|
||||
- `GET /api/rag/stores/overview`
|
||||
- `POST /api/rag/documents/save`
|
||||
|
||||
用途：
|
||||
### 3.5 删除知识文档
|
||||
|
||||
- 顶部 4 张卡片数据
|
||||
- `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
|
||||
{
|
||||
"resultcode": "0",
|
||||
"message": null,
|
||||
"data": {
|
||||
"storeCount": 12,
|
||||
"documentCount": 1286,
|
||||
"chunkCount": 24390,
|
||||
"retrievableStoreCount": 9
|
||||
}
|
||||
"documentIds": [1, 2],
|
||||
"chunkStrategy": "FIXED_LENGTH",
|
||||
"chunkSize": 800,
|
||||
"chunkOverlap": 120,
|
||||
"delimiter": "。"
|
||||
}
|
||||
```
|
||||
|
||||
建议响应 DTO：
|
||||
当前行为：
|
||||
|
||||
- `RagStoreOverviewResponse`
|
||||
- 校验 `chunkStrategy` 是否属于 `RagChunkStrategyEnum`
|
||||
- 根据附件后缀或 content type 选择 Tika 解析器
|
||||
- 解析成功后更新 `parseStatus=PARSED`
|
||||
- 解析失败后更新 `parseStatus=FAILED` 和 `errorMessage`
|
||||
- 当前暂不写入 `rag_chunk`
|
||||
|
||||
字段建议：
|
||||
## 4. 下一批建议补充的接口
|
||||
|
||||
- `storeCount`
|
||||
- `documentCount`
|
||||
- `chunkCount`
|
||||
- `retrievableStoreCount`
|
||||
当前已有接口能支撑知识库、文档、上传和解析入口。下一批建议聚焦切片、索引和任务化。
|
||||
|
||||
### 4.2 知识库列表查询增强版
|
||||
### 4.1 知识库列表查询增强版
|
||||
|
||||
- `POST /api/rag/stores/manage/query`
|
||||
- `POST /api/rag/store/manage/query`
|
||||
|
||||
用途：
|
||||
|
||||
@@ -216,9 +273,9 @@
|
||||
- `retrievable`
|
||||
- `updateTime`
|
||||
|
||||
### 4.3 查询单个知识库详情增强版
|
||||
### 4.2 查询单个知识库详情增强版
|
||||
|
||||
- `GET /api/rag/stores/{id}/detail`
|
||||
- `GET /api/rag/store/detailPlus?id={id}`
|
||||
|
||||
用途：
|
||||
|
||||
@@ -258,86 +315,9 @@
|
||||
|
||||
- `RagStoreDetailResponse`
|
||||
|
||||
### 4.4 新建知识库独立接口
|
||||
### 4.3 发起当前知识库重建索引
|
||||
|
||||
- `POST /api/rag/stores`
|
||||
|
||||
请求体建议：
|
||||
|
||||
```json
|
||||
{
|
||||
"storeCode": "PROD_DOC",
|
||||
"storeName": "产品制度库",
|
||||
"description": "产品制度、业务规范、流程材料"
|
||||
}
|
||||
```
|
||||
|
||||
返回建议：
|
||||
|
||||
- 返回新建后的 `id` 或完整 `RagStoreDetailResponse`
|
||||
|
||||
建议请求 DTO：
|
||||
|
||||
- `RagStoreSaveRequest`
|
||||
|
||||
### 4.5 编辑知识库独立接口
|
||||
|
||||
- `PUT /api/rag/stores/{id}`
|
||||
|
||||
请求体建议：
|
||||
|
||||
```json
|
||||
{
|
||||
"storeCode": "PROD_DOC",
|
||||
"storeName": "产品制度库",
|
||||
"description": "产品制度、业务规范、流程材料",
|
||||
"status": "ENABLED"
|
||||
}
|
||||
```
|
||||
|
||||
用途：
|
||||
|
||||
- 右侧“编辑”按钮
|
||||
|
||||
### 4.6 当前知识库批量导入文件
|
||||
|
||||
- `POST /api/rag/stores/{id}/documents/import`
|
||||
|
||||
用途：
|
||||
|
||||
- 右侧“批量导入文件”按钮
|
||||
|
||||
建议请求类型：
|
||||
|
||||
- `multipart/form-data`
|
||||
|
||||
表单字段建议：
|
||||
|
||||
- `files`: 文件数组
|
||||
- `remark`: 批次备注，可选
|
||||
|
||||
返回建议：
|
||||
|
||||
```json
|
||||
{
|
||||
"resultcode": "0",
|
||||
"message": null,
|
||||
"data": {
|
||||
"taskId": 1001,
|
||||
"storeId": 1,
|
||||
"fileCount": 12,
|
||||
"status": "PROCESSING"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
建议响应 DTO：
|
||||
|
||||
- `RagImportTaskResponse`
|
||||
|
||||
### 4.7 发起当前知识库重建索引
|
||||
|
||||
- `POST /api/rag/stores/{id}/reindex`
|
||||
- `POST /api/rag/store/reindex?storeId={id}`
|
||||
|
||||
用途：
|
||||
|
||||
@@ -365,9 +345,9 @@
|
||||
}
|
||||
```
|
||||
|
||||
### 4.8 查询当前知识库最近任务
|
||||
### 4.4 查询当前知识库最近任务
|
||||
|
||||
- `GET /api/rag/stores/{id}/tasks?limit=10`
|
||||
- `GET /api/rag/store/tasks?storeId={id}&limit=10`
|
||||
|
||||
用途：
|
||||
|
||||
@@ -404,31 +384,34 @@
|
||||
|
||||
## 5. 这页前后端最小联调顺序
|
||||
|
||||
如果想尽快把这页从演示版切到真实联调版，建议按下面顺序接：
|
||||
当前知识库页和知识文档页已经接入基础接口。下一步联调顺序建议：
|
||||
|
||||
1. 先复用已有：
|
||||
- `POST /api/rag/stores/query`
|
||||
1. 完成切片入库：
|
||||
- `POST /api/rag/documents/parse` 解析后写入 `rag_chunk`
|
||||
|
||||
2. 然后新增：
|
||||
- `GET /api/rag/stores/overview`
|
||||
- `GET /api/rag/stores/{id}/detail`
|
||||
2. 完成索引入口：
|
||||
- `POST /api/rag/documents/index`
|
||||
- `POST /api/rag/store/reindex`
|
||||
|
||||
3. 再补动作接口：
|
||||
- `POST /api/rag/stores`
|
||||
- `PUT /api/rag/stores/{id}`
|
||||
- `POST /api/rag/stores/{id}/documents/import`
|
||||
- `POST /api/rag/stores/{id}/reindex`
|
||||
- `GET /api/rag/stores/{id}/tasks`
|
||||
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/stores/overview`
|
||||
- 左侧列表：改调 `/api/rag/stores/manage/query`
|
||||
- 右侧详情：改调 `/api/rag/stores/{id}/detail`
|
||||
- 批量导入：改调 `/api/rag/stores/{id}/documents/import`
|
||||
- 重建索引：改调 `/api/rag/stores/{id}/reindex`
|
||||
- 最近任务：改调 `/api/rag/stores/{id}/tasks`
|
||||
仍待后端补齐后再联调：
|
||||
|
||||
- 重建索引
|
||||
- 最近任务
|
||||
- 检索配置
|
||||
- 检索测试/召回预览
|
||||
|
||||
Reference in New Issue
Block a user