一、LongChain4j 核心定位与简介

1.1 什么是 LongChain4j

LongChain4j 是 Java 生态下的大语言模型（LLM）应用开发框架，灵感源自 Python 生态的 LangChain，专为 Java 开发者设计，用于简化基于 LLM 的复杂应用开发（如问答系统、智能对话、知识图谱交互、自动化代理等）。

其核心价值在于：封装 LLM 调用细节、提供标准化组件、支持组件灵活组合，让开发者无需关注底层 API 调用、请求封装、响应解析等重复工作，专注于业务逻辑的实现。

1.2 核心特点

• Java 原生适配：完全基于 Java 开发，支持 Java 8+，无缝集成 Spring Boot、Spring Cloud 等主流 Java 框架，符合 Java 开发者编程习惯。

• 多 LLM 支持：兼容主流大模型，如 OpenAI（GPT-3.5/4）、阿里云通义千问、百度文心一言、讯飞星火、本地模型（Llama 2、ChatGLM 等），切换模型无需大幅修改代码。

• 组件化设计：将 LLM 应用拆解为 Prompt、Chain、Agent、Memory、Tool 等标准化组件，组件可独立配置、灵活组合，降低复杂应用的开发难度。

• 轻量易用：API 设计简洁，入门成本低，无需掌握复杂的 LLM 底层原理，快速上手开发 Demo 及生产级应用。

• 可扩展性强：支持自定义组件（如自定义 Prompt 模板、自定义 Tool、自定义 Memory），适配不同业务场景的个性化需求。

1.3 与 Python LangChain 的区别

两者核心思想一致（组件化、链化调用），但适配不同技术栈，关键区别如下：

对比维度	LongChain4j	Python LangChain
技术栈	Java（8+），适配 Java 生态	Python，适配 Python 生态
易用性（对应生态）	Java 开发者无需切换语言，上手更快	Python 开发者更易上手，组件更丰富（起步早）
核心能力	覆盖主流组件，满足大部分 Java 后端 LLM 需求	组件极其丰富，支持复杂场景（如多 Agent 协作）
生产适配	更适配 Java 后端生产环境（稳定性、兼容性）	更适合快速原型开发、数据科学场景

1.4 适用场景

• Java 后端开发 LLM 相关应用（如智能客服、文档问答、接口调用助手）；

• 需要集成多 LLM，实现模型动态切换的场景；

• 需要结合 Java 现有业务系统（如数据库、接口、知识图谱）与 LLM 交互的场景；

• 轻量级、可扩展的 LLM 应用开发（避免重复封装 LLM 调用逻辑）。

二、环境搭建（入门必备）

2.1 前置条件

• JDK：8 及以上（推荐 JDK 11，兼容性更好）；

• 构建工具：Maven 3.6+ 或 Gradle 7.0+（本文以 Maven 为例）；

• 依赖管理：通过 Maven/Gradle 引入 LongChain4j 核心依赖及对应 LLM 的依赖；

• LLM 密钥：若使用在线模型（如 OpenAI、通义千问），需提前获取对应平台的 API 密钥；若使用本地模型，需部署模型服务（如 Llama 2 部署为 API 服务）。

2.2 Maven 依赖引入（核心）

LongChain4j 的核心依赖分为 核心包 和 模型适配包，按需引入对应模型的依赖即可。

2.2.1 核心依赖（必引）

<!-- LongChain4j 核心包 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-core</artifactId> <version>0.24.0</version> <!-- 最新版本可在 Maven 中央仓库查询 --> </dependency>

2.2.2 常用模型依赖（按需引入）

不同模型对应不同的依赖，以下是最常用的几种：

<!-- 1. OpenAI（GPT-3.5/4） --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-openai</artifactId> <version>0.24.0</version> </dependency> <!-- 2. 阿里云通义千问 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-qwen</artifactId> <version>0.24.0</version> </dependency> <!-- 3. 百度文心一言 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-ernie</artifactId> <version>0.24.0</version> </dependency> <!-- 4. 本地模型（如 Llama 2、ChatGLM，通过 OpenAI 兼容接口调用） --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-openai</artifactId> <version>0.24.0</version> </dependency> <!-- 5. 讯飞星火 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-xunfei</artifactId> <version>0.24.0</version> </dependency>

2.2.3 可选依赖（增强功能）

<!-- 记忆组件（用于对话上下文管理） --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-memory</artifactId> <version>0.24.0</version> </dependency> <!-- 工具组件（用于调用外部工具，如数据库、接口） --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-tool</artifactId> <version>0.24.0</version> </dependency> <!-- JSON 解析（部分场景需要） --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.15.2</version> </dependency>

2.3 版本说明

LongChain4j 处于快速迭代中，不同版本的 API 可能存在细微差异，建议使用 稳定版（如 0.24.0），最新版本可在 Maven 中央仓库 查询。

2.4 第一个 Demo（OpenAI 调用）

快速验证环境是否搭建成功，实现简单的文本生成功能（需提前获取 OpenAI API Key）。

2.4.1 代码实现

import dev.langchain4j.model.openai.OpenAiChatModel; public class FirstLongChain4jDemo { public static void main(String[] args) { // 1. 配置 OpenAI 模型（替换为自己的 API Key） String openAiApiKey = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; OpenAiChatModel model = OpenAiChatModel.builder() .apiKey(openAiApiKey) .modelName("gpt-3.5-turbo") // 模型名称，可选 gpt-4 .temperature(0.7) // 生成文本的随机性（0-1，越小越严谨） .maxTokens(1024) // 最大生成 tokens 数 .build(); // 2. 调用模型生成文本 String prompt = "请用一句话介绍 LongChain4j"; String response = model.generate(prompt); // 3. 输出结果 System.out.println("Prompt: " + prompt); System.out.println("Response: " + response); } }

2.4.2 运行说明

• 替换代码中的 openAiApiKey 为自己的 OpenAI API 密钥（需科学上网，或使用国内代理）；

• 运行 main 方法，若控制台输出模型响应结果，说明环境搭建成功；

• 常见问题：API Key 错误 → 提示认证失败；网络问题 → 超时异常，需检查网络连接或代理。

三、LongChain4j 核心组件详解

LongChain4j 的核心是 组件化，所有组件围绕“LLM 调用 + 业务逻辑”展开，核心组件包括：Prompt、Model、Chain、Memory、Agent、Tool，下面逐一详解。

3.1 Prompt（提示词）

3.1.1 核心定义

Prompt 是开发者传递给 LLM 的“指令 + 上下文”，是 LLM 生成响应的依据。LongChain4j 提供了 Prompt 相关工具，用于简化 Prompt 的构建、模板化、参数化。

3.1.2 两种 Prompt 构建方式

方式1：简单文本 Prompt（适用于简单场景）

即直接传递字符串，如 2.4 中的 Demo 所示，适合不需要动态参数的场景。

String prompt = "请解释什么是 Chain 组件"; String response = model.generate(prompt);

方式2：模板化 Prompt（适用于复杂场景）

当 Prompt 中需要动态替换参数（如用户输入、上下文信息）时，使用模板化 Prompt，避免重复编写固定文本。LongChain4j 支持 占位符替换，常用 PromptTemplate 类。

import dev.langchain4j.prompt.PromptTemplate; public class PromptTemplateDemo { public static void main(String[] args) { // 1. 定义 Prompt 模板（{question} 是占位符） String template = "用户问：{question}\n请用简洁的语言回答，不超过50字。"; PromptTemplate promptTemplate = PromptTemplate.from(template); // 2. 替换占位符（传递参数） String userQuestion = "LongChain4j 的 Memory 组件有什么用？"; String prompt = promptTemplate.apply(userQuestion); // 3. 调用模型（省略模型配置，同 2.4） // String response = model.generate(prompt); System.out.println("最终 Prompt: " + prompt); // 输出结果：用户问：LongChain4j 的 Memory 组件有什么用？ // 请用简洁的语言回答，不超过50字。 } }

3.1.3 高级 Prompt 技巧

• 指令清晰：在 Prompt 中明确告诉 LLM 输出格式（如“分点回答”“用 JSON 格式输出”）；

• 添加上下文：将历史对话、业务数据等上下文信息加入 Prompt，让 LLM 生成更精准的响应；

• 参数化模板：对于重复场景（如用户问答、文档总结），使用模板化 Prompt，提高开发效率。

3.2 Model（模型）

3.2.1 核心定义

Model 是 LongChain4j 与 LLM 交互的核心接口，封装了 LLM 的调用逻辑（请求构建、API 调用、响应解析）。开发者无需关注底层 API 细节，只需通过 Model 接口调用 LLM。

3.2.2 核心 Model 接口

LongChain4j 提供了两类核心 Model 接口，适配不同场景：

• ChatModel：适用于对话场景（多轮对话、上下文关联），如 OpenAiChatModel、QwenChatModel；

• LanguageModel：适用于单轮文本生成场景（如文本总结、翻译），功能更简洁。

大部分场景下，推荐使用 ChatModel，支持多轮对话，更贴合实际业务需求。

3.2.3 常用 Model 配置（以 OpenAiChatModel 为例）

OpenAiChatModel model = OpenAiChatModel.builder() .apiKey("sk-xxx") // 必传，模型 API 密钥 .modelName("gpt-3.5-turbo") // 模型名称，可选 gpt-4、gpt-4-turbo .temperature(0.5) // 随机性：0（严谨，固定输出）~1（灵活，随机输出） .maxTokens(2048) // 最大生成 tokens 数，避免输出过长 .timeout(Duration.ofSeconds(30)) // 超时时间，避免长时间阻塞 .topP(0.9) // 采样阈值，控制生成文本的多样性（0~1） .frequencyPenalty(0.1) // 频率惩罚，减少重复词汇（0~2） .presencePenalty(0.1) // 存在惩罚，鼓励生成新词汇（0~2） .build();

3.2.4 多模型切换（核心优势）

LongChain4j 支持快速切换不同 LLM，只需修改 Model 的实现类，无需修改后续调用逻辑。例如，将 OpenAI 切换为通义千问：

// 通义千问配置（需获取通义千问 API Key 和 Access Token） QwenChatModel qwenModel = QwenChatModel.builder() .apiKey("your-qwen-api-key") .accessToken("your-qwen-access-token") .modelName("qwen-turbo") .maxTokens(1024) .build(); // 调用逻辑与 OpenAI 完全一致，无需修改 String response = qwenModel.generate("介绍 LongChain4j");}

3.2.5 本地模型调用

若需使用本地模型（如 Llama 2、ChatGLM 3），需先将模型部署为 OpenAI 兼容接口（如使用 vllm、text-generation-webui 部署），然后通过 OpenAiChatModel 调用（修改 baseUrl 即可）：

// 本地模型（Llama 2）调用，部署后获取本地接口地址 OpenAiChatModel localModel = OpenAiChatModel.builder() .apiKey("empty") // 本地模型无需真实 API Key，填任意值即可 .baseUrl("http://localhost:8080/v1") // 本地模型接口地址 .modelName("llama-2-7b-chat") // 本地模型名称 .maxTokens(2048) .build(); String response = localModel.generate("请总结下面这段话...");

3.3 Chain（链）

3.3.1 核心定义

Chain 是 LongChain4j 的核心组件，用于将 多个操作（Prompt 构建、Model 调用、结果处理）串联起来，形成一个完整的流程。例如：“用户输入 → 构建 Prompt → 调用 Model → 解析响应 → 输出结果”，这个流程即可封装为一个 Chain。

Chain 的核心价值：将复杂流程拆解为多个步骤，每个步骤可独立配置、复用，降低代码耦合度。

3.3.2 常用 Chain 类型

1. SimpleChain（简单链）

最基础的 Chain，将“Prompt 模板 + Model 调用”串联起来，适用于单轮问答、文本生成场景。

import dev.langchain4j.chain.SimpleChain; import dev.langchain4j.prompt.PromptTemplate; import dev.langchain4j.model.openai.OpenAiChatModel; public class SimpleChainDemo { public static void main(String[] args) { // 1. 配置 Model OpenAiChatModel model = OpenAiChatModel.builder() .apiKey("sk-xxx") .modelName("gpt-3.5-turbo") .build(); // 2. 配置 Prompt 模板 PromptTemplate promptTemplate = PromptTemplate.from("请翻译这句话：{text}，翻译成{language}"); // 3. 构建 SimpleChain（串联 Prompt 模板和 Model） SimpleChain chain = SimpleChain.builder() .promptTemplate(promptTemplate) .chatModel(model) .build(); // 4. 调用 Chain（传递参数） String result = chain.run("Hello, LongChain4j!", "中文"); System.out.println("翻译结果：" + result); // 输出：翻译结果：你好，LongChain4j！ } }

2. SequentialChain（顺序链）

将多个 Chain 按顺序串联，前一个 Chain 的输出作为后一个 Chain 的输入，适用于多步骤流程。例如：“文本总结 → 总结内容翻译 → 翻译结果格式化”。

import dev.langchain4j.chain.SequentialChain; import dev.langchain4j.chain.SimpleChain; public class SequentialChainDemo { public static void main(String[] args) { // 1. 配置 Model（省略，同前） OpenAiChatModel model = ...; // 2. 构建第一个 Chain：文本总结 SimpleChain summarizeChain = SimpleChain.builder() .promptTemplate(PromptTemplate.from("请总结下面这段话：{text}，不超过30字")) .chatModel(model) .build(); // 3. 构建第二个 Chain：总结内容翻译（输入是第一个 Chain 的输出） SimpleChain translateChain = SimpleChain.builder() .promptTemplate(PromptTemplate.from("请将这句话翻译成英文：{text}")) .chatModel(model) .build(); // 4. 构建 SequentialChain，串联两个 Chain SequentialChain sequentialChain = SequentialChain.builder() .addChain(summarizeChain) // 第一步：总结 .addChain(translateChain) // 第二步：翻译 .build(); // 5. 调用顺序链（传递初始输入 text） String originalText = "LongChain4j 是 Java 生态下的 LLM 应用开发框架，支持多模型集成，组件化设计，易用性强。"; String finalResult = sequentialChain.run(originalText); System.out.println("最终结果：" + finalResult); // 输出流程：总结原文 → 将总结结果翻译成英文 → 输出英文总结 } }

3. 自定义 Chain（灵活适配业务）

若内置 Chain 无法满足业务需求，可通过实现 Chain 接口，自定义流程逻辑。

import dev.langchain4j.chain.Chain; // 自定义 Chain：先过滤敏感词，再调用 Model 生成响应 public class CustomChain implements Chain { private final OpenAiChatModel model; // 构造方法注入 Model public CustomChain(OpenAiChatModel model) { this.model = model; } @Override public String run(String input) { // 自定义步骤1：过滤敏感词（示例：过滤“敏感词”） String filteredInput = input.replace("敏感词", "***"); // 自定义步骤2：构建 Prompt String prompt = "请回答用户问题：" + filteredInput; // 自定义步骤3：调用 Model String response = model.generate(prompt); // 自定义步骤4：处理响应（如格式化） return "用户问题：" + filteredInput + "\n回答：" + response; } } // 使用自定义 Chain public class CustomChainDemo { public static void main(String[] args) { OpenAiChatModel model = OpenAiChatModel.builder() .apiKey("sk-xxx") .build(); CustomChain customChain = new CustomChain(model); String result = customChain.run("请解释什么是敏感词"); System.out.println(result); } }

3.4 Memory（记忆）

3.4.1 核心定义

Memory 用于 存储对话上下文信息，让 LLM 能够记住多轮对话中的历史内容，实现“连续对话”效果。例如：用户先问“介绍 LongChain4j”，再问“它支持多模型吗”，LLM 需通过 Memory 获取上一轮对话，理解“它”指代 LongChain4j。

若无 Memory，LLM 每一轮调用都是独立的，无法关联上下文。

3.4.2 常用 Memory 类型

1. ChatMemory（基础对话记忆）

最基础的 Memory，存储所有对话历史（用户消息 + 模型响应），适用于简单多轮对话场景。

import dev.langchain4j.memory.ChatMemory; import dev.langchain4j.memory.InMemoryChatMemory; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.model.chat.ChatResponse; public class ChatMemoryDemo { public static void main(String[] args) { // 1. 配置 Model OpenAiChatModel model = OpenAiChatModel.builder() .apiKey("sk-xxx") .modelName("gpt-3.5-turbo") .build(); // 2. 配置 Memory（内存级，重启后丢失） ChatMemory memory = InMemoryChatMemory.builder() .maxMessages(10) // 最大存储消息数，避免内存溢出 .build(); // 3. 多轮对话（通过 Memory 关联上下文） // 第一轮对话 String userMessage1 = "介绍一下 LongChain4j"; ChatResponse response1 = model.generate(memory.messages(), userMessage1); memory.addUserMessage(userMessage1); // 将用户消息加入 Memory memory.addAssistantMessage(response1.content()); // 将模型响应加入 Memory System.out.println("用户1：" + userMessage1); System.out.println("助手1：" + response1.content()); // 第二轮对话（关联上一轮） String userMessage2 = "它支持本地模型吗？"; ChatResponse response2 = model.generate(memory.messages(), userMessage2); memory.addUserMessage(userMessage2); memory.addAssistantMessage(response2.content()); System.out.println("用户2：" + userMessage2); System.out.println("助手2：" + response2.content()); } }

输出效果：助手2的回答会基于上一轮对 LongChain4j 的介绍，明确“它”指代 LongChain4j，无需用户再次说明。

2. 持久化 Memory（生产级场景）

InMemoryChatMemory 是内存级记忆，重启应用后会丢失，生产环境中需使用持久化 Memory，如基于 Redis、数据库的 Memory。LongChain4j 支持集成 Redis：

<!-- Redis Memory 依赖 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-redis</artifactId> <version>0.24.0</version> </dependency>

import dev.langchain4j.memory.redis.RedisChatMemory; import redis.clients.jedis.JedisPool; public class RedisMemoryDemo { public static void main(String[] args) { // 1. 配置 Redis 连接池 JedisPool jedisPool = new JedisPool("localhost", 6379); // 2. 配置 Redis Memory（每个用户对应一个 uniqueId，避免对话混淆） String userId = "user123"; // 每个用户的唯一标识 ChatMemory memory = RedisChatMemory.builder() .jedisPool(jedisPool) .uniqueId(userId) .maxMessages(20) .build(); // 3. 多轮对话（用法同 InMemoryChatMemory） OpenAiChatModel model = ...; // 后续调用同 ChatMemoryDemo，对话历史会持久化到 Redis，重启应用后不丢失 } }

3.4.3 Memory 核心配置

• maxMessages：最大存储消息数，避免对话历史过多导致 Prompt 过长、 tokens 消耗过大；

• uniqueId：用于区分不同用户/对话的唯一标识（仅持久化 Memory 需配置）；

• ttl：消息过期时间（仅持久化 Memory 支持），避免无效对话占用存储。

3.5 Tool（工具）

3.5.1 核心定义

Tool 是 LLM 调用外部资源的“桥梁”，用于让 LLM 能够执行特定操作（如调用数据库、调用 API、查询文档、执行代码等）。例如：用户问“今天的天气怎么样”，LLM 可通过 Tool 调用天气 API，获取实时天气后再生成响应。

LongChain4j 提供了内置 Tool，也支持自定义 Tool。

3.5.2 自定义 Tool（最常用场景）

通过注解 @Tool 标记方法，即可将其封装为 Tool，LLM 会根据用户问题，自动判断是否需要调用该 Tool。

import dev.langchain4j.agent.tool.Tool; // 自定义 Tool：获取当前时间 public class TimeTool { // @Tool 注解：标记该方法为 Tool，description 用于告诉 LLM 该 Tool 的用途 @Tool(description = "获取当前系统时间，格式为：yyyy-MM-dd HH:mm:ss") public String getCurrentTime() { SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"); return sdf.format(new Date()); } } // 自定义 Tool：调用天气 API（示例） public class WeatherTool { @Tool(description = "根据城市名称，获取该城市的实时天气，参数为城市名称（如：北京）") public String getWeather(String city) { // 模拟调用天气 API，返回天气信息 if ("北京".equals(city)) { return "北京，晴，10~22℃，微风"; } else if ("上海".equals(city)) { return "上海，多云，12~20℃，东风3级"; } else { return "暂未获取到" + city + "的天气信息"; } } }

3.5.3 Tool 的使用（结合 Agent）

Tool 通常与 Agent 配合使用（Agent 负责判断是否需要调用 Tool、调用哪个 Tool、如何处理 Tool 的返回结果），下面结合 Agent 演示 Tool 的使用。

3.6 Agent（智能代理）

3.6.1 核心定义

Agent 是“智能决策者”，能够根据用户问题、对话上下文（Memory），自动判断：

• 是否需要调用 Tool（无需调用则直接让 Model 生成响应）；

• 调用哪个/哪些 Tool（若有多个 Tool）；

• 如何处理 Tool 的返回结果（如将结果整合为自然语言响应）。

Agent 是 LongChain4j 实现复杂 LLM 应用的核心组件，适用于需要 LLM 自主决策、调用外部资源的场景（如智能助手、自动化办公）。

3.6.2 常用 Agent 类型：ReActAgent

ReActAgent 是最常用的 Agent，遵循“思考 → 行动 → 观察 → 思考”的循环逻辑，适合大部分场景。

import dev.langchain4j.agent.ReActAgent; import dev.langchain4j.memory.InMemoryChatMemory; import dev.langchain4j.model.openai.OpenAiChatModel; public class ReActAgentDemo { public static void main(String[] args) { // 1. 配置 Model OpenAiChatModel model = OpenAiChatModel.builder() .apiKey("sk-xxx") .modelName("gpt-3.5-turbo") .build(); // 2. 配置 Memory（关联对话上下文） InMemoryChatMemory memory = InMemoryChatMemory.builder() .maxMessages(10) .build(); // 3. 实例化自定义 Tool TimeTool timeTool = new TimeTool(); WeatherTool weatherTool = new WeatherTool(); // 4. 构建 ReActAgent（注入 Model、Memory、Tool） ReActAgent agent = ReActAgent.builder() .chatModel(model) .chatMemory(memory) .tools(timeTool, weatherTool) // 传入多个 Tool .build(); // 5. 调用 Agent 处理用户问题 // 场景1：不需要调用 Tool（直接回答） String response1 = agent.chat("介绍一下 LongChain4j"); System.out.println("用户1：介绍一下 LongChain4j"); System.out.println("助手1：" + response1); // 场景2：需要调用 Tool（获取当前时间） String response2 = agent.chat("现在是什么时间？"); System.out.println("用户2：现在是什么时间？"); System.out.println("助手2：" + response2); // 场景3：需要调用 Tool（获取天气） String response3 = agent.chat("北京今天的天气怎么样？"); System.out.println("用户3：北京今天的天气怎么样？"); System.out.println("助手3：" + response3); } }

3.6.3 Agent 核心配置

• chatModel：用于决策和生成响应的 LLM；

• chatMemory：用于存储对话上下文，辅助 Agent 决策；

• tools：Agent 可调用的 Tool 集合；

• maxIterations：最大决策循环次数，避免 Agent 陷入无限循环；

• temperature：决策的随机性，0 更严谨，1 更灵活。

四、实操案例（综合运用核心组件）

下面实现一个 智能问答助手，综合运用 Prompt、Model、Chain、Memory、Tool、Agent 组件，实现以下功能：

• 支持多轮对话（Memory）；

• 可获取当前时间、城市天气（Tool）；

• 可回答 LongChain4j 相关问题（Prompt + Model）；

• 自动判断是否需要调用 Tool（Agent）。

4.1 完整代码实现

import dev.langchain4j.agent.ReActAgent; import dev.langchain4j.memory.InMemoryChatMemory; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.agent.tool.Tool; import java.text.SimpleDateFormat; import java.util.Date; // 1. 自定义 Tool：时间工具 class TimeTool { @Tool(description = "获取当前系统时间，格式为：yyyy-MM-dd HH:mm:ss，无需参数") public String getCurrentTime() { return new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date()); } } // 2. 自定义 Tool：天气工具 class WeatherTool { @Tool(description = "根据城市名称获取实时天气，参数为城市名称（如北京、上海），返回天气详情") public String getWeather(String city) { // 模拟调用天气 API，实际场景可替换为真实 API 调用 return switch (city) { case "北京" -> "北京：晴，气温8~20℃，东北风2级，空气质量优"; case "上海" -> "上海：多云，气温11~19℃，东南风3级，空气质量良"; case "广州" -> "广州：阴，气温15~23℃，南风2级，空气质量优"; default -> "暂未查询到「" + city + "」的实时天气，请确认城市名称是否正确"; }; } } // 3. 核心应用类 public class IntelligentAssistantDemo { public static void main(String[] args) { // 3.1 配置 OpenAI Model OpenAiChatModel model = OpenAiChatModel.builder() .apiKey("sk-xxx") // 替换为自己的 API Key .modelName("gpt-3.5-turbo") .temperature(0.6) .maxTokens(1024) .build(); // 3.2 配置 Memory（多轮对话支持） InMemoryChatMemory memory = InMemoryChatMemory.builder() .maxMessages(15) // 最多存储15条对话消息 .build(); // 3.3 实例化 Tool TimeTool timeTool = new TimeTool(); WeatherTool weatherTool = new WeatherTool(); // 3.4 构建 ReActAgent（智能决策核心） ReActAgent agent = ReActAgent.builder() .chatModel(model) .chatMemory(memory) .tools(timeTool, weatherTool) // 注入工具 .maxIterations(5) // 最大决策循环次数，避免无限循环 .build(); // 3.5 模拟多轮对话交互 String[] userQuestions = { "介绍一下 LongChain4j", "它支持自定义 Tool 吗？", "现在是什么时间？", "北京今天的天气怎么样？", "那上海呢？" }; for (String question : userQuestions) { System.out.println("用户：" + question); String response = agent.chat(question); System.out.println("助手：" + response); System.out.println("----------------------------------------"); } } }

4.2 运行结果说明

• 第1个问题：无需调用 Tool，Model 直接生成 LongChain4j 的介绍；

• 第2个问题：关联上一轮对话（Memory），无需调用 Tool，直接回答；

• 第3个问题：Agent 判断需要调用 TimeTool，获取当前时间后生成响应；

• 第4个问题：Agent 判断需要调用 WeatherTool，传入“北京”参数，获取天气后生成响应；

• 第5个问题：关联上一轮对话（Memory），知道用户问的是“上海的天气”，调用 WeatherTool 获取结果后响应。

4.3 生产级优化建议

• Memory 替换为 Redis 持久化，避免重启丢失对话；

• Tool 中加入异常处理（如 API 调用超时、参数错误）；

• 添加日志记录（记录 Agent 决策过程、Tool 调用情况、Model 响应），方便排查问题；

• 限制 Model 的 maxTokens 和 Agent 的 maxIterations，避免 tokens 消耗过大和无限循环；

• 多模型适配，可根据场景动态切换模型（如普通问题用通义千问，复杂决策用 GPT-4）。

五、进阶用法

5.1 集成 Spring Boot（生产级常用）

LongChain4j 可无缝集成 Spring Boot，通过依赖注入管理 Model、Chain、Agent 等组件，下面是简单示例。

5.1.1 引入依赖

<!-- Spring Boot 核心依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter</artifactId> <version>2.7.15</version> </dependency> <!-- LongChain4j 核心依赖 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-core</artifactId> <version>0.24.0</version> </dependency> <!-- OpenAI 依赖 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-openai</artifactId> <version>0.24.0</version> </dependency> <!-- Redis Memory 依赖（可选） --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-redis</artifactId> <version>0.24.0</version> </dependency>

5.1.2 配置文件（application.yml）

spring: application: name: longchain4j-springboot-demo # OpenAI 配置 openai: api-key: sk-xxx model-name: gpt-3.5-turbo max-tokens: 1024 temperature: 0.6 # Redis 配置（用于持久化 Memory，可选） redis: host: localhost port: 6379

5.1.3 配置类（注入组件）

import dev.langchain4j.agent.ReActAgent; import dev.langchain4j.memory.InMemoryChatMemory; import dev.langchain4j.model.openai.OpenAiChatModel; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class LongChain4jConfig { // 注入 OpenAI 配置 @Value("${openai.api-key}") private String openAiApiKey; @Value("${openai.model-name}") private String modelName; @Value("${openai.max-tokens}") private Integer maxTokens; @Value("${openai.temperature}") private Double temperature; // 1. 注入 Model @Bean public OpenAiChatModel openAiChatModel() { return OpenAiChatModel.builder() .apiKey(openAiApiKey) .modelName(modelName) .maxTokens(maxTokens) .temperature(temperature) .build(); } // 2. 注入 Memory（这里用内存级，生产可用 Redis） @Bean public InMemoryChatMemory chatMemory() { return InMemoryChatMemory.builder() .maxMessages(15) .build(); } // 3. 注入 Tool（自定义 Tool） @Bean public TimeTool timeTool() { return new TimeTool(); } @Bean public WeatherTool weatherTool() { return new WeatherTool(); } // 4. 注入 Agent @Bean public ReActAgent reActAgent(OpenAiChatModel model, InMemoryChatMemory memory, TimeTool timeTool, WeatherTool weatherTool) { return ReActAgent.builder() .chatModel(model) .chatMemory(memory) .tools(timeTool, weatherTool) .maxIterations(5) .build(); } }

5.1.4 业务层使用

import dev.langchain4j.agent.ReActAgent; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; @Service public class ChatService { @Autowired private ReActAgent reActAgent; // 对话接口 public String chat(String userQuestion) { return reActAgent.chat(userQuestion); } }

5.1.5 控制层（提供接口）

import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; @RestController public class ChatController { @Autowired private ChatService chatService; @PostMapping("/chat") public String chat(@RequestBody String userQuestion) { return chatService.chat(userQuestion); } }

5.2 文档问答（结合文档加载）

LongChain4j 支持加载本地文档（如 TXT、PDF、DOCX），将文档内容作为上下文，实现“文档问答”（用户提问，LLM 基于文档内容回答）。需引入文档加载依赖：

<!-- 文档加载依赖 --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId