LangChain4j 深度解析：@AiService、RAG 与 20+ Provider——Java AI 的生态之王

📚 本文是「Java 大模型框架专题」系列第 3 篇。全系列 5 篇，建议按序阅读：

1. [总纲] 2026 Java 大模型框架选型终极指南：Spring AI vs LangChain4j vs AgentScope Java 深度横评
2. [深度] Spring AI 2.0 深度解析
3. [深度] LangChain4j 深度解析（本篇）
4. [深度] AgentScope Java 深度解析
5. [实战] 同一需求三套写法：带工具调用的 RAG 助手三框架实战对比

---

写在前面：它凭什么成为"事实标准"

先破除一个高频误区：LangChain4j 不是 Python LangChain 的 Java 移植，而是一个独立设计、Java 原生的库（Apache 2.0，Java 17+）。截至 2026 年 10 月稳定版 1.22.0，以 ~13k Star 领跑 Java AI 生态。它最被人记住的，是那个 Java 味极浓的抽象——@AiService。

---

一、@AiService：声明式 AI 服务的魔法

LangChain4j 的核心思路是：你把 AI 能力写成一个接口，框架在运行时替你生成实现。这对"接口 + 注解"的 Java 肌肉记忆极度友好。

interface Assistant {

    @SystemMessage("你是资深 Java 架构师，回答要给出理由和代码")
    String chat(@UserMessage String question);

    @SystemMessage("根据以下资料回答问题，并标注来源：\n{{information}}")
    String rag(@UserMessage String question, @V("information") String information);
}

// 装配
Assistant assistant = AiServices.builder(Assistant.class)
        .chatLanguageModel(model)          // 任意 Provider 的 ChatModel
        .build();

String answer = assistant.chat("什么是 RAG？");

结构化输出

record Person(String firstName, String lastName, LocalDate birthDate) {}

interface Extractor {
    @UserMessage("从这段文本提取人物信息：{{it}}")
    Person extract(String text);
}

流式 & 非阻塞（1.20 起）

LangChain4j 是三者中响应式能力最彻底的：方法返回 Flux<String> 走流式，返回 CompletableFuture/CompletionStage 走异步，返回 Flow.Publisher 走背压流——执行模式由方法的返回类型自动决定，且非阻塞能力一路打通到工具调用、记忆、检索。

interface StreamingAssistant {
    Flux<String> chat(String question);            // 流式
    CompletableFuture<String> chatAsync(String q); // 异步非阻塞
}

---

二、RAG 全流程拆解

RAG 是 LangChain4j 的看家本领，也是它生态优势最直观的体现。完整管线分"写入"和"查询"两段：

写入（离线）：文档 → 分块 → 向量化 → 入库

EmbeddingStore<TextSegment> store = EmbeddingStoreFactory.pgvector(...); // 或 InMemory
EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder()...build();

// 切块 + 向量化 + 写入（一站式）
DocumentSplitter splitter = DocumentSplitters.recursive(500, 50);
for (TextSegment seg : splitter.split(doc)) {
    store.add(embeddingModel.embed(seg).content(), seg);
}

查询（在线）：问题 → 检索 → 增强 → 生成

ContentRetriever retriever = EmbeddingStoreContentRetriever.builder()
        .embeddingStore(store)
        .embeddingModel(embeddingModel)
        .maxResults(3)
        .minScore(0.7)
        .build();

Assistant assistant = AiServices.builder(Assistant.class)
        .chatLanguageModel(model)
        .contentRetriever(retriever)   // 自动把检索结果注入 @V("information")
        .build();

这里的 @V("information") 会自动被检索到的上下文填充——你不需要手动拼接 prompt。这是 LangChain4j RAG 体验最顺滑的地方。

---

三、工具调用与 Agent

class Calculator {
    @Tool("计算两个浮点数之和")
    double add(double a, double b) { return a + b; }
}

Assistant assistant = AiServices.builder(Assistant.class)
        .chatLanguageModel(model)
        .tools(new Calculator())   // 注入后自动参与工具调用循环
        .build();

对更复杂的多步任务，LangChain4j 提供了 Agent/AiServices 的 agentic 能力，以及 langchain4j-agentic-* 模块；langchain4j-guardrails 则给输出加了护栏。

---

四、ChatMemory 记忆管理

ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10);

Assistant assistant = AiServices.builder(Assistant.class)
        .chatLanguageModel(model)
        .chatMemory(memory)          // 自动维护多轮上下文
        .chatMemoryProvider(memoryId -> /* 按会话隔离的记忆 */)
        .build();

多租户/多会话场景用 ChatMemoryProvider 按 memoryId 隔离，避免串号。

---

五、Guardrails 与可观测性

• Guardrails：输入/输出护栏，可拦截敏感信息、限制输出范围；
• 可观测性：langchain4j-otel 支持 OpenTelemetry GenAI 语义，把模型调用、工具调用、RAG 检索全链路打进你的观测体系——这是企业落地最容易被忽略、也最容易加分的一项。

---

六、模块化工程：几十个 Maven 模块怎么选

关注点	推荐模块
主库	langchain4j
Provider	langchain4j-open-ai / -anthropic / -ollama / -google-ai-gemini…
向量库	langchain4j-pgvector / -milvus / -elasticsearch / -chroma…
MCP	langchain4j-mcp
Spring 集成	langchain4j-spring-boot-starter（Boot 3.5+ 与 Boot 4 双 Starter）
Jackson 3	langchain4j-jackson3（可选，不引入则默认 Jackson 2）

关键点：Jackson 3 是可选依赖、Boot 双 Starter 齐发——这意味着你不必先迁 Boot 4就能用上它，这也是它对 Boot 3.x 团队最友好的一点。

---

七、什么时候选 LangChain4j

一句话：非 Spring 或混合技术栈、要最广的 Provider/向量库覆盖、做复杂 RAG/Agent、或团队还没/不想迁 Boot 4——选 LangChain4j。它的代价是概念更多、上手曲线更陡，需要一点时间把 AiServices/ChatMemory/ContentRetriever 这套心智理顺。

---

系列矩阵导航

• 🔗 [第 1 篇·总纲] 三框架选型深度横评（含分层定位图 + 决策树)
• 🔗 [第 2 篇·深度] Spring AI 2.0 深度解析
• 🔗 [第 4 篇·深度] AgentScope Java 深度解析
• 🔗 [第 5 篇·实战] 同一需求三套写法：RAG 助手三框架实战对比

---

本文数据截至 2026-11-02；API 细节以 LangChain4j 官方文档 为准。