Files

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

2026-05-31 23:56:31 +08:00

10 KiB

Raw Permalink Blame History

Common Agent

Common Agent 是一个规划中的通用 Agent 平台，技术路线基于 Java、Spring Boot 和 Spring AI。项目目标是建设一套完整的前后端系统，支持 Agent 编排、工具调用、会话管理、RAG 知识库和平台管理能力。

当前项目已经完成基础工程、公共模块、RAG 元数据管理、文档上传、文档解析入口、解析快照、手动切片入口、模型服务商配置基础能力、Agent 定义管理与调试页面。会话持久化、工具调用编排、RAG 全量向量化与检索问答能力会在后续阶段逐步完善。

项目愿景

Common Agent 希望成为一个可复用的企业级 AI 应用基础平台：

Agent 运行时：支持对话、工具调用、记忆、任务执行和流程编排。
RAG 知识库：支持文档导入、解析、切片、向量化、检索和基于上下文的回答生成。
模型抽象：通过 Spring AI 统一接入聊天模型、Embedding 模型和重排序模型。
管理控制台：提供 Agent、知识库、文档、模型配置和系统配置的 Web 管理界面。
多环境部署：支持本地开发、测试环境和生产环境的配置隔离。

当前技术栈

类别	技术
后端	Java 21, Spring Boot 4.0.6, MyBatis-Plus 3.5.16
数据库	PostgreSQL
工具库	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
后端测试	Spring Boot Test

项目结构

common_agent
├── frontend/                          # Vue 3 前端控制台
│   ├── src/
│   │   ├── api/                       # Axios 封装与各模块 API
│   │   ├── layouts/                   # AdminLayout 管理后台布局
│   │   ├── pages/                     # 业务页面（系统、RAG、Agent）
│   │   ├── router/                    # Vue Router 配置
│   │   ├── stores/                    # Pinia 状态管理
│   │   ├── styles/                    # 全局样式
│   │   └── types/                     # TypeScript 类型声明
│   └── package.json
├── src/
│   ├── main/java/com/bruce/
│   │   ├── CommonAgentApplication.java
│   │   ├── common/                    # 公共模块
│   │   │   ├── config/                # AttachmentProperties, EntityAuditMetaObjectHandler
│   │   │   ├── controller/            # SysAttachmentController, SysEnumController
│   │   │   ├── document/parse/        # 文档解析抽象与 Tika 实现
│   │   │   ├── domain/
│   │   │   │   ├── entity/            # SysAttachment, SysEnum
│   │   │   │   └── model/             # BaseEntity, RequestResult
│   │   │   ├── dto/
│   │   │   │   ├── request/           # 各模块请求 DTO
│   │   │   │   └── response/          # 各模块响应 DTO
│   │   │   ├── enums/                 # CommonStatusEnum, EnableStatusEnum
│   │   │   ├── handler/               # GlobalExceptionHandler
│   │   │   ├── mapper/                # SysAttachmentMapper, SysEnumMapper
│   │   │   └── service/               # 接口与实现
│   │   ├── rag/                       # RAG 知识库模块
│   │   │   ├── constant/              # RagSystemConstants
│   │   │   ├── controller/            # RagStoreController, RagDocumentController
│   │   │   ├── dto/                   # 请求/响应 DTO
│   │   │   ├── entity/                # RagStore, RagDocument, RagChunk, RagChunkEmbedding
│   │   │   ├── enums/                 # RagParseStatusEnum, RagIndexStatusEnum, RagChunkStrategyEnum
│   │   │   ├── mapper/                # RagDocumentMapper, RagStoreMapper
│   │   │   └── service/               # 接口与实现
│   │   ├── modelprovider/             # 模型服务商、模型配置、路由、网关与调用日志
│   │   └── agent/                     # Agent 定义管理与调试链路
│   ├── main/resources/
│   │   ├── application.yaml           # 环境选择
│   │   ├── application-dev.yaml       # 开发环境配置
│   │   └── application-template.yaml  # 配置模板
│   └── test/java/                     # 单元测试（结构稳定性测试 + 前端 API 测试）
├── docs/
│   ├── ARCHITECTURE.md                # 架构说明
│   ├── ROADMAP.md                     # 开发路线图
│   ├── MODEL_PROVIDER_REQUIREMENTS.md # 模型服务商配置与路由需求
│   ├── MODEL_PROVIDER_DESIGN.md       # 模型服务商配置与路由设计
│   └── MODEL_PROVIDER_SCHEMA.sql      # 模型平台与Agent核心表结构
├── AGENT.md                           # 平台设计草案
├── agent-page-apis.md                 # Agent页面后端接口清单
├── pom.xml
└── README.md

配置说明

主配置文件只负责选择当前环境：

spring:
  application:
    name: common_agent
  profiles:
    active: dev

本地开发环境配置位于 src/main/resources/application-dev.yaml。当前开发环境数据库指向 PostgreSQL：

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://110.42.106.130:5431/common_agent?currentSchema=common_agent
    username: common_agent
    password: common_agent

src/main/resources/application-template.yaml 是配置模板，可用于复制生成 application-test.yaml、application-prod.yaml 等其他环境配置文件。

运行方式

运行测试：

./mvnw test

启动应用：

./mvnw spring-boot:run

启动前端：

cd frontend
npm install
npm run dev

前端检查：

cd frontend
npm run test:unit
npm run type-check
npm run build

前端控制台

前端控制台位于 frontend 目录，当前使用 Vue 3、Vite、Pinia、Vue Router 和 Element Plus。

当前已有页面：

页面	状态
RAG 工作台	文档解析与切片概览
系统枚举	完整 CRUD + 批量新增
附件管理	占位
知识库	完整 CRUD + 双栏详情
知识文档	条件查询 + 批量上传 + 解析重试 + 批量切片 + 编辑/启停用/删除
切片任务	解析成功/失败文档概览 + 切片入口
Agent管理	Agent 定义 CRUD + 知识库绑定
Agent调试	普通对话 / RAG 对话切换 + 引用切片回显

当前 UI 规范：

左侧为固定管理导航，右侧为主内容区。
主内容区不再额外渲染外层页面标题，标题由各业务页面面板自行展示。
全局样式集中在 frontend/src/styles/global.css，页面专属样式优先放在对应 .vue 文件的 scoped style 中。
后台页面以清晰、克制、便于扫描为优先目标，避免营销式大面积装饰。

接口规范

统一返回体：RequestResult<T>（resultcode, message, data）
所有接口通过 DTO 交互，不直接暴露实体
查询条件封装为 XxxQueryRequest
响应 DTO 提供 fromEntity() 静态转换
大整数 ID 通过 @JsonSerialize(ToStringSerializer.class) 防止前端精度丢失
全局异常处理返回 HTTP 400/500 状态码

RAG 当前能力边界

当前 RAG 已经从元数据管理推进到"上传 + 解析 + 手动切片 + Agent 调试召回"阶段：

知识库：支持列表、条件查询、详情、总览、单库文档概览、新增、编辑、删除。
知识文档：支持列表、条件查询、详情、新增/编辑、删除、批量上传。
文档解析：基于 Apache Tika 支持 TXT/Markdown/LOG、PDF、Word、Excel 文本抽取，解析时更新 parseStatus 并保存解析快照。
文档切片：支持按解析快照进行手动异步切片，已落地定长切片和分隔符切片，写入 rag_chunk。
向量表：rag_chunk_embedding 实体、Mapper、Service 已有结构，向量写入与召回 SQL 已用于 Agent 调试链路，RAG 检索问答接口仍待补齐。
模型配置：模型服务商、模型配置、路由规则、调用日志基础能力已落地，Embedding/Chat 网关可用于 RAG 与 Agent 调试调用。
前端：知识库页、知识文档页、RAG 工作台和切片任务页已经接入当前接口，检索配置、最近任务、重建索引仍是后续能力。

Agent 当前能力边界

Agent 定义：支持 agent_definition 的列表、查询、详情、新增/更新、删除。
Agent 对话：支持 POST /api/agents/{agentId}/chat，ragEnabled=true 时走 RAG 召回，false 时走普通对话。
RAG 对话流程：用户问题向量化 -> 按知识库召回 TopK 切片 -> 组装系统提示词与上下文 -> Chat 模型回答。
调试回显：返回答案、请求 ID 和引用切片，便于前端页面展示与排障。
当前限制：尚未持久化 agent_session/agent_message，工具调用和任务编排仍在规划中。

规划模块

agent-core：Agent 执行模型、工具注册、记忆和编排能力。
rag-core：文档导入、解析、切片、Embedding、检索和引用元数据。
model-provider：模型服务商配置、模型路由、调用日志，以及基于 OpenAI-compatible / Spring AI 的聊天模型、Embedding、重排序适配层。
platform-api：面向前端和外部系统的 REST API。
platform-admin：平台管理前端。
common-infra：持久化、审计日志、安全、租户隔离和可观测性。

10 KiB Raw Permalink Blame History Unescape Escape