# 知识库页面后端接口清单 本文对应前端页面：[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>` 当前字段： - `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` ### 2.4 新增或修改知识库 - `POST /api/rag/store/save` 请求体： ```json { "id": 1, "storeCode": "PROD_DOC", "storeName": "产品制度库", "description": "产品制度、业务规范、流程材料", "status": "启用", "remark": "核心制度库" } ``` 返回类型： - `RequestResult` 说明： - `id` 为空时新增 - `id` 不为空时修改 ### 2.5 删除知识库 - `POST /api/rag/store/delete?id={id}` 返回类型： - `RequestResult` ### 2.6 知识库总览统计 - `GET /api/rag/store/overview` 返回类型： - `RequestResult` 字段： - `totalStores` - `totalDocuments` - `totalChunks`（当前为 `null`，待切片入库后统计） - `retrievableStores` ### 2.7 知识库文档概览 - `GET /api/rag/store/documentOverview?storeId={storeId}` 返回类型： - `RequestResult` 字段： - `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)