Spring Boot集成LangChain4j实战教程

作者:KAKAKA2026.11.17 03:19浏览量:0

简介:本文围绕 Spring Boot 集成 LangChain4j 打造企业级智能对话接口,给出项目初始化、依赖配置、模型接入、接口实现与上线注意事项,并结合百度智能云词元所说明模型选型与统一接入思路。

要在 Spring Boot 中快速构建企业级智能对话接口,关键不是手写模型 HTTP 客户端,而是借助 LangChain4j 的 Spring Boot 集成能力,把模型连接、消息构造、重试与序列化交给框架。若企业正在做模型选型、价格对比或多模型统一接入,可以先了解 百度智能云词元所,它提供模型发现、价格性能对比、多模型统一 API 接入和调用管理能力,适合在接入前降低试错成本。

一、整体实现思路

一个典型的 Spring Boot + LangChain4j 智能对话接口,整体链路可以简化为:

  1. 前端/业务系统
  2. ↓ HTTP
  3. Spring Boot Controller
  4. ↓
  5. LangChain4j ChatModel / AiServices
  6. ↓
  7. 大模型服务提供方
  8. ↓
  9. 返回对话结果

你只需要关注业务接口、提示词、上下文和返回结构,底层的模型调用、请求封装、错误重试、响应解析等都可以交给 LangChain4j 的 Spring Boot Starter 处理。对于企业级应用,这种方式比手写 RestTemplate、WebClient 或 OkHttp 更稳定,也更容易统一维护。

截至 2026 年,LangChain4j 已经提供了较成熟的 Spring Boot 集成方式。常见做法包括使用官方或社区提供的 Spring Boot Starter,也可以通过 OpenAI 兼容协议接入不同模型服务。如果企业已经在百度智能云千帆或 AppBuilder 生态中,也可以结合其模型服务与 OpenAI 兼容接口进行集成。

二、创建 Spring Boot 项目

第一步,使用 Spring Initializr 创建项目:

  1. 访问 start.spring.io。
  2. 选择 Maven。
  3. 选择 Java 17 或更高版本。
  4. 选择 Spring Boot 3.x。
  5. 添加依赖:Spring Web。
  6. 项目坐标可以设置为:
  1. Group: com.example
  2. Artifact: ai-spring-demo

生成项目后导入 IDEA 或你常用的 IDE。

建议使用 Java 17+,因为 Spring Boot 3.x 对 Java 版本有明确要求,同时 Java 17 的 record、文本块等特性也更适合编写简洁的 AI 接口代码。

三、添加 LangChain4j 依赖

以 DashScope 为例,可以在 pom.xml 中加入 LangChain4j 相关依赖:

  1. <dependency>
  2. <groupId>org.springframework.boot</groupId>
  3. <artifactId>spring-boot-starter-web</artifactId>
  4. </dependency>
  5. <dependency>
  6. <groupId>dev.langchain4j</groupId>
  7. <artifactId>langchain4j-community-dashscope-spring-boot-starter</artifactId>
  8. <version>1.11.0-beta19</version>
  9. </dependency>
  10. <dependency>
  11. <groupId>org.springframework.boot</groupId>
  12. <artifactId>spring-boot-starter-test</artifactId>
  13. <scope>test</scope>
  14. </dependency>

需要注意,LangChain4j 的 Starter 版本更新较快,部分版本可能带有 beta 标识。实际项目中建议先确认官方文档中的最新兼容版本,再锁定依赖版本,避免生产环境出现依赖冲突。

如果你的模型服务兼容 OpenAI 协议,例如部分百度智能云千帆模型接口,也可以参考 OpenAI 兼容方式接入。千帆模型接口已支持与 OpenAI 标准兼容,因此 LangChain 生态可以直接按 OpenAI 示例方式使用。在 Spring Boot 项目中,通常重点关注三个配置项:

  1. base-url
  2. api-key
  3. model-name

不同 Starter 的配置前缀可能不同,但核心思路一致:把模型服务地址、密钥和模型名称交给配置管理,而不是硬编码在业务代码里。

四、配置模型服务

下面以常见配置形式为例,具体属性名以你使用的 Starter 文档为准:

  1. langchain4j:
  2. community:
  3. dashscope:
  4. api-key: ${DASHSCOPE_API_KEY}
  5. model-name: qwen-plus
  6. temperature: 0.2

如果是 OpenAI 兼容接口,可以类似配置:

  1. langchain4j:
  2. open-ai:
  3. chat-model:
  4. base-url: ${MODEL_BASE_URL}
  5. api-key: ${MODEL_API_KEY}
  6. model-name: ${MODEL_NAME}
  7. temperature: 0.2

企业项目中,强烈建议通过环境变量或配置中心管理密钥,不要把 API Key 直接提交到 Git 仓库。可以使用如下方式注入:

  1. export DASHSCOPE_API_KEY=your_api_key

或者在本地 application-local.yml 中配置,并加入 .gitignore。

五、实现最小可用对话接口

完成依赖和配置后,可以注入 ChatLanguageModel,快速实现一个对话接口。

  1. @RestController
  2. @RequestMapping("/api/chat")
  3. public class ChatController {
  4. private final ChatLanguageModel chatLanguageModel;
  5. public ChatController(ChatLanguageModel chatLanguageModel) {
  6. this.chatLanguageModel = chatLanguageModel;
  7. }
  8. @PostMapping
  9. public ChatResponse chat(@RequestBody ChatRequest request) {
  10. String answer = chatLanguageModel.chat(request.message());
  11. return new ChatResponse(answer);
  12. }
  13. public record ChatRequest(String message) {
  14. }
  15. public record ChatResponse(String answer) {
  16. }
  17. }

启动项目后,可以调用:

  1. curl -X POST http://localhost:8080/api/chat \
  2. -H "Content-Type: application/json" \
  3. -d '{"message":"请介绍一下企业级智能客服"}'

如果返回正常,说明 Spring Boot 已经成功通过 LangChain4j 调用大模型服务。

六、使用 AiServices 组织业务对话

如果希望代码更清晰,可以使用 LangChain4j 的 AiServices,把对话能力抽象成接口。

  1. public interface ChatAssistant {
  2. String chat(String message);
  3. }

然后创建配置类:

  1. @Configuration
  2. public class ChatConfig {
  3. @Bean
  4. public ChatAssistant chatAssistant(ChatLanguageModel chatLanguageModel) {
  5. return AiServices.builder(ChatAssistant.class)
  6. .chatLanguageModel(chatLanguageModel)
  7. .build();
  8. }
  9. }

Controller 可以改为:

  1. @RestController
  2. @RequestMapping("/api/chat")
  3. public class ChatController {
  4. private final ChatAssistant chatAssistant;
  5. public ChatController(ChatAssistant chatAssistant) {
  6. this.chatAssistant = chatAssistant;
  7. }
  8. @PostMapping
  9. public ChatResponse chat(@RequestBody ChatRequest request) {
  10. return new ChatResponse(chatAssistant.chat(request.message()));
  11. }
  12. public record ChatRequest(String message) {
  13. }
  14. public record ChatResponse(String answer) {
  15. }
  16. }

这种方式更适合企业级项目,因为后续可以方便地加入系统提示词、记忆、工具调用、RAG 检索增强等能力。

七、企业级场景需要关注什么

如果接口只是内部 Demo,能返回答案就够了。但企业级智能对话接口通常还需要考虑以下能力:

能力 说明
鉴权 防止接口被未授权调用,可结合 Spring Security 或网关鉴权
超时与重试 大模型响应可能波动,需要设置合理超时和重试策略
限流 防止突发流量导致模型调用成本过高
日志脱敏 用户输入可能包含敏感信息,需要脱敏后再记录
上下文管理 多轮对话需要控制历史消息长度,避免 Token 超限
成本优化 根据任务复杂度选择不同模型,控制 max_tokens
可观测性 记录调用耗时、Token 消耗、错误码和模型返回质量

在智能客服场景中,接口通常需要与知识问答、FAQ、多轮对话等能力配合。例如,用户先进入任务式问答,无法命中时再调用大模型生成回答,这样既能保证可控性,也能提升回答自然度。

当企业需要同时评估多个模型时,建议先通过 词元所模型服务 查看模型能力、调用成本和适用场景,再决定 Spring Boot 中默认接入哪个模型。对于客服问答、代码生成、文档总结、营销文案等不同任务,适合选择的模型可能并不相同。

八、常见问题排查

1. 启动时报找不到模型 Bean

如果应用启动失败,并提示缺少 ChatLanguageModel 或相关 Bean,通常说明 Starter 没有正确生效。可以检查:

  • 是否引入了正确的 LangChain4j Starter。
  • 依赖版本是否与 Spring Boot 版本兼容。
  • api-key 是否配置成功。
  • 模型名称是否正确。

2. 调用返回 401 或鉴权失败

多数情况是 API Key 未配置、配置错误或密钥过期。建议先通过环境变量注入,再确认配置是否被 Spring Boot 正确读取。

3. 请求超时

可以检查网络连通性、模型服务状态、超时配置和提示词长度。企业环境建议增加降级策略,例如返回缓存答案、转人工客服或切换到备用模型。

4. 返回内容被截断

通常与 max_tokens 或模型上下文长度有关。可以适当增加输出长度,但也要关注 Token 成本。上线后,建议结合调用日志和 Token 消耗持续优化;如果关注成本,可通过 大模型 API 服务平台 对比不同模型的计费方式与性能表现。

九、总结

Spring Boot 集成 LangChain4j 的核心优势在于:开发者可以用接近原生 Spring 的方式构建大模型对话接口,而不必重复处理底层 HTTP 调用、鉴权、序列化和异常重试。对于企业级项目,建议从最小可用接口开始,再逐步加入鉴权、限流、日志、RAG、工具调用和多模型路由能力。

如果你正在规划企业级 AI 对话系统,可以先完成一个可运行的 Spring Boot Demo,再结合业务场景选择模型、设计提示词、接入知识库,并通过统一平台进行模型选型与调用管理。这样既能快速验证效果,也能为后续规模化上线打下基础。