From 5a872ef197a64f66eae0ab03448c924356ddf7f8 Mon Sep 17 00:00:00 2001 From: bruce Date: Sun, 24 May 2026 19:38:45 +0800 Subject: [PATCH] =?UTF-8?q?docs(agent):=20=E5=90=8C=E6=AD=A5=20RAG=20?= =?UTF-8?q?=E5=BD=93=E5=89=8D=E8=83=BD=E5=8A=9B=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENT.md | 53 +++++---- README.md | 27 +++-- docs/ARCHITECTURE.md | 41 +++++-- docs/ROADMAP.md | 51 ++++---- rag-store-page-apis.md | 265 +++++++++++++++++++---------------------- 5 files changed, 237 insertions(+), 200 deletions(-) diff --git a/AGENT.md b/AGENT.md index e16d3ec..53c6419 100644 --- a/AGENT.md +++ b/AGENT.md @@ -11,7 +11,8 @@ - 文件上传与附件管理 - 前后端统一的管理控制台 -当前阶段以"先搭平台骨架，再逐步补智能能力"为主，优先保证工程结构、接口规范、知识库链路和可扩展性。 +当前阶段已经完成平台骨架、公共接口规范、知识库/知识文档管理、文档上传与解析入口。 +后续重点从"元数据可管"推进到"RAG 可检索"和"Agent 可运行"。 ## 2. 总体设计思路 @@ -37,6 +38,7 @@ - `sys_enum`：系统枚举配置（已完成 CRUD、批量新增、管理端查询） - `sys_attachment`：附件与文件上传（已完成本地上传、元数据持久化） +- 文档解析抽象：`DocumentParser`、`DocumentParserFactory` 与 Tika 解析实现（已完成 TXT/Markdown/LOG、PDF、Word、Excel 文本抽取） - 统一 DTO / `RequestResult`（已完成） - 通用状态枚举、启用禁用枚举（已完成） - 全局异常处理 `GlobalExceptionHandler`（已完成） @@ -45,19 +47,23 @@ ### 3.2 RAG 知识库模块 -当前已有完整的元数据管理层： +当前已有元数据管理、文档上传和解析入口： - `rag_store`：知识库主表（已完成 CRUD、编码唯一性校验） -- `rag_document`：知识库文档表（已完成实体、Mapper、Service、条件查询） +- `rag_document`：知识库文档表（已完成 CRUD、条件查询、批量上传、启停用） +- `rag_chunk`：知识切片表结构、实体、Mapper、Service（已完成结构，待生成逻辑） +- `rag_chunk_embedding`：切片向量表结构、实体、Mapper、Service（已完成结构，待向量化逻辑） - RAG 解析状态枚举 `RagParseStatusEnum`（已完成） - RAG 索引状态枚举 `RagIndexStatusEnum`（已完成） +- RAG 切片策略枚举 `RagChunkStrategyEnum`（已完成） +- 文档解析接口 `/api/rag/documents/parse`（已完成状态流转和文本抽取，尚未落切片） 后续计划继续扩展： -- 文档切片 -- 向量化 -- 检索召回 -- 索引任务 +- 将解析结果按切片策略写入 `rag_chunk` +- 调用 Embedding 模型并写入 `rag_chunk_embedding` +- 检索召回与重排序 +- 索引任务、失败重试和任务日志 当前设计原则： @@ -94,8 +100,8 @@ - 工作台（占位） - 系统枚举管理页（完整 CRUD + 批量新增） - 附件管理入口（占位） -- 知识库管理页（完整 CRUD + 双栏详情） -- 知识文档入口（占位） +- 知识库管理页（完整 CRUD + 概览卡片 + 双栏详情 + 批量上传入口） +- 知识文档页（条件查询 + 批量上传 + 批量解析入口 + 编辑/启停用/删除） 前端技术要点： @@ -115,7 +121,7 @@ 后续控制台至少继续覆盖： - 附件管理页面前端联调 -- 知识文档管理页面前端联调 +- RAG 检索配置、索引任务和最近任务页面联调 - Agent 调试页 - 执行日志查看 @@ -177,25 +183,28 @@ 1. ~~统一接口层规范~~ DTO、返回体、基础校验、通用异常处理（已完成） 2. ~~收紧基础模块~~ `sys_enum`、`sys_attachment`（已完成） 3. ~~补全 RAG 基础元数据管理~~ `rag_store`、`rag_document`（已完成） -4. 接入 Spring AI -5. 建立 Agent 运行时骨架 -6. ~~补前端控制台基础骨架~~（已完成，部分页面待联调） +4. ~~补全 RAG 文档上传与解析入口~~ 批量上传、Tika 文本抽取、解析状态流转（已完成） +5. 接入切片生成与切片持久化 +6. 接入 Spring AI Embedding / Chat 模型 +7. 建立 Agent 运行时骨架 +8. ~~补前端控制台基础骨架~~（已完成，部分高级页面待联调） 剩余重点： -- 完善 RAG 文档上传、解析、索引的业务闭环 -- 补齐前端附件管理、知识文档页面的表单与接口联调 -- 接入 Spring AI 并实现模型调用链路 +- 完成 RAG 解析结果到 `rag_chunk` 的落库闭环 +- 接入 Embedding，生成并保存 `rag_chunk_embedding` +- 补齐索引任务、重试、重建索引和最近任务接口 +- 接入 Spring AI 并实现最小模型调用链路 ## 7. 下一步建议 结合当前代码状态，接下来建议重点做： -- 实现知识库文档上传并自动创建 `rag_document` 记录 -- 建立文档解析任务入口与状态流转 -- 为后续切片与向量化预留任务入口 -- 补齐前端附件管理、知识文档页面的联调 -- 接入 Spring AI，实现最小模型调用链路 +- 实现解析结果切片：根据 `RagChunkStrategyEnum` 生成 `rag_chunk` +- 实现索引入口：对切片调用 Embedding 模型并写入 `rag_chunk_embedding` +- 把 `indexStatus` 从手工字段推进为真实状态流转 +- 补齐重建索引、失败重试、最近任务接口和前端展示 +- 接入 Spring AI，实现最小 Chat / Embedding 调用链路 ## 8. 文档用途说明 @@ -210,4 +219,4 @@ - `agent-runtime.md` - `rag-design.md` - `api-style.md` -- `frontend-console.md` \ No newline at end of file +- `frontend-console.md` diff --git a/README.md b/README.md index 22737ac..5be51cb 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,8 @@ Common Agent 是一个规划中的通用 Agent 平台，技术路线基于 Java、Spring Boot 和 Spring AI。 项目目标是建设一套完整的前后端系统，支持 Agent 编排、工具调用、会话管理、RAG 知识库和平台管理能力。 -当前项目处于基础工程阶段。后端骨架（含 DTO、统一返回体、全局异常处理、审计自动填充）、PostgreSQL 配置、MyBatis-Plus、Lombok、多环境配置文件和前端控制台基础页面已经完成； -Agent 运行时、RAG 文档解析与向量化和更多管理功能会在后续阶段逐步实现。 +当前项目已经完成基础工程、公共模块、RAG 元数据管理、文档上传、文档解析入口、前端知识库与知识文档管理页面。 +Agent 运行时、RAG 切片入库、向量化、检索问答和更多平台管理能力会在后续阶段逐步实现。 ## 项目愿景 @@ -22,7 +22,7 @@ Common Agent 希望成为一个可复用的企业级 AI 应用基础平台： |------|------| | 后端 | Java 21, Spring Boot 4.0.6, MyBatis-Plus 3.5.16 | | 数据库 | PostgreSQL | -| 工具库 | Lombok, Springdoc OpenAPI 2.8.13, Jackson | +| 工具库 | Lombok, Springdoc OpenAPI 2.8.13, Jackson, Apache Tika 3.2.3 | | 构建 | Maven Wrapper | | 前端 | Vue 3, TypeScript 5.9, Vite, Element Plus, Pinia, Vue Router 4 | | 前端测试 | Vitest, @vue/test-utils | @@ -48,6 +48,7 @@ common_agent │ │ ├── common/ # 公共模块 │ │ │ ├── config/ # AttachmentProperties, EntityAuditMetaObjectHandler │ │ │ ├── controller/ # SysAttachmentController, SysEnumController +│ │ │ ├── document/parse/ # 文档解析抽象与 Tika 实现 │ │ │ ├── domain/ │ │ │ │ ├── entity/ # SysAttachment, SysEnum │ │ │ │ └── model/ # BaseEntity, RequestResult @@ -62,8 +63,8 @@ common_agent │ │ ├── constant/ # RagSystemConstants │ │ ├── controller/ # RagStoreController, RagDocumentController │ │ ├── dto/ # 请求/响应 DTO -│ │ ├── entity/ # RagStore, RagDocument -│ │ ├── enums/ # RagParseStatusEnum, RagIndexStatusEnum +│ │ ├── entity/ # RagStore, RagDocument, RagChunk, RagChunkEmbedding +│ │ ├── enums/ # RagParseStatusEnum, RagIndexStatusEnum, RagChunkStrategyEnum │ │ ├── mapper/ # RagDocumentMapper, RagStoreMapper │ │ └── service/ # 接口与实现 │ ├── main/resources/ @@ -149,7 +150,7 @@ npm run build | 系统枚举 | 完整 CRUD + 批量新增 | | 附件管理 | 占位 | | 知识库 | 完整 CRUD + 双栏详情 | -| 知识文档 | 占位 | +| 知识文档 | 条件查询 + 批量上传 + 批量解析入口 + 编辑/启停用/删除 | 当前 UI 规范： @@ -167,10 +168,20 @@ npm run build - 大整数 ID 通过 `@JsonSerialize(ToStringSerializer.class)` 防止前端精度丢失 - 全局异常处理返回 HTTP 400/500 状态码 +## RAG 当前能力边界 + +当前 RAG 已经从元数据管理推进到"上传 + 解析入口"阶段： + +- 知识库：支持列表、条件查询、详情、总览、单库文档概览、新增、编辑、删除。 +- 知识文档：支持列表、条件查询、详情、新增/编辑、删除、批量上传。 +- 文档解析：基于 Apache Tika 支持 TXT/Markdown/LOG、PDF、Word、Excel 文本抽取，解析时更新 `parseStatus`。 +- 切片与向量表：`rag_chunk`、`rag_chunk_embedding` 实体、Mapper、Service 已有结构，但尚未实现切片生成、向量写入和检索召回。 +- 前端：知识库页和知识文档页已经接入当前接口，检索配置、最近任务、重建索引仍是后续能力。 + ## 规划模块 - `agent-core`：Agent 执行模型、工具注册、记忆和编排能力。 -- `rag-core`：文档导入、切片、Embedding、检索和引用元数据。 +- `rag-core`：文档导入、解析、切片、Embedding、检索和引用元数据。 - `model-provider`：基于 Spring AI 的聊天模型、Embedding、重排序和模型配置层。 - `platform-api`：面向前端和外部系统的 REST API。 - `platform-admin`：平台管理前端。 @@ -186,4 +197,4 @@ npm run build - [Spring AI Reference](https://docs.spring.io/spring-ai/reference/) - [Spring AI RAG Reference](https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html) -- [MyBatis-Plus](https://baomidou.com/) \ No newline at end of file +- [MyBatis-Plus](https://baomidou.com/) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9be2604..8a3a6f8 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -40,6 +40,7 @@ - 全局异常处理 `GlobalExceptionHandler`。 - MyBatis-Plus 审计自动填充 `EntityAuditMetaObjectHandler`。 - 附件本地存储配置 `AttachmentProperties`。 +- 文档解析抽象与 Apache Tika 解析实现。 - 系统枚举管理能力（CRUD + 批量新增 + 管理端查询）。 - 附件上传能力（本地磁盘 + 元数据持久化）。 @@ -58,6 +59,11 @@ | SysAttachmentController | `common/controller/SysAttachmentController.java` | | SysEnumServiceImpl | `common/service/impl/SysEnumServiceImpl.java` | | SysAttachmentServiceImpl | `common/service/impl/SysAttachmentServiceImpl.java` | +| DocumentParserFactory | `common/document/parse/DocumentParserFactory.java` | +| TxtDocumentParser | `common/document/parse/impl/TxtDocumentParser.java` | +| PdfDocumentParser | `common/document/parse/impl/PdfDocumentParser.java` | +| WordDocumentParser | `common/document/parse/impl/WordDocumentParser.java` | +| ExcelDocumentParser | `common/document/parse/impl/ExcelDocumentParser.java` | | CommonStatusEnum | `common/enums/CommonStatusEnum.java` | | EnableStatusEnum | `common/enums/EnableStatusEnum.java` | @@ -80,7 +86,8 @@ - 维护 RAG 知识库主数据（CRUD + 编码唯一性校验）。 - 维护知识库文档与附件的关联关系。 -- 定义解析状态、索引状态和 RAG 相关来源常量。 +- 支持知识文档批量上传、解析入口和解析状态流转。 +- 定义切片、向量、解析状态、索引状态和 RAG 相关来源常量。 关键类： @@ -88,28 +95,42 @@ |----|------| | RagStore | `rag/entity/RagStore.java` | | RagDocument | `rag/entity/RagDocument.java` | +| RagChunk | `rag/entity/RagChunk.java` | +| RagChunkEmbedding | `rag/entity/RagChunkEmbedding.java` | | RagStoreController | `rag/controller/RagStoreController.java` | | RagDocumentController | `rag/controller/RagDocumentController.java` | | RagStoreServiceImpl | `rag/service/impl/RagStoreServiceImpl.java` | | RagDocumentServiceImpl | `rag/service/impl/RagDocumentServiceImpl.java` | +| RagDocumentParseServiceImpl | `rag/service/impl/RagDocumentParseServiceImpl.java` | | RagParseStatusEnum | `rag/enums/RagParseStatusEnum.java` | | RagIndexStatusEnum | `rag/enums/RagIndexStatusEnum.java` | +| RagChunkStrategyEnum | `rag/enums/RagChunkStrategyEnum.java` | | RagSystemConstants | `rag/constant/RagSystemConstants.java` | 接口列表： | 方法 | 路径 | 说明 | |------|------|------| +| POST | `/api/rag/store/list` | 查询全部知识库 | | POST | `/api/rag/store/query` | 知识库条件查询 | | GET | `/api/rag/store/detail` | 获取知识库详情 | +| GET | `/api/rag/store/overview` | 获取知识库总览 | +| GET | `/api/rag/store/documentOverview` | 获取单个知识库文档概览 | | POST | `/api/rag/store/save` | 新增/更新知识库 | | POST | `/api/rag/store/delete` | 删除知识库 | +| POST | `/api/rag/documents/list` | 查询全部知识文档 | | POST | `/api/rag/documents/query` | 知识文档条件查询 | +| GET | `/api/rag/documents/detail` | 获取知识文档详情 | +| POST | `/api/rag/documents/save` | 新增/更新知识文档 | +| POST | `/api/rag/documents/delete` | 删除知识文档 | +| POST | `/api/rag/documents/batchUpload` | 批量上传文档并创建 `rag_document` | +| POST | `/api/rag/documents/parse` | 批量解析知识文档 | 当前边界： -- 元数据管理层已完成（知识库 CRUD、文档查询）。 -- 尚未实现"文档上传后自动建档"、"解析入库"、"切片向量化"、"检索问答"等业务流程。 +- 知识库 CRUD、文档 CRUD、批量上传、Tika 文本解析和状态流转已完成。 +- 解析结果当前只返回给调用方并更新文档状态，尚未写入 `rag_chunk`。 +- `rag_chunk`、`rag_chunk_embedding` 的结构层已就绪，尚未实现切片生成、向量化、索引任务和检索问答。 ## 4. 数据模型关系 @@ -121,8 +142,10 @@ | `sys_attachment` | 附件元数据 | 独立，被 rag_document 引用 | | `rag_store` | 知识库主表 | 独立 | | `rag_document` | 知识库文档表 | 关联 `rag_store.id` 和 `sys_attachment.id` | +| `rag_chunk` | 知识切片表 | 关联 `rag_store.id` 和 `rag_document.id` | +| `rag_chunk_embedding` | 切片向量表 | 关联 `rag_store.id`、`rag_document.id` 和 `rag_chunk.id` | -`rag_document` 是 RAG 模块与附件模块的连接点。 +`rag_document` 是 RAG 模块与附件模块的连接点，`rag_chunk` 和 `rag_chunk_embedding` 是下一步检索链路的核心落点。 ## 5. 配置与运行 @@ -141,15 +164,15 @@ ## 7. 当前不足 -- RAG 尚未进入"可用链路"，只有元数据管理层。 +- RAG 尚未进入"可检索链路"，当前完成上传与解析，但未完成切片、向量化和召回。 - Agent 运行时相关模型与服务尚未开始建设。 -- 前端部分页面（工作台、附件管理、知识文档）为占位状态。 +- 前端部分页面（工作台、附件管理、检索配置、最近任务）为占位或后续能力提示。 - 缺少鉴权、租户、操作日志。 ## 8. 建议演进方向 -1. 补 RAG 最小闭环：上传附件 → 建立文档 → 状态流转 → 解析占位。 +1. 补 RAG 最小检索闭环：解析文本 → 生成切片 → 生成向量 → 检索召回。 2. 接入 Spring AI，实现最小模型调用链路。 3. 建设 Agent 域模型：Agent、Session、Message、Tool、Task。 -4. 补齐前端占位页面的表单与联调。 -5. 衔接模型供应商、工作流编排和前端管理台。 \ No newline at end of file +4. 补齐索引任务、重试、重建索引和前端任务视图。 +5. 衔接模型供应商、工作流编排和前端管理台。 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index a33ff15..ee2bd63 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,6 +1,6 @@ # Common Agent 开发路线图 -本文档基于 2026-05-21 当前分支代码整理，用来区分"已经完成""建议优先做""中期建设项"。 +本文档基于 2026-05-24 当前分支代码整理，用来区分"已经完成""建议优先做""中期建设项"。 ## 已完成 @@ -9,6 +9,7 @@ - Spring Boot 4.0.6 后端工程初始化。 - PostgreSQL 数据源与多环境配置文件（dev / template）。 - MyBatis-Plus 3.5.16、Lombok、Springdoc OpenAPI 2.8.13 已接入。 +- Apache Tika 3.2.3 已接入，用于文档文本抽取。 - Maven Wrapper。 ### 公共能力 @@ -18,6 +19,8 @@ - `RequestResult` 统一 API 返回体。 - `GlobalExceptionHandler` 全局异常处理。 - `AttachmentProperties` 附件本地存储配置。 +- 文档解析抽象：`DocumentParser`、`DocumentParserFactory`、`DocumentParseContext`、`DocumentParseResult`。 +- Tika 解析实现：TXT/Markdown/LOG、PDF、Word、Excel。 - `sys_enum` 完整能力：实体、Mapper、Service、Controller、DTO 层。 - 支持单条增删改查、批量新增、管理端条件查询（含关键词搜索）。 - 批量新增内含重复值校验。 @@ -27,10 +30,14 @@ ### RAG 基础能力 - `rag_store`、`rag_document` 表结构与实体定义。 +- `rag_chunk`、`rag_chunk_embedding` 表结构与实体定义。 - RAG 知识库完整 CRUD（含编码唯一性校验）。 -- 知识文档条件查询服务。 +- 知识文档完整 CRUD、条件查询、批量上传。 +- 文档解析入口：支持批量提交文档 ID，按切片策略参数发起解析，状态流转为 PARSING / PARSED / FAILED。 +- 知识库总览接口与单库文档概览接口。 - RAG 解析状态枚举 `RagParseStatusEnum`（UPLOADED / PARSING / PARSED / FAILED）。 - RAG 索引状态枚举 `RagIndexStatusEnum`（PENDING / INDEXING / INDEXED / FAILED）。 +- RAG 切片策略枚举 `RagChunkStrategyEnum`（FIXED_LENGTH / PARAGRAPH / HEADING / TABLE_ROW / DELIMITER / SEMANTIC）。 - RAG 来源常量 `RagSystemConstants`。 ### 前端控制台 @@ -38,7 +45,9 @@ - Vue 3 + TypeScript + Vite + Element Plus + Pinia + Vue Router 工程。 - `AdminLayout.vue` 管理后台布局（侧边栏菜单 + 主内容区）。 - 系统枚举管理页：完整 CRUD + 批量新增对话框 + 关键词搜索 + 响应式布局。 -- 知识库管理页：完整 CRUD + 概览卡片 + 双栏详情 + 编辑对话框。 +- 知识库管理页：完整 CRUD + 概览卡片 + 双栏详情 + 编辑对话框 + 批量上传入口。 +- 知识文档管理页：条件查询 + 批量上传 + 批量解析入口 + 编辑/启停用/删除。 +- RAG 文档批量上传组件：支持锁定知识库或选择知识库上传。 - API 层：Axios 封装 + Long 类型安全解析 + 统一错误拦截。 - 单元测试：Vitest + @vue/test-utils，覆盖路由、布局、页面和 API。 @@ -49,24 +58,24 @@ ## 短期优先级 -建议优先完成下面几项，把 RAG 元数据管理层升级为可用的业务闭环： +建议优先完成下面几项，把 RAG 上传解析链路升级为可检索链路： -1. 知识库文档上传接口：上传文件后自动创建 `rag_document` 记录。 -2. 文档解析任务入口与状态流转。 -3. 向量化任务入口与状态流转。 -4. 知识库文档新增、详情、启停用、重试等管理接口。 -5. 前端附件管理页面联调。 -6. 前端知识文档页面联调。 +1. 切片生成服务：把解析服务拿到的 `DocumentParseResult.text` 改造成可持久化的 `rag_chunk` 记录。 +2. 按 `RagChunkStrategyEnum` 先落地 `FIXED_LENGTH` 和 `DELIMITER`，再扩展段落/标题/表格/语义切片。 +3. 索引任务入口：把文档或知识库的 `indexStatus` 推进为真实状态流转。 +4. 接入 Spring AI Embedding 模型，生成并保存 `rag_chunk_embedding`。 +5. 补齐重建索引、失败重试、最近任务接口。 +6. 前端接入检索配置、最近任务和重建索引动作。 ## RAG 最小闭环 -在基础规范层补齐后，当前 RAG 元数据层已完成，下一步建设业务闭环： +当前上传与解析入口已完成，下一步建设最小检索闭环： -1. 附件上传后自动创建 `rag_document` 记录。 -2. 建立文档解析任务入口（占位解析器）。 -3. 解析状态、索引状态按流程流转。 -4. 接入占位向量化接口。 -5. 提供知识库文档管理完整接口（新增、详情、启停用、重试、删除）。 +1. 批量上传文件，自动创建 `sys_attachment` 与 `rag_document`。 +2. 调用解析入口，使用 Tika 抽取文本并更新 `parseStatus`。 +3. 根据切片策略生成 `rag_chunk`。 +4. 调用 Embedding 模型生成向量并写入 `rag_chunk_embedding`。 +5. 提供检索接口，按 query 向量召回切片并返回引用元数据。 ## Agent 核心能力 @@ -98,6 +107,8 @@ RAG 数据链路稳定后，再进入 Agent 主线： - 上传接口返回模型：`SysAttachmentResponse`。 - 枚举查询接口规范：POST `/api/sys-enum/queryForManagement`。 - RAG 文档状态字段：`parseStatus` + `indexStatus` + `enabled`。 +- RAG 文档批量上传接口：POST `/api/rag/documents/batchUpload`。 +- RAG 文档解析接口：POST `/api/rag/documents/parse`，当前同步解析并返回解析元数据。 - 大整数 ID 通过 `@JsonSerialize(ToStringSerializer.class)` 输出为字符串。 ## 里程碑 @@ -109,9 +120,9 @@ RAG 数据链路稳定后，再进入 Agent 主线： ### 里程碑 2：RAG 可演示 -- 实现知识库文档上传、建档、状态流转。 -- 预留解析和索引任务接口。 -- 前端知识库页面完整联调。 +- 已完成知识库文档上传、建档、解析状态流转。 +- 下一步完成切片持久化、向量化和检索接口。 +- 前端知识库与知识文档页面已接入当前接口，索引任务和检索配置待接入。 ### 里程碑 3：Agent 最小运行时 @@ -119,4 +130,4 @@ RAG 数据链路稳定后，再进入 Agent 主线： ### 里程碑 4：平台管理化 -- 补齐前端占位页面联调与后台配置能力，形成完整平台雏形。 \ No newline at end of file +- 补齐前端占位页面联调与后台配置能力，形成完整平台雏形。 diff --git a/rag-store-page-apis.md b/rag-store-page-apis.md index 81b7ef2..516ae7b 100644 --- a/rag-store-page-apis.md +++ b/rag-store-page-apis.md @@ -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` -## 3. 当前项目里已有但本批前端未联调的接口 +### 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 查询全部知识文档 -- `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` +仍待后端补齐后再联调： + +- 重建索引 +- 最近任务 +- 检索配置 +- 检索测试/召回预览