开篇篇：从0到1搭建企业级 LangChain4j + Spring AI 智能对话与知识库框架（架构与模块总览）
本文介绍了一个企业级AI应用全栈实战项目，重点构建可扩展的智能体底座。项目包含多模型统一、对话系统、知识库检索和MCP工具化等核心模块，满足企业级需求如多模型并存、对话体验优化、知识增强和工具协作。架构采用后端多模块聚合（Maven）+前端多UI设计，主要模块包括多轮对话、模型统一封装、知识库索引管理等。文章还展示了会话自动摘要机制、知识库同步流程和前端交互设计，并介绍了MCP协议在工具集成中的作
系列定位：企业级 AI 应用全栈实战，从“多模型统一 + 对话系统 + 知识库检索 + MCP 工具化”一步步搭建可扩展智能体底座。本篇为开篇介绍与代码结构导览。
1. 为什么再造一个脚手架？
在大模型应用快速迭代的当下，单纯“调用一个 Chat 接口”已经不能满足企业需求：
- 多模型并存：OpenAI 兼容、阿里云百炼、国产模型差异化明显。
- 对话体验：需要多轮上下文、流式输出、历史摘要、成本控制。
- 知识增强：RAG 检索 + 内部知识库同步（结构化 & 文本）。
- 工具协作：Agent 需要安全、可控、标准协议调用外部能力（MCP）。
- 企业治理：权限、审计、日志、指标、合规与可观测是刚需。
langchain4j-spring-agent 目标：成为“企业级智能对话与检索增强的最小可行底座”，让你把精力投入在业务 Prompt 与场景创新上。
2. 整体模块速览
后端多模块聚合（Maven）+ 前端多 UI。核心模块：
| 模块 | 职责 | 关键词 |
|---|---|---|
| chat-v2 | 多轮对话 / SSE / 自动摘要(>16轮触发) | Redis / MyBatis-Plus / 流式 |
| llm-common | 模型统一封装 / 适配层 | Spring AI / LangChain4j / Provider |
| elasticsearch | 知识库索引管理 & 检索 API | ES / 文本索引 / 预留向量 |
| elasticsearch-mcp | 将检索暴露为 MCP Tool | MCP 协议 / Agent 工具化 |
| elasticsearch-common | 公共 DTO & 客户端 | 复用 / 规范化 |
| security-(common | v1) | JWT / 权限演示 |
| logging | 日志埋点 + 收集服务 | 审计 / 可观测预留 |
| ui-chat-v2 | 聊天前端 (模型+MCP 会话配置) | Vue3 / Element Plus |
| ui-v1 | 管理后台基础骨架 | 菜单 / 权限 / 动态路由 |
3. 运行一眼就懂的主类
3.1 会话自动摘要机制
当前已实现“多轮对话上下文自动摘要”逻辑：当同一会话累计消息数（user+assistant）超过 16 轮时触发：
- 取早期历史片段拼接成压缩输入，调用所选模型生成一段 Summary（保留角色/主题/关键上下文）。
- 用摘要替换最早的大段历史，仅保留必要系统提示 + 近期 K 轮原始对话。
- 记录摘要产生时间与原始内容长度（便于后续成本分析与回溯）。
带来收益：
- 控制 Token 成本（上下文膨胀风险降低）。
- 维持语义连续性（保留主题与人物/任务状态）。
- 为 RAG 后续拼接预留更多上下文窗口空间。
后续增强计划：
- 多摘要分层：第一层“主题摘要”+第二层“细节补充”。
- Token 使用统计面板（展示压缩前后差异）。
- 可选关闭 / 不同阈值（配置化：如 12/16/20）。
Chat 服务：
@MapperScan(basePackages = "com.soft.nda.chat.mapper")
@SpringBootApplication(exclude = { SecurityAutoConfiguration.class })
@EnableScheduling
public class ChatV2ServerApplication { ... }
MCP 检索服务：
@SpringBootApplication
public class McpSearchServerApplication { ... }
它们是独立进程，可按需部署或合并。
4. 知识库如何进入 Elasticsearch？
4.1 拆章节写入数据库
测试类 OcrFileInsertTest#testInsertChapters 会读取 ./doc/斗破苍穹.txt，按“第X章”正则切分写入表 aigc_ocr_file。
核心片段：
Pattern chapterPattern = Pattern.compile("^(\\s*(正文|卷)?\\s*)?第([\\u4e00-\\u9fa5]{1,9}|\\d{1,4})章[ ：:，、.．\\s]?.*$");
它支持中文数字、阿拉伯数字、“正文/卷”前缀，适配常见网络小说章节格式。
4.2 从 DB 同步到 ES
两种方式：
- 测试方法
syncToES()（或之前的sync）手动执行。 - 生产：
SyncDocTask（可加 @Scheduled）分页扫描未同步记录（SYNC_BY_ES_STATUS != 2），写入 ES。
任务核心：
queryWrapper.ne("SYNC_BY_ES_STATUS", 2);
fulltextService.addDocument(doc);
ocr.setSyncByEsStatus(2);
失败会回写状态 99，便于重试/告警。
5. 前端：如何发起“模型 + MCP 工具”对话？
ui-chat-v2 设计关注：
- 会话创建时绑定：模型配置 + MCP 服务地址。
- 对话流式渲染：SSE 事件增量刷新。
- 未来接入：RAG 片段高亮 / 工具调用轨迹（Plan → Tool → Final）。
（后续篇章将给出前端交互与接口协议细节）
5.1 可视化步骤（截图演示）
下面通过实际界面，展示“配置模型 → 测试 → 配置 MCP → 建立会话 → 流式对话与记忆”完整链路：
-
创建模型（填写模型名称、Base URL、API Key 等）
-
点击测试按钮，校验模型连通性（成功后提示可用）
-
进入 MCP 配置视图（支持 SSE 与 stdio 两种接入方式总览）
-
stdio 方式参数示例（适合本地可执行工具 / 进程型 Tool Server）
-
SSE 方式参数示例（适合远程部署的轻量服务）
-
测试 MCP 连接并查看返回的 Tool 列表 / 示例响应
-
新增会话时选择“模型 + MCP”组合（为后续对话注入工具上下文）
-
实际对话界面：模型调用 + MCP 工具检索 + 记忆生效（多轮上下文）
提示：会话超过 16 轮后，后端已自动触发摘要，界面仍仅展示近期核心上下文，减少 Token 消耗。
6. MCP 在这里扮演什么角色？
传统 REST + SDK 模式下，Agent 工具集成碎片化、协议不统一。MCP（Model Context Protocol）提供：
- 双向模型上下文交互标准。
- Tool 列表、调用、结果封装统一。
- 更易于在多模型/多供应商之间迁移。
elasticsearch-mcp 将检索包装成 Tool：Agent 能通过统一协议获取文档，再与模型对话融合（典型链：Query → Tool(Search) → Context → LLM 回答）。
6.1 MCP 两种接入模式对比（SSE vs stdio）
| 方式 | 典型场景 | 优点 | 注意事项 |
|---|---|---|---|
| SSE | 远程 HTTP 服务 / 云端工具 | 配置简单，天然支持容器/网关 | 需保证网络稳定与超时控制 |
| stdio | 本地进程型工具 / CLI / 私有脚本 | 低延迟、便于调试 | 进程守护与资源回收需自行处理 |
截图 3/4/5 已演示两种模式的配置界面与差异。
7. 后续会补什么？
| 方向 | 计划 | 价值 |
|---|---|---|
| RAG 向量检索 | 增加 Embedding 写入 & Hybrid 检索 | 更准召回 |
| 会话摘要 | 长上下文压缩 | 降低 Token 成本 |
| 观察性 | 指标 + Trace + 日志关联 | 快速定位问题 |
| Tool 权限 | MCP Tool 频控 / 白名单 | 防滥用 |
| 多租户 | tenantId 透传隔离 | SaaS 化准备 |
8. 如何快速尝鲜？
中间件环境准备
| 组件 | 版本建议 | 获取方式 | 备注 |
|---|---|---|---|
| MySQL | 8.x (>=8.0.28) | 本地/容器自行安装 | 需提前建库并执行对应 init.sql |
| Redis | 6.x / 7.x | 本地/容器 | 用于会话上下文、黑名单等 |
| Elasticsearch | 8.19.4 | 提供 docker-compose | 单节点开发模式，生产请多节点 |
| Kibana | 8.19.4 | docker-compose 伴随启动 | 用于可视化查看索引/调试 |
Elasticsearch + Kibana 一键启动脚本：langchain4j-spring-ai/langchain4j-spring-ai-elasticsearch-common/docker/docker-compose-elasticsearch-8.19.4.yml
启动示例：
cd langchain4j-spring-ai/langchain4j-spring-ai-elasticsearch-common/docker
docker compose -f docker-compose-elasticsearch-8.19.4.yml up -d
# 验证
curl http://localhost:9200
MySQL 不提供内置脚本，请自行安装（Windows / macOS / Linux 任一环境或使用官方容器）：
docker run -d --name mysql8 -e MYSQL_ROOT_PASSWORD=your_pwd -p 3306:3306 mysql:8.0
建库示例：
CREATE DATABASE IF NOT EXISTS langchain4j_ai DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
仓库地址
Gitee：https://gitee.com/zhangjq123/langchain4j-spring-agent.git
git clone https://gitee.com/zhangjq123/langchain4j-spring-agent.git
cd langchain4j-spring-agent
数据库初始化脚本位置
| 模块 | 脚本路径 | 说明 |
|---|---|---|
| chat-v2 | langchain4j-spring-ai/langchain4j-spring-ai-chat-v2/doc/init.sql |
会话/用户/演示表结构（若存在） |
| elasticsearch | langchain4j-spring-ai/langchain4j-spring-ai-elasticsearch/doc/init.sql |
OCR 拆章节数据相关表（如 aigc_ocr_file） |
执行（示例）：
mysql -u root -p < langchain4j-spring-ai/langchain4j-spring-ai-chat-v2/doc/init.sql
mysql -u root -p < langchain4j-spring-ai/langchain4j-spring-ai-elasticsearch/doc/init.sql
后端
mvn -DskipTests clean package
# 运行 chat-v2 / elasticsearch / elasticsearch-mcp
前端
cd langchain4j-spring-ai-ui/langchain4j-spring-ai-ui-chat-v2
pnpm install
pnpm dev
初始化知识库
# 在 elasticsearch 模块执行对应测试 (IDE 内运行 testInsertChapters / syncToES)
9. 你可以这样参与
- ⭐ Star / Fork / Issue 你的需求
- 提交：向量检索实现 / Embedding 接入 / 指标埋点 / Tool 安全策略
- 反馈：模型适配、MCP 行为、RAG 场景想法
详细贡献流程（分支模型、Issue / PR 模板、命名规范、测试要求）请参见仓库根目录文件：代码贡献方式.md。
如果本文对你有帮助，欢迎点赞、收藏、转发，让更多人少踩坑。
（系列同步更新：可关注专栏 “企业级AI实战：LangChain4j+SpringAI”）
更多推荐
19
0- 0
已为社区贡献5条内容
所有评论(0)