LangChain4j 入门：ChatModel 第一个 AI 对话实战

大家好，我是晚安code。

Java 项目想接大模型，是不是只能拿 HTTP 客户端自己拼 messages？为什么不试试 LangChain4j------Java 这边能打的 AI 框架本来就少，能查到的资料又散。这篇 LangChain4j 入门就把最基础的一层讲透：ChatModel 对话、SystemMessage 系统提示词、多模态输入，跟着跑通你的第一个 AI 对话。点个收藏，我们开始。

一、为什么 Java 开发者需要 LangChain4j

LangChain4j：一个 Java 生态的大模型应用框架，用统一 API 对接各家大模型（OpenAI、Gemini、通义、DeepSeek 等 20 多家），并封装了对话记忆、工具调用、知识库检索这些高频能力。你可以把它理解成「Java 版的 LangChain」------Python 生态早就有 LangChain、LlamaIndex 一堆选择，Java 这边直到它出现才算有了个像样的。

直接调模型 API 有多痛，写过的人都懂：每个接口的 messages 结构记一遍，多轮对话的上下文自己拼，返回的 JSON 自己解析，工具调用自己实现循环。这些胶水代码，换个项目重写一遍。LangChain4j 把这层抽象出来了------你用 Java 声明「我要什么」，它负责「怎么调模型、怎么组装消息」。

在我这边，判断一个 AI 框架值不值得用就一条：它有没有把「对话 + 记忆 + 工具 + 知识库」这四件事当成一等公民。LangChain4j 全都有，而且 API 是给 Java 开发者的直觉写法，不是照搬 Python 那套。

二、三分钟跑通第一个对话：ChatModel

ChatModel（聊天模型）：LangChain4j 里负责对话的核心接口，把「发消息给模型、拿回回复」封装成最简单的方法调用。它是整个框架的最小入口，后面的记忆、工具、RAG 全都建立在它之上。

先说环境。需要 JDK 17+（官方建议 21）、Maven 3.9+。截至 2026 年 8 月，最新稳定版是 1.17.x（2026-07 发布），下面的例子按这个版本写，发布前记得核对官方文档。

先加依赖，pom.xml 里：

xml 复制代码

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>1.17.2</version>
</dependency>
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>1.17.2</version>
</dependency>

API Key 走环境变量，别硬编码进代码。然后三行代码就够：

java 复制代码

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;

ChatModel model = OpenAiChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o-mini")
        .build();

String answer = model.chat("用一句话解释什么是 RAG");
System.out.println(answer);

第一次跑通那种感觉，我自己就记得很清楚（示例场景）：原来接大模型能短到这个程度，之前手拼 JSON 的活全被藏起来了。终端里会打出模型的回答------注意，日志里如果出现 sk-*** 这类 key 前缀，记得打码再发出去。

chat() 这个方法是 String 进出，适合快速验证。要控制细节时，用完整的 ChatMessage 版本：

java 复制代码

ChatResponse response = model.chat(
    UserMessage.from("今天上海天气怎么样？")
);
System.out.println(response.aiMessage().text());
System.out.println(response.metadata().tokenUsage()); // 输入/输出 token 数

ChatResponse 里不只有 AI 的回复，还带着 token 用量、结束原因这些元数据------后面写监控、算成本都用得上。一次完整的对话调用，链路长这样：

对话里消息一共五种类型（UserMessage、AiMessage、SystemMessage 等），下一节先讲最该懂的那种。

三、SystemMessage：给 AI 立人设的系统提示词

SystemMessage（系统消息）：对话里由开发者发的消息，用来设定 AI 的角色、行为规则和回复风格，一般放在对话最开头。模型对它的遵从度比普通消息高，所以别把废话放进去。

假设你要做个客服助手，第一版可以这么写：

java 复制代码

ChatResponse response = model.chat(
    SystemMessage.from("你是 XX 产品的客服，回答用简体中文，先道歉再给解决方案"),
    UserMessage.from("你们 App 闪退怎么办？")
);
System.out.println(response.aiMessage().text());

有了 SystemMessage，多轮对话里模型也会一直维持这个人设------哪怕用户夹带私货问别的问题，它也会尽量往角色上靠。这是写进 UserMessage 里「你是客服」给不了的效果。

我自己的体会（示例场景）：系统提示词决定 AI 的上限，后面再怎么调 prompt 都只是下限。人设写歪了的机器人，靠多轮对话很难掰回来。建议一次对话只放一个 SystemMessage，别写一段就追加一段------不同模型对「谁说了算」的行为不一致，叠多了反而不可控。

可能有人会问：SystemMessage 和直接在用户消息里写「你是...」有什么区别？

有，而且挺大。系统消息的约束力更强，多轮对话中不容易被用户的话带偏；写在用户消息里，模型可能把它当成普通聊天内容，角色感说没就没。能走 SystemMessage 就别省这一步。

四、多模态：让模型看懂图片

多模态（Multimodality）：指模型能同时处理文字和图片（部分还支持音频、视频）这类多种输入。在 LangChain4j 里，把图片和文字拼进一条 UserMessage 就行。

最常见的场景是「截图找 bug」。报错弹窗看不清，直接丢给模型：

java 复制代码

UserMessage message = UserMessage.from(
    ImageContent.from("https://example.com/error.png"),
    TextContent.from("这张截图是程序报错，帮我看问题出在哪")
);
ChatResponse response = model.chat(message);
System.out.println(response.aiMessage().text());

模型得有视觉能力才能这么干（gpt-4o、Gemini、通义千问 VL 这类都行），纯文本模型会直接忽略图片。ImageContent.from() 支持 URL，也支持 base64 字符串------敏感截图走 base64，别把内网地址直接丢给模型。

有个点要提醒：多模态请求通常更贵，token 按图片分辨率算。能用文字描述就别传图，传了就挑小图。在我这边，只有「看图说话」真的比文字省事时（报错截图、扫描件、UI 还原），才值得花这份钱。

五、小结

到这，你已经跑通了 LangChain4j 最基础的三件事：ChatModel 对话、SystemMessage 立人设、多模态看图。单次调用没难度，真正的生产力在下一层------AiService。

下一篇我们聊 AiService：只写一个接口，框架自动把会话记忆、结构化输出、提示词模板全给你接上。点个关注不迷路。

我是晚安code，持续分享编程干货。觉得有用的话记得点赞收藏和关注~也欢迎在评论区聊聊：你接大模型第一个踩的坑是什么？