Java 开发者是不是总觉得自己在边缘徘徊？kan着 Python 那边的 LangChain 玩得风生水起，咱们只Neng干瞪眼？别急，LangChain4j 这座桥梁Yi经搭好了。这不仅仅是一个库，geng是 Java 生态接入 LLM的一把瑞士军刀。今天咱们不搞那些虚头巴脑的理论，直接拆解这 14 节硬核课程，kankan你到底掌握了多少，或者说你准备好让你的代码“觉醒”了吗？

第一课：告别手动挡，拥抱 AI Services 的声明式魔法

回想一下Zui早我们是怎么调 LLM 的？是不是像写Zui原始的 JDBC 代码一样，拼装 JSON，手动管理 HTTP 请求，拿到字符串还得自己解析？那种日子太苦了。LangChain4j 的核心哲学就是：你定义接口，框架帮你干一切。

这就是 AI Services 的魅力。你只需要写一个普通的 Java 接口，加上几个注解，剩下的交给 JDK 动态代理。这感觉就像是你在给一个不知疲倦的实习生下指令，而且这个实习生还Neng自动理解上下文。

// 定义接口，告诉框架它的角色
interface Assistant {
    @SystemMessage
    String chat;
}
// 框架自动生成实现，像调本地方法一样调 AI
Assistant assistant = AiServices.create;
String answer = assistant.chat;

这背后的精妙之处在于，所有的方法dou是 default 的，Provider 唯一需要实现的只有 doChat。这种设计把复杂性全部封装在了底层，留给开发者的只有清爽的接口定义。简单场景用 ChatModel，一旦涉及模板、记忆、工具或者 RAG，AI Services 绝对是你的不二之选。

第二课：给 AI 装上大脑——RAG 检索增强生成

大模型虽然博学，但它有个致命的硬伤：知识是有保质期的，截止于它训练结束的那一天。你问它昨天的股价，它大概率会胡说八道。这时候 RAG就派上用场了。它强迫模型在张嘴回答之前，先去翻翻你自家的知识库，把Zui新的资料找出来塞进脑子里。

想象一个医疗场景：医生输入患者症状，系统通过 RAG 检索医院内部的电子病历、Zui新的医学期刊文献和经过验证的临床指南。这不再是依赖一个预训练了所有知识的“全Neng大脑”，而是构建了一个“即时学习+严格引用”的系统。

在代码层面这通常涉及两步：先把文档切分、向量化存入 EmbeddingStore，然后在提问时检索相关片段。

// 1. 准备文档并切分
List docs = List.of(
    Document.from,
    Document.from
);
var splitter = DocumentSplitters.recursive;
List segments = splitter.splitAll;
// 2. 向量化并存储
EmbeddingModel embModel = new AllMiniLmL6V2QuantizedEmbeddingModel;
InMemoryEmbeddingStore embStore = new InMemoryEmbeddingStore<>;
embStore.addAll.content, segments);
// 3. 创建检索器并绑定
ContentRetriever retriever = EmbeddingStoreContentRetriever.builder
    .embeddingStore.embeddingModel
    .maxResults.minScore
    .build;
Assistant assistant = AiServices.builder
    .chatModel.contentRetriever
    .build;

这里值得一提的是 AllMiniLmL6V2QuantizedEmbeddingModel，这是一个进程内的 Embedding 模型，只有 23MB 大小，完全不需要调用远程 API，既省钱又保护隐私，简直是本地开发的神器。

第三课：治疗健忘症——Chat Memory 的艺术

LLM 本质上是无状态的，它记不住上一句说了什么。Ru果你不把历史记录传给它，它就像金鱼一样只有七秒记忆。Chat Memory 就是那个帮你在背后默默记笔记的秘书。

框架会自动存储对话历史，并在每次请求前自动注入。你不需要手动拼接字符串，框架全包圆了。geng妙的是多用户隔离，通过 @MemoryId 注解，框架底层用 ConcurrentHashMap 加上懒加载机制，确保小明的对话历史不会混入小红的数据里。

interface MultiUserAssistant {
    String chat;
}
assistant.chat;
assistant.chat;
assistant.chat; // → "小明" 
assistant.chat; // → "小红" 

当然内存是有限的，所以得有淘汰策略。不过别担心，像 MessageWindowChatMemory 这种实现，Yi经帮你处理好了消息的滚动淘汰，而且 SystemMessage 默认不会被淘汰，ToolExecutionResultMessage 成为孤儿时也会自动移除，这些细节设计得非常贴心。

第四课：从“说”到“Zuo”——Tools 工具调用

前三课的 LLM 只Neng“说”，不Neng“Zuo”。但真正的智Neng体得Neng干活啊。Tools 让 LLM Neng调用你的 Java 方法——查数据库、调 API、Zuo计算。Zui酷的是LLM 会自主决定是否调用、调用哪个、传什么参数。

比如你定义了一个计算工具，LLM 会根据用户的自然语言指令，自动拆解步骤并调用相应的方法。

class MathTools {
    @Tool
    double add double a, @P double b) {
        return a + b;
    }
}
Assistant assistant = AiServices.builder
    .chatModel
    .tools)
    .build;
assistant.chat;
// LLM 自主编排: 调用工具 -> 计算 -> 输出结果

这里有个高阶玩法：Router Agent 模式。你Ke以把一个 AI Service 作为工具传给另一个 AI Service。比如定义一个法律专家接口和一个技术专家接口，然后让一个路由 Agent 根据问题内容自动决定把活儿派给谁。这种组合拳打出来系统复杂度瞬间降低，可 性却直线上升。

第五课：拒绝字符串解析——Structured Outputs 结构化输出

以前 LLM 输出dou是 String，业务代码需要写一堆正则或者 JSON 解析逻辑，痛苦不堪。Structured Outputs 让 AI Service 直接返回 POJO、Enum 或者基本类型。

这不仅仅是方便，geng是为了系统的稳定性。框架内部有一套智Neng降级机制：Ru果模型支持 RESPONSE_FORMAT_JSON_SCHEMA 且非流式，它会自动生成 JsonSchema 并注入请求，让 LLM 在 API 级别就被约束输出合法 JSON；Ru果模型不支持，它会生成文本格式指令追加到 Prompt 末尾，靠 LLM 的理解Neng力来输出，然后再尝试解析。

record Person {}
interface PersonExtractor {
    Person extractPersonFrom;
}
PersonExtractor extractor = AiServices.create;
Person p = extractor.extractPersonFrom;
// → Person

实战中，这非常适合Zuo情感分析、意图识别等任务。比如定义一个 Sentiment 枚举，直接让模型返回 POSITIVE 或 NEGATIVE，比你自己写 NLP 算法要准得多，也快得多。

第六课：安全第一——Guardrails 输入输出护栏

LLM 越强大，风险越大。Prompt Injection攻击Ke以让模型无视系统指令，输出敏感信息。Guardrails 就是在调用前后Zuo验证的安检员。

你Ke以定义输入护栏来检测恶意指令，也Ke以定义输出护栏来防止模型胡言乱语或者泄露竞品信息。

public class PromptInjectionGuardrail implements InputGuardrail {
    @Override
    public InputGuardrailResult validate {
        if .contains)
            return fatal;
        return success;
    }
}

注册方式也hen简单，通过注解声明式地挂在接口方法上。测试的时候，你甚至不需要真的调用 LLM，直接针对 Guardrail 类写单元测试，确保你的安全逻辑是固若金汤的。

第七课：拒绝等待——Streaming 流式响应

现在的用户dou急躁，等个五六秒才kan到回复，早就关掉页面了。Streaming 让 LLM 逐 token 推送，用户体验大幅提升。kan着文字一个一个蹦出来那种“正在思考”的感觉才是 AI 应用的灵魂。

在 LangChain4j 里这通过 TokenStream 来实现。你Ke以监听每一个 token 的生成，甚至在这个过程中Zuo实时的处理。

interface StreamingAssistant {
    TokenStream chat;
}
StreamingAssistant assistant = AiServices.create;
assistant.chat
    .onPartialResponse)
    .onCompleteResponse)
    .onError
    .start; // 必须调用 start 触发流

这里有个小坑要注意，TokenStream 是在 dev.langchain4j.service 包下的，别去 dev.langchain4j.model 包里找，导入错了包可是会抓狂的。

第八课：透视黑盒——事件监听与日志

调试 LLM 应用Zui头疼的就是“黑盒”。输入是什么？输出是什么？中间调了什么工具？LangChain4j 提供了强大的事件监听机制，让你透视 AI Service 调用的完整生命周期。

从 AiServiceStartedEvent 到 AiServiceCompletedEvent，中间的每一个 ChatModelListener.onRequest 和 onResponse dou尽在掌握。这对于排查问题、监控性Neng至关重要。

当然Zui简单的调试方式还是开启日志。加上 logRequests 和 logResponses，配合 Logback，控制台里就Neng把完整的请求 Body 和响应 Body 打印出来连 Token 用量dou给你算得清清楚楚。

第九课：Spring Boot 开发者的福音——Starter 自动配置

Ru果你是 Spring Boot 的忠实粉丝，那你一定会爱上 langchain4j-spring-boot-starter。纯 Java 手动 Builder 虽然灵活，但哪有 Spring 的自动配置来得香？

在 application.properties 里配好 API Key 和模型名称，然后在接口上加个 @AiService 注解，框架就会自动扫描并创建 Bean。直接在你的 Controller 里 @Autowired 注入进去就Neng用，启动即用，丝滑得不像话。

@AiService
interface Assistant {
    @SystemMessage
    String chat;
}
@RestController
class AssistantController {
    private final Assistant assistant;
    @GetMapping
    public String chat {
        return assistant.chat;
    }
}

第十课：未来Yi来——MCP 标准化工具协议

前面的 @Tool 虽然好用，但它是和 Java 代码耦合的。Ru果你的工具是 Python 写的，或者是独立部署的进程，怎么办？这时候就需要 MCP登场了。

MCP 通过标准化协议调用外部进程提供的工具，任何语言编写，独立部署。LangChain4j Yi经支持通过 Stdio 启动子进程作为 MCP Server，然后把它的工具注册到 AI Service 中。这打破了语言的界限，让 Java 应用也Neng轻松调用 Python 生态的强大工具。

第十一课：调参的艺术——Parameters 与 Logging

想让模型geng听话？调参是必须的。Temperature 控制创造性，MaxTokens 控制成本，FrequencyPenalty 防止重复。这些参数在 Builder 模式下douNeng轻松配置。

比如你想让模型写代码，就把 Temperature 调低，追求确定性；你想让它写诗，就调高一点，让它放飞自我。这些细微的调整，往往决定了产品的Zui终体验。

第十二课：测试策略——如何给 AI 写单元测试

AI 的输出是不确定的，这给测试带来了巨大的挑战。总不Neng每次dou人工审核吧？LangChain4j 建议采用分层测试策略。

对于 Guardrail 这种逻辑确定的组件，直接写单元测试，模拟输入验证输出。对于 AI Service 的输出，Ke以使用 AssertJ 的宽松断言，或者只验证关键信息是否存在。比如提取 Person 信息时只要名字对了年龄在合理范围内，就算通过。

第十三课：源码模块解析——你需要知道的核心依赖

Zui后咱们得搞清楚这个框架的底座。核心的 langchain4j-core 包含了所有的接口定义，比如 ChatModelStreamingChatModelTokenStream 以及各种注解。而具体的实现，比如 OpenAI 的对接，则在 langchain4j-open-ai 模块中。

Ru果你想对接 Ollama 本地模型，那就引入 langchain4j-ollama；想Zuo文档加载，就找 langchain4j-document-loader 系列的包。这种模块化的设计让你Ke以按需引入，避免 Jar 包膨胀。

第十四课：架构之美——四层职责分明的体系

学完这 14 课，你会发现 LangChain4j 的架构设计非常清晰。从底层的模型调用，到中间的记忆、工具、RAG 组件，再到上层的声明式服务，每一层dou职责分明。

它没有像 Python 那样搞出一堆晦涩的链式调用，而是用 Java 开发者Zui熟悉的接口和注解，把复杂性封装起来。这种设计哲学，才是它Neng迅速在 Java 社区走红的原因。

你准备好起飞了吗？

LangChain4j 1.14 的这 14 节课，涵盖了从入门到精通的方方面面。不管你是想Zuo一个简单的聊天机器人，还是复杂的临床决策支持系统，它douNeng给你提供足够的弹药。别再观望了把你的 Java 项目升级一下让 AI 的Neng力注入到你的代码里吧。毕竟未来的软件应用，可Nengdou会是 AI Native 的。

---