feat(modelprovider): 完善模型调用与RAG召回支撑

2026-05-31 23:56:31 +08:00
parent 1e004f1a83
commit ab9b099e9b
9 changed files with 295 additions and 58 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -135,8 +135,50 @@

 - 知识库 CRUD、文档 CRUD、批量上传、Tika 文本解析、解析快照和状态流转已完成。
 - `rag_chunk` 已支持基于解析快照的手动异步切片，当前已落地定长切片和分隔符切片。
- `rag_chunk_embedding` 的结构层已就绪，尚未实现模型调用、向量化、索引任务和检索问答。
- 模型服务商配置与路由已有需求/设计文档，后续会作为 Embedding、Chat 和 Rerank 的统一接入层。
+- `rag_chunk_embedding` 已支持按知识库向量相似度召回 TopK，用于 Agent 调试链路引用回显。
+- RAG 对外检索问答接口、索引任务化和重排序能力仍在后续建设中。
+
+### 3.3 Agent 模块
+
+包路径：`com.bruce.agent`
+
+职责：
+
+- 维护 Agent 定义主数据（CRUD + 编码唯一性 + 绑定知识库校验）。
+- 提供 Agent 调试对话接口，支持普通对话与 RAG 对话模式切换。
+- 在 RAG 对话模式下，完成“问题向量化 -> 切片召回 -> 上下文组装 -> Chat 模型回答”的最小链路。
+- 返回引用切片和请求 ID，便于前端调试与调用追踪。
+
+关键类：
+
+| 类 | 路径 |
+|----|------|
+| AgentDefinition | `agent/entity/AgentDefinition.java` |
+| AgentDefinitionController | `agent/controller/AgentDefinitionController.java` |
+| AgentDefinitionServiceImpl | `agent/service/impl/AgentDefinitionServiceImpl.java` |
+| AgentDefinitionResponse | `agent/dto/response/AgentDefinitionResponse.java` |
+| AgentChatResponse | `agent/dto/response/AgentChatResponse.java` |
+| ChatModelGateway | `modelprovider/gateway/ChatModelGateway.java` |
+| ChatModelGatewayImpl | `modelprovider/gateway/ChatModelGatewayImpl.java` |
+| ChatRequest | `modelprovider/gateway/ChatRequest.java` |
+| ChatResult | `modelprovider/gateway/ChatResult.java` |
+
+接口列表：
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/agents/list` | 查询全部 Agent |
+| POST | `/api/agents/query` | Agent 条件查询 |
+| GET | `/api/agents/detail` | 获取 Agent 详情 |
+| POST | `/api/agents/save` | 新增/更新 Agent |
+| POST | `/api/agents/delete` | 删除 Agent |
+| POST | `/api/agents/{agentId}/chat` | Agent 调试对话 |
+
+当前边界：
+
+- `agent_definition` 与前端 Agent 管理页已完成联调。
+- 对话入口已支持 `ragEnabled` 开关，`true` 走 RAG 召回，`false` 走普通对话。
+- 尚未落地会话持久化（`agent_session` / `agent_message`）和工具调用编排。

 ## 4. 数据模型关系

@@ -150,8 +192,9 @@
 | `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` |
+| `agent_definition` | Agent 定义表 | 关联 `rag_store.id` |

-`rag_document` 是 RAG 模块与附件模块的连接点，`rag_chunk` 和 `rag_chunk_embedding` 是下一步检索链路的核心落点。
+`rag_document` 是 RAG 模块与附件模块的连接点，`rag_chunk` 和 `rag_chunk_embedding` 是检索链路核心落点，`agent_definition` 负责把 Agent 与知识库绑定到同一调用链路。

 ## 5. 配置与运行

@@ -183,16 +226,15 @@

 ## 7. 当前不足

- RAG 尚未进入"可检索链路"，当前完成上传、解析和手动切片，但未完成向量化和召回。
- 模型服务商配置、模型路由和调用日志尚未落地代码。
- Agent 运行时相关模型与服务尚未开始建设。
+- RAG 尚未形成独立检索问答接口，当前召回能力主要用于 Agent 调试链路。
+- Agent 运行时尚未持久化会话，工具调用与任务编排仍未落地。
 - 前端部分页面（附件管理、检索配置、最近任务）为占位或后续能力提示。
 - 缺少鉴权、租户、操作日志。

 ## 8. 建议演进方向

 1. 补 RAG 最小检索闭环：解析文本 → 生成切片 → 生成向量 → 检索召回。
-2. 建设模型服务商配置与路由层，统一接入 Ollama、硅基流动、百炼等 OpenAI-compatible 来源。
-3. 建设 Agent 域模型：Agent、Session、Message、Tool、Task。
+2. 把当前 Agent 调试链路升级为会话化运行：沉淀 Session、Message 和上下文裁剪策略。
+3. 建设 Agent 工具注册与调用协议，补齐任务状态与执行日志。
 4. 补齐索引任务、重试、重建索引和前端任务视图。
 5. 衔接模型供应商、Spring AI 适配层、工作流编排和前端管理台。
--- a/docs/MODEL_PROVIDER_SCHEMA.sql
+++ b/docs/MODEL_PROVIDER_SCHEMA.sql
@@ -94,6 +94,23 @@ CREATE TABLE IF NOT EXISTS rag_store_model_config (
    CONSTRAINT fk_rag_store_model_config_embedding_model_id FOREIGN KEY (embedding_model_id) REFERENCES model_config (id)
 );

+CREATE TABLE IF NOT EXISTS agent_definition (
+    id BIGSERIAL PRIMARY KEY,
+    agent_code VARCHAR(100) NOT NULL,
+    agent_name VARCHAR(200) NOT NULL,
+    system_prompt TEXT,
+    store_id BIGINT NOT NULL,
+    status VARCHAR(50) NOT NULL DEFAULT 'ENABLED',
+    version INTEGER NOT NULL DEFAULT 1,
+    create_time TIMESTAMP,
+    update_time TIMESTAMP,
+    remark VARCHAR(500) DEFAULT '',
+    create_by VARCHAR(64),
+    update_by VARCHAR(64),
+    CONSTRAINT uk_agent_definition_code UNIQUE (agent_code),
+    CONSTRAINT fk_agent_definition_store_id FOREIGN KEY (store_id) REFERENCES rag_store (id)
+);
+
 CREATE TABLE IF NOT EXISTS model_call_log (
    id BIGSERIAL PRIMARY KEY,
    request_id VARCHAR(64) NOT NULL,
@@ -112,8 +129,12 @@ CREATE TABLE IF NOT EXISTS model_call_log (
    request_hash VARCHAR(64),
    error_code VARCHAR(100),
    error_message VARCHAR(1000),
+    version INTEGER NOT NULL DEFAULT 1,
    create_time TIMESTAMP,
+    update_time TIMESTAMP,
    remark VARCHAR(500) DEFAULT '',
+    create_by VARCHAR(64),
+    update_by VARCHAR(64),
    CONSTRAINT uk_model_call_log_request_id UNIQUE (request_id)
 );

@@ -200,6 +221,20 @@ COMMENT ON COLUMN rag_store_model_config.remark IS '备注';
 COMMENT ON COLUMN rag_store_model_config.create_by IS '创建者';
 COMMENT ON COLUMN rag_store_model_config.update_by IS '更新者';

+COMMENT ON TABLE agent_definition IS 'Agent定义表';
+COMMENT ON COLUMN agent_definition.id IS 'ID';
+COMMENT ON COLUMN agent_definition.agent_code IS 'Agent编码';
+COMMENT ON COLUMN agent_definition.agent_name IS 'Agent名称';
+COMMENT ON COLUMN agent_definition.system_prompt IS '系统提示词';
+COMMENT ON COLUMN agent_definition.store_id IS '绑定知识库ID';
+COMMENT ON COLUMN agent_definition.status IS '状态';
+COMMENT ON COLUMN agent_definition.version IS '版本';
+COMMENT ON COLUMN agent_definition.create_time IS '创建时间';
+COMMENT ON COLUMN agent_definition.update_time IS '更新时间';
+COMMENT ON COLUMN agent_definition.remark IS '备注';
+COMMENT ON COLUMN agent_definition.create_by IS '创建者';
+COMMENT ON COLUMN agent_definition.update_by IS '更新者';
+
 COMMENT ON TABLE model_call_log IS '模型调用日志表';
 COMMENT ON COLUMN model_call_log.id IS 'ID';
 COMMENT ON COLUMN model_call_log.request_id IS '请求唯一ID';
@@ -218,5 +253,9 @@ COMMENT ON COLUMN model_call_log.duration_ms IS '耗时(毫秒)';
 COMMENT ON COLUMN model_call_log.request_hash IS '请求哈希';
 COMMENT ON COLUMN model_call_log.error_code IS '错误码';
 COMMENT ON COLUMN model_call_log.error_message IS '错误信息摘要';
+COMMENT ON COLUMN model_call_log.version IS '版本';
 COMMENT ON COLUMN model_call_log.create_time IS '创建时间';
+COMMENT ON COLUMN model_call_log.update_time IS '更新时间';
 COMMENT ON COLUMN model_call_log.remark IS '备注';
+COMMENT ON COLUMN model_call_log.create_by IS '创建者';
+COMMENT ON COLUMN model_call_log.update_by IS '更新者';
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -1,6 +1,6 @@
 # Common Agent 开发路线图

-本文档基于 2026-05-25 当前分支代码整理，用来区分"已经完成""建议优先做""中期建设项"。
+本文档基于 2026-05-27 当前分支代码整理，用来区分"已经完成""建议优先做""中期建设项"。

 ## 已完成

@@ -52,30 +52,34 @@
 - 知识文档管理页：条件查询 + 批量上传 + 解析重试 + 批量切片入口 + 编辑/启停用/删除。
 - RAG 工作台与切片任务页：展示文档解析/切片概览并提供切片入口。
 - RAG 文档批量上传组件：支持锁定知识库或选择知识库上传。
+- Agent 管理页：支持 Agent 定义新增、编辑、删除、状态管理和知识库绑定。
+- Agent 调试页：支持普通对话 / RAG 对话切换、请求 ID 与引用切片回显。
 - API 层：Axios 封装 + Long 类型安全解析 + 统一错误拦截。
 - 单元测试：Vitest + @vue/test-utils，覆盖路由、布局、页面和 API。

-### 模型平台设计
+### 模型平台与 Agent 最小链路

- 已新增模型服务商配置与路由需求文档：`docs/MODEL_PROVIDER_REQUIREMENTS.md`。
- 已新增模型服务商配置与路由设计文档：`docs/MODEL_PROVIDER_DESIGN.md`。
- 已明确后续通过模型网关统一接入 Ollama、硅基流动、百炼等 OpenAI-compatible 来源。
+- 模型服务商、模型配置、路由规则、知识库模型绑定、调用日志核心表结构已落地（`docs/MODEL_PROVIDER_SCHEMA.sql`）。
+- `EmbeddingModelGateway` 和 `ChatModelGateway` 已落地，统一走 OpenAI-compatible 协议调用上游模型。
+- `AgentDefinitionController` 与 `AgentDefinitionServiceImpl` 已提供 Agent CRUD 与调试对话接口。
+- Agent 调试链路已接入：问题向量化 -> `rag_chunk_embedding` 召回 -> 组装上下文 -> Chat 回答 -> 返回引用切片。

 ### 质量保障

 - 后端结构稳定性单元测试。
 - 前端组件与 API 单元测试。
+- Agent 结构与服务单元测试（`AgentComponentStructureTests`、`AgentDefinitionServiceImplTests`）。

 ## 短期优先级

 建议优先完成下面几项，把 RAG 上传解析切片链路升级为可检索链路：

-1. 模型服务商配置：新增服务商、模型、路由规则和调用日志基础表。
-2. Embedding 网关：优先支持 OpenAI-compatible 接口，接入硅基流动或 Ollama Embedding。
-3. 向量写入：对 `rag_chunk` 调用 Embedding 模型并保存 `rag_chunk_embedding`。
-4. 索引任务入口：把文档或知识库的 `indexStatus` 推进为真实状态流转。
-5. 补齐重建索引、失败重试、最近任务接口。
-6. 前端接入模型配置、检索配置、最近任务和重建索引动作。
+1. 打通文档切片后的全量向量写入，确保 `rag_chunk_embedding` 可持续更新。
+2. 新增独立 RAG 检索问答接口，避免仅依赖 Agent 调试入口消费召回能力。
+3. 索引任务入口：把文档或知识库的 `indexStatus` 推进为真实状态流转。
+4. 补齐重建索引、失败重试、最近任务接口。
+5. 落地 Agent 会话持久化（`agent_session`、`agent_message`）与多轮上下文管理。
+6. 补齐 Agent 工具注册、工具调用协议和任务执行日志。

 ## RAG 最小闭环

@@ -84,14 +88,14 @@
 1. ~~批量上传文件，自动创建 `sys_attachment` 与 `rag_document`。~~
 2. ~~调用解析入口，使用 Tika 抽取文本并更新 `parseStatus`。~~
 3. ~~根据切片策略生成 `rag_chunk`。~~
-4. 调用 Embedding 模型生成向量并写入 `rag_chunk_embedding`。
-5. 提供检索接口，按 query 向量召回切片并返回引用元数据。
+4. 调用 Embedding 模型生成向量并写入 `rag_chunk_embedding`（已被 Agent 调试链路消费）。
+5. 提供独立检索接口，按 query 向量召回切片并返回引用元数据。

 ## Agent 核心能力

-RAG 数据链路稳定后，再进入 Agent 主线：
+Agent 主线能力按以下顺序继续推进：

-1. Agent 定义管理。
+1. ~~Agent 定义管理。~~
 2. 会话与消息模型。
 3. 工具注册与工具调用协议。
 4. Prompt 模板管理。
@@ -120,6 +124,8 @@ RAG 数据链路稳定后，再进入 Agent 主线：
 - RAG 文档批量上传接口：POST `/api/rag/documents/batchUpload`。
 - RAG 文档解析接口：POST `/api/rag/documents/parse`，当前同步解析、保存解析快照并返回解析元数据。
 - RAG 文档切片接口：POST `/api/rag/documents/chunk`，当前异步生成并替换 `rag_chunk`。
+- Agent 管理接口：`/api/agents/list`、`/api/agents/query`、`/api/agents/detail`、`/api/agents/save`、`/api/agents/delete`。
+- Agent 调试接口：POST `/api/agents/{agentId}/chat`，支持 `ragEnabled` 开关。
 - 大整数 ID 通过 `@JsonSerialize(ToStringSerializer.class)` 输出为字符串。

 ## 里程碑
@@ -137,7 +143,8 @@ RAG 数据链路稳定后，再进入 Agent 主线：

 ### 里程碑 3：Agent 最小运行时

- 支持一个可配置 Agent、一个会话、一次模型调用、一次工具调用。
+- 已完成：支持一个可配置 Agent、一次模型调用与 RAG 召回调试链路。
+- 待完成：会话持久化、工具调用与任务编排。

 ### 里程碑 4：平台管理化