大模型应用开发不再是 Python 的专属领域。对于广大的 Java 开发者来说，LangChain4j 提供了一套符合 Java 生态习惯的 API，让你可以在 Spring Boot、Quarkus 或普通 Maven 项目中，以类型安全、面向对象的方式接入大语言模型、构建 RAG 检索增强生成、编排工具调用（Function Calling）以及实现多轮对话记忆。

本文是一篇面向初学者的入门教程，从环境准备开始，逐步带你完成第一个 LangChain4j 程序，并理解其核心抽象模型，最后给出一个可运行的实战示例。

一、LangChain4j 是什么

LangChain4j 是 LangChain 生态在 Java 侧的实现，目标是简化大语言模型（LLM）与 Java 应用的集成。它并不强制绑定某一家模型厂商，而是通过统一的抽象层，让你可以在 OpenAI、Azure OpenAI、通义千问、Ollama 本地模型等不同后端之间切换。

它的核心价值可以概括为三点：

• 统一抽象：用同一套接口对接不同模型提供商，降低替换成本。
• 开箱即用：内置对话记忆、提示词模板、RAG、工具调用等常见能力。
• Java 原生：基于接口和注解的声明式编程，与 Spring 生态天然契合。

二、环境准备

在开始编码之前，请确认本地环境满足以下条件：

项目	要求
JDK	17 及以上
构建工具	Maven 3.8+ 或 Gradle 7+
模型服务	OpenAI API Key，或本地 Ollama

本文示例使用 Maven 构建。在 pom.xml 中引入核心依赖：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>0.35.0</version>
</dependency>

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>0.35.0</version>
</dependency>

提示：版本号请以 Maven Central 上的最新稳定版为准，不同版本之间 API 可能存在细微差异。

三、第一个 LangChain4j 程序

下面这段代码演示了最基础的调用方式：创建一个 ChatLanguageModel 实例，然后发送一条用户消息并打印模型回复。

import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;

public class HelloLangChain4j {

    public static void main(String[] args) {
        ChatLanguageModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-4o-mini")
                .temperature(0.7)
                .build();

        String answer = model.generate("用一句话解释什么是 LangChain4j");
        System.out.println(answer);
    }
}

运行后，控制台会输出模型生成的回答。这里有几个关键点值得注意：

• apiKey 建议通过环境变量注入，不要硬编码在源码中。
• modelName 决定实际调用的模型，不同模型的价格和能力差异较大。
• temperature 控制输出随机性，取值越低回答越稳定。

四、核心抽象模型

理解 LangChain4j 的关键，在于掌握它提供的几个核心抽象。它们构成了后续所有高级能力的基础。

4.1 ChatLanguageModel

这是最基础的模型接口，负责接收消息并返回文本结果。它适合简单的单轮问答场景。

4.2 ChatMemory 对话记忆

大模型本身是无状态的，ChatMemory 负责保存历史消息，让多轮对话具备上下文。常用的实现是 MessageWindowChatMemory，它按窗口大小保留最近若干条消息。

import dev.langchain4j.memory.ChatMemory;
import dev.langchain4j.memory.chat.MessageWindowChatMemory;

ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10);

4.3 AiServices 声明式接口

这是 LangChain4j 最具特色的能力。你只需要定义一个 Java 接口，框架会自动生成实现类，把方法调用转换为模型请求。

import dev.langchain4j.service.MemoryId;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.spring.AiService;

@AiService
public interface Assistant {

    @SystemMessage("你是一位耐心的 Java 技术顾问，回答要简洁准确。")
    String chat(@MemoryId String sessionId, @UserMessage String message);
}

通过 @SystemMessage 设定角色，通过 @MemoryId 区分不同会话，代码可读性远高于手工拼接提示词。

五、实战：带记忆的对话助手

下面把前面的知识点组合起来，构建一个支持多轮对话的助手。这里使用 Spring Boot 集成方式。

import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;

public class ChatAssistantDemo {

    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)
                .chatMemory(MessageWindowChatMemory.withMaxMessages(20))
                .build();

        System.out.println(assistant.chat("session-1", "我叫小明，正在学习 LangChain4j"));
        System.out.println(assistant.chat("session-1", "我刚才说我叫什么？"));
    }
}

第二次提问时，模型能够正确回答“小明”，说明记忆机制已经生效。如果把 sessionId 换成另一个值，模型就不会记得之前的对话内容。

六、常见问题与注意事项

• API Key 泄露：务必使用环境变量或配置中心管理密钥，不要提交到代码仓库。
• 超时与重试：网络调用可能失败，建议在模型构建时配置超时时间，并在业务层做重试。
• Token 成本：记忆窗口越大，每次请求携带的历史越多，成本越高，需要根据场景权衡。
• 版本兼容：LangChain4j 迭代较快，升级前请阅读官方迁移说明。

七、总结

本文从环境准备出发，介绍了 LangChain4j 的基本用法、核心抽象以及一个带记忆的对话助手示例。掌握这些内容后，你可以进一步探索 RAG 检索增强生成、工具调用和流式输出等进阶能力，把大模型真正融入 Java 业务系统。