当前位置：首页 > news >正文

基于Spring AI的RAG和智能体应用实践

news 2025/11/16 6:39:09

利用现有的云端或自部署大模型，配合AI应用框架，我们能快速搭建属于自己的企业级AI应用，JAVA应用体系中，Spring AI和LangChain4j都是目前较为成熟的框架方案。

在这些封装级框架基础上，如何实践，如何搭架适合业务需求的AI应用级框架，是每一个企业或业务总线会考虑的问题。本文将以Spring AI为基础，搭建一套简单的可按需拓展的AI助手为例展开实践描述。

注：本实践基于能源管理运营行业，AI定位趋向于为客服AI助手，涉及内容仅基础应用实现和接口参考，无关具体业务和更详细的架构描述；本文实践的"智能体"更准确描述应为简版工作流。

github开源工程：https://github.com/endcy/base-ai-assistant

基于spring-boot、spring-ai、spring-ai-alibaba实现的RAG、MCP、Agent智能体基础服务框架应用；智能客服、智能运维、智能助手、简单工作流/垂直领域智能体的基础应用架构版本，按需拓展。

基础界面&API示例

注：接口随项目需求自定义实现，当前部分接口仅供测试验证参考。

管理和API演示界面(部分接口应用)

文档内容管理

接口调用

注：上述页面为静态html文件，由AI生成。

应用背景

在具备一定业务量的平台系统中，无论是客户对接还是普通用户服务（下文统称用户），客服功能/模块必不可缺，基于普通的QA文档点选、对外电话客服、在线服务号沟通，甚至是工单系统，可能没办法统一精准、及时解决各类问题，服务大打折扣。在更大体量的平台应用中，用户可能提出更加专业，甚至是具有一定分析工作量的问题，很显然普通的客服手段，解决问题能力似乎捉襟见肘或者需加大真实人力投入，成本提升明显。

拥有一款智能的客服，能显著降低运营成本，提高系统服务对接吞吐量，让产品到运营整体周期闭环，更重要的是拥有AI赋能，拓展价值无限可能，可显著提高产品市场竞争力。

客服类型	用户友善度	执行效率	解决问题范围	使用维护成本
电话客服	不够友善且难等待	视人工专业情况	所有问题	无
文档点选	十分不友善	效率较高但效果差	仅支持常见问题记录	低
异步工单/社交渠道客服	十分不友善	效率极低	所有问题	高
在线人工客服	简洁友善	视人工专业情况	所有问题	中
AI客服	简洁友善	效率较高	所有问题（视文档维护积累量）	前期高后期低

基础需求分析

用户基础QA问
客户增量文档维护和检
用户实时信息查
运维信息分
特定场景的数据决策

基础版本功能

基础对话
DeepSeek在线搜索对话
本地模型调用
在线AI应用调用
在线LLM调用
在线知识库检索增强
本地文档检索增强
数据库文档检索增强
数据库文档管理
mcp验证
工具链验证

系统总体设计

总体流程设计

用户提问到输出回答内容，中间涉及意图分析、MCP数据补充、RAG检索增强、提示词工程、大模型调用输出等，完整流程图如下。

MCP应用适合于RAG之外的数据增强，作为AI与外部系统的"通用接口"，实现工具标准化调用，定义MCP功能可以包含例如用户需要获取天气数据、获取节假日信息等等功能，也可用于类似做数据预测前的条件数据查询，如目标温度湿度等时序数据、电网定价信息等等。

MCP和Tools的关系：

MCP是一种标准化的通信协议，Spring AI通过McpSyncToolCallbackProvider等实现类将MCP协议的工具映射为ToolCallback接口的实现。
Tools是调用工具的定义，无论底层使用什么协议（MCP、Function Calling等），由LLM意图识别之后框架自动选择调用。

Tools及MCP定义的要点

清晰的工具描述：@Tool和 @ToolParam的 description务必准确、清晰，这是大模型判断是否调用和如何填参的主要依据。
严格的参数模式：正确定义工具的输入参数以生成框架可读 JSON Schema，确保大模型能生成格式正确的参数。
合理的工具设计：每个工具应功能单一且明确，避免过于复杂的功能，这有助于大模型做出更精准的决策。

数据架构设计

数据库文档管理使用的数据库可选，这里使用其他工程已用的MYSQL作为内容管理库，PGSQL作为文档向量库，其中文档支持本地md文档，自定义拓展也可支持其他格式文档。

工程中数据库支持多数据源。

上述数据云文档为在线文档库的数据管理。实际使用过程中，localVectorStore和pgVectorStore文档向量数据，可能和cloudVectorStore（云知识库）数据存在冲突，为避免维护困难，工程中通过开关实现分开验证。

程序架构设计

本项目采用Spring Boot + Spring AI为基础底座，微服务应用的形式管理，支持水平扩容。

注册中心采用Nacos/阿里云MSE；
配置中心采用Apollo，可自定义按需变更为Nacos；
任务调度中心框架xxl-job；
mysql/pgsql多数据源支持；
微服务调用框架支持Dubbo、Feign；
微服务熔断工具支持resilience4j。

程序架构设计图如下：

RAG检索增强设计

为啥不用类似Dify、RagFlow、Anything-LLM等本地RAG知识文档库的LLM工具？

变化不频繁的文档或特定文档如单纯运维工具文档，适合使用上述框架RAG工具，但无论他们解析结构化还是非结构化文档，本质上都是解析内容后加入向量库，但文档维护无法做到saas一样灵活，且针对线上应用，理论上格式没那么多遍，使用内容管理而不是一股脑上传文档的维护效果更好，就可预见的功能需求而言，Spring AI + DB可用性更高，更契合需求要求。

参考"数据架构设计"，Rag文档来源支持多样化，云知识库文档由云服务自动解析加载向量，这里仅讨论本地文档和知识管理数据库的文档RAG流程。

文档分割器

定义DocumentTokenTextSplitter初始化文档分割器，分为三种选型实现，本工程使用自定义优化实现。

基于固定token范围的TokenTextSplitter分割器，指定token上下浮动分片，英文的文档效果好点，中文文档基本有效；
基于语义断句的SentenceSplitter分割器，效果不佳，基于格式严格的英文的文档效果好点，中文文档可用性大打折扣；
自定义实现ChineseEnhancedTextSplitter分割器，优化TokenTextSplitter的实现，主要优化标点符号分隔(CHINESE_SEPARATORS参数按需更新)，支持中文更加友好。

文档向量库

pg向量库PgVectorStore，存储管理后端维护的知识库文档表文档向量数据；
内存向量库SimpleVectorStore，存储指定路径分类或指定resources目录的本地文档向量；
云文档检索库DashScopeDocumentRetriever，针对云文档库文档检索，向量由云文档应用管理；

查询改写

查询改写即优化查询的表达形式，提升检索效果，能一定程度提高当前查询的检索召回率和精度，本工程使用QueryTransformer配合ChatModel，定义QueryRewriter，将用户问题文本变更为更易查询的RAG目标参数文本。

文档召回配置

配置ai.rag相关参数，实现自定义配置类ChatRagProperties，设定rag参数，默认向量相似度0.6，召回数为3；

自定义多条件Filter.Expression生成工具，支持多条件的元数据查询。

架构LLM工具选型

大模型

dashscope大模型

支持定义阿里百炼平台云端模型，可按需更新为其他平台，模型暂选定qwen3-max，按需更新。

模型token量暂无监控，由运维跟踪。

ollama本地模型

按需部署需要的模型，验证阶段使用qwen3:8b，本地运行因为涉及硬件配置的考虑，可按需更新。线上基于线上ollama的运行环境，如需要独立部署大模型，可租赁GPU资源，参考阿里团队建议，生产使用部署最少需32b参数及以上的模型。

模型微调

在用户问题的意图识别，以及其他分类时，微调模型更加精准和高效，不浪费云端模型token，最重要的是垂直领域做简单分类正是微调模型的强项。针对本地的qwen3模型，适当做微调处理，微调方案按需选择，如阿里百炼微调、LLaMA-Factory、ModelScope(swift)等等，一般租借云显卡和环境进行微调。

微调模型语料可参考各开源datasets，根据格式将内容更新为自己的语料库，语料收集较为繁杂，但是微调必不可少的前期步骤。

语料数据集是关键！！！语料数据集是关键！！！语料数据集是关键！！！

使用阿里百炼在线微调

参考阿里云模型调优操作

使用Swift或其他平台微调

swift或其他微调平台微调，自行参考，过程存在一定难度但作为生产级应用很有必要，本文不做具体操作描述。

工具链工具库

AI工作流的执行包含了N个工具的串行或并行任务，大模型根据工具获取到的结果，执行后续操作，最终得到结果。优秀的工具库工具，是智能的前提，可使用MCP协议工具或本地工具，其中MCP包含网络发布的MCP或者自定义的MCP工具。

本工程验证实现的工具参考如下列表，建议按需直接复用网络上其他开发者写好和实践过的工具，进一步减少重复造轮子。

网页抓取工具
关键词在线搜索工具
文件读写操作工具
DeepSeek在线搜索工具
……

MCP框架选择

这里指的是，业务应用服务暴露mcp端点给本AI应用，前者开发mcp服务应该用到的框架。市场上存在两个java较为常用的 mcp-server 应用开发框架（ID类，封装后体验都比较简洁）：

spring-ai-mcp，支持 java17 或以上
solon-ai-mcp，支持 java8 或以上（也支持集成到 springboot2, jfinal, vert.x 等第三方框架）

比较	srping-ai-mcp	solon-ai-mcp
开发	基于组件开发	基于组件开发
配置	通过 yaml 配置	组件，即是配置（也可引用 yaml 配置）
发布	通过配置器发布为 ToolCallbackProvider	组件，即是发布
jdk要求	jdk17或以上	jdk8或以上
端点支持	WebFlux支持多端点；普通MVC单端点	支持多端点（一个服务内）

solon-ai-mcp的开发相对更简洁，三位一体且支持多端点。业务服务集群创建mcp服务时，应根据jdk版本或具体服务容器进行选择。

MCP开发特别注意事项

参考github描述

远程MCP开发流程

参考github描述

数据结构设计

知识文档数据

云文档知识库

使用ModeScope的应用加载和检索文档，即线上RAG应用，支持配置模型、元数据配置、文档分割方式等等配置，文档库需专人将知识内容文件化并手动上传和维护文档。

本工程使用Alibaba Spring Ai作为基础框架，所以默认支持阿里云百炼平台知识库应用。

本地知识库文档

本地也支持类似dify等rag框架的本地文档管理，实现了工程resources源文件的文档库、指定目录的文档库等实现。但局限于文档文件管理的复杂性，以及本系统无需支持过多的文档格式，所以该文档库方式也仅作为参考实现。

数据库知识文档

区别于云知识库以及本地各类格式文件的知识库文档，数据库知识文档数据是文件数据数据库存储的一种形式，更为方便管理，也便于展示和实时维护。前端定义支持图文的文档编辑器，将内容存储到后端对应数据表，数据表的每一行数据则对应一份文档。

该表信息属性中，内容的属性为 content ，文本内容描述，例如某个菜单页面操作指南、某个设计文档全内容或某个章节、某个业务数据信息描述(例如XXX站点信息)等等。

作为元数据的属性包含：id、scope_type、business_type、group_id、source_type、source_path等，作为元数据过滤或者补充信息展示等。

知识库文档表：ai_knowledge_document

列名	注释	数据类型	非空	自增
id	自增主键	bigint	TRUE	TRUE
scope_type	知识领域类型	varchar(255)	TRUE	FALSE
business_type	业务领域类型	varchar(255)	TRUE	FALSE
title	内容标题	varchar(255)	TRUE	FALSE
group_id	内容分组id，如租户id	bigint	FALSE	FALSE
content	精细化文档内容(Markdown/纯文本)	longtext	TRUE	FALSE
source_type	来源类型(1-文档 2-数据库 3-api 0-未知)	varchar(255)	TRUE	FALSE
source_path	文件路径或API地址	varchar(512)	FALSE	FALSE
doc_version	文档版本号	int	FALSE	FALSE
enable_public	是否公开	tinyint(1)	FALSE	FALSE
loaded	是否已加载到向量库	tinyint(1)	FALSE	FALSE
enabled	是否可用	tinyint(1)	FALSE	FALSE
expired_time	过期时间	datetime	FALSE	FALSE
create_user	创建人	bigint	FALSE	FALSE
create_time	创建时间	datetime	FALSE	FALSE
update_user	更新人	bigint	FALSE	FALSE
update_time	更新时间	datetime	FALSE	FALSE

可按需拓展数据库知识文档属性，或新增其他知识库文档表。

对话内容数据

针对用户会话数据的存储，工程应该将用户对话持久化到文档或者数据表中。这里仅描述存储到数据库的对话信息实现的数据格式。由于上下文相关内容存储会十分冗余，所以不考虑存储rag检索的关联文档内容以及用户上下文信息。

用户对话记录表：ai_context_user_record

列名	注释	数据类型	非空	自增
id	主键	bigint	TRUE	TRUE
chat_id	对话id	bigint	TRUE	FALSE
user_id	知识领域类型	bigint	FALSE	FALSE
user_type	1普通用户 2客户租户	tinyint(1)	FALSE	FALSE
group_id	用户分组id，如租户id	bigint	FALSE	FALSE
scope_type	知识领域类型	varchar(255)	FALSE	FALSE
business_type	业务领域类型，意图分类	varchar(255)	FALSE	FALSE
question	用户对话问题	longtext	TRUE	FALSE
content	用户对话输出结果	longtext	FALSE	FALSE
enabled	是否展示	tinyint(1)	FALSE	FALSE
create_time	创建时间	datetime	FALSE	FALSE
update_time	更新时间	datetime	FALSE	FALSE

向量存储

知识文档向量化存储，用于用户问题使用文本向量相似度检索知识文档关联性查询，本工程使用本地结构或者pgsql向量库实现，向量库建表时使用通用的向量数据表结构，Spring AI或其他框架默认定义方式，仅元数据根据平台业务设计差异化区分。

一份文件知识文档、知识数据表行数据通过内容分割后，可对应多份向量数据。

列名	数据类型	非空	默认值	注释
id	uuid	TRUE	uuid_generate_v4()
content	text	TRUE	[NULL]	原始文本内容
metadata	json	TRUE	[NULL]	元数据
embedding	public.vector	TRUE	[NULL]	1024维向量