LangChain4j 实战：从零构建智能对话系统

1. LangChain4j 入门指南为什么选择它来构建智能对话系统如果你是一名Java开发者想要快速构建一个智能对话系统LangChain4j绝对值得你深入了解。这个开源框架是Python生态中流行的LangChain框架的Java实现专门为Java开发者设计让集成和使用各种大语言模型LLM变得异常简单。我在实际项目中使用LangChain4j构建过多个对话系统发现它最大的优势在于开箱即用。你不需要从零开始处理复杂的模型集成、会话管理等问题框架已经帮你封装好了这些核心功能。比如最近我帮一家电商公司搭建的客服机器人从零开始到上线只用了3天时间。与Spring AI相比LangChain4j对JDK版本要求更友好最低支持JDK 8而且社区活跃度很高。它的设计非常符合Java开发者的思维习惯特别是如果你熟悉Spring框架集成起来会非常顺畅。框架的核心功能包括多模型支持可以轻松切换不同的大模型提供商会话管理内置记忆功能支持多轮对话知识增强通过RAG技术接入外部知识库工具调用让大模型能够执行具体操作流式响应实现类似ChatGPT的逐字输出效果2. 环境准备与基础配置2.1 开发环境要求在开始之前确保你的开发环境满足以下要求JDK 17或更高版本推荐使用Amazon Corretto或OpenJDKMaven 3.6或Gradle 7.xIDEIntelliJ IDEA或Eclipse可访问的大模型API如阿里云百炼、OpenAI等我建议使用Spring Boot作为基础框架它能与LangChain4j完美配合。最近一个项目中我们使用Spring Boot 3.2 LangChain4j 1.1.0的组合运行非常稳定。2.2 基础依赖配置在pom.xml中添加核心依赖dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version1.1.0/version /dependency !-- 如果你使用Spring Boot -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai-spring-boot-starter/artifactId version1.1.0-beta7/version /dependency对于日志输出添加Logback依赖能让你更清晰地看到请求和响应dependency groupIdch.qos.logback/groupId artifactIdlogback-classic/artifactId version1.5.18/version /dependency2.3 模型基础配置在application.yml中配置大模型连接信息langchain4j: open-ai: chat-model: base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 api-key: ${API_KEY} # 建议通过环境变量设置 model-name: qwen-plus log-requests: true log-responses: true这里有个小技巧把api-key放在环境变量中而不是直接写在配置文件里更安全。在IDEA中设置环境变量后记得重启IDE才能生效。3. 构建第一个对话接口3.1 直接使用ChatModel最简单的使用方式是直接注入OpenAiChatModelRestController public class ChatController { Resource private OpenAiChatModel chatModel; GetMapping(/chat) public String chat(String message) { return chatModel.chat(message); } }这种方式虽然简单但功能有限。我在初期项目中也这样用过后来发现当需要添加记忆、知识库等功能时代码会变得很臃肿。3.2 使用AiServices工具类更推荐的方式是使用AiServices它能提供更高级的功能封装。首先定义一个服务接口public interface ChatService { String chat(String message); }然后通过配置类创建代理实例Configuration public class LangChainConfig { Bean public ChatService chatService(OpenAiChatModel chatModel) { return AiServices.builder(ChatService.class) .chatModel(chatModel) .build(); } }在控制器中注入使用RestController public class ChatController { Resource private ChatService chatService; GetMapping(/chat) public String chat(String message) { return chatService.chat(message); } }这种方式的好处是后续添加记忆、工具等功能时只需要修改配置类业务代码几乎不用变动。我在重构项目时这种设计节省了大量时间。3.3 声明式AiService用法LangChain4j还提供了更简洁的声明式用法AiService public interface ChatService { String chat(String message); }框架会自动处理所有绑定工作。不过我个人更推荐显式配置因为当需要添加额外功能时会更清晰。4. 实现流式对话体验4.1 后端流式配置现代对话系统普遍采用流式响应让用户能即时看到生成结果。实现这个功能需要添加额外依赖dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-reactor/artifactId version1.1.0-beta7/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency配置流式模型langchain4j: open-ai: streaming-chat-model: base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 api-key: ${API_KEY} model-name: qwen-plus修改服务接口AiService public interface ChatService { FluxString chatStream(String message); }控制器调整GetMapping(value /chat-stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxString chatStream(String message) { return chatService.chatStream(message); }4.2 前端实现一个简单的前端实现可以使用Vue.jsdiv idapp div v-for(msg, index) in messages :keyindex {{ msg }} /div input v-modelinput keyup.entersend / /div script const { createApp, ref } Vue; createApp({ setup() { const messages ref([]); const input ref(); async function send() { const response await fetch(/chat-stream?message encodeURIComponent(input.value)); const reader response.body.getReader(); const decoder new TextDecoder(); let result ; while (true) { const { done, value } await reader.read(); if (done) break; result decoder.decode(value); messages.value.push(result); } } return { messages, input, send }; } }).mount(#app); /script在实际项目中你可能需要添加更多功能如消息历史、加载状态等。我最近实现的一个前端包含了打字机效果、消息分角色显示等功能用户体验大幅提升。5. 高级功能实现5.1 会话记忆管理LangChain4j提供了完善的会话记忆管理。配置方法Bean public ChatMemory chatMemory() { return MessageWindowChatMemory.withMaxMessages(20); } Bean public ChatService chatService(OpenAiChatModel chatModel, ChatMemory chatMemory) { return AiServices.builder(ChatService.class) .chatModel(chatModel) .chatMemory(chatMemory) .build(); }对于多用户场景需要使用ChatMemoryProviderBean public ChatMemoryProvider chatMemoryProvider() { return memoryId - MessageWindowChatMemory.builder() .id(memoryId) .maxMessages(20) .build(); }然后在服务接口中添加MemoryId参数AiService public interface ChatService { String chat(MemoryId String sessionId, String message); }5.2 RAG知识库集成LangChain4j的RAG功能非常强大。基本配置Bean public EmbeddingStoreTextSegment embeddingStore() { // 从类路径加载文档 ListDocument documents ClassPathDocumentLoader.loadDocuments(knowledge); // 创建内存向量存储 InMemoryEmbeddingStoreTextSegment store new InMemoryEmbeddingStore(); // 创建ingestor处理文档 EmbeddingStoreIngestor ingestor EmbeddingStoreIngestor.builder() .embeddingStore(store) .documentSplitter(DocumentSplitters.recursive(500, 100)) .build(); ingestor.ingest(documents); return store; } Bean public ContentRetriever contentRetriever(EmbeddingStoreTextSegment embeddingStore) { return EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .maxResults(3) .minScore(0.5) .build(); }然后在AiService中配置retrieverBean public ChatService chatService(OpenAiChatModel chatModel, ContentRetriever retriever) { return AiServices.builder(ChatService.class) .chatModel(chatModel) .contentRetriever(retriever) .build(); }5.3 工具方法集成让大模型能够调用实际方法Component public class BookingTools { Tool(预约会议室) public String bookMeetingRoom( P(会议室名称) String roomName, P(开始时间 yyyy-MM-dd HH:mm) String startTime, P(结束时间 yyyy-MM-dd HH:mm) String endTime) { // 实际预约逻辑 return 已预约 roomName 从 startTime 到 endTime; } }然后在AiService配置中注册工具Bean public ChatService chatService(OpenAiChatModel chatModel, BookingTools tools) { return AiServices.builder(ChatService.class) .chatModel(chatModel) .tools(tools) .build(); }6. 生产环境优化建议6.1 性能调优使用连接池管理模型API连接合理设置超时时间对频繁查询实现缓存层监控token使用量6.2 安全考虑API密钥安全管理用户输入过滤输出内容审核限流防滥用6.3 监控与日志记录完整对话历史监控响应时间错误预警机制使用Micrometer集成监控我在实际项目中发现良好的监控能帮助快速定位问题。特别是当对话出现异常时完整的日志能大大缩短排查时间。7. 常见问题解决7.1 流式响应中断可能原因网络不稳定超时设置过短模型响应慢解决方案增加超时时间添加重试机制前端实现断线重连7.2 记忆失效可能原因memoryId不一致存储未持久化超出最大消息数解决方案检查memoryId生成逻辑使用持久化存储调整maxMessages大小7.3 工具调用失败可能原因参数解析错误方法权限问题返回值格式不符解决方案检查P注解验证方法可访问性确保返回简单类型8. 扩展与定制8.1 自定义组件你可以实现这些接口来扩展功能ChatMemoryStoreEmbeddingStoreEmbeddingModelTokenizer8.2 多模型路由根据场景选择不同模型Bean public ChatModelRouter modelRouter(OpenAiChatModel gpt4, OpenAiChatModel gpt3) { return message - { if (message.contains(复杂)) { return gpt4; } return gpt3; }; }8.3 本地模型集成使用Ollama运行本地模型dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-ollama/artifactId version1.1.0/version /dependency配置langchain4j: ollama: chat-model: base-url: http://localhost:11434 model-name: llama2我在内部知识管理系统使用了这种方案既保证了数据安全又节省了API成本。