✅ LangChain4j AI Services 核心实战代码（2大高频场景）
基于官方文档「AI Services」，为你提供结构化输出+JSON模式配置、Spring Boot多AI Service协作两套可直接复制运行的完整代码，包含✅依赖配置、✅核心代码、✅调用示例、✅关键注解解释、✅避坑要点，完美贴合生产级开发规范。
📌 环境前置约束（必满足）：JDK 17+、Spring Boot 3.x、LangChain4j 0.26.0（版本统一）
🎯 场景一：结构化输出 + JSON模式配置（核心高频）
✅ 核心价值
解决LLM返回「非结构化文本」的痛点，让大模型严格返回指定Java POJO格式数据，无需手动解析JSON字符串；开启JSON模式后，LLM输出100%符合格式要求，彻底避免解析异常，是生产环境必备配置。
✅ 步骤1：完整Maven依赖（直接复制到pom.xml）
<?xml version="1.0" encoding="UTF-8"?><projectxmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.2.1</version><relativePath/></parent><groupId>com.example</groupId><artifactId>langchain4j-ai-service</artifactId><version>0.0.1-SNAPSHOT</version><properties><java.version>17</java.version><langchain4j.version>0.26.0</langchain4j.version></properties><dependencies><!-- Spring Web 基础依赖 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- LangChain4j Spring核心启动器 --><dependency><groupId>dev.langchain4j</groupId><artifactId>langchain4j-spring-boot-starter</artifactId><version>${langchain4j.version}</version></dependency><!-- OpenAI适配器（含JSON模式支持，可替换为Ollama/通义千问） --><dependency><groupId>dev.langchain4j</groupId><artifactId>langchain4j-open-ai-spring-boot-starter</artifactId><version>${langchain4j.version}</version></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build></project>✅ 步骤2：application.yml配置（开启JSON模式+密钥配置）
# 核心：开启JSON模式 + 模型参数优化，保证结构化输出准确性langchain4j:open-ai:api-key:sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx# 替换为你的真实密钥chat-model:model-name:gpt-3.5-turbo# 推荐3.5/4o，均完美支持JSON模式temperature:0.0# 结构化输出建议0，保证结果稳定无随机性timeout:60s# ✅ 关键配置：开启JSON模式（强制LLM输出标准JSON）response-format:json_object✅ 步骤3：定义结构化返回的POJO实体（核心）
根据业务需求定义任意Java实体类，支持嵌套对象、枚举、基础类型，LangChain4j会自动完成LLM输出 → POJO的映射。
packagecom.example.entity;importlombok.Data;importjava.util.List;/** * 示例：商品信息结构化实体（可根据业务自定义） */@Data// Lombok简化get/set，无Lombok可手动编写publicclassProductInfo{// 基础字段privateStringproductName;// 商品名称privateDoubleprice;// 商品价格privateIntegerstock;// 库存数量// 嵌套集合字段privateList<String>tags;// 商品标签（如：热销、新品）// 嵌套对象字段privateMerchantmerchant;// 商家信息/** * 嵌套实体类 */@DatapublicstaticclassMerchant{privateStringmerchantName;// 商家名称privateStringcontactPhone;// 联系电话}}✅ 步骤4：编写AI Service接口（声明式，无实现类）
核心特点：返回值直接指定POJO类型，框架自动完成「LLM JSON输出 → Java对象」的转换，零解析代码。
packagecom.example.service;importcom.example.entity.ProductInfo;importdev.langchain4j.service.SystemMessage;importdev.langchain4j.service.UserMessage;importdev.langchain4j.service.spring.AiService;/** * 结构化输出AI服务接口（核心） */@AiService// ✅ 标记为AI服务，框架自动生成代理实现publicinterfaceProductAnalysisService{/** * 从用户输入中提取商品信息，返回结构化POJO * @param userDesc 用户输入的商品描述文本 * @return 结构化的商品信息实体 */@SystemMessage({"你是一个专业的信息提取专家，严格按照要求提取数据并返回JSON格式","必须完全匹配指定的字段名，字段类型严格对应（价格为Double、库存为Integer）","无数据的字段填充null，禁止新增未定义的字段"})@UserMessage("从以下文本中提取商品信息：{{userDesc}}")ProductInfoextractProductInfo(@UserMessageStringuserDesc);}✅ 步骤5：调用测试（Controller+单元测试双版本）
✅ 方式1：Controller接口调用（Web测试）
packagecom.example.controller;importcom.example.entity.ProductInfo;importcom.example.service.ProductAnalysisService;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestParam;importorg.springframework.web.bind.annotation.RestController;@RestControllerpublicclassStructOutputController{@AutowiredprivateProductAnalysisServiceproductAnalysisService;// 测试地址：http://localhost:8080/extract?desc=苹果手机15Pro售价5999元，库存100台，标签有旗舰、5G，商家是苹果官方店，电话10086@GetMapping("/extract")publicProductInfoextract(@RequestParamStringdesc){// ✅ 直接返回POJO，框架自动完成所有转换returnproductAnalysisService.extractProductInfo(desc);}}✅ 方式2：单元测试（更便捷，无需启动Web）
packagecom.example;importcom.example.entity.ProductInfo;importcom.example.service.ProductAnalysisService;importorg.junit.jupiter.api.Test;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.boot.test.context.SpringBootTest;@SpringBootTestclassAiServiceApplicationTests{@AutowiredprivateProductAnalysisServiceproductAnalysisService;@TestvoidtestStructOutput(){StringuserDesc="华为Mate70售价4999元，库存200台，标签有鸿蒙、拍照、续航，商家是华为旗舰店，电话10010";ProductInfoproductInfo=productAnalysisService.extractProductInfo(userDesc);// 直接操作Java对象，无需解析JSONSystem.out.println("商品名称："+productInfo.getProductName());System.out.println("商品价格："+productInfo.getPrice());System.out.println("商家名称："+productInfo.getMerchant().getMerchantName());}}✅ 结构化输出核心要点（避坑）
- ✅
response-format: json_object是强制配置，缺失则LLM可能返回非JSON文本，导致转换失败； - ✅
temperature: 0.0建议配置，结构化输出追求「确定性」，该参数可避免LLM生成随机内容； - ✅ 系统提示词中明确字段约束（类型、非空、字段名），可大幅提升映射准确率；
- ✅ 支持的返回类型：
String/Boolean/Enum/任意POJO/List<POJO>，完全覆盖业务场景。
🎯 场景二：Spring Boot 多AI Service 协作（生产级必备）
✅ 核心价值
实际业务中，AI能力往往需要拆分、复用、组合（如：「意图识别」→「专业问答」→「结果格式化」），多AI Service协作可实现：
✅ 职责分离：不同Service负责不同AI能力，代码更整洁；
✅ 能力复用：单个Service可被多个业务模块调用；
✅ 灵活组合：结合Java原生逻辑（if/else/循环）实现复杂AI流程；
✅ 易测试：可单独Mock某个Service，不影响整体流程。
✅ 整体设计思路
本次实现3个AI Service协作完成「智能客服」流程：
📌 流程链路：用户提问 → 「意图识别Service」判断问题类型 → 路由到「技术问答Service」/「闲聊Service」 → 返回最终结果
✅ 步骤1：编写3个职责分离的AI Service接口
✅ ① 意图识别Service（负责判断用户问题类型）
packagecom.example.service;importdev.langchain4j.service.SystemMessage;importdev.langchain4j.service.UserMessage;importdev.langchain4j.service.spring.AiService;/** * 职责1：意图识别（判断用户问题是技术问题/闲聊） */@AiServicepublicinterfaceIntentRecognitionService{@SystemMessage({"你是意图识别专家，仅返回以下2个结果中的一个，不返回任何额外内容：","1. TECH_QUESTION（技术相关问题）","2. CHAT（闲聊、问候等非技术问题）"})@UserMessage("判断问题类型：{{userQuestion}}")StringrecognizeIntent(@UserMessageStringuserQuestion);}✅ ② 技术问答Service（负责解答Java/Spring技术问题）
packagecom.example.service;importdev.langchain4j.service.SystemMessage;importdev.langchain4j.service.UserMessage;importdev.langchain4j.service.spring.AiService;/** * 职责2：专业技术问答（Java/Spring方向） */@AiServicepublicinterfaceTechQaService{@SystemMessage({"你是资深Java架构师，精通Spring Boot全家桶，回答简洁、准确、干货","只回答技术问题，非技术问题直接回复「不支持该类型问题」"})@UserMessage("解答技术问题：{{question}}")StringanswerTechQuestion(@UserMessageStringquestion);}✅ ③ 闲聊Service（负责处理问候、闲聊等非技术问题）
packagecom.example.service;importdev.langchain4j.service.SystemMessage;importdev.langchain4j.service.UserMessage;importdev.langchain4j.service.spring.AiService;/** * 职责3：闲聊互动（处理问候、日常对话） */@AiServicepublicinterfaceChatService{@SystemMessage("你是一个友好的闲聊助手，语气亲切，回复简洁，仅处理非技术闲聊")@UserMessage("回复用户：{{message}}")Stringchat(@UserMessageStringmessage);}✅ 步骤2：编写「协作调度器」（核心：组合多AI Service）
创建普通Spring服务，注入所有AI Service，结合Java原生逻辑实现路由、组合，这是多Service协作的核心入口。
packagecom.example.service;importlombok.RequiredArgsConstructor;importorg.springframework.stereotype.Service;/** * 多AI Service协作调度器（核心） * 整合所有AI能力，对外提供统一入口 */@Service// 普通Spring服务，非AI Service@RequiredArgsConstructor// Lombok注入所有依赖，替代@AutowiredpublicclassAiAssistantDispatcher{// ✅ 注入3个AI ServiceprivatefinalIntentRecognitionServiceintentRecognitionService;privatefinalTechQaServicetechQaService;privatefinalChatServicechatService;/** * 对外统一入口：接收用户提问，自动路由到对应AI Service */publicStringhandleUserQuestion(StringuserQuestion){// 1. 第一步：调用意图识别Service，判断问题类型Stringintent=intentRecognitionService.recognizeIntent(userQuestion);// 2. 第二步：基于意图，路由到不同的AI Service（Java原生逻辑）returnswitch(intent){case"TECH_QUESTION"->techQaService.answerTechQuestion(userQuestion);case"CHAT"->chatService.chat(userQuestion);default->"暂无法识别你的问题类型，请重新提问";};}}✅ 步骤3：编写测试接口（统一调用）
packagecom.example.controller;importcom.example.service.AiAssistantDispatcher;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestParam;importorg.springframework.web.bind.annotation.RestController;@RestControllerpublicclassAiDispatcherController{@AutowiredprivateAiAssistantDispatcheraiAssistantDispatcher;// 统一测试入口：http://localhost:8080/ai/ask?question=Spring Bean生命周期是什么// 切换问题测试：http://localhost:8080/ai/ask?question=你好呀@GetMapping("/ai/ask")publicStringask(@RequestParamStringquestion){// ✅ 统一调用调度器，无需关心内部多Service协作逻辑returnaiAssistantDispatcher.handleUserQuestion(question);}}✅ 多AI Service协作核心技巧（生产级）
✅ 技巧1：Service拆分原则
- 按能力维度拆分：意图识别、问答、翻译、提取、格式化，各司其职；
- 按业务维度拆分：订单AI服务、商品AI服务、用户AI服务，贴合业务模块；
- 按模型维度拆分：轻量任务用GPT-3.5，复杂任务用GPT-4o，低成本+高性能兼顾。
✅ 技巧2：进阶协作方式（复杂场景）
- 链式调用：A→B→C，前一个Service的输出作为后一个的输入（如：文本提取→翻译→格式化）；
- 分支调用：根据条件路由到不同Service（本次示例）；
- 并行调用：多Service同时执行，汇总结果（如：同时调用「情感分析」+「关键词提取」）；
- 嵌套调用：在一个Service中注入另一个Service（调度器模式）。
✅ 技巧3：优雅注入（替代@Autowired）
- 推荐使用
构造器注入（Lombok@RequiredArgsConstructor），符合Spring最佳实践； - 所有AI Service均为单例Bean，可安全注入、重复调用，无性能问题。
✅ 技巧4：单元测试与Mock（关键）
多Service协作时，若需单独测试某个Service，可通过Mock屏蔽其他依赖：
@SpringBootTestclassTechQaServiceTest{// Mock意图识别Service，避免真实调用@MockBeanprivateIntentRecognitionServiceintentRecognitionService;// 注入真实的技术问答Service@AutowiredprivateTechQaServicetechQaService;@TestvoidtestTechQa(){Stringresult=techQaService.answerTechQuestion("Spring Boot自动装配原理");System.out.println(result);}}📌 补充：AI Services 核心注解速查表（官方全量）
整理官方文档中所有高频注解，开发时直接查阅，无需翻文档：
| 注解 | 核心作用 |
|---|---|
@AiService | 标记接口为AI服务，框架自动生成代理实现类（核心注解） |
@SystemMessage | 定义系统提示词，约束AI角色/规则，支持静态文本/资源文件加载fromResource |
@UserMessage | 定义用户输入模板，支持{{变量}}占位符，绑定方法参数 |
@AssistantMessage | 定义AI历史回复，用于多轮对话上下文关联 |
@MemoryId | 标记会话ID，实现多用户/多会话的独立记忆隔离（多轮对话必备） |
@Tool | 标记工具方法，让AI自动决定是否调用该方法完成任务（Function Calling） |
@V("变量名") | 显式绑定方法参数到模板变量，Spring环境中可省略，自动匹配 |
🎯 最终总结
- 结构化输出+JSON模式：是LangChain4j AI Services最核心的生产级能力，解决了LLM输出格式混乱的痛点，返回值直接用POJO接收，零解析成本；
- 多AI Service协作：通过「职责拆分+调度组合」，让AI能力复用性、可维护性翻倍，完全贴合Spring开发思想；
- 核心优势：声明式接口+自动代理，无冗余代码，开发者只需关注「业务逻辑」，无需关心LLM底层调用、格式转换、记忆管理；
- 版本兼容：上述代码完全适配LangChain4j 0.26.0最新版，与Spring Boot 3.x无缝集成。
✅ 如需扩展其他能力（如：多轮对话记忆
@MemoryId、工具调用@Tool、RAG集成），可以随时告诉我，我会为你补充对应的完整代码示例~
