一、引言介绍
什么是 LangChain4j?
LangChain4j 的目标是简化将 LLM(大语言模型)集成到 Java 应用程序中的过程。
主要特性:
- 统一 API:提供统一的接口调用不同的 LLM 提供商(如 OpenAI、Google Vertex AI)和嵌入存储(如 Pinecone、Milvus)。支持 15+ 个 LLM 提供商和 20+ 个嵌入存储,切换供应商无需重写代码。
- 全面的工具箱:包含从低级提示模板、聊天记忆管理、函数调用到高级模式如代理和 RAG 的工具。提供接口及基于常见技术的即用型实现。
- 丰富的示例:官方提供大量示例,展示如何创建各种 LLM 驱动的应用程序。
架构分层:
- 低级抽象:拥有最多自由度,使用底层组件(如 ChatModel、EmbeddingStore),需编写更多胶水代码。
- 高层次抽象:通过 AI 服务(AI Services)等高级 API 交互,隐藏复杂性,采用声明式处理方式。
简单来说,框架分为两部分:ChatModel 相关对象用于调用大模型 API 进行对话;AI Service 服务类用于实现拓展功能(如 Memory、RAG、Prompt 等)。两者结合可构建完整的 AI 应用。
二、搭建环境
LangChain4j 支持与多种 LLM 提供商和向量存储集成。每个集成有独立的 Maven 依赖。
环境要求:
- JDK 版本:最小支持 JDK 17(建议使用 JDK 21)。
- Spring Boot:支持 Spring Boot 3.x 系列及以上(底层依赖 Spring 6+、Jakarta EE 9+,不兼容 Spring Boot 2.x)。
1. 引入 Maven 依赖
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
<version>1.12.2-beta22</version>
</dependency>
2. 初始配置
初始化一个 OpenAiChatModel。官方推荐将密钥放在环境变量中,此处为方便演示放在 application.yml 中。
langchain4j:
open-ai:
chat-model:
api-key: ${OPENAI_API_KEY}
model-name: deepseek-chat
log-requests: true
base-url: https://api.deepseek.com
若需要使用流式消息,配置如下:
langchain4j.open-ai.streaming-chat-model.api-key=${OPENAI_API_KEY}
3. 获取 AI 接口密钥
以 DeepSeek 为例(量大且便宜)。进入 API 开放平台选择密钥管理,创建 apiKey。充值余额后,将 key 粘贴到 yml 文件的 api-key 后面。
官方建议示例:
String apiKey = System.getenv("OPENAI_API_KEY");
三、测试
基础 ChatModel 调用
@RestController
public class ChatController {
@Autowired
private ChatModel chatModel;
@RequestMapping("/chat")
public String toChat(@RequestParam(value = "message") String message) {
return chatModel.chat(message);
}
}
单元测试:
@Test
public void test2() {
String response = chatController.toChat("你好,AI!");
System.out.println("response:" + response);
}
请求会被转换为 JSON 格式的 POST 请求,API Key 加入请求头 Authorization 校验,Body 包含模型名称及是否流式等信息。
四、对话进阶
一、AiService 初识
为使用更多功能,推荐使用 AiService。
1. 引入依赖
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-spring-boot-starter</artifactId>
<version>1.12.2-beta22</version>
</dependency>
该依赖自动配置 AI 服务、RAG、工具等功能。
2. 定义接口
@AiService
public interface Assistant {
@SystemMessage("你是小离")
String chat(String userMessage);
}
3. 注入与调用
@Autowired
private Assistant assistant;
@RequestMapping("/ServiceChat")
public String chat2(String msg) {
return assistant.chat(msg);
}
测试结果显示 AI 会根据系统消息设定返回内容。
二、AiService 的其他特性
1. 多模型支持
可在配置中定义多个模型,并通过 wiringMode 指定注入哪个模型。
langchain4j.open-ai.chat-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.chat-model.model-name=gpt-4o-mini
langchain4j.ollama.chat-model.base-url=http://localhost:11434
langchain4j.ollama.chat-model.model-name=llama3.1
@AiService(wiringMode = EXPLICIT, chatModel = "openAiChatModel")
interface OpenAiAssistant {
@SystemMessage("You are a polite assistant")
String chat(String userMessage);
}
@AiService(wiringMode = EXPLICIT, chatModel = "ollamaChatModel")
interface OllamaAssistant {
@SystemMessage("You are a polite assistant")
String chat(String userMessage);
}
2. 支持流式消息
使用 StreamChatModel 时,AI 服务返回类型可使用 Flux<String>。
@SystemMessage("你是小离")
Flux<String> chat2(String userMessage);
需引入 Reactor 依赖:
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-reactor</artifactId>
<version>1.0.0-beta3</version>
</dependency>
可通过 ChatModelListener 监听请求与响应:
@Configuration
class MyConfiguration {
@Bean
ChatModelListener chatModelListener() {
return new ChatModelListener() {
private static final Logger log = LoggerFactory.getLogger(ChatModelListener.class);
@Override
public void onRequest(ChatModelRequestContext requestContext) {
log.info("onRequest(): {}", requestContext.chatRequest());
}
@Override
public void onResponse(ChatModelResponseContext responseContext) {
log.info("onResponse(): {}", responseContext.chatResponse());
}
@Override
public void onError(ChatModelErrorContext errorContext) {
log.info("onError(): {}", errorContext.error().getMessage());
}
};
}
}
三、工具 (Tools)
工具相当于 LLM 的手臂,使其能触发操作。需提供清晰的工具名称、功能描述及参数说明。
示例:BookingTools
@Service
public class BookingTools {
@Tool("一个说你好的工具,如果你的满意值达到 90,请使用这个工具,并输入你的满意值")
public void sayHello(@P(value = "你的满意值 (0-100)", required = true) Integer Satisfied) {
if (Satisfied >= 90) {
System.out.println("哈喽哇,你好呀");
} else {
System.out.println("Ai,心情有点不太好");
}
}
}
测试:
@Test
public void test3() {
String response = chatController.toChat("你是谁?然后回复一下你的满意度");
System.out.println("response:" + response);
}
注意:若描述不清,AI 可能无法正确调用工具。
1. Tool 注解参数
name():工具名称,默认方法名。
value():工具描述。
returnBehavior():控制执行结果返回给 AI 还是直接返回给用户。
ReturnBehavior.TO_LLM(默认):用户 → AI → 工具 → AI 组织语言 → 用户。
ReturnBehavior.IMMEDIATE:用户 → AI → 工具 → 直接返回用户。
searchBehavior():控制工具是否对 AI 可见。
SearchBehavior.SEARCHABLE(默认):通过搜索策略匹配。
SearchBehavior.ALWAYS_VISIBLE:始终可见。
metadata():额外信息。
2. 工具注入上下文
在 AutoConfiguration.imports 文件中定义了 dev.langchain4j.spring.LangChain4jAutoConfig,导入了 AiServicesAutoConfig。该类遍历 Bean 容器中含有 @Tool 注解的方法,组装 ToolSpecification 并设置到 AiServiceFactory 的上下文中,最终在 DefaultAiServices 的代理实现中完成工具组装。
本文介绍了 LangChain4j 的基础环境搭建、ChatModel 调用、AiService 核心功能及工具集成原理,为后续深入 RAG 及会话存储打下基础。