# langchain4j-spring-agent

**Repository Path**: zhangjq123/langchain4j-spring-agent

## Basic Information

- **Project Name**: langchain4j-spring-agent
- **Description**: 面向企业级 AI 应用的开源脚手架，集成 Spring AI、LangChain4j、Elasticsearch、MCP 协议等主流技术，支持多模型统一接入、多轮对话、RAG 检索增强、Agent 工具调用、JWT 安全与日志治理，并配套 Vue3 前端套件，适合快速孵化智能助手、知识库、Agent 工作流等场景，持续跟进主流 AI 生态最新版本。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 1
- **Created**: 2025-09-30
- **Last Updated**: 2025-11-19

## Categories & Tags

**Categories**: ai

**Tags**: None

## README

# langchain4j-spring-agent

> 多模型统一接入 · 企业级 Chat/RAG/MCP 工具化脚手架 · 前后端整合示例  
> 一套可用于内部 AI 中台、知识助手、Agent 工作流实验的开源基础工程。

<p align="center">
  <b>Spring Boot 3.5 · Spring AI · LangChain4j · MCP · Elasticsearch · Redis · MyBatis-Plus · JWT · Vue3</b>
</p>

## 🔄 版本策略（Spring AI & LangChain4j）
| 组件 | 当前集成版本 | 上游状态 | 策略 | 升级窗口 |
|------|--------------|----------|------|----------|
| Spring AI | 1.0.1 | 稳定 GA | 跟随次/补丁版本，评估破坏性变更 | 发布后 3~7 天内评估并同步 |
| LangChain4j | 1.6.0 | 最新稳定线 | 优先升级，验证 Chain/Memory/Tool 回归 | 发布当周内 |

说明：
- 本项目将持续跟进 Spring AI 与 LangChain4j 的最新稳定版本，优先保证 API 兼容与核心能力（对话、RAG 预留、Tool 调用）可用。
- 升级流程：依赖差异扫描 (mvn dependency:tree) → 关键用例回归（多轮对话、流式输出、MCP Tool）→ 更新白皮书与 README 版本矩阵。
- 若上游出现破坏性变更，会暂时维持“上一个稳定版本 + 可选分支试用”的策略，并在 README 标记“实验特性”。

关注 LangChain4j & LangChain 最新特性解读与最佳实践，可订阅作者专栏：
> https://blog.csdn.net/jianqiao19931029/category_13056941.html

欢迎通过 Issue 提交：
- “上游已发布新版本 / 建议升级”  
- “升级后某 API/Chain 行为变化”  

## ✨ Core Features 核心特性
- 🤖 多模型统一：Spring AI + LangChain4j 适配（OpenAI 兼容 / 阿里云百炼等）
- 💬 多轮对话：Redis + MySQL 上下文管理，支持流式（SSE）输出
- 📚 RAG / KAG：Elasticsearch 向量 & Graph 增强检索（知识图谱构建、节点/关系抽取、关系可视化、TopN 问答），规划 Hybrid / Re-rank
- 🛠 MCP Tool：检索能力以 MCP 协议暴露，支撑 Agent 工具调用
- 🔐 安全基线：JWT、权限演示（RBAC）、黑名单、统一响应包装
- 📊 日志/审计：Logging SDK + Server，规划接入指标 & Trace
- 🧩 模块化：llm-common / chat / search / security / logging / gateway（预留）
- 🖥 前端套件：多版本聊天 UI、权限后台、日志面板（Vue3 + Element Plus）
- 🧪 Embedding 性能实测：text2vec-base-chinese vs bge-large-zh-v1.5 语义检索速度 & 准确率对比报告
- ⚙️ Xinference 本地多引擎调优：Embedding 模型部署、并发与批量参数调优实践

## 🆕 最近更新 (Latest Updates)
| 日期 | 主题 | 摘要 |
|------|------|------|
| 2025-11-05 | KAG 服务上线 | 引入 Knowledge-Augmented Graph 服务：统一任务面板（文本上传抽取）、分页任务状态 & 实时进度、图谱节点浏览、关系多视图（出边/入边/邻居）、力导向可视化、TopN 问答（QA）与服务元数据（模型/估算规模/版本）。 |
| 2025-10-23 | 语义检索对比实测 | 发布《四大名著》中文语料语义检索深度评测：text2vec-base-chinese 与 bge-large-zh-v1.5 在延迟、召回与准确率上的差异；提供切分策略、评估方法论与调优建议。 |
| 2025-10-22 | Xinference 部署调优文档 | 新增 Xinference 本地运行与多引擎性能调优实战文档：覆盖模型拉取、GPU/CPU 混合、批处理/并发参数、吞吐监控与故障回退策略。 |

提示：详尽测试方法与参数分析请参考各自新增的评测 / 调优文档；README 仅保留摘要。

## 🏗 Repository Layout 仓库结构
```
root
 ├─ langchain4j-spring-ai/            # 后端多模块聚合 (Maven)
 │   ├─ ...-chat-v2                   # Chat 主版本 (SSE + 上下文)
 │   ├─ ...-llm-common                # LLM Provider 抽象
 │   ├─ ...-elasticsearch(-mcp|-common)
 │   ├─ ...-security-(common|v1)      # 安全通用 + 演示实现
 │   ├─ ...-logging                   # logging-sdk + logging-server
 │   └─ ...-gateway (planning)
 ├─ langchain4j-spring-ai-ui/         # 前端多套 UI
 │   ├─ ...-ui-chat-v2                # 新版聊天体验/Markdown
 │   ├─ ...-ui-v1                     # 管理后台+权限示例
 │   └─ ...-ui-logging                # 日志可视化
 ├─ TECH_WHITEPAPER.md                # 综合技术白皮书
 └─ README.md                         # (当前) 引流 & 快速开始
```

## 文档导航
| 文档 | 作用 | 适合读者 |
|------|------|----------|
| `入门篇.md` | 从 0 到 1 的架构/模块导览（章节拆分、MCP 截图、知识库流程） | 初次接触项目 / 想快速理解全貌 |
| `TECH_WHITEPAPER.md` | 深度技术白皮书（架构细节、Roadmap、扩展点、治理） | 需要评估/二次开发 / 架构 & 负责人 |
| `README.md` | 引流 + 快速启动 + 版本策略 + Roadmap 摘要 | 想 5 分钟跑起来的人 |
| `代码贡献方式.md` | 分支模型 / Commit & PR 规范 / 参与路径 | 贡献代码 / 提交 Issue |
| `Xinference本地部署与多引擎性能调优实战.md` | 本地 + 多引擎 embedding 部署、并发批量参数调优、性能监控 | 需要压测 / 优化 embedding 性能的人 |
| `深度实测｜四大名著语义检索对比.md` | 中文长文本检索模型对比（速度、准确率、召回、切分策略） | 关注模型效果选型 / RAG 调优 |

提示：避免文档内容长期分叉，推荐：
- 白皮书作为“权威源”，入门篇偏教学/引导，可精简但不改动规范性描述。
- README 仅保留摘要 & 链接；遇到更新，优先改白皮书/入门篇，再同步 README 要点。
- 后续可新增 `docs/` + mkdocs/vitepress 统一站点（多语言、检索、版本快照）。


## 🚀Quick Start 后端快速启动
```powershell
# 1. 克隆
git clone https://gitee.com/<your-namespace>/langchain4j-spring-agent.git
cd langchain4j-spring-agent/langchain4j-spring-ai

# 2. 启动必需依赖 (本地或容器自行准备)
# MySQL / Redis / Elasticsearch 8.x

# 3. 初始化数据库 (示例 SQL 可在各模块 doc/init.sql 中补充)
# mysql -u root -p < init.sql

# 4. 启动核心服务 (IDE 或命令行)
mvn -DskipTests clean package
# 例如运行 chat-v2 / elasticsearch / elasticsearch-mcp / security-v1 / logging-server

# 5. 访问接口文档
# http://localhost:<port>/doc.html 或 /swagger-ui/index.html
```

### 环境变量示例 (摘取)
| 变量 | 说明 |
|------|------|
| OPENAI_API_KEY | OpenAI 兼容模型 Key |
| DASHSCOPE_API_KEY | 阿里云百炼 Key |
| JWT_SECRET | Token 签名密钥 |
| ES_HOST | Elasticsearch 地址 |
| REDIS_HOST | Redis 地址 |

> 建议使用 `.env` / K8s Secret / Vault 统一管理，不要提交密钥。

## 💻 Frontend 前端启动
```powershell
cd langchain4j-spring-ai-ui/langchain4j-spring-ai-ui-chat-v2
pnpm install
pnpm dev
# 配置 .env: VITE_API_BASE=http://localhost:<chat-port>
```

## 🧬 Architecture 架构总览
```
Client/UI -> Gateway(规划) -> Chat Service -> LLM Common -> (LLM Provider)
                                |-> (RAG: Elasticsearch)
                                |-> (MCP Tool 调用)
Security Filter -> JWT 验证
Logging SDK -> Logging Server -> (集中采集/分析)
```

## 🔌 Extensibility 扩展点
| 类别 | 扩展点 | 说明 |
|------|--------|------|
| LLM | ProviderAdapter | 接入新模型 (流式/非流式) |
| RAG | RetrieverChain | Hybrid / 向量检索实现 |
| Chat | MessageSummarizer | 会话摘要策略 (长上下文压缩) |
| MCP | ToolRegistry | 注册外部系统能力为 Tool |
| 安全 | TenantResolver | 多租户隔离上下文 |
| 日志 | AuditAppender | 推送至外部审计平台 |

## 📅 Roadmap (摘要)
- 短期：会话摘要 / 指标 & Tracing / maven-enforcer / Embedding POC
- 中期：Hybrid+向量检索 / Gateway 限流 / Tool 频控 / 成本统计 / KAG 服务扩展（关系类型过滤、可视化交互增强、图谱增量更新）
- 长期：多租户配额 / Agent 工作流 DSL / 内容审核 & 输出水印

完整版本参见：`TECH_WHITEPAPER.md`

## 🤝 Contribution 贡献指南
1. Fork & 创建分支：`feature/<topic>`  
2. 提交信息规范：`feat: xxx` / `fix: xxx` / `refactor:`  
3. 提交前执行：`mvn -DskipTests=false clean verify` & 前端 `pnpm build`  
4. PR 模板中需包含：变更说明 / 影响范围 / 测试结果截图  

建议新增：单元测试 (service 层)、集成测试 (API 层)、日志与安全影响评估。

## 🛡 License & 使用场景
当前未显式声明 License，准备开源阶段建议采用 Apache-2.0（企业友好，可二次分发）。如内部先行试用，可保留私有协议备注。欢迎在遵循合规的前提下用于：
- 企业内部知识库助手
- ChatOps / 支持工单智能化
- Agent 工具实验平台

## ⭐ Star
如果本项目对你有帮助：
1. Gitee 点 Star & 收藏
2. 分享到你的技术群 / 公众号 / 博客
3. 关注后续 Roadmap，欢迎提交 Issue 与需求
4. 欢迎补充：向量检索 / Tracing / 成本统计 PR

可选推广素材（自行复制）：
> 一个开箱即用的企业级 AI 脚手架：Spring AI + LangChain4j + MCP + RAG 预留 + Vue3 前后端示例，支持多模型、对话上下文、权限与日志治理，适合快速孵化内部智能应用。

## 📞 Contact & Feedback
- Issue：提交问题/需求/优化建议
- PR：欢迎贡献任何改进
- 计划新增讨论区 (Discussions) 用于架构/模型选型交流

---
更多细节请阅读：`TECH_WHITEPAPER.md`

> Together build a pragmatic & extensible AI application foundation.