LangChain4j 入门指南：从零开始构建 Java AI 应用
1. 什么是 LangChain4jLangChain4j 是一个面向 Java 生态的 LLM大语言模型应用开发框架其设计灵感来自 Python 生态中广受欢迎的 LangChain。它旨在为 Java 开发者提供一套简洁、统一的 API用于构建基于大语言模型的应用程序例如聊天机器人、文档问答、智能体Agent和 RAG检索增强生成应用。LangChain4j 的核心价值在于它把与大模型交互、提示词管理、记忆存储、工具调用、文档切分、向量检索等常见能力封装成开箱即用的组件让 Java 开发者无需深入底层细节就能快速搭建生产可用的 AI 应用。2. 环境准备在开始编写代码之前我们需要准备好开发环境。LangChain4j 基于 Java 17 及以上版本并使用 Maven 或 Gradle 作为构建工具。同时你需要一个可用的 LLM API Key例如 OpenAI、Azure OpenAI、智谱 GLM 或本地部署的 Ollama。2.1 环境要求JDK17 或更高版本。构建工具Maven 3.8 或 Gradle 7.5。LLM 服务OpenAI、Azure OpenAI、智谱 GLM、Ollama 等任选其一。网络能够访问所选的 LLM 服务端点。2.2 创建 Maven 项目并添加依赖首先创建一个标准的 Maven 项目然后在pom.xml中添加 LangChain4j 的核心依赖。这里以 OpenAI 为例同时引入核心模块和 OpenAI 模块。dependencies dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependency /dependencies如果你使用的是 Gradle则在build.gradle中添加如下依赖dependencies { implementation dev.langchain4j:langchain4j:0.35.0 implementation dev.langchain4j:langchain4j-open-ai:0.35.0 }如果你希望使用智谱 GLM 或本地 Ollama只需将langchain4j-open-ai替换为对应的模块即可核心 API 用法保持一致。3. 第一个对话程序依赖配置完成后我们来编写第一个 LangChain4j 程序一个最简单的聊天对话。下面的代码创建了一个 OpenAI 聊天模型并向模型发送一条消息然后打印模型的回复。import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.message.ChatMessage; import dev.langchain4j.message.UserMessage; public class HelloLangChain4j { public static void main(String[] args) { // 1. 创建聊天模型实例 ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .temperature(0.7) .build(); // 2. 构造用户消息 ChatMessage userMessage UserMessage.from(用一句话介绍 LangChain4j); // 3. 发送消息并获取回复 String answer model.generate(userMessage); // 4. 输出结果 System.out.println(answer); } }运行上述程序前请确保环境变量OPENAI_API_KEY已正确设置。程序运行后控制台会输出模型生成的回答。4. 提示词模板Prompt Template在实际应用中我们通常不会直接发送裸文本而是使用提示词模板来构造结构化的请求。LangChain4j 提供了PromptTemplate支持占位符替换让提示词更易维护和复用。import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.model.input.Prompt; import dev.langchain4j.model.input.PromptTemplate; import java.util.Map; public class PromptTemplateExample { public static void main(String[] args) { ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .build(); // 定义提示词模板使用 {{name}} 和 {{topic}} 作为占位符 PromptTemplate template PromptTemplate.from( 你好{{name}}请用三句话介绍{{topic}}。 ); // 填充模板变量 Prompt prompt template.apply(Map.of( name, 小明, topic, Java 编程 )); // 发送提示词并打印回复 String answer model.generate(prompt.text()); System.out.println(answer); } }使用提示词模板的好处是提示词与业务逻辑分离后续调整文案时无需修改 Java 代码只需改动模板字符串即可。5. 流式输出Streaming对于聊天机器人等交互式应用逐字返回结果能显著提升用户体验。LangChain4j 提供了流式接口StreamingChatLanguageModel通过回调函数实时接收增量内容。import dev.langchain4j.model.chat.StreamingChatLanguageModel; import dev.langchain4j.model.openai.OpenAiStreamingChatModel; import dev.langchain4j.model.output.Response; import dev.langchain4j.message.ChatMessage; import dev.langchain4j.message.UserMessage; import reactor.core.publisher.Flux; public class StreamingExample { public static void main(String[] args) throws InterruptedException { StreamingChatLanguageModel model OpenAiStreamingChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .build(); ChatMessage userMessage UserMessage.from(请写一首关于春天的短诗); // 订阅流式响应 FluxString flux model.generate(userMessage); flux.subscribe( token - System.out.print(token), // 每个增量片段 error - System.err.println(出错: error), () - System.out.println(\n[完成]) ); // 等待流式输出完成 Thread.sleep(15000); } }流式输出非常适合用于打字机效果的聊天界面。需要注意的是流式接口基于 Reactor 的Flux因此项目需要引入 Reactor 依赖。6. 对话记忆Memory多轮对话需要维护上下文记忆。LangChain4j 提供了ChatMemory和MessageWindowChatMemory可以自动保存历史消息让模型理解对话上下文。import dev.langchain4j.memory.ChatMemory; import dev.langchain4j.memory.chat.MessageWindowChatMemory; import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.service.AiServices; import dev.langchain4j.service.UserMessage; public class MemoryExample { // 定义一个 AI 服务接口 interface Assistant { String chat(String userMessage); } public static void main(String[] args) { ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .build(); // 创建窗口大小为 10 的对话记忆 ChatMemory memory MessageWindowChatMemory.builder() .maxMessages(10) .build(); // 通过 AiServices 绑定模型和记忆 Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(memory) .build(); // 第一轮对话 String answer1 assistant.chat(我叫小明我喜欢 Java。); System.out.println(AI: answer1); // 第二轮对话模型应能记住上文 String answer2 assistant.chat(我叫什么名字); System.out.println(AI: answer2); } }通过AiServicesLangChain4j 把模型、记忆和工具调用整合到一个类型安全的接口中这是构建复杂 Agent 应用的基础。7. 工具调用Function Calling工具调用让模型能够调用外部函数例如查询数据库、调用 REST API 或执行计算。LangChain4j 通过Tool注解将 Java 方法暴露给模型。import dev.langchain4j.agent.tool.Tool; import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.service.AiServices; import java.time.LocalDateTime; public class ToolCallingExample { // 定义一个工具类 static class DateTimeTools { Tool(获取当前日期和时间) public String currentDateTime() { return LocalDateTime.now().toString(); } Tool(计算两个整数的和) public int add(int a, int b) { return a b; } } // AI 服务接口 interface Assistant { String chat(String userMessage); } public static void main(String[] args) { ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .build(); Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(new DateTimeTools()) .build(); // 模型会自动决定是否调用工具 String answer1 assistant.chat(现在几点了); System.out.println(AI: answer1); String answer2 assistant.chat(请计算 123 加 456 等于多少); System.out.println(AI: answer2); } }当模型认为需要调用工具时LangChain4j 会自动执行对应的 Java 方法并把结果返回给模型最终生成自然语言回复。这一机制是构建智能体的核心能力。8. RAG 检索增强生成实战RAGRetrieval-Augmented Generation是当前最热门的应用模式之一。它通过把文档切分、向量化并存储到向量数据库中在回答问题时先检索相关片段再交给模型生成答案从而让模型基于私有知识库回答问题。8.1 添加向量存储依赖这里我们使用内存向量存储InMemoryEmbeddingStore作为演示无需额外部署数据库。在pom.xml中补充以下依赖dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-easy-rag/artifactId version0.35.0/version /dependency8.2 构建 RAG 问答系统import dev.langchain4j.data.document.Document; import dev.langchain4j.data.document.loader.FileSystemDocumentLoader; import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.memory.chat.MessageWindowChatMemory; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.model.openai.OpenAiEmbeddingModel; import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever; import dev.langchain4j.service.AiServices; import dev.langchain4j.store.embedding.EmbeddingStore; import dev.langchain4j.store.embedding.EmbeddingStoreIngestor; import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore; import java.nio.file.Path; import java.nio.file.Paths; public class RagExample { interface Assistant { String chat(String userMessage); } public static void main(String[] args) { // 1. 初始化模型 OpenAiChatModel chatModel OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .build(); EmbeddingModel embeddingModel OpenAiEmbeddingModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(text-embedding-3-small) .build(); // 2. 加载文档并切分 Path documentPath Paths.get(docs/company_manual.txt); Document document FileSystemDocumentLoader.loadDocument(documentPath); // 3. 创建内存向量存储并导入文档 EmbeddingStoreTextSegment embeddingStore new InMemoryEmbeddingStore(); EmbeddingStoreIngestor ingestor EmbeddingStoreIngestor.builder() .documentSplitter(new dev.langchain4j.data.document.splitter.RecursiveDocumentSplitter(500, 100)) .embeddingModel(embeddingModel) .embeddingStore(embeddingStore) .build(); ingestor.ingest(document); // 4. 构建检索器 EmbeddingStoreContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(embeddingModel) .maxResults(3) .build(); // 5. 组装 AI 服务 Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .chatMemory(MessageWindowChatMemory.withMaxMessages(20)) .contentRetriever(retriever) .build(); // 6. 提问 String answer assistant.chat(公司的年假政策是什么); System.out.println(AI: answer); } }在上述代码中我们完成了文档加载、切分、向量化、存储和检索的完整链路。当用户提问时系统会先从向量库中检索最相关的文档片段再结合这些片段生成回答从而显著提升回答的准确性和针对性。9. 结构化输出Structured Output在很多业务场景中我们希望模型返回结构化的 JSON 数据而不是自由文本。LangChain4j 支持将模型输出直接映射为 Java 对象。import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.service.AiServices; import dev.langchain4j.service.UserMessage; public class StructuredOutputExample { // 定义数据结构 record Person(String name, int age, String city) {} interface PersonExtractor { UserMessage(从文本中提取人物信息{{text}}) Person extractPerson(String text); } public static void main(String[] args) { ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .build(); PersonExtractor extractor AiServices.builder(PersonExtractor.class) .chatLanguageModel(model) .build(); Person person extractor.extractPerson(张三今年28岁住在上海。); System.out.println(姓名: person.name()); System.out.println(年龄: person.age()); System.out.println(城市: person.city()); } }通过定义 Java record 或 POJOLangChain4j 会自动引导模型输出符合结构的 JSON并完成反序列化。这大大简化了信息抽取、表单填充等场景的开发。10. 总结与进阶方向本文从零开始介绍了 LangChain4j 的核心用法包括环境搭建、基础对话、提示词模板、流式输出、对话记忆、工具调用、RAG 检索增强生成和结构化输出。掌握这些能力后你已经可以构建大多数常见的 LLM 应用。接下来你可以从以下几个方向继续深入多模态模型探索图片输入和视觉理解能力。复杂智能体结合多个工具和记忆构建自主决策的 Agent。生产级向量数据库将内存向量存储替换为 Milvus、PGVector 或 Elasticsearch。模型评估使用 LangChain4j 的评估模块对回答质量进行自动化评测。Spring Boot 集成LangChain4j 提供了langchain4j-spring-boot-starter可无缝融入 Spring 生态。希望这篇入门指南能帮助你快速上手 LangChain4j开启 Java AI 应用开发之旅。
)
