01-LangChain4j是什么-Java程序员的Agent框架入门
做 Java 后端久了，突然有一天老板说："咱们也接个大模型，做个会聊天的机器人吧。"你打开浏览器一搜，满屏都是 Python 的 LangChain、LlamaIndex、AutoGPT......Java 这边呢？好像只能手写 HttpClient 调个接口，拼接 JSON 像在玩俄罗斯方块。
别慌。LangChain4j 就是给咱们 Java 程序员准备的"大模型应用框架"。今天这篇，我把它的底裤......不对，把它的定位、核心抽象、和 Python 那套的关系、以及它能干和不能干的事，一次性讲清楚。
一、它到底是什么
一句话：LangChain4j 是一个在 JVM 上用的、用来构建大模型（LLM）应用的 Java 框架。
它干的事，本质上是帮你把下面这些"脏活累活"封装好：
- 把大模型的 API 调用封装成类型安全的 Java 接口；
- 帮你管理"对话记忆"（上句说了啥，下句得记得）；
- 让你能用"声明式"的方式定义一个 AI 助手，而不是自己拼 prompt 字符串；
- 支持"工具调用"（Tool Calling），让大模型能反过来调你的 Java 方法，去查数据库、调接口、发消息。
如果你没接触过大模型，先把大模型理解成一个"特别能聊、但是失忆、而且不会自己动手干活"的聪明哑巴：你问它，它答你；它记不住十分钟前的话（除非你每次都把历史喂给它）；它想查个数据库？做不到，得你帮它查好塞回去。LangChain4j 就是帮你把这些"喂历史、帮它干活"的流程串起来的胶水层。
二、四个你必须认识的核心抽象
LangChain4j 概念不少，但 AI 伙伴（AI-Partner）这个项目真正用到的，就四个。吃透这四个，你就拿到了 Agent 的入场券。
1. ChatLanguageModel：模型本身
这是最底层的抽象，代表"一个能聊天的语言模型"。在 AI 伙伴里，它具体是 OpenAiChatModel------因为 DeepSeek、通义千问都提供了"OpenAI 兼容协议"，所以一套 OpenAiChatModel 就能通吃，换个 base-url 就换厂。
它最核心的方法就一个：chat(String) 返回 String（或者流式版本 StreamingChatLanguageModel）。注意，本项目用的是阻塞式 OpenAiChatModel，没有流式。
2. ChatMemory：对话记忆
大模型本身无状态（每次调用都是全新的）。要让它"记得"上下文，得由框架在每次调用前后把历史消息塞进去。ChatMemory 就是干这个的。AI 伙伴用了 MessageWindowChatMemory，意思是"只保留最近 N 条消息"的滑动窗口。
3. AiServices：声明式 AI 服务
这是 LangChain4j 最香的地方。你写一个 Java 接口，加几个注解，框架在运行时用动态代理帮你生成实现类。接口方法一调，框架自动：拼系统提示词 → 取记忆 → 调模型 → 处理工具 → 返回结果。
AI 伙伴的 CompanionAssistant 就是这个接口的极致简化版，全接口只有一个方法（后面两篇细讲）。
4. Tool：工具调用
大模型光会说不够，得能"动手"。Tool 就是把你任意一个 Java 方法包装成"大模型可以调用的工具"。当模型觉得该查记忆了，它就返回一个"我要调 saveMemory 工具，参数是这个"，框架替它执行，再把结果喂回模型。AI 伙伴里有 6 个工具类、13 个工具方法，涵盖记忆、提醒、情绪、健康、设备、时间。
下面这张表帮你快速建立对应关系：
| 核心抽象 | 在 AI 伙伴里谁扮演 | 一句话职责 |
|---|---|---|
ChatLanguageModel |
OpenAiChatModel |
真正跟大模型对话的那个 |
ChatMemory |
MessageWindowChatMemory（窗口 12） |
让模型记得最近聊了啥 |
AiServices |
AiServices.builder(CompanionAssistant.class) |
把接口变成能跑的 Agent |
Tool |
6 个 *Tool 类、13 个 @Tool 方法 |
让模型能动手查库/调设备 |
三、它和 Python 的 LangChain 什么关系
经常有人问："LangChain4j 是不是就是把 Python 的 LangChain 翻译成 Java 了？"
是，也不是。
说"是"，是因为理念一脉相承：链式调用、记忆、工具、RAG（检索增强生成）这些概念两边都有，命名也尽量对齐。比如 Python 里的 ChatModel、Memory、Tool，Java 这边基本同名。
说"不是"，是因为两者的"脾气"完全不同：
| 维度 | Python LangChain | LangChain4j（Java） |
|---|---|---|
| 语言风格 | 脚本式、灵活、动态 | 强类型、接口式、声明式 |
| 和 Spring 的关系 | 基本各玩各的 | 天生为 Spring 设计，能当 @Bean 注入 |
| 类型安全 | 较弱，运行时才发现问题 | 编译期就能发现参数错 |
| 上手门槛 | 概念飘、版本跳得快 | 更稳，依赖 Spring 的成熟生态 |
对一支 Java 后端团队来说，选 LangChain4j 而不是"用 Python 再起一个服务"，最大的好处是：不用再维护一套异构技术栈。模型调用、记忆、工具，全是 Java Bean，跟你的 JPA、Controller 无缝融在一起，部署也只打一个包。
四、为什么 AI 伙伴选了它
AI 伙伴（AI-Partner）是 Spring Boot 3.5 + JDK 17 的后端，选 LangChain4j 几乎是顺理成章：
- 同语言、同进程 ：Agent 和你的业务代码（用户、提醒、设备）跑在同一个 JVM 里，工具方法直接
@Autowired你的 Service，零 RPC。 - 声明式省力 ：
CompanionAssistant一个接口搞定，不用手写 prompt 拼接和消息循环。 - OpenAI 兼容协议：DeepSeek、通义都能接，厂商切换成本低。
- 生态齐：模型、记忆、工具、RAG......需要啥引入啥，不想要的可以不引（本项目就没引向量库）。
小提示：框架能帮你接模型，但选哪个模型、提示词怎么写、工具怎么设计，还是你自己的活。框架是脚手架，不是替你思考。
五、生态模块一览
LangChain4j 是个"分模块"的框架，按需引入，不会一上来就给你塞几百个 jar。常用的几个：
| 模块 artifactId | 作用 | AI 伙伴用了吗 |
|---|---|---|
langchain4j |
核心抽象（Model/Memory/AiServices/Tool） | 用了 |
langchain4j-open-ai |
OpenAI 及兼容协议的模型实现 | 用了 |
langchain4j-spring-boot-starter |
Spring Boot 自动装配 | 没用 |
langchain4j-embeddings-* |
向量嵌入 | 没用 |
langchain4j-community-* |
社区模型/向量库适配 | 没用 |
注意最后一行：AI 伙伴没有引入 langchain4j-spring-boot-starter 。这意味着它不走框架自带的自动配置（你不会在 yml 里看到任何 langchain4j.* 前缀），而是自己在 config/LangChain4jConfig 里手工用 @Bean 装配。这是后面第 3、7 篇的重点，这里先埋个伏笔。
六、它"不"做什么（别指望错对象）
很多新手踩坑，是把框架当万能胶。说清楚边界，能省你三天加班：
- 它不是大模型本身：它不训练模型、不存模型权重，只是个"调用客户端 + 编排层"。模型在远端（如 DeepSeek 的服务器）跑。
- 它不替你写提示词 ：人设、语气、约束，得你设计（AI 伙伴的人设写在
PersonaProvider里）。 - 它不内置业务：记忆要落库、提醒要调度、设备要 MQTT，这些全是你的代码，框架只负责"在合适的时机调你的工具"。
- 它不解决隐私合规：涉及老人、儿童、健康数据，框架不会自动帮你脱敏或授权，得你自己做（这也是系列三、六的合规篇要讲的）。
一句话总结：LangChain4j 是把"大模型 + 你的业务"粘起来的胶水，胶水再好，也得你提供两面要粘的东西。
七、动手前先懂的四个大模型黑话
既然面向零基础，有几个术语你迟早会撞上，提前翻译成人话，省得后面看代码一脸懵。
- Token（词元） ：大模型不是按"字"也不是按"词"计费的，而是按 token。中文大致 1
2 个字算 1 个 token，英文一个单词约 12 个 token。模型有"上下文窗口"上限（比如 8k/32k token），超了就记不住前面的话------这就是为什么MessageWindowChatMemory只留最近 12 条，本质是给 token 预算瘦身。 - Prompt（提示词）：你喂给模型的所有文字，统称 prompt。它通常分"系统提示词（system，规定人设和规矩）"和"用户消息（user，你这句说了啥）"。AI 伙伴的人设就装在系统提示词里。
- Temperature（温度）：控制"胡说程度"的参数，取值 0~1 甚至更高。越低越死板保守（贴近训练分布），越高越发散有创意。AI 伙伴写死 0.7，是个"既有温度又不至于胡言乱语"的折中值。
- System / User / Assistant 三种消息角色：系统=给模型的底色指令；用户=你输入的；助手=模型上轮的回复。对话历史就是这三种角色消息的队列，框架帮你维护，你基本不用管。
懂了这四个词，后面 systemMessageProvider、temperature: 0.7、memory-window-size: 12 这些配置你一眼就明白在干嘛，而不是对着 yml 发呆。
八、一个最小可感知的代码片段
为了让"框架帮你干活"这件事更具体，给你看一段示意代码（非 AI 伙伴源码，仅为说明 AiServices 的长相）：
java
// 示意：一个最朴素的 AI 服务接口
interface Assistant {
@SystemMessage("你是个乐于助人的 Java tutor。")
String chat(@UserMessage String userMessage);
}
// 示意：装配并调用
Assistant assistant = AiServices.builder(Assistant.class)
.chatModel(openAiModel)
.build();
String answer = assistant.chat("HashMap 和 ConcurrentHashMap 有啥区别？");你看，没有拼 JSON、没有手写 HTTP、没有解析返回。你只声明"我想要个什么样的助手"，框架把脏活全包了。 AI 伙伴的 CompanionAssistant 只是把这里的 @SystemMessage 换成了运行时动态注入、再补上记忆和 6 个工具------骨架完全一致。
九、给零基础同学的最小心智模型
如果今天你只记住一句话，记住这个：
你写一个接口
String chat(...)，框架在背后帮你"拼好 prompt → 带上历史 → 问模型 → 需要就调你的工具 → 把答案还给你"。你只管声明"我想要个什么样的 AI 助手"，剩下的脏活 LangChain4j 承包。
把这个模型装进脑子，你就已经跨过了 Agent 开发的第一道门槛。剩下的就是一步一步把工程跑起来、把配置读熟、把那一行极简接口看透------这些，我们一篇一篇来。