LangChain4j 新版本的核心升级点 —— @AiService 声明式接口

@AiService 是 LangChain4j 的“声明式接口定义”，它让你只需要声明“我这个接口想用哪个模型”，框架就会自动创建并注入代理对象，像 FeignClient 一样方便。

一、示例

这段代码：

@AiService(wiringMode = AiServiceWiringMode.EXPLICIT,chatModel = "openAiChatModel"
)
public interface ConsultantService {String chat(String message);
}

是 LangChain4j 提供的一种声明式（Declarative）写法，

二、实现流程

当你使用 @AiService 标注接口时，LangChain4j + Spring Boot 会自动帮你完成：

1. 扫描注解

   • 框架扫描到 @AiService 标注的接口；

2. 自动创建代理对象

   • 根据 chatModel 指定的模型 Bean（如 openAiChatModel）；

   • 生成一个实现了该接口的动态代理；

3. 注册为 Spring Bean

   • Spring 自动把这个代理对象注册到 IOC 容器；

4. 自动注入使用

   • 你就能在 Controller 里直接 @Autowired 使用它。

三、@AiService 参数详解

完整注解定义如下（来自 dev.langchain4j.service.spring.AiService）：

参数	作用	示例
chatModel	指定要使用的模型 Bean 名称（通常是你在 @Configuration 里定义的 @Bean）	"openAiChatModel"
wiringMode	绑定方式，控制模型如何自动注入	AiServiceWiringMode.EXPLICIT（或 AUTOMATIC）
retriever	可选，指定检索器 Bean（用于 RAG 场景）	"vectorStoreRetriever"
memory	可选，指定记忆模块 Bean（对话上下文）	"memoryStore"
name	给该服务指定一个自定义 Bean 名称	"consultantService"
scope	控制 Bean 的作用域	"singleton"（默认）或 "prototype"
description	可选，提供接口的文字描述	"用于咨询聊天的AI服务"

四、wiringMode 两种模式区别

模式	含义	特点
AUTOMATIC（默认）	框架自动查找符合类型的 ChatModel Bean 并绑定	省事，但如果有多个模型 Bean 可能会冲突
EXPLICIT	明确指定模型名称（chatModel = "openAiChatModel"）	推荐用法，更安全、更清晰

五、怎么使用？

1️⃣ 定义模型 Bean

@Configuration
public class CommonConfig {@Beanpublic OpenAiChatModel openAiChatModel() {return OpenAiChatModel.builder().apiKey(System.getenv("OPENAI_API_KEY")).modelName("gpt-4o-mini").build();}
}

2️⃣ 定义 AI 接口

@AiService(wiringMode = AiServiceWiringMode.EXPLICIT,chatModel = "openAiChatModel"
)
public interface ConsultantService {String chat(String message);
}

3️⃣ 在 Controller 注入使用

@RestController
@RequestMapping("/chat")
public class ChatController {@Autowiredprivate ConsultantService consultantService;@GetMappingpublic String chat(@RequestParam String msg) {return consultantService.chat(msg);}
}

🌟 没有任何配置类、没有 .builder()、没有手动注入，Spring 会自动生成代理对象并注入。

六、和旧写法（CommonConfig 手动配置）的区别

手动配置介绍：
https://blog.csdn.net/laosao_66/article/details/152560763?spm=1011.2124.3001.6209

对比项	@AiService 声明式	AiServices.builder() 手动式
写法	一行注解即可	需要在 @Configuration 手动写 Bean
Bean 创建	自动由 Spring 管理	手动创建并注册
可读性	高（接口上就能看到依赖模型）	低（依赖关系隐藏在配置类）
灵活性	一般（框架自动生成）	高（可自定义代理逻辑）
推荐场景	快速集成、简单聊天服务	高度自定义、多模型组合、复杂逻辑
本质实现	Spring 扫描注解 → 动态代理	手动调用 AiServices.builder() 创建代理

总结对比

角度	旧方式（手动配置）	新方式（@AiService 声明式）
代码量	多	少
易读性	配置分散	结构集中
灵活性	高	一般
自动化程度	低	高
使用体验	像手动拼装 Bean	像声明 FeignClient 一样方便