LangChain4j实战：Java集成大语言模型的统一开发框架

如果你是一个Java开发者最近想要在自己的应用中集成大语言模型LLM能力比如构建一个智能客服、文档问答系统或者一个能自动执行任务的AI助手那么你很可能面临一个现实困境面对市场上众多的LLM提供商如OpenAI、Google Gemini、Anthropic等和向量数据库如Pinecone、Milvus、Chroma等每个都有自己独特的API和SDK你是应该选择一个并绑定到底还是为每个供应商写一套适配代码前者限制了灵活性后者则意味着巨大的开发和维护成本。这正是LangChain4j要解决的核心问题。它不是一个简单的Java版LangChain而是一个为JVM生态量身定制的、地道的开源Java库。它的核心价值在于提供了一个统一的API层让你能用一套代码与20主流LLM提供商和30向量存储进行交互。这意味着你今天可以快速用OpenAI的模型搭建原型明天如果成本或性能需要可以几乎无缝地切换到本地的Ollama或云上的Google Vertex AI而业务逻辑代码无需改动。更重要的是LangChain4j将社区中验证过的AI应用模式如RAG、Agent、函数调用等封装成了开箱即用的工具箱。你不需要从零开始实现提示词模板、对话记忆管理或复杂的检索逻辑而是可以像搭积木一样快速组合出功能强大的生产级应用。本文将带你从零开始深入理解LangChain4j的设计哲学并通过完整的实战示例展示如何将其集成到Spring Boot等主流Java框架中构建真正可用的LLM驱动应用。1. LangChain4j 的核心定位为什么Java开发者需要它在AI应用开发领域Python凭借其丰富的库生态一度占据主导地位。但对于庞大的Java企业级应用市场来说直接将Python组件嵌入现有Java系统往往面临性能损耗、运维复杂性和技术栈割裂的挑战。LangChain4j的诞生正是为了填补JVM生态在LLM应用开发工具链上的空白。1.1 统一API的价值从供应商锁定到灵活架构在没有统一抽象层的情况下直接调用特定LLM提供商的SDK会导致严重的供应商锁定问题。例如如果你直接使用OpenAI的Java SDK那么代码中会充满OpenAI特有的参数和响应处理逻辑。当需要切换模型时重写成本很高。LangChain4j通过定义统一的接口如ChatLanguageModel、EmbeddingModel、ChatMemory等让开发者面向接口编程而不是具体实现。这种设计带来的直接好处是降低迁移成本更换LLM提供商只需修改配置和依赖核心业务逻辑不变简化测试可以轻松注入Mock实现进行单元测试多云策略在同一应用中根据不同场景使用不同提供商的模型1.2 企业级集成与Spring Boot、Quarkus等框架的无缝融合LangChain4j从设计之初就考虑了企业级Java应用的集成需求。它原生支持依赖注入与Spring Boot、Quarkus、Micronaut和Helidon等主流框架深度集成。这意味着你可以像使用其他Spring Bean一样使用LangChain4j的组件享受完整的生命周期管理和配置化体验。例如在Spring Boot中只需添加相应的starter依赖就可以通过application.properties文件配置模型参数并通过Autowired注解注入AI组件。这种设计显著降低了在现有Java项目中引入AI能力的学习曲线和集成成本。1.3 模式化工具箱避免重复造轮子LangChain4j不仅仅是一个API适配层更重要的是它提供了一整套经过实践检验的AI应用模式实现。这些模式包括RAG检索增强生成完整的文档处理、向量化、检索和生成流水线Agent智能体能够使用工具执行复杂任务的自主AI系统函数调用让LLM能够调用外部工具和API对话记忆管理维护多轮对话的上下文状态这些模式封装了最佳实践让开发者可以专注于业务逻辑而不是底层AI基础设施的实现细节。2. 核心架构与关键概念解析要有效使用LangChain4j需要理解其核心架构中的几个关键抽象。这些抽象构成了整个库的设计基础。2.1 核心组件架构LangChain4j的架构围绕几个核心接口构建下图展示了主要组件之间的关系用户输入 → ChatLanguageModel → 响应输出 ↑ 工具调用/函数调用 ↑ 外部工具/API ↑ EmbeddingModel VectorStore ↑ 文档数据源2.2 关键接口详解ChatLanguageModel这是最核心的接口定义了与LLM交互的基本契约。无论底层是OpenAI、Gemini还是本地模型都通过这个接口提供统一的聊天完成功能。// 基础使用示例 ChatLanguageModel model OpenAiChatModel.builder() .apiKey(your-api-key) .modelName(gpt-4o) .temperature(0.7) .build(); String response model.generate(请用Java写一个Hello World程序); System.out.println(response);EmbeddingModel负责将文本转换为向量表示。这些向量用于语义搜索、相似度计算等任务。EmbeddingModel embeddingModel OpenAiEmbeddingModel.builder() .apiKey(your-api-key) .modelName(text-embedding-3-small) .build(); Embedding embedding embeddingModel.embed(你好世界).content();ChatMemory管理对话历史确保LLM能够理解上下文。支持基于Token数量、消息条数等多种记忆策略。ChatMemory chatMemory MessageWindowChatMemory.withMaxMessages(10); chatMemory.add(UserMessage.userMessage(我喜欢编程)); chatMemory.add(AiMessage.aiMessage(那很棒你最喜欢什么语言)); // 后续对话会自动包含之前的上下文2.3 高级模式抽象Tool工具让LLM能够调用外部函数或API的关键抽象。通过简单的注解即可将Java方法暴露给LLM调用。public class Calculator { Tool(将两个数字相加) public double add(double a, double b) { return a b; } }Agent智能体结合了LLM、工具和记忆的自主系统能够根据目标规划并执行一系列动作。Agent agent AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(new Calculator()) .chatMemory(chatMemory) .build();3. 环境准备与项目搭建现在让我们开始实战搭建一个基于Spring Boot的LangChain4j项目。3.1 系统要求与前置条件JavaJDK 17或更高版本LangChain4j充分利用了Java的新特性构建工具Maven 3.6 或 Gradle 7.xIDEIntelliJ IDEA推荐或Eclipse、VS CodeLLM访问OpenAI API密钥或本地模型访问权限3.2 创建Spring Boot项目使用Spring Initializr创建新项目选择以下依赖Spring WebSpring Boot DevTools可选用于热部署!-- pom.xml 中的关键依赖 -- dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- LangChain4j Spring Boot Starter -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version0.32.0/version !-- 请使用最新版本 -- /dependency !-- OpenAI集成 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.32.0/version /dependency /dependencies3.3 基础配置在application.properties中配置基本参数# application.properties # OpenAI配置如果使用OpenAI langchain4j.openai.chat-model.api-key${OPENAI_API_KEY} langchain4j.openai.chat-model.model-namegpt-4o langchain4j.openai.chat-model.temperature0.7 langchain4j.openai.chat-model.max-tokens1000 # 如果使用本地模型如Ollama # langchain4j.ollama.base-urlhttp://localhost:11434 # langchain4j.ollama.chat-model.model-namellama3.1:8b3.4 项目结构规划建议采用以下项目结构便于扩展和维护src/main/java/com/example/ai/ ├── config/ # 配置类 ├── service/ # 业务服务 ├── controller/ # Web控制器 ├── model/ # 数据模型 └── tool/ # AI工具定义4. 第一个LangChain4j应用智能问答服务让我们构建一个完整的智能问答服务演示LangChain4j的核心功能。4.1 创建配置类首先创建配置类来管理AI组件// src/main/java/com/example/ai/config/AiConfig.java package com.example.ai.config; import dev.langchain4j.model.chat.ChatLanguageModel; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class AiConfig { Bean public ChatLanguageModel chatLanguageModel() { return OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o) .temperature(0.3) .maxTokens(500) .logRequests(true) .logResponses(true) .build(); } }4.2 创建问答服务实现核心的问答业务逻辑// src/main/java/com/example/ai/service/QaService.java package com.example.ai.service; import dev.langchain4j.model.chat.ChatLanguageModel; import org.springframework.stereotype.Service; Service public class QaService { private final ChatLanguageModel model; public QaService(ChatLanguageModel model) { this.model model; } public String answerQuestion(String question) { // 构建带上下文的提示词 String prompt String.format( 你是一个专业的编程助手。请用中文回答以下问题回答要简洁明了、准确专业。 问题%s 回答 , question); return model.generate(prompt); } public String explainCode(String code, String language) { String prompt String.format( 请解释以下%s代码的功能和工作原理。解释要详细但不超过300字。 代码 %s %s 解释 , language, language, code); return model.generate(prompt); } }4.3 创建Web控制器提供REST API接口// src/main/java/com/example/ai/controller/AiController.java package com.example.ai.controller; import com.example.ai.service.QaService; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/api/ai) public class AiController { private final QaService qaService; public AiController(QaService qaService) { this.qaService qaService; } PostMapping(/question) public String answerQuestion(RequestBody QuestionRequest request) { return qaService.answerQuestion(request.getQuestion()); } PostMapping(/explain-code) public String explainCode(RequestBody CodeExplanationRequest request) { return qaService.explainCode(request.getCode(), request.getLanguage()); } // 请求DTO类 public static class QuestionRequest { private String question; // getter/setter省略 } public static class CodeExplanationRequest { private String code; private String language; // getter/setter省略 } }4.4 测试应用启动应用后可以使用curl或Postman进行测试# 启动应用 mvn spring-boot:run # 测试问答接口 curl -X POST http://localhost:8080/api/ai/question \ -H Content-Type: application/json \ -d {question: Java中的Stream API有什么优势} # 测试代码解释接口 curl -X POST http://localhost:8080/api/ai/explain-code \ -H Content-Type: application/json \ -d { code: public class HelloWorld { public static void main(String[] args) { System.out.println(\Hello, World!\); } }, language: java }5. 构建RAG系统文档问答实战单纯的问答服务知识有限接下来我们构建一个更实用的RAG检索增强生成系统让AI能够基于特定文档内容回答问题。5.1 RAG系统架构设计一个完整的RAG系统包含以下组件文档加载器从各种来源加载文档文本分割器将长文档分割为适合处理的片段嵌入模型将文本转换为向量向量数据库存储和检索向量检索器根据问题查找相关文档片段生成模型基于检索结果生成答案5.2 实现文档处理流水线首先添加必要的依赖!-- 向量数据库支持这里使用内存向量库作为示例 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.32.0/version /dependency !-- 文档处理工具 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-document-parser-apache-poi/artifactId version0.32.0/version /dependency实现文档处理服务// src/main/java/com/example/ai/service/RagService.java package com.example.ai.service; import dev.langchain4j.data.document.Document; import dev.langchain4j.data.document.DocumentSplitter; import dev.langchain4j.data.document.parser.TextDocumentParser; import dev.langchain4j.data.document.splitter.DocumentSplitters; import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever; import dev.langchain4j.store.embedding.EmbeddingStore; import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore; import org.springframework.stereotype.Service; import java.nio.file.Paths; import java.util.List; Service public class RagService { private final EmbeddingModel embeddingModel; private final EmbeddingStoreTextSegment embeddingStore; public RagService(EmbeddingModel embeddingModel) { this.embeddingModel embeddingModel; this.embeddingStore new InMemoryEmbeddingStore(); } public void loadDocuments(String filePath) { try { // 加载文档 Document document Document.from(Paths.get(filePath), new TextDocumentParser()); // 分割文档每段500字符重叠50字符 DocumentSplitter splitter DocumentSplitters.recursive(500, 50); ListTextSegment segments splitter.split(document); // 生成嵌入并存储 embeddingStore.addAll(embeddingModel, segments); } catch (Exception e) { throw new RuntimeException(文档加载失败: e.getMessage(), e); } } public EmbeddingStoreContentRetriever createRetriever() { return EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(embeddingModel) .maxResults(3) // 每次检索3个最相关的片段 .build(); } }5.3 创建RAG问答服务// src/main/java/com/example/ai/service/RagQaService.java package com.example.ai.service; import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.rag.content.retriever.ContentRetriever; import dev.langchain4j.service.AiServices; import dev.langchain4j.service.SystemMessage; import org.springframework.stereotype.Service; Service public class RagQaService { public interface Assistant { SystemMessage( 你是一个专业的文档问答助手。请基于提供的文档内容回答问题。 如果文档中没有相关信息请如实告知用户无法回答。 回答要准确、简洁并引用文档中的具体信息。 ) String answer(String question); } private final Assistant assistant; public RagQaService(ChatLanguageModel model, ContentRetriever retriever) { this.assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .contentRetriever(retriever) .build(); } public String answerBasedOnDocuments(String question) { return assistant.answer(question); } }5.4 集成到控制器扩展之前的控制器添加RAG功能// 在AiController中添加 PostMapping(/rag/load-document) public String loadDocument(RequestBody DocumentLoadRequest request) { try { ragService.loadDocuments(request.getFilePath()); return 文档加载成功; } catch (Exception e) { return 文档加载失败: e.getMessage(); } } PostMapping(/rag/question) public String ragAnswer(RequestBody QuestionRequest request) { ContentRetriever retriever ragService.createRetriever(); return ragQaService.answerBasedOnDocuments(request.getQuestion()); }6. 实现AI智能体让LLM使用工具AI智能体是LangChain4j的高级功能它允许LLM根据目标自主选择和使用工具完成任务。6.1 定义工具集创建一些实用的工具供AI调用// src/main/java/com/example/ai/tool/CalculatorTool.java package com.example.ai.tool; import dev.langchain4j.agent.tool.Tool; import org.springframework.stereotype.Component; Component public class CalculatorTool { Tool(执行数学计算支持加减乘除等基本运算) public double calculate(String expression) { // 简化实现实际项目中应使用更安全的表达式求值库 try { return eval(expression); } catch (Exception e) { throw new RuntimeException(计算表达式失败: expression); } } private double eval(String expression) { // 简单的表达式求值生产环境请使用安全的求值库 return new ScriptEngineManager().getEngineByName(JavaScript) .eval(expression.replace( , )).toString()); } } // src/main/java/com/example/ai/tool/TimeTool.java Component public class TimeTool { Tool(获取当前时间或指定时区的时间) public String getCurrentTime(P(时区例如Asia/Shanghai) String timezone) { ZoneId zone timezone ! null ? ZoneId.of(timezone) : ZoneId.systemDefault(); return LocalDateTime.now(zone).format(DateTimeFormatter.ISO_LOCAL_DATE_TIME); } }6.2 创建智能体服务// src/main/java/com/example/ai/service/AgentService.java package com.example.ai.service; import dev.langchain4j.service.AiServices; import dev.langchain4j.service.SystemMessage; import dev.langchain4j.service.TokenStream; import org.springframework.stereotype.Service; Service public class AgentService { public interface Assistant { SystemMessage(你是一个有用的助手可以执行计算、查询时间等任务。) String chat(String message); TokenStream chatStream(String message); } private final Assistant assistant; public AgentService(ChatLanguageModel model, CalculatorTool calculator, TimeTool timeTool) { this.assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(calculator, timeTool) .build(); } public String executeTask(String task) { return assistant.chat(task); } }6.3 测试智能体功能// 测试类示例 SpringBootTest class AgentServiceTest { Autowired private AgentService agentService; Test void testCalculatorTool() { String result agentService.executeTask(请计算123乘以456等于多少); System.out.println(智能体回答: result); // 预期输出包含计算结果的解释 } Test void testTimeQuery() { String result agentService.executeTask(现在上海的时间是多少); System.out.println(智能体回答: result); } }7. 高级特性与生产级配置7.1 对话记忆管理在实际对话场景中保持上下文记忆至关重要// 配置有状态的对话服务 public class ConversationalService { private final MapString, ChatMemory chatMemories new ConcurrentHashMap(); public String continueConversation(String sessionId, String userMessage) { ChatMemory memory chatMemories.computeIfAbsent(sessionId, id - MessageWindowChatMemory.withMaxMessages(20)); memory.add(UserMessage.userMessage(userMessage)); // 使用记忆进行对话 String response model.generate(memory.messages()); memory.add(AiMessage.aiMessage(response)); return response; } }7.2 流式响应对于需要实时显示响应的场景支持流式输出GetMapping(/stream-chat) public SseEmitter streamChat(RequestParam String message) { SseEmitter emitter new SseEmitter(); assistant.chatStream(message) .onNext(token - { try { emitter.send(SseEmitter.event().data(token)); } catch (IOException e) { throw new RuntimeException(e); } }) .onComplete(() - emitter.complete()) .onError(emitter::completeWithError) .start(); return emitter; }7.3 生产环境配置建议# application.yml 生产配置示例 langchain4j: openai: chat-model: api-key: ${OPENAI_API_KEY} model-name: gpt-4 temperature: 0.1 timeout: 60s max-retries: 3 log-requests: true log-responses: true metrics: micrometer: enabled: true management: endpoints: web: exposure: include: metrics,prometheus endpoint: metrics: enabled: true prometheus: enabled: true8. 常见问题与解决方案在实际使用LangChain4j过程中可能会遇到一些典型问题以下是排查指南8.1 依赖冲突问题问题现象启动时报错multiple HTTP clients have been found in the classpath解决方案在pom.xml中显式指定HTTP客户端dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-http-client/artifactId version0.32.0/version /dependency8.2 内存溢出问题问题现象处理大文档时出现OOM错误解决方案优化文档处理策略// 使用更精细的文档分割策略 DocumentSplitter splitter DocumentSplitters.recursive( 300, // 更小的片段大小 30, // 更小的重叠区域 new TokenCountEstimator() // 基于Token计数而非字符 );8.3 超时和重试配置问题现象API调用频繁超时解决方案合理配置超时和重试策略OpenAiChatModel.builder() .apiKey(apiKey) .modelName(modelName) .timeout(Duration.ofSeconds(30)) .maxRetries(3) .retryer(Retryer.fixed(3, Duration.ofSeconds(2))) .build();8.4 向量检索精度问题问题现象RAG系统返回不相关的内容解决方案优化检索策略EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(embeddingModel) .maxResults(5) // 增加检索数量 .minScore(0.7) // 设置相似度阈值 .dynamicMaxResults(true) // 动态调整结果数量 .build();9. 性能优化与最佳实践9.1 缓存策略对频繁查询的内容实施缓存Service public class CachedEmbeddingService { private final EmbeddingModel embeddingModel; private final CacheString, Embedding embeddingCache; public CachedEmbeddingService(EmbeddingModel embeddingModel) { this.embeddingModel embeddingModel; this.embeddingCache Caffeine.newBuilder() .maximumSize(10_000) .expireAfterWrite(1, TimeUnit.HOURS) .build(); } public Embedding embed(String text) { return embeddingCache.get(text, key - embeddingModel.embed(key).content()); } }9.2 批量处理优化减少API调用次数使用批量处理// 批量生成嵌入 ListString texts Arrays.asList(text1, text2, text3); ListEmbedding embeddings embeddingModel.embedAll(texts).content(); // 批量对话如果模型支持 ListChatMessage messages // ... 多个对话 ListChatMessage responses model.generate(messages);9.3 监控与日志建立完整的监控体系Configuration public class MonitoringConfig { Bean public MeterRegistry meterRegistry() { return new SimpleMeterRegistry(); } Bean public MicrometerObservationObservationHandlerObservation.Context observationHandler() { return new MicrometerObservationObservationHandler(meterRegistry()); } }9.4 安全最佳实践API密钥管理使用环境变量或密钥管理服务避免硬编码输入验证对用户输入进行严格的验证和清理输出过滤对AI生成内容进行安全过滤访问控制实施适当的权限控制机制通过本文的全面介绍你应该对LangChain4j有了深入的理解并能够开始在自己的Java项目中集成AI能力。LangChain4j的真正价值在于它让Java开发者能够以熟悉的方式构建先进的AI应用而无需深入掌握复杂的AI基础设施细节。无论是简单的聊天机器人还是复杂的企业级RAG系统LangChain4j都提供了可靠的工具箱和最佳实践指导。