LangChain4j 实战指南

LangChain4j 实战指南在 Java 应用中优雅集成大语言模型概述如果你是一名 Java 后端开发者一定经历过这样的阶段为了调用一次 ChatGPT自己拼 HTTP 请求、解析 JSON、处理重试与超时想做 RAG 问答又要单独对接向量库、Embedding 模型和 Prompt 模板。代码越写越长却越来越难维护。LangChain4j正是为解决这类问题而生的开源 Java 库。它对标 Python 生态中的 LangChain为 JVM 世界提供统一的 LLM 接入 API并内置 RAG、Tool Calling、对话记忆、Agent 等能力与 Spring Boot、Quarkus 等企业级框架深度集成。本文将带你从零理解 LangChain4j 的设计思路并通过可运行的示例掌握在 Spring Boot 3 项目中落地 AI 能力的正确姿势。为什么选择 LangChain4j对比维度手写 HTTP 调用LangChain4j模型切换每个厂商一套 SDK统一ChatModel接口改配置即可Prompt 管理字符串散落各处SystemMessage/UserMessage声明式注解RAG自研检索 拼接逻辑ContentRetriever/RetrievalAugmentor开箱即用工具调用手动解析 function callTool注解 自动注册Spring 集成自行封装 BeanAiService自动扫描与注入LangChain4j 的核心价值不是「多包一层 HTTP」而是把 LLM 应用中的重复模式抽象成可组合、可测试的组件让业务代码只关注「做什么」而不是「怎么调 API」。核心概念1. ChatModel 与 EmbeddingModelLangChain4j 将大模型交互抽象为接口ChatModel同步对话传入UserMessage返回AiMessageStreamingChatModel流式输出适合 SSE 场景EmbeddingModel文本向量化RAG 的基础官方与社区提供了 OpenAI、Anthropic、Ollama、Azure、DashScope通义等多种集成 Starter通过application.yml即可完成配置。2. AI Services声明式 AI 接口AI Services 是 LangChain4j 最具特色的 API类似 Spring Data JPA 的 Repository你定义接口框架生成实现。AiServicepublicinterfaceAssistant{SystemMessage(你是一名专业的 Java 技术顾问回答简洁准确。)Stringchat(UserMessageStringuserMessage);}启动 Spring Boot 应用后langchain4j-spring-boot-starter会扫描AiService接口自动注入ChatModel、ChatMemory、ContentRetriever等组件并注册为 Spring Bean。在 Controller 中直接注入即可RestControllerRequestMapping(/api/assistant)RequiredArgsConstructorpublicclassAssistantController{privatefinalAssistantassistant;PostMapping(/chat)publicStringchat(RequestBodyValidChatRequestrequest){returnassistant.chat(request.getMessage());}}3. Chat Memory对话记忆多轮对话需要上下文。LangChain4j 提供MessageWindowChatMemory保留最近 N 条消息ChatMemoryProvider按用户 ID 隔离会话配合MemoryIdAiServicepublicinterfaceCustomerSupportAgent{SystemMessage(你是客服助手请根据历史对话回答用户问题。)Stringreply(MemoryIdStringsessionId,UserMessageStringmessage);}4. Tools工具调用当 LLM 需要查数据库、调接口、执行计算时使用Tool将 Java 方法暴露给模型ComponentpublicclassOrderTools{privatefinalOrderServiceorderService;publicOrderTools(OrderServiceorderService){this.orderServiceorderService;}Tool(根据订单号查询订单状态)publicStringgetOrderStatus(P(订单号)StringorderNo){returnorderService.getStatus(orderNo);}}在 AI Service 中注册工具AssistantassistantAiServices.builder(Assistant.class).chatModel(chatModel).tools(newOrderTools(orderService)).build();Spring Boot 场景下将OrderTools注册为 Bean 后Starter 会自动发现并注入。5. RAG检索增强生成RAG 解决「模型不知道你的私有知识」的问题典型流程用户提问 → 向量化 → 检索相关文档片段 → 拼入 Prompt → LLM 生成回答LangChain4j 提供Naive RAG与Advanced RAG两档能力模式组件适用场景简单 RAGEmbeddingStoreContentRetriever文档问答、知识库高级 RAGRetrievalAugmentor查询改写、重排序、多路检索示例使用内存向量库做文档问答EmbeddingStoreTextSegmentembeddingStorenewInMemoryEmbeddingStore();// 1. 导入文档并切分DocumentdocumentFileSystemDocumentLoader.loadDocument(Paths.get(docs/manual.pdf));DocumentSplittersplitterDocumentSplitters.recursive(300,30);ListTextSegmentsegmentssplitter.split(document);// 2. 向量化并入库EmbeddingModelembeddingModelnewAllMiniLmL6V2EmbeddingModel();for(TextSegmentsegment:segments){EmbeddingembeddingembeddingModel.embed(segment).content();embeddingStore.add(embedding,segment);}// 3. 构建 ContentRetrieverContentRetrievercontentRetrieverEmbeddingStoreContentRetriever.builder().embeddingStore(embeddingStore).embeddingModel(embeddingModel).maxResults(3).minScore(0.75).build();// 4. 注入 AI ServiceAssistantragAssistantAiServices.builder(Assistant.class).chatModel(chatModel).contentRetriever(contentRetriever).build();Spring Boot 快速集成Maven 依赖以 OpenAI 为例Spring Boot 3dependencygroupIddev.langchain4j/groupIdartifactIdlangchain4j-open-ai-spring-boot-starter/artifactIdversion1.0.0-beta3/version/dependencydependencygroupIddev.langchain4j/groupIdartifactIdlangchain4j-spring-boot-starter/artifactIdversion1.0.0-beta3/version/dependency版本号请以 Maven Central 最新发布为准。application.yml 配置langchain4j:open-ai:chat-model:api-key:${OPENAI_API_KEY}model-name:gpt-4o-minitemperature:0.7timeout:60slog-requests:truelog-responses:true定义 AI ServiceAiServicepublicinterfaceCodeReviewer{SystemMessage( 你是一名资深 Java Code Reviewer。 请从可读性、性能、空安全、并发安全四个维度给出建议。 输出 Markdown 格式。 )UserMessage( 请 Review 以下代码 java {{code}} )Stringreview(V(code)Stringcode);}Controller 直接注入使用无需手动AiServices.builder(...)。生产环境最佳实践1. 分层清晰Controller 不写 PromptController参数校验、鉴权、返回封装AiServicePrompt 与 AI 逻辑Tool / Service业务数据访问这与常规 Spring 分层一致避免 Prompt 字符串污染 Web 层。2. 明确事务边界Tool方法可能触发数据库写操作。遵循 Spring 事务规范Tool 内的 DB 操作走 Service 层不要在 Tool 里直接发 HTTP 或 MQ若 Tool 被 AI 多次调用注意幂等与性能。3. RAG 文档更新策略向量库与源文档需保持一致文档变更 → 重新 Embedding 并 upsert大规模场景使用 Milvus、PgVector、Elasticsearch 等外部EmbeddingStore检索结果设置minScore阈值避免低相关片段污染回答4. 可观测性开启请求/响应日志见上方 yml并结合 TraceId 关联一次用户会话内的多次 LLM 调用。LangChain4j 支持监听AiServiceRegisteredEvent在启动时打印已注册的 AI Service 与 Tool 列表便于排查。5. 流式响应提升体验长文生成场景接口返回类型改为TokenStream配合 SSE 推送到前端AiServicepublicinterfaceStreamingWriter{TokenStreamwrite(UserMessageStringtopic);}与 LangChainPython的对比特性LangChain (Python)LangChain4j (Java)生态成熟度非常成熟快速发展中企业框架FastAPI 等Spring Boot / Quarkus 原生AI Services部分支持核心设计注解驱动MCP 支持有已支持 Tool / MCP 集成适用团队AI 工程 / 数据Java 后端 / 企业 IT若团队技术栈以 Java 为主LangChain4j 的学习与维护成本显著低于引入 Python 微服务。FAQQ1LangChain4j 需要什么 Java 版本A官方要求Java 17推荐 Java 21 LTS与 Spring Boot 3.5 搭配。Q2能否使用本地 Ollama 模型A可以。引入langchain4j-ollama-spring-boot-starter配置base-url为http://localhost:11434无需 API Key适合开发与离线场景。Q3RAG 检索结果不准怎么办A依次排查文档切分粒度chunk size、Embedding 模型质量、maxResults/minScore参数、是否需 Advanced RAG查询扩展、重排序。Q4AI Service 和直接调用 ChatModel 怎么选A简单单次对话可直接用ChatModel涉及 Memory、Tools、RAG、结构化输出时优先AI Services代码量通常减少 60% 以上。Q5如何防止 Prompt 注入A对用户输入做长度限制与敏感词过滤System Prompt 中明确「仅回答与业务相关的问题」Tool 方法内校验参数合法性禁止 LLM 间接执行危险操作。总结LangChain4j 让 Java 开发者可以用熟悉的方式构建 LLM 应用统一 API屏蔽不同模型厂商差异AI Services用接口 注解声明 Prompt 与能力Tools / RAG / Memory以组件形式组合而非堆砌 if-elseSpring Boot Starter实现零样板配置从「调一次 OpenAI API」到「上线一个可维护的 AI 功能」差距往往不在模型能力而在工程化程度。LangChain4j 正是补齐 Java 生态这块短板的关键拼图。建议下一步用AiService 本地 Ollama 跑通一个最小问答接口再逐步叠加 RAG 与 Tool比一上来追求复杂 Agent 更稳妥。参考链接LangChain4j 官方文档Spring Boot 集成教程AI Services 教程GitHub 示例仓库