这次我们来看一条 Java 生态做 LLM 应用开发的完整技术路线Spring AI 2.0 Langchain4j Tools RAG Agent。它不是某个一键启动的开源小工具而是一整套从模型接入、工具调用、知识库检索到智能体编排的落地组合方式。Java 后端开发者在 2026 年面对大模型应用时常见的场景是Python 生态的资料看得很多真正要接进 Spring Boot 系统里却不知道从哪一步开始。这套技术栈恰好补上这段路让 Java 服务可以像写普通接口一样去调用大模型、做多轮对话、绑定外部工具、构建私有知识库问答以及编排自主 Agent。值得先说清楚的是这条路线不是“Python 能做、Java 不能做”的替代方案而是把 Java 工程化能力用在大模型应用上。Spring AI 2.0 负责模型接入和标准化接口Langchain4j 负责把文档加载、切分、向量检索、提示词模板、工具调用和 Agent 循环串起来。两者叠加后可以做到用 Spring Boot 的 Controller 直接暴露对话接口。用Tool注解让模型调用 Java 方法例如查订单、查库存、调天气。把企业内部的 PDF、Word、Markdown 转成 embedding 存进向量库实现私域 RAG 问答。把“用户问题 - 检索 - 工具调用 - 多步生成”的 Agent 流程稳定落地。本文会围绕这套技术栈完整讲一遍环境准备、依赖配置、启动方式、功能验证、API 调用、批量任务、性能观察和常见排错。没有具体版本号的参数不会硬写因为 Spring AI 2.0 和 Langchain4j 的迭代节奏较快实际使用时要优先参考官方最新版本和本机环境。文章适合三类读者想用 Java 做 AI 应用的 Spring Boot 工程师需要给团队内部搭建知识库问答系统的后端开发者以及准备把大模型能力接进现有业务系统的架构师。1. 核心能力速览能力项说明技术栈Spring AI 2.0、Langchain4j、Spring Boot、Tools、RAG、Agent核心用途Java 后端接入大模型实现对话、工具调用、私域知识库问答、Agent 编排模型接入方式支持 OpenAI 兼容接口也可通过 Ollama、llama.cpp 等接入本地模型本地部署门槛可用远端 API完全本地化需要 CPU/GPU 推理服务显存需求以所选模型为准主要功能基础对话、函数调用、文档加载、向量检索、RAG 问答、Agent 多步任务支持平台只要 Java 环境能跑通的系统均可Windows、Linux、macOS 都适用启动方式Spring Boot 应用启动配合 Maven 依赖管理是否支持 API支持Spring Boot 天然提供 REST 接口是否支持批量任务支持但需要自己在应用层做队列和重试适合场景企业内部知识库、客服问答、报表生成、工具调用助手、RAG 应用、Agent 原型不适合场景纯模型训练、零代码快速搭建、非 Java 技术栈团队需要说明本文不是某个开源软件的一键包而是一套技术组合。读者最终得到的不是“一个可执行文件”而是一个可以放在自己业务工程里的 Spring Boot 项目。2. 适用场景与使用边界这套技术栈最适合的场景是“已有 Java 后端想把大模型能力并进去”。例如公司内部有一个订单系统用户提问“帮我查一下最近一周的售后单状态”Agent 可以拆解意图调用订单查询工具再结合搜索结果生成回复。再比如医院、金融、制造等行业有大量私有文档不能直接发给公网模型就可以用 RAG 流程把文档向量化之后做限定范围的问答。它并不适合那些“想快速做一个聊天机器人 demo”的团队。如果核心诉求是可视化编排、低代码搭建Dify 或同类平台可能更快如果核心团队是 Python 背景LangChain 和 FastAPI 仍然是更顺手的路径。Java 这条线的核心优势是工程化稳定、现有代码复用率高、能直接复用公司内部的微服务体系和权限模型。使用边界必须讲清楚。RAG 会加载文档、切分内容、生成向量并存储这意味着如果文档包含客户隐私、商业机密、未公开数据首先要确认是否有权使用这些数据再考虑是否用本地模型部署。Tools 会让大模型调用 Java 方法本质上是把外部系统操作权交给模型因此必须对工具做权限隔离加上参数校验、用户身份透传和操作审计。Agent 的多次工具调用可能产生不可预料的副作用例如删除数据、提交订单、发送消息测试环境验证是第一步生产环境要限制工具范围并设置最大迭代次数。涉及人脸、声音、版权素材的场景必须单独确认授权链路。3. 环境准备与前置条件在实际写代码之前先把环境检查一遍。Spring AI 2.0 和 Langchain4j 都要求 JDK 17 及以上推荐直接使用 JDK 21 长期支持版本。构建工具使用 Maven 3.8 或 Gradle 7.6。Spring Boot 版本建议选择 3.2 或更高版本具体看当前 Starter 的兼容矩阵。除了 Java 环境还需要一个大模型服务。两种常见选择远端 API使用 OpenAI 兼容接口只需要配置base-url、api-key、model-name。本地模型推理使用 Ollama 或 llama.cpp 加载 Qwen 等开源模型然后让 Spring AI 通过 OpenAI 兼容接口或本地 HTTP 接口访问。如果做 RAG还需要一个向量数据库。常用方案是 Milvus也可以用 Qdrant、PGVector、Redis Stack。选择依据是团队运维能力和数据量。Milvus 适合生产级大规模检索PGVector 适合复用 PostgreSQL 实例Redis Stack 适合轻量缓存级场景。磁盘空间取决于模型和向量数据大小。纯 API 模式基本不占本地模型空间本地模型模式至少要预留模型文件大小两倍以上的空间。建议至少准备 10GB 可用磁盘。端口方面Spring Boot 默认 8080Ollama 默认 11435Milvus 默认 19530启动前先确认端口不冲突。4. 依赖配置与快速启动先创建一个 Spring Boot 工程在pom.xml中加入核心依赖。以下代码是通用模板具体版本号需要到 Maven Central 或 Spring 官方 BOM 中查最新版本。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.3.5/version relativePath/ /parent properties java.version21/java.version spring-ai.version2.0.0/spring-ai.version langchain4j.version1.0.0/langchain4j.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI 模型接入 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId version${spring-ai.version}/version /dependency !-- Spring AI 向量库支持 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-vector-store-milvus/artifactId version${spring-ai.version}/version /dependency !-- Langchain4j Spring Boot Starter -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version${langchain4j.version}/version /dependency !-- 文档解析与切分 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency /dependencies如果使用本地 Ollama可以把 Spring AI 的模型接入改成 Ollama Starterdependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-ollama/artifactId version${spring-ai.version}/version /dependency然后在application.yml里配置模型和向量库。spring: application: name: spring-ai-demo ai: openai: base-url: http://localhost:11434/v1 api-key: local-ollama chat: options: model: qwen2.5:7b embedding: options: model: bge-m3 vectorstore: milvus: client: host: localhost port: 19530 database: default collection: java_rag_demo embedding-dimension: 1024 index-type: AUTOINDEX metric-type: COSINE server: port: 8080上面配置里用了 Ollama 本地服务作为 OpenAI 兼容接口因此api-key填local-ollama即可。如果没有本地模型直接把base-url和api-key换成真实服务地址。embedding-dimension必须和模型输出的向量维度一致例如 bge-m3 通常是 1024 维具体以模型文档为准。启动方式很简单mvn clean spring-boot:run或在工程目录下执行mvn package -DskipTests java -jar target/spring-ai-demo-0.0.1-SNAPSHOT.jar启动后访问http://localhost:8080如果配置了 Spring Boot Actuator可先看健康检查是否通过。后面的测试接口都需要在这个服务运行状态下进行。5. 功能测试与效果验证5.1 基础对话测试先写一个最简单的 ChatModel 调用接口用来验证模型接入是否通。RestController RequestMapping(/api/chat) public class ChatController { private final ChatModel chatModel; public ChatController(ChatModel chatModel) { this.chatModel chatModel; } PostMapping public String chat(RequestBody ChatRequest request) { return chatModel.call(request.message()); } public record ChatRequest(String message) { } }用 curl 测试curl -X POST http://localhost:8080/api/chat \ -H Content-Type: application/json \ -d {message: 请用一句话解释什么是 RAG}预期结果是模型返回一段可读的中文回答。如果接口返回 500 或超时先看应用日志确认模型服务地址、API Key、模型名是否正确。基础对话能通后面的工具调用、RAG、Agent 才有意义。5.2 Tools 工具调用测试Tools 是让大模型调用 Java 方法的关键能力。Langchain4j 用Tool注解标记方法模型在回答问题时自动决定是否调用。定义一个订单查询工具Component public class OrderTools { Tool(查询指定用户最近订单的状态) public String getOrderStatus(P(用户ID) Long userId) { // 这里替换成真实业务查询 return userId userId 最近订单状态为已发货; } }把工具注入到调用模型的地方Service public class AssistantService { private final ChatModel chatModel; private final OrderTools orderTools; public AssistantService(ChatModel chatModel, OrderTools orderTools) { this.chatModel chatModel; this.orderTools orderTools; } public String ask(String userQuestion) { return chatModel.call(userQuestion, orderTools); } }在 Controller 里开放接口测试问题时输入“帮我查一下用户10086最近订单的状态”。如果模型判断需要调用工具返回结果里应体现订单状态。工具调用失败时常见原因是方法入参描述不清晰、模型无法从对话中提取参数或Tool注解没有被正确扫描。5.3 RAG 知识库问答测试RAG 流程通常分三步加载文档、向量化入库、检索增强生成。Langchain4j 提供了完整组件核心代码结构如下Component public class RagService { private final EmbeddingModel embeddingModel; private final VectorStore vectorStore; public RagService(EmbeddingModel embeddingModel, VectorStore vectorStore) { this.embeddingModel embeddingModel; this.vectorStore vectorStore; } // 文档入库 public void loadDocuments(String filePath) { Document doc DocumentLoader.load(new File(filePath)).get(0); TextSplitter splitter new DocumentByParagraphSplitter(200, 50); ListTextSegment segments splitter.split(doc); ListEmbedding embeddings embeddingModel.embedAll(segments); vectorStore.addAll(segments, embeddings); } // 检索增强问答 public String ask(String question) { Embedding queryEmbedding embeddingModel.embed(question); ListEmbeddingMatchTextSegment matches vectorStore.findSimilar(queryEmbedding, 5); String context matches.stream() .map(EmbeddingMatch::embedded) .map(TextSegment::text) .reduce(, (a, b) - a \n---\n b); String prompt 基于以下资料回答问题如果资料中没有答案直接说不知道。\n\n资料\n context; return chatModel.call(prompt); } }实际项目中文档类型可能包括 PDF、Word、Excel需要引入对应解析器。入库之前要确认文档授权并做好敏感信息清洗。测试时先导入一份小文档然后提问文档里明确写过的内容看回答是否引用正确段落。如果回答完全跑偏先检查 embedding 模型和向量库维度是否一致再看切分粒度是否过大或过小。搜索材料里提到的 Qwen Embedding Milvus 方案是 Java 生态里很常见的组合Langchain4j 也支持在 Milvus 上做混合检索与重排进阶阶段可以引入关键词检索与向量检索融合再用重排模型提升结果质量。5.4 Agent 多步任务测试Agent 的核心是“多轮工具调用 动态规划”。Langchain4j 的 LLM 服务可以配置ChatMemory和工具列表让模型在上下文基础上连续执行多个工具。Service public class AgentService { private final ChatModel chatModel; private final OrderTools orderTools; private final ProductTools productTools; public AgentService(ChatModel chatModel, OrderTools orderTools, ProductTools productTools) { this.chatModel chatModel; this.orderTools orderTools; this.productTools productTools; } public String run(String question) { ChatMemory chatMemory MessageWindowChatMemory.withMaxMessages(20); return chatModel.call( chatMemory, question, orderTools, productTools ); } }测试时给一个需要拆解的任务例如“查询用户10010的最近订单并推荐该订单商品所在分类的另一个畅销品”。Agent 需要先查订单拿到商品分类后再查商品库。如果链路能自动完成说明 Agent 编排成功。关键观察点是模型是否准确解析参数、工具返回结果后是否继续追问、多轮任务会不会超时。如果 Agent 陷入循环或调用工具次数过多需要限制工具数量并在提示词中明确“最多调用两次工具”。5.5 批量任务与稳定性验证批量任务不是 AI 框架开箱自带的能力需要应用层自己控制。核心点是控制并发、记录任务状态、失败重试。可以把待处理问题列表放到数据库或消息队列中然后由定时任务消费调用上面的AssistantService或RagService接口。一个简单的批量处理伪代码Component public class BatchProcessor { private final RagService ragService; public BatchProcessor(RagService ragService) { this.ragService ragService; } public void process(ListString questions) { questions.stream().parallel().forEach(question - { try { String answer ragService.ask(question); log.info(问题{}回答{}, question, answer); } catch (Exception e) { log.error(处理失败{}, question, e); // 按业务需要决定是否重试或标记失败 } }); } }批量测试建议用 10 条以内的问题先跑一遍观察是否存在上下文混乱、接口超时和内存涨高的问题。稳定后再逐步扩大批大小。生产环境不要使用无限并行流应该使用线程池并设置队列上限。6. 接口 API 与批量任务编排Spring Boot 服务天然是 REST API。除了上面的/api/chatRAG 问答和 Agent 任务也建议封装成独立接口。接口返回格式要统一方便下游调用。下面是一段 curl 调用 Agent 接口的例子curl -X POST http://localhost:8080/api/agent/run \ -H Content-Type: application/json \ -d {question: 查询用户10086最近订单并推荐类似商品}也可以先做成流式接口让回答像聊天工具一样逐字返回。Spring AI 2.0 支持FluxString流式返回Controller 返回类型改成流后前端可以边接收边渲染。流式接口对超时控制更友好长文本生成体验也更好。批量任务需要更完整的编排。建议方案是用一张任务表记录question、status、answer、error_msg、retry_count再配合定时任务或消息队列消费。每次处理前先查重和限流避免相同内容重复调用产生费用。调用接口时设置合理的超时时间大模型接口通常建议 60 秒到 120 秒具体看模型生成速度和文本长度。以下是 Python 批量调用接口的示例import requests import time url http://localhost:8080/api/rag/ask questions [ 什么是 RAG, 这份文档里的关键流程是什么, 有哪些注意事项 ] headers {Content-Type: application/json} for idx, q in enumerate(questions): try: response requests.post(url, json{question: q}, timeout120) print(f[{idx}] {q} - {response.json()}) except requests.exceptions.Timeout: print(f[{idx}] {q} - 超时) except Exception as e: print(f[{idx}] {q} - 错误: {e}) time.sleep(1)批量任务的失败重试建议采用指数退避策略第一次失败后隔 2 秒重试第二次隔 4 秒最多重试三次。重试时要判断错误类型模型限流错误可以重试参数校验错误不能重试。7. 资源占用与性能观察很多 Java 开发者关心“这套东西到底吃多少内存、多少显存”。这里不能给一个固定数字因为资源占用取决于模型大小、推理方式、并发数和文档切片数量。但可以给出观察方法和优化方向。模型推理层面的资源占用主要由所选模型决定。使用远端 API 时本地服务的内存压力主要来自 Java 应用本身和向量数据使用本地推理时显存或内存占用主要由模型推理服务决定。可以用nvidia-smi查看 GPU 利用率用jstat -gc pid查看 JVM 堆内存变化用top查看进程 CPU 和内存占用。重点观察三类指标接口响应时间、单位时间吞吐量、以及长时间运行后是否有内存持续增长。RAG 流程的性能瓶颈通常在文档切分、向量入库和检索环节。切分粒度太细会产生大量小块检索慢但回答上下文更精确切分粒度太粗则检索快但上下文噪声多。Embedding 模型调用如果走本地推理批量导入文档时建议控制并行数避免一次性把大量文本塞给模型导致 OOM。向量库的索引类型和度量方式也会影响检索耗时Milvus 的 AUTOINDEX 在小规模数据集上通常够用大规模场景需要根据数据量调整索引参数。降低资源占用的常见手段包括对话历史保存时限制最大消息数避免上下文越堆越长。使用缓存相同问题直接命中缓存减少模型调用次数。本地模型场景下优先选择量化版本模型例如 Qwen2.5 7B 的 Q4 量化版本。批量任务使用线程池而不是无限并行流避免瞬时把 CPU 和内存打满。8. 常见问题与排查方法问题现象可能原因排查方式解决方案启动后接口返回 500模型服务没启动或模型名错误查看应用日志调用模型服务健康检查确认本地模型服务已启动核对模型名java.lang.NoClassDefFoundErrorSpring AI 与 Langchain4j 版本冲突查看完整堆栈对比依赖版本使用相同版本的 BOM或排除冲突依赖JDK 版本过低编译报错或注解不生效检查java -version升级到 JDK 17 及以上向量库连接失败Milvus 服务未启动或配置错误检查端口连通性确认 collection 是否创建启动 Milvus核对 host、port、database检索结果为空embedding 维度不一致或 collection 中无数据检查embedding-dimension配置清空 collection 后重新入库回答内容不在文档中检索命中片段不相关打印检索返回的文本片段调整切分参数、检索条数或引入重排接口响应超时模型生成时间过长或上游服务慢查看日志中的耗时分布开启流式返回设置合理超时时间限制上下文长度批量任务内存涨高并行数过大文档加载过多观察 JVM 堆内存和 GC 日志使用有界线程池分批处理Agent 循环调用工具提示词缺少终止条件或工具太多打印调用日志观察决策路径限制最大调用次数精简工具列表本地推理显存不足模型过大或量化等级不够用nvidia-smi查看显存占用换小模型或量化版本降低并发9. 最佳实践与使用建议第一次尝试这套技术栈时不要一上来就接生产文档、跑完整 Agent。建议按“最小链路”起步先在 Spring Boot 里跑通基础对话再单独调用一个工具然后导入一份 50 行以内的文档做 RAG最后再把这些能力组合成 Agent。每步都留可重复执行的测试用例后续改动可以快速定位问题。工程目录规划要提前做好建议分为controller、service、tool、rag、config五个包。模型相关的配置集中放application.yml不要散落在代码里。向量库的数据和输出结果分开存储输入文档、临时文件、最终输出各建一个目录。批量任务一定要有任务日志日志里记录问题原文、调用耗时、模型返回、错误码方便复盘。涉及外部系统调用时工具方法要做用户身份透传。也就是模型生成要调用的参数里带上当前登录用户 ID后端再去校验这个用户是否真的有权限操作对应数据不能只依赖模型自己判断。工具方法内部要加参数校验和操作审计重要操作要二次确认。未经授权的人脸、声音、客户资料、内部合同等数据不能直接进入 RAG 向量库更不能发给外部模型服务。生产环境上线前还要关注接口访问范围。如果服务只给内部系统调用建议绑定内网 IP或加网关鉴权如果开放给外部必须做身份认证、限流和内容审核。模型生成的回答未必正确涉及医疗、金融、法务等场景页面和接口都应提示“AI 生成内容仅供参考”并在关键结论上增加人工复核流程。10. 总结与下一步这条技术路线最值得尝试的点是让 Java 开发者不用切换语言就能把大模型能力接入现有业务系统。Spring AI 2.0 给出标准接入层Langchain4j 提供完整的 RAG 和 Agent 组件再加上 Spring Boot 的工程化能力AI 功能可以很快变成稳定接口。第一步建议先验证基础对话和 Tools这两个能力跑通了后面 RAG 和 Agent 只是组合问题。最容易踩的坑是版本冲突、向量维度不一致和模型调用超时排错时先看日志再逐步缩小范围。下一步可以往三个方向继续深入一是把 RAG 的混合检索和重排做起来解决复杂业务文档的检索精度问题二是用 Spring AI 2.0 的流式接口改造问答体验三是把 Agent 的任务状态和人工审核流程接进公司现有工单系统让 AI 应用真正走进业务流程。先保留一套最小可运行配置后面迭代时随时回退。