四散1. SpringBoot与LangChain4j整合概述
在当今AI技术快速发展的背景下，将大语言模型能力集成到Java应用中已成为提升开发效率的重要手段。LangChain4j作为Java生态中的LangChain实现，为开发者提供了便捷的AI能力接入方案。而SpringBoot作为Java领域最流行的应用框架，其与LangChain4j的整合能够极大简化AI功能的开发流程。
我最近在实际项目中深度使用了LangChain4j与SpringBoot的整合方案，发现这套组合能够实现：
- 通过简单的注解配置快速接入各类大语言模型
- 声明式AI服务开发模式显著降低代码复杂度
- 自动化的组件装配机制减少样板代码
- 完善的流式响应和可观测性支持
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与基础配置
2.1 项目依赖配置
首先需要在pom.xml中添加LangChain4j的SpringBoot启动器依赖。以OpenAI为例：
xml复制<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
<version>1.0.0-beta3</version>
</dependency>
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-spring-boot-starter</artifactId>
<version>1.0.0-beta3</version>
</dependency>
注意：LangChain4j要求Java 17+和SpringBoot 3.2+环境。如果使用其他模型提供商，需要替换对应的starter依赖。
2.2 基础参数配置
在application.properties中配置模型参数：
properties复制# OpenAI基础配置
langchain4j.open-ai.chat-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.chat-model.model-name=gpt-4
langchain4j.open-ai.chat-model.temperature=0.7
langchain4j.open-ai.chat-model.max-tokens=1000
# 日志记录配置
langchain4j.open-ai.chat-model.log-requests=true
langchain4j.open-ai.chat-model.log-responses=true
配置完成后，SpringBoot会自动创建ChatLanguageModel实例并注入到应用上下文中。
3. 核心使用模式详解
3.1 基础聊天模型使用
最简单的使用方式是直接注入ChatLanguageModel：
java复制@RestController
public class ChatController {
private final ChatLanguageModel chatModel;
public ChatController(ChatLanguageModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/chat")
public String chat(@RequestParam String message) {
return chatModel.generate(message);
}
}
这种模式适合简单的问答场景，但缺乏对话上下文管理能力。
3.2 声明式AI服务开发
更高级的用法是使用@AiService注解创建声明式AI服务：
java复制@AiService
public interface CustomerSupportAgent {
@SystemMessage("你是一名专业的客服代表，用中文回答用户问题")
@UserMessage("请回答以下客户问题：{{question}}")
String answerQuestion(@V("question") String question);
@SystemMessage("你是一名专业的客服代表")
@UserMessage("根据订单号{{orderId}}查询状态")
String checkOrderStatus(@V("orderId") String orderId);
}
SpringBoot启动时会自动生成接口实现类并注册为Bean，你可以像使用普通Service一样注入它：
java复制@RestController
public class SupportController {
private final CustomerSupportAgent agent;
public SupportController(CustomerSupportAgent agent) {
this.agent = agent;
}
@GetMapping("/support")
public String getSupport(@RequestParam String question) {
return agent.answerQuestion(question);
}
}
3.3 流式响应处理
对于需要实时响应的场景，可以使用Flux实现流式返回：
java复制@AiService
public interface StreamingAssistant {
@SystemMessage("你是一名乐于助人的助手")
Flux<String> chat(String userMessage);
}
@RestController
public class StreamingController {
private final StreamingAssistant assistant;
public StreamingController(StreamingAssistant assistant) {
this.assistant = assistant;
}
@GetMapping(value = "/stream-chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChat(@RequestParam String message) {
return assistant.chat(message);
}
}
需要在pom中添加reactor支持：
xml复制<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-reactor</artifactId>
<version>1.0.0-beta3</version>
</dependency>
4. 高级功能与定制化
4.1 自定义工具集成
LangChain4j允许将任意Java方法作为工具供AI调用：
java复制@Component
public class BookingTools {
@Tool("根据订单号查询订单详情")
public Booking getBookingDetails(
@P("订单号") String bookingNumber,
@P("客户姓名") String customerName,
@P("客户姓氏") String customerSurname) {
// 实现实际的订单查询逻辑
}
@Tool("取消指定订单")
public void cancelBooking(
@P("订单号") String bookingNumber,
@P("客户姓名") String customerName,
@P("客户姓氏") String customerSurname) {
// 实现订单取消逻辑
}
}
AI服务会自动发现这些工具并在需要时调用它们。
4.2 多模型配置与显式装配
当需要同时使用多个模型时，可以配置多个模型实例：
properties复制# OpenAI配置
langchain4j.open-ai.chat-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.chat-model.model-name=gpt-4
# Ollama本地模型配置
langchain4j.ollama.chat-model.base-url=http://localhost:11434
langchain4j.ollama.chat-model.model-name=llama3
然后通过显式装配指定每个AI服务使用的模型：
java复制@AiService(wiringMode = EXPLICIT, chatModel = "openAiChatModel")
interface OpenAiAssistant {
String chat(String message);
}
@AiService(wiringMode = EXPLICIT, chatModel = "ollamaChatModel")
interface LocalAssistant {
String chat(String message);
}
4.3 可观测性与监控
通过实现ChatModelListener接口可以监控模型调用情况：
java复制@Configuration
public class ObservabilityConfig {
@Bean
public ChatModelListener metricsChatModelListener() {
return new ChatModelListener() {
@Override
public void onRequest(ChatModelRequestContext context) {
// 记录请求指标
}
@Override
public void onResponse(ChatModelResponseContext context) {
// 记录响应指标
}
@Override
public void onError(ChatModelErrorContext context) {
// 记录错误指标
}
};
}
}
5. 实战经验与问题排查
5.1 常见问题解决方案
-
模型无法初始化
- 检查API密钥是否正确
- 确认网络连接正常，特别是使用本地模型时
- 验证SpringBoot版本是否符合要求
-
工具方法不被识别
- 确保工具类被@Component或@Service注解
- 检查方法参数是否使用@P注解标注
- 确认方法访问权限是public
-
流式响应不工作
- 检查是否添加了langchain4j-reactor依赖
- 确认控制器produces属性设置为MediaType.TEXT_EVENT_STREAM_VALUE
- 测试直接访问模型端点是否正常
5.2 性能优化建议
-
合理设置超时参数
properties复制langchain4j.open-ai.chat-model.timeout=60s -
启用响应缓存
java复制@AiService(cache = true) interface CachedAssistant { String chat(String message); } -
批量处理请求
java复制@AiService interface BatchAssistant { List<String> chatBatch(List<String> messages); }
5.3 安全最佳实践
-
敏感信息处理
java复制@AiService interface SafeAssistant { @Moderate String chat(@UserMessage String message); } -
输入验证
java复制@RestController public class SafeChatController { private final ChatLanguageModel model; @PostMapping("/safe-chat") public String safeChat(@RequestBody @Valid ChatRequest request) { return model.generate(request.getMessage()); } } -
权限控制
java复制@RestController public class SecureChatController { private final ChatLanguageModel model; @PreAuthorize("hasRole('USER')") @PostMapping("/secure-chat") public String secureChat(@RequestBody String message) { return model.generate(message); } }
6. 扩展应用场景
6.1 检索增强生成(RAG)
结合向量数据库实现知识增强：
java复制@AiService
public interface RagAssistant {
@SystemMessage("你是一名技术支持专家，根据提供的文档回答问题")
@UserMessage("问题：{{question}}")
String answerWithKnowledge(@V("question") String question,
@RagContent List<String> documents);
}
6.2 结构化输出
让AI返回结构化数据：
java复制@AiService
public interface StructuredAssistant {
@UserMessage("从文本中提取个人信息：{{text}}")
Person extractPersonInfo(@V("text") String text);
}
public record Person(String name, String phone, String email) {}
6.3 分类与路由
实现自动问题分类：
java复制@AiService
public interface ClassificationAssistant {
@UserMessage("将以下问题分类到合适的类别：{{question}}")
Category classifyQuestion(@V("question") String question);
}
public enum Category {
BILLING, TECHNICAL, ACCOUNT, OTHER
}
在实际项目中使用LangChain4j与SpringBoot整合时，我发现合理设计AI服务接口至关重要。将复杂流程拆分为多个专注的AI服务，比使用单一全能服务更容易维护和扩展。同时，为关键业务操作添加人工审核环节，可以显著提高系统可靠性。