docs(project): 更新 RAG 与模型平台现状

AGENT.md

@@ -11,8 +11,8 @@
 - 文件上传与附件管理
 - 前后端统一的管理控制台
 
-当前阶段已经完成平台骨架、公共接口规范、知识库/知识文档管理、文档上传与解析入口。
+当前阶段已经完成平台骨架、公共接口规范、知识库/知识文档管理、文档上传、文档解析、解析快照与手动切片入口。
-后续重点从"元数据可管"推进到"RAG 可检索"和"Agent 可运行"。
+后续重点从"文档可切片"推进到"向量可检索"、"模型可路由"和"Agent 可运行"。
 
 ## 2. 总体设计思路
 
@@ -51,16 +51,17 @@
 
 - `rag_store`：知识库主表（已完成 CRUD、编码唯一性校验）
 - `rag_document`：知识库文档表（已完成 CRUD、条件查询、批量上传、启停用）
-- `rag_chunk`：知识切片表结构、实体、Mapper、Service（已完成结构，待生成逻辑）
+- `rag_chunk`：知识切片表结构、实体、Mapper、Service、定长/分隔符切片器与手动切片入口（已完成基础闭环）
-- `rag_chunk_embedding`：切片向量表结构、实体、Mapper、Service（已完成结构，待向量化逻辑）
+- `rag_chunk_embedding`：切片向量表结构、实体、Mapper、Service（已完成结构，待模型网关接入后生成向量）
 - RAG 解析状态枚举 `RagParseStatusEnum`（已完成）
 - RAG 索引状态枚举 `RagIndexStatusEnum`（已完成）
 - RAG 切片策略枚举 `RagChunkStrategyEnum`（已完成）
-- 文档解析接口 `/api/rag/documents/parse`（已完成状态流转和文本抽取，尚未落切片）
+- 文档解析接口 `/api/rag/documents/parse`（已完成状态流转、文本抽取和解析快照保存）
+- 文档切片接口 `/api/rag/documents/chunk`（已完成按解析快照生成并替换 `rag_chunk`）
 
 后续计划继续扩展：
 
-- 将解析结果按切片策略写入 `rag_chunk`
+- 接入模型服务商配置与模型路由，统一管理 Ollama、硅基流动、百炼等模型来源
 - 调用 Embedding 模型并写入 `rag_chunk_embedding`
 - 检索召回与重排序
 - 索引任务、失败重试和任务日志
@@ -97,11 +98,12 @@
 已具备的页面与布局：
 
 - 左侧管理菜单与品牌区（232px 侧边栏）
-- 工作台（占位）
+- RAG 工作台（文档解析与切片概览）
 - 系统枚举管理页（完整 CRUD + 批量新增）
 - 附件管理入口（占位）
 - 知识库管理页（完整 CRUD + 概览卡片 + 双栏详情 + 批量上传入口）
-- 知识文档页（条件查询 + 批量上传 + 批量解析入口 + 编辑/启停用/删除）
+- 知识文档页（条件查询 + 批量上传 + 解析重试 + 批量切片 + 编辑/启停用/删除）
+- 切片任务页（解析成功/失败文档概览与切片入口）
 
 前端技术要点：
 
@@ -121,7 +123,8 @@
 后续控制台至少继续覆盖：
 
 - 附件管理页面前端联调
-- RAG 检索配置、索引任务和最近任务页面联调
+- RAG 检索配置、向量索引任务和最近任务页面联调
+- 模型服务商、模型配置、路由规则和调用日志管理
 - Agent 调试页
 - 执行日志查看
 
@@ -213,27 +216,28 @@
 2. ~~收紧基础模块~~ `sys_enum`、`sys_attachment`（已完成）
 3. ~~补全 RAG 基础元数据管理~~ `rag_store`、`rag_document`（已完成）
 4. ~~补全 RAG 文档上传与解析入口~~ 批量上传、Tika 文本抽取、解析状态流转（已完成）
-5. 接入切片生成与切片持久化
+5. ~~接入切片生成与切片持久化~~（已完成定长/分隔符切片与手动切片入口）
-6. 接入 Spring AI Embedding / Chat 模型
+6. 建设模型服务商配置与模型路由层
-7. 建立 Agent 运行时骨架
+7. 接入 Embedding / Chat 模型并完成向量写入
-8. ~~补前端控制台基础骨架~~（已完成，部分高级页面待联调）
+8. 建立 Agent 运行时骨架
+9. ~~补前端控制台基础骨架~~（已完成，部分高级页面待联调）
 
 剩余重点：
 
-- 完成 RAG 解析结果到 `rag_chunk` 的落库闭环
+- 完成模型服务商配置、模型配置、路由规则和调用日志基础能力
 - 接入 Embedding，生成并保存 `rag_chunk_embedding`
 - 补齐索引任务、重试、重建索引和最近任务接口
-- 接入 Spring AI 并实现最小模型调用链路
+- 接入 OpenAI-compatible / Spring AI 适配层并实现最小模型调用链路
 
 ## 7. 下一步建议
 
 结合当前代码状态，接下来建议重点做：
 
-- 实现解析结果切片：根据 `RagChunkStrategyEnum` 生成 `rag_chunk`
+- 实现模型服务商和模型配置表：支持 Ollama、硅基流动、百炼等 OpenAI-compatible 来源
-- 实现索引入口：对切片调用 Embedding 模型并写入 `rag_chunk_embedding`
+- 实现 Embedding 网关：对已落库切片调用 Embedding 模型并写入 `rag_chunk_embedding`
 - 把 `indexStatus` 从手工字段推进为真实状态流转
 - 补齐重建索引、失败重试、最近任务接口和前端展示
-- 接入 Spring AI，实现最小 Chat / Embedding 调用链路
+- 接入模型路由，实现本地小模型与云端大模型的成本优先调用链路
 
 ## 8. 文档用途说明
 
@@ -247,5 +251,7 @@
 
 - `agent-runtime.md`
 - `rag-design.md`
+- `MODEL_PROVIDER_REQUIREMENTS.md`
+- `MODEL_PROVIDER_DESIGN.md`
 - `api-style.md`
 - `frontend-console.md`

README.md

@@ -3,8 +3,8 @@
 Common Agent 是一个规划中的通用 Agent 平台，技术路线基于 Java、Spring Boot 和 Spring AI。
 项目目标是建设一套完整的前后端系统，支持 Agent 编排、工具调用、会话管理、RAG 知识库和平台管理能力。
 
-当前项目已经完成基础工程、公共模块、RAG 元数据管理、文档上传、文档解析入口、前端知识库与知识文档管理页面。
+当前项目已经完成基础工程、公共模块、RAG 元数据管理、文档上传、文档解析入口、解析快照、手动切片入口、前端知识库与知识文档管理页面。
-Agent 运行时、RAG 切片入库、向量化、检索问答和更多平台管理能力会在后续阶段逐步实现。
+Agent 运行时、RAG 向量化、检索问答、模型服务商配置与更多平台管理能力会在后续阶段逐步实现。
 
 ## 项目愿景
 
@@ -146,11 +146,12 @@ npm run build
 
 | 页面 | 状态 |
 |------|------|
-| 工作台 | 占位 |
+| RAG 工作台 | 文档解析与切片概览 |
 | 系统枚举 | 完整 CRUD + 批量新增 |
 | 附件管理 | 占位 |
 | 知识库 | 完整 CRUD + 双栏详情 |
-| 知识文档 | 条件查询 + 批量上传 + 批量解析入口 + 编辑/启停用/删除 |
+| 知识文档 | 条件查询 + 批量上传 + 解析重试 + 批量切片 + 编辑/启停用/删除 |
+| 切片任务 | 解析成功/失败文档概览 + 切片入口 |
 
 当前 UI 规范：
 
@@ -170,19 +171,21 @@ npm run build
 
 ## RAG 当前能力边界
 
-当前 RAG 已经从元数据管理推进到"上传 + 解析入口"阶段：
+当前 RAG 已经从元数据管理推进到"上传 + 解析 + 手动切片"阶段：
 
 - 知识库：支持列表、条件查询、详情、总览、单库文档概览、新增、编辑、删除。
 - 知识文档：支持列表、条件查询、详情、新增/编辑、删除、批量上传。
-- 文档解析：基于 Apache Tika 支持 TXT/Markdown/LOG、PDF、Word、Excel 文本抽取，解析时更新 `parseStatus`。
+- 文档解析：基于 Apache Tika 支持 TXT/Markdown/LOG、PDF、Word、Excel 文本抽取，解析时更新 `parseStatus` 并保存解析快照。
-- 切片与向量表：`rag_chunk`、`rag_chunk_embedding` 实体、Mapper、Service 已有结构，但尚未实现切片生成、向量写入和检索召回。
+- 文档切片：支持按解析快照进行手动异步切片，已落地定长切片和分隔符切片，写入 `rag_chunk`。
-- 前端：知识库页和知识文档页已经接入当前接口，检索配置、最近任务、重建索引仍是后续能力。
+- 向量表：`rag_chunk_embedding` 实体、Mapper、Service 已有结构，向量写入、检索召回和重排序仍待接入。
+- 模型配置：已补充模型服务商配置与路由需求/设计文档，后续用于统一接入 Ollama、硅基流动、百炼等来源。
+- 前端：知识库页、知识文档页、RAG 工作台和切片任务页已经接入当前接口，检索配置、最近任务、重建索引仍是后续能力。
 
 ## 规划模块
 
 - `agent-core`：Agent 执行模型、工具注册、记忆和编排能力。
 - `rag-core`：文档导入、解析、切片、Embedding、检索和引用元数据。
-- `model-provider`：基于 Spring AI 的聊天模型、Embedding、重排序和模型配置层。
+- `model-provider`：模型服务商配置、模型路由、调用日志，以及基于 OpenAI-compatible / Spring AI 的聊天模型、Embedding、重排序适配层。
 - `platform-api`：面向前端和外部系统的 REST API。
 - `platform-admin`：平台管理前端。
 - `common-infra`：持久化、审计日志、安全、租户隔离和可观测性。
@@ -191,6 +194,8 @@ npm run build
 
 - [架构说明](docs/ARCHITECTURE.md)
 - [开发路线图](docs/ROADMAP.md)
+- [模型服务商配置与路由需求](docs/MODEL_PROVIDER_REQUIREMENTS.md)
+- [模型服务商配置与路由设计](docs/MODEL_PROVIDER_DESIGN.md)
 - [平台设计草案](AGENT.md)
 
 ## 参考资料

docs/ARCHITECTURE.md

@@ -86,7 +86,7 @@
 
 - 维护 RAG 知识库主数据（CRUD + 编码唯一性校验）。
 - 维护知识库文档与附件的关联关系。
-- 支持知识文档批量上传、解析入口和解析状态流转。
+- 支持知识文档批量上传、解析入口、解析快照、手动切片入口和状态流转。
 - 定义切片、向量、解析状态、索引状态和 RAG 相关来源常量。
 
 关键类：
@@ -102,6 +102,10 @@
 | RagStoreServiceImpl | `rag/service/impl/RagStoreServiceImpl.java` |
 | RagDocumentServiceImpl | `rag/service/impl/RagDocumentServiceImpl.java` |
 | RagDocumentParseServiceImpl | `rag/service/impl/RagDocumentParseServiceImpl.java` |
+| RagDocumentChunkServiceImpl | `rag/service/impl/RagDocumentChunkServiceImpl.java` |
+| ChunkerFactory | `rag/parse/ChunkerFactory.java` |
+| FixedLengthChunker | `rag/parse/impl/FixedLengthChunker.java` |
+| DelimiterChunker | `rag/parse/impl/DelimiterChunker.java` |
 | RagParseStatusEnum | `rag/enums/RagParseStatusEnum.java` |
 | RagIndexStatusEnum | `rag/enums/RagIndexStatusEnum.java` |
 | RagChunkStrategyEnum | `rag/enums/RagChunkStrategyEnum.java` |
@@ -125,12 +129,14 @@
 | POST | `/api/rag/documents/delete` | 删除知识文档 |
 | POST | `/api/rag/documents/batchUpload` | 批量上传文档并创建 `rag_document` |
 | POST | `/api/rag/documents/parse` | 批量解析知识文档 |
+| POST | `/api/rag/documents/chunk` | 按策略异步生成文档切片 |
 
 当前边界：
 
-- 知识库 CRUD、文档 CRUD、批量上传、Tika 文本解析和状态流转已完成。
+- 知识库 CRUD、文档 CRUD、批量上传、Tika 文本解析、解析快照和状态流转已完成。
-- 解析结果当前只返回给调用方并更新文档状态，尚未写入 `rag_chunk`。
+- `rag_chunk` 已支持基于解析快照的手动异步切片，当前已落地定长切片和分隔符切片。
-- `rag_chunk`、`rag_chunk_embedding` 的结构层已就绪，尚未实现切片生成、向量化、索引任务和检索问答。
+- `rag_chunk_embedding` 的结构层已就绪，尚未实现模型调用、向量化、索引任务和检索问答。
+- 模型服务商配置与路由已有需求/设计文档，后续会作为 Embedding、Chat 和 Rerank 的统一接入层。
 
 ## 4. 数据模型关系
 
@@ -177,15 +183,16 @@
 
 ## 7. 当前不足
 
-- RAG 尚未进入"可检索链路"，当前完成上传与解析，但未完成切片、向量化和召回。
+- RAG 尚未进入"可检索链路"，当前完成上传、解析和手动切片，但未完成向量化和召回。
+- 模型服务商配置、模型路由和调用日志尚未落地代码。
 - Agent 运行时相关模型与服务尚未开始建设。
-- 前端部分页面（工作台、附件管理、检索配置、最近任务）为占位或后续能力提示。
+- 前端部分页面（附件管理、检索配置、最近任务）为占位或后续能力提示。
 - 缺少鉴权、租户、操作日志。
 
 ## 8. 建议演进方向
 
 1. 补 RAG 最小检索闭环：解析文本 → 生成切片 → 生成向量 → 检索召回。
-2. 接入 Spring AI，实现最小模型调用链路。
+2. 建设模型服务商配置与路由层，统一接入 Ollama、硅基流动、百炼等 OpenAI-compatible 来源。
 3. 建设 Agent 域模型：Agent、Session、Message、Tool、Task。
 4. 补齐索引任务、重试、重建索引和前端任务视图。
-5. 衔接模型供应商、工作流编排和前端管理台。
+5. 衔接模型供应商、Spring AI 适配层、工作流编排和前端管理台。

docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # Common Agent 开发路线图
 
-本文档基于 2026-05-24 当前分支代码整理，用来区分"已经完成""建议优先做""中期建设项"。
+本文档基于 2026-05-25 当前分支代码整理，用来区分"已经完成""建议优先做""中期建设项"。
 
 ## 已完成
 
@@ -33,7 +33,10 @@
 - `rag_chunk`、`rag_chunk_embedding` 表结构与实体定义。
 - RAG 知识库完整 CRUD（含编码唯一性校验）。
 - 知识文档完整 CRUD、条件查询、批量上传。
-- 文档解析入口：支持批量提交文档 ID，按切片策略参数发起解析，状态流转为 PARSING / PARSED / FAILED。
+- 文档解析入口：支持批量提交文档 ID，状态流转为 PARSING / PARSED / FAILED。
+- 解析快照：解析成功后保存 `rag_document_parse_result`，供后续切片复用。
+- 切片基础能力：已完成 `Chunker`、`ChunkerFactory`、定长切片和分隔符切片。
+- 文档切片入口：支持按切片策略异步生成并替换 `rag_chunk`。
 - 知识库总览接口与单库文档概览接口。
 - RAG 解析状态枚举 `RagParseStatusEnum`（UPLOADED / PARSING / PARSED / FAILED）。
 - RAG 索引状态枚举 `RagIndexStatusEnum`（PENDING / INDEXING / INDEXED / FAILED）。
@@ -46,11 +49,18 @@
 - `AdminLayout.vue` 管理后台布局（侧边栏菜单 + 主内容区）。
 - 系统枚举管理页：完整 CRUD + 批量新增对话框 + 关键词搜索 + 响应式布局。
 - 知识库管理页：完整 CRUD + 概览卡片 + 双栏详情 + 编辑对话框 + 批量上传入口。
-- 知识文档管理页：条件查询 + 批量上传 + 批量解析入口 + 编辑/启停用/删除。
+- 知识文档管理页：条件查询 + 批量上传 + 解析重试 + 批量切片入口 + 编辑/启停用/删除。
+- RAG 工作台与切片任务页：展示文档解析/切片概览并提供切片入口。
 - RAG 文档批量上传组件：支持锁定知识库或选择知识库上传。
 - API 层：Axios 封装 + Long 类型安全解析 + 统一错误拦截。
 - 单元测试：Vitest + @vue/test-utils，覆盖路由、布局、页面和 API。
 
+### 模型平台设计
+
+- 已新增模型服务商配置与路由需求文档：`docs/MODEL_PROVIDER_REQUIREMENTS.md`。
+- 已新增模型服务商配置与路由设计文档：`docs/MODEL_PROVIDER_DESIGN.md`。
+- 已明确后续通过模型网关统一接入 Ollama、硅基流动、百炼等 OpenAI-compatible 来源。
+
 ### 质量保障
 
 - 后端结构稳定性单元测试。
@@ -58,22 +68,22 @@
 
 ## 短期优先级
 
-建议优先完成下面几项，把 RAG 上传解析链路升级为可检索链路：
+建议优先完成下面几项，把 RAG 上传解析切片链路升级为可检索链路：
 
-1. 切片生成服务：把解析服务拿到的 `DocumentParseResult.text` 改造成可持久化的 `rag_chunk` 记录。
+1. 模型服务商配置：新增服务商、模型、路由规则和调用日志基础表。
-2. 按 `RagChunkStrategyEnum` 先落地 `FIXED_LENGTH` 和 `DELIMITER`，再扩展段落/标题/表格/语义切片。
+2. Embedding 网关：优先支持 OpenAI-compatible 接口，接入硅基流动或 Ollama Embedding。
-3. 索引任务入口：把文档或知识库的 `indexStatus` 推进为真实状态流转。
+3. 向量写入：对 `rag_chunk` 调用 Embedding 模型并保存 `rag_chunk_embedding`。
-4. 接入 Spring AI Embedding 模型，生成并保存 `rag_chunk_embedding`。
+4. 索引任务入口：把文档或知识库的 `indexStatus` 推进为真实状态流转。
 5. 补齐重建索引、失败重试、最近任务接口。
-6. 前端接入检索配置、最近任务和重建索引动作。
+6. 前端接入模型配置、检索配置、最近任务和重建索引动作。
 
 ## RAG 最小闭环
 
 当前上传与解析入口已完成，下一步建设最小检索闭环：
 
-1. 批量上传文件，自动创建 `sys_attachment` 与 `rag_document`。
+1. ~~批量上传文件，自动创建 `sys_attachment` 与 `rag_document`。~~
-2. 调用解析入口，使用 Tika 抽取文本并更新 `parseStatus`。
+2. ~~调用解析入口，使用 Tika 抽取文本并更新 `parseStatus`。~~
-3. 根据切片策略生成 `rag_chunk`。
+3. ~~根据切片策略生成 `rag_chunk`。~~
 4. 调用 Embedding 模型生成向量并写入 `rag_chunk_embedding`。
 5. 提供检索接口，按 query 向量召回切片并返回引用元数据。
 
@@ -108,7 +118,8 @@ RAG 数据链路稳定后，再进入 Agent 主线：
 - 枚举查询接口规范：POST `/api/sys-enum/queryForManagement`。
 - RAG 文档状态字段：`parseStatus` + `indexStatus` + `enabled`。
 - RAG 文档批量上传接口：POST `/api/rag/documents/batchUpload`。
-- RAG 文档解析接口：POST `/api/rag/documents/parse`，当前同步解析并返回解析元数据。
+- RAG 文档解析接口：POST `/api/rag/documents/parse`，当前同步解析、保存解析快照并返回解析元数据。
+- RAG 文档切片接口：POST `/api/rag/documents/chunk`，当前异步生成并替换 `rag_chunk`。
 - 大整数 ID 通过 `@JsonSerialize(ToStringSerializer.class)` 输出为字符串。
 
 ## 里程碑
@@ -120,9 +131,9 @@ RAG 数据链路稳定后，再进入 Agent 主线：
 
 ### 里程碑 2：RAG 可演示
 
-- 已完成知识库文档上传、建档、解析状态流转。
+- 已完成知识库文档上传、建档、解析状态流转和手动切片持久化。
-- 下一步完成切片持久化、向量化和检索接口。
+- 下一步完成模型配置、向量化和检索接口。
-- 前端知识库与知识文档页面已接入当前接口，索引任务和检索配置待接入。
+- 前端知识库、知识文档、RAG 工作台和切片任务页面已接入当前接口，索引任务和检索配置待接入。
 
 ### 里程碑 3：Agent 最小运行时
 

rag-store-page-apis.md

@@ -193,10 +193,29 @@
 
 请求体：
 
+```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": "FIXED_LENGTH",
+  "chunkStrategy": 1,
   "chunkSize": 800,
   "chunkOverlap": 120,
   "delimiter": "。"
@@ -205,15 +224,14 @@
 
 当前行为：
 
-- 校验 `chunkStrategy` 是否属于 `RagChunkStrategyEnum`
+- `chunkStrategy` 使用 `RagChunkStrategyEnum` 的整型枚举值，例如 `1` 表示固定长度切片，`5` 表示按分隔符切片。
-- 根据附件后缀或 content type 选择 Tika 解析器
+- 只处理已经存在解析快照的文档。
-- 解析成功后更新 `parseStatus=PARSED`
+- 按策略生成 `rag_chunk`，写入前会替换该文档已有切片。
-- 解析失败后更新 `parseStatus=FAILED` 和 `errorMessage`
+- 当前尚未调用 Embedding 模型写入 `rag_chunk_embedding`。
-- 当前暂不写入 `rag_chunk`
 
 ## 4. 下一批建议补充的接口
 
-当前已有接口能支撑知识库、文档、上传和解析入口。下一批建议聚焦切片、索引和任务化。
+当前已有接口能支撑知识库、文档、上传、解析和手动切片入口。下一批建议聚焦向量索引、模型配置和任务化。
 
 ### 4.1 知识库列表查询增强版
 
@@ -386,8 +404,9 @@
 
 当前知识库页和知识文档页已经接入基础接口。下一步联调顺序建议：
 
-1. 完成切片入库：
+1. 完成向量入库：
-   - `POST /api/rag/documents/parse` 解析后写入 `rag_chunk`
+   - `POST /api/rag/documents/chunk` 生成 `rag_chunk`
+   - 通过模型网关调用 Embedding 并写入 `rag_chunk_embedding`
 
 2. 完成索引入口：
    - `POST /api/rag/documents/index`
@@ -408,10 +427,12 @@
 - 批量上传：`/api/rag/documents/batchUpload`
 - 知识文档列表：`/api/rag/documents/query`
 - 批量解析：`/api/rag/documents/parse`
+- 批量切片：`/api/rag/documents/chunk`
 
 仍待后端补齐后再联调：
 
 - 重建索引
 - 最近任务
+- 模型服务商与 Embedding 模型配置
 - 检索配置
 - 检索测试/召回预览