一文入门Spring AI 与 LangChain4j 核心概念及重要 API
一、概述
Spring AI 和 LangChain4j 是 Java 生态中两个主流的 AI 应用开发框架。Spring AI 由 Spring 官方团队维护，深度融入 Spring Boot 生态，强调"约定优于配置"和企业级工程实践；LangChain4j 是 LangChain 思想的 Java 实现，以声明式接口（AiServices）为核心，提供轻量、灵活的 AI 编排能力。两者都覆盖了模型调用、对话记忆、工具调用、RAG 检索增强等核心场景，但设计哲学和 API 风格有明显差异。
二、Spring AI
2.1 整体架构
Spring AI 采用分层架构设计，自上而下为：应用调用层 → ChatClient（链式客户端）→ Advisors（拦截器链）→ ChatModel（模型抽象）→ 具体 Provider（OpenAI / Ollama / 通义千问等）。横向还包含 VectorStore（向量存储）、Document Pipeline（文档管线）、Tool Registry（工具注册）和 Observability（可观测性）等模块。
2.2 核心概念
ChatModel（模型抽象层）
ChatModel 是底层模型调用接口，屏蔽不同厂商 API 的差异。核心方法为 call(Prompt) 同步调用和 stream(Prompt) 流式调用。相关对象包括：Prompt（封装消息列表）、SystemMessage / UserMessage / AssistantMessage（消息类型）、ChatResponse（响应结果与元数据）、ChatOptions（温度、topP、maxTokens 等参数）。
ChatClient（业务层封装）
ChatClient 是面向业务开发的上层封装，提供流式 Builder API，依赖 ChatModel 但极大简化了调用代码。支持同步/流式调用、结构化输出（自动映射 POJO）、多轮对话、工具注册和 Advisor 拦截。
Advisors（可组合拦截器）
Advisor 是 Spring AI 的 AOP 式增强机制，可在请求前注入历史消息、检索结果，也可在响应后做过滤、日志、审计。内置 Advisor 包括：MessageChatMemoryAdvisor（对话记忆）、RetrievalAugmentationAdvisor（RAG 检索增强）、SimpleLoggerAdvisor（日志）、PromptTemplateAdvisor（模板处理）。也支持自定义 Advisor 实现鉴权、限流、敏感词过滤等。
VectorStore 与 RAG
RAG 流程分为离线索引和在线检索两阶段。离线阶段通过 DocumentReader 读取文档 → TextSplitter 切分 → EmbeddingModel 向量化 → VectorStore 写入。在线阶段由 RetrievalAugmentationAdvisor 自动召回相关片段并拼入 Prompt。Spring AI 内置了 Redis、PgVector、Milvus、Elasticsearch 等多种 VectorStore 实现。
Function Calling / Tools
Spring AI 支持声明式工具注册。通过 @Tool 注解或编程式回调暴露本地函数，框架自动推导参数 JSON Schema 并传递给模型，由模型决定是否调用。调用结果自动回传模型生成最终回答。
MCP（Model Context Protocol）
Spring AI 2.0 原生支持 MCP 协议，可接入外部 MCP Server（文件系统、数据库、代码平台等），使对话系统具备可扩展的外部工具能力。
2.3 重要 API 示例
基础同步调用：
java
@Autowired
private ChatClient chatClient;
String answer = chatClient.prompt()
.system("你是一位Java技术专家")
.user("解释什么是Spring IoC")
.call()
.content();流式输出：
java
Flux<String> stream = chatClient.prompt()
.user("写一首关于春天的诗")
.stream()
.content();结构化输出（自动映射 POJO）：
java
record CodeReview(String language, List<String> issues, int score) {}
CodeReview review = chatClient.prompt()
.user("审查这段代码: " + code)
.call()
.entity(CodeReview.class);多轮对话记忆：
java
ChatMemory memory = new InMemoryChatMemory();
String reply = chatClient.prompt()
.advisors(new MessageChatMemoryAdvisor(memory))
.user("我刚才问了什么？")
.call()
.content();工具调用：
java
@Component
public class WeatherTools {
@Tool(description = "查询指定城市的天气")
public String getWeather(String city) {
return weatherService.query(city);
}
}
String reply = chatClient.prompt()
.tools(weatherTools)
.user("北京今天天气怎么样？")
.call()
.content();ChatClient Builder 配置：
java
ChatClient client = ChatClient.builder(chatModel)
.defaultSystem("你是智能客服")
.defaultAdvisors(new MessageChatMemoryAdvisor(memory))
.defaultOptions(ChatOptions.builder().temperature(0.7).build())
.build();三、LangChain4j
3.1 整体架构
LangChain4j 的核心设计围绕 AiServices 展开。它通过 JDK 动态代理将 Java 接口方法转化为对大模型的调用，内部自动处理消息组装、记忆管理、工具调用和结果解析。整体架构可概括为：接口定义（声明式）→ AiServices 代理 → ChatLanguageModel → 具体 Provider。
3.2 核心概念
AiServices（声明式 AI 服务）
AiServices 是 LangChain4j 最核心的抽象。开发者只需定义一个 Java 接口，用注解描述提示词和参数绑定，框架自动生成代理实现。调用接口方法时，内部会解析注解、生成消息、读取记忆、携带工具说明、请求模型、执行工具回传、写入记忆并返回结果。
ChatLanguageModel（模型接口）
等价于 Spring AI 的 ChatModel，是与大模型交互的底层接口。支持 generate() 同步调用和 generate() 流式调用（返回 TokenStream）。
注解体系
LangChain4j 提供丰富的注解用于声明式配置：@SystemMessage（设定系统提示词）、@UserMessage（标记用户输入）、@V（将方法参数填入提示词模板变量）、@MemoryId（区分多用户会话）。
ChatMemory（对话记忆）
用于保存多轮对话上下文。MessageWindowChatMemory 按消息数量限制窗口大小；chatMemoryProvider 可按 @MemoryId 为不同用户创建独立记忆空间。
Tools（工具调用）
通过 @Tool 注解描述本地方法，框架自动生成工具说明（JSON Schema）传递给模型。模型返回工具调用请求由框架执行，结果再次发送给模型生成最终回答。
EmbeddingModel / EmbeddingStore / ContentRetriever（RAG 组件）
RAG 流程为：DocumentLoader 加载文档 → DocumentSplitter 切分 → EmbeddingModel 向量化 → EmbeddingStore 存储 → ContentRetriever 检索。查询时由 ContentRetriever 召回相关片段，注入 Prompt 后交给模型生成回答。
3.3 重要 API 示例
基础 AiServices 定义与调用：
java
interface Assistant {
@SystemMessage("你是一位友好的AI助手")
String chat(String userMessage);
}
Assistant assistant = AiServices.create(Assistant.class, chatModel);
String answer = assistant.chat("你好，介绍一下自己");模板变量绑定：
java
interface Translator {
@SystemMessage("你是专业翻译，将内容翻译为{{language}}")
String translate(@V("language") String lang, @UserMessage String text);
}
Translator translator = AiServices.create(Translator.class, chatModel);
String result = translator.translate("英文", "今天天气真好");带记忆的多用户对话：
java
interface CustomerService {
String chat(@MemoryId Long userId, @UserMessage String message);
}
CustomerService service = AiServices.builder(CustomerService.class)
.chatLanguageModel(chatModel)
.chatMemoryProvider(userId -> MessageWindowChatMemory.withMaxMessages(20))
.build();
String reply = service.chat(1001L, "我的订单到哪了？");工具调用：
java
class CalculatorTools {
@Tool("计算两个数的乘积")
double multiply(double a, double b) {
return a * b;
}
}
interface MathAssistant {
String solve(String question);
}
MathAssistant assistant = AiServices.builder(MathAssistant.class)
.chatLanguageModel(chatModel)
.tools(new CalculatorTools())
.chatMemory(MessageWindowChatMemory.withMaxMessages(10))
.build();
String answer = assistant.solve("123乘以456等于多少？");结构化输出：
java
record SentimentResult(String sentiment, double confidence) {}
interface Analyzer {
@UserMessage("分析以下文本的情感倾向: {{text}}")
SentimentResult analyze(@V("text") String text);
}
Analyzer analyzer = AiServices.create(Analyzer.class, chatModel);
SentimentResult result = analyzer.analyze("这个产品太棒了！");RAG 检索增强：
java
// 离线索引
EmbeddingModel embeddingModel = new AllMiniLmL6V2EmbeddingModel();
EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>();
Document doc = FileSystemDocumentLoader.loadDocument(Path.of("knowledge.pdf"));
List<TextSegment> segments = new DocumentByParagraphSplitter(300, 50).split(doc);
store.addAll(embeddingModel.embedAll(segments).content(), segments);
// 在线检索
ContentRetriever retriever = EmbeddingStoreContentRetriever.builder()
.embeddingStore(store)
.embeddingModel(embeddingModel)
.maxResults(5)
.minScore(0.7)
.build();
interface KnowledgeAssistant {
String answer(String question);
}
KnowledgeAssistant assistant = AiServices.builder(KnowledgeAssistant.class)
.chatLanguageModel(chatModel)
.contentRetriever(retriever)
.build();
String answer = assistant.answer("公司的退货政策是什么？");四、对比与选型
| 维度 | Spring AI | LangChain4j |
|---|---|---|
| 生态定位 | Spring Boot 官方组件，自动配置、Starter 依赖 | 独立轻量框架，不绑定 Spring（也有 Spring Boot Starter） |
| API 风格 | 链式 Builder（ChatClient.prompt().user().call()） | 声明式接口 + 注解（AiServices 代理） |
| 拦截/增强 | Advisors（AOP 式拦截器链） | 无显式拦截器，通过 AiServices 内部管线处理 |
| 工具调用 | @Tool 注解 + 编程式注册 | @Tool 注解，框架自动推导 Schema |
| RAG | VectorStore + RetrievalAugmentationAdvisor | EmbeddingStore + ContentRetriever |
| 结构化输出 | .entity(Class) 自动映射 | 接口返回值直接声明类型 |
| MCP 支持 | 2.0 原生支持 | 社区扩展支持 |
| 可观测性 | 内置 Micrometer 指标/追踪 | 需自行集成 |
| 适用场景 | 已有 Spring Boot 技术栈的企业项目 | 轻量级 AI 服务、快速原型、非 Spring 项目 |
选型建议： 如果项目已基于 Spring Boot，优先选择 Spring AI，可享受自动配置、依赖注入、可观测性等生态红利；如果追求极简代码量、声明式开发体验，或项目不依赖 Spring，LangChain4j 的 AiServices 模式更为直观。两者也可混用------例如在 Spring Boot 项目中用 LangChain4j 的 AiServices 定义接口，底层复用 Spring AI 的模型连接。