
大家好，我是晚安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 一句调用的清爽](https://developer.qcloudimg.com/http-save/yehe-12591818/ec95787eb88b8c2f38871a244583d2eb.png)

## 二、三分钟跑通第一个对话：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 用量、结束原因这些元数据——后面写监控、算成本都用得上。一次完整的对话调用，链路长这样：

![LangChain4j 入门：ChatModel 对话的一次完整调用时序图](https://developer.qcloudimg.com/http-save/yehe-12591818/9354cf8f9910cae1d04e0f6eadef47c8.png)

对话里消息一共五种类型（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，别把内网地址直接丢给模型。



![图片加文字一起进去，模型直接给答案](https://developer.qcloudimg.com/http-save/yehe-12591818/e90f17b1e829960d4258d588bda6d704.png)

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

## 五、小结

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

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

---

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


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

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

LangChain4j 入门必读：Java 生态的大模型框架。从依赖配置到 ChatModel 第一个对话，再讲清 SystemMessage 与多模态输入。

编程语言

人工智能

开发工具

LangChain4j入门教程：详解Java大模型开发核心组件。教你用ChatModel三行代码跑通AI对话、SystemMessage设定角色人设、多模态识别图片，支持OpenAI、DeepSeek等20多家模型，解决Java接大模型拼消息痛点，附完整代码示例。

大模型应用

代码解释

LlamaIndex

LangChain

DeepSeek

Python

JSON

Java

2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

LangChain4j 入门：ChatModel 第一个 AI 对话实战-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐