【LangChain4j系列01】LangChain4j 快速入门与核心概念

本章涵盖框架架构总览、Maven 依赖管理、以及第一个 LangChain4j 程序。

1.1 LangChain4j 是什么？

LangChain4j 是一个面向 Java 生态的 LLM 应用开发框架。与 Python LangChain 处于同一赛道，但为 JVM 量身定制：

统一 API：一套接口抽象所有 LLM 厂商和向量数据库
声明式编程：定义接口 → 框架生成代理实现（类似 Spring Data JPA）
类型安全：Java 类型系统贯穿 LLM 输入/输出全过程
企业级就绪：Spring Boot / Quarkus Starter、可观测性、安全护栏

与 Python LangChain 的关键差异

维度	LangChain (Python)	LangChain4j (Java)
类型系统	动态类型，运行时错误多	编译期类型检查
编程模型	Chain/LCEL 表达式	接口代理 + 注解驱动
框架集成	FastAPI/Flask 手动集成	Spring Boot/Quarkus 自动装配
成熟度	生态极大但碎片化	专注 JVM 深度集成

1.2 架构分层

LangChain4j 采用经典的三层架构：

关键设计决策

ChatModel 取代 LanguageModel ：LanguageModel（String→String）逐渐废弃，ChatModel（List<ChatMessage> → ChatResponse）是未来唯一的主 API
Chains 被 AI Services 取代 ：仅保留 ConversationalChain 和 ConversationalRetrievalChain，不再扩展
Easy RAG 到 Advanced RAG 的平滑升级路径：新手可用一行代码启动，后续逐步替换组件

1.3 第一个程序

依赖配置

xml 复制代码

<!-- Maven 核心依赖 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>1.18.1</version>
</dependency>

<!-- OpenAI 集成（按需替换为其他厂商） -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>1.18.1</version>
</dependency>

最低可用代码

java 复制代码

import dev.langchain4j.model.openai.OpenAiChatModel;
import static dev.langchain4j.model.openai.OpenAiChatModelName.GPT_4_O_MINI;

public class HelloLangChain4j {
    public static void main(String[] args) {
        // 1. 创建 ChatModel（一行 Builder）
        ChatModel model = OpenAiChatModel.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .modelName(GPT_4_O_MINI)
            .build();

        // 2. 发送消息，获取回复
        String answer = model.chat("用一句话介绍 LangChain4j");
        System.out.println(answer);
    }
}

使用 AI Services（推荐方式）

java 复制代码

// 定义接口
interface Assistant {
    String chat(String userMessage);
}

// 创建代理实例
Assistant assistant = AiServices.create(Assistant.class, model);

// 调用
String answer = assistant.chat("解释 Java 21 的虚拟线程");

1.4 核心模型类型速览

LangChain4j 在 langchain4j-core 中定义了多种模型接口：

模型接口	输入	输出	典型用途
`ChatModel`	`ChatMessage...` / `ChatRequest`	`ChatResponse`	对话、文本生成（主力 API）
`StreamingChatModel`	`ChatRequest` + Handler	流式回调	实时打字效果
`EmbeddingModel`	`String` / `TextSegment`	`Embedding`	文本向量化
`ImageModel`	`String` 提示词	`Image`	图片生成/编辑
`ModerationModel`	`String`	`Moderation`	内容安全审查
`ScoringModel`	Query + 文本列表	`List<Double>`	相关性打分（RAG 重排序）

1.5 ChatMessage 五种类型

这是整个框架最基础的数据模型，必须掌握：

java 复制代码

// 1. SystemMessage --- 定义 AI 的角色和行为
SystemMessage.from("你是一个幽默的中文助手");

// 2. UserMessage --- 来自用户（或应用）
UserMessage.from("讲个笑话");
UserMessage.from(TextContent.from("描述这张图"), ImageContent.from("https://..."));

// 3. AiMessage --- LLM 生成的回复
AiMessage aiMessage = response.aiMessage();
aiMessage.text();                      // 文本内容
aiMessage.toolExecutionRequests();      // 工具调用请求

// 4. ToolExecutionResultMessage --- 工具执行结果
ToolExecutionResultMessage.from(toolRequest, "执行结果");

// 5. CustomMessage --- 自定义属性（仅 Ollama）
CustomMessage.from(Map.of("custom_key", "value"));

关键理解

LLM 是无状态的：每次调用需要传递完整的对话历史
SystemMessage 权重最高：LLM 训练时被特殊训练为优先遵从，绝不要让终端用户输入污染它
UserMessage 支持多模态 ：一个 UserMessage 可以同时包含文本、图片、音频、视频、PDF

1.6 两个编程层级

LangChain4j 提供两个清晰的抽象层级，开发者可按需选择：

makefile 复制代码

高层: AI Services (接口 + 注解)
  ↓ 自动处理: 消息格式化、输出解析、工具执行、记忆管理、RAG
低层: ChatModel / EmbeddingModel / ... (直接 API)
  ↓ 开发者手动: 构造消息、管理历史、解析输出
HTTP: OkHttp / Retrofit / 自定义 HTTP 客户端

选择建议：

场景	推荐层级
原型验证、简单问答	低层 ChatModel
生产应用、复杂业务逻辑	高层 AI Services
需要精细控制每次请求参数	低层 + ChatRequest
需要记忆/工具/RAG/护栏	高层 AI Services

1.7 配置模型参数的三种方式

方式一：Builder 模式（独立应用）

java 复制代码

OpenAiChatModel model = OpenAiChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName("gpt-4o")
    .temperature(0.3)          // 0-2，越高越随机
    .maxTokens(4096)
    .timeout(Duration.ofSeconds(60))
    .logRequests(true)
    .logResponses(true)
    .build();

方式二：Spring Boot 配置

properties 复制代码

langchain4j.open-ai.chat-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.chat-model.model-name=gpt-4o
langchain4j.open-ai.chat-model.temperature=0.3
langchain4j.open-ai.chat-model.max-tokens=4096

方式三：Quarkus 配置

properties 复制代码

quarkus.langchain4j.openai.api-key=${OPENAI_API_KEY}
quarkus.langchain4j.openai.chat-model.temperature=0.5
quarkus.langchain4j.openai.timeout=60s

1.8 关键设计模式预览

在深入后续章节之前，先预览 LangChain4j 中反复出现的核心设计模式：

1. 接口代理模式（AI Services）

lua 复制代码

用户定义接口 → AiServices.create() → 反射代理 → 自动编排调用链

这是整个框架的基石，类比 Spring Data JPA 的 findByName(String) 自动化查询。

2. Builder 模式（无处不在）

java 复制代码

Foo foo = Foo.builder()
    .bar(x).baz(y)
    .build();

所有核心对象（ChatModel、ChatRequest、ToolSpecification、各种 RAG 组件）都通过 Builder 构建，链式调用，不可变对象。

3. SPI 插件机制

bash 复制代码

META-INF/services/dev.langchain4j.spi.Supplier  ← 自定义实现

用于 DocumentParser、EmbeddingModel、ToolSpecificationJsonCodec 等组件的自动发现。

4. Result 包装模式

java 复制代码

Result<T> = content(T) + tokenUsage() + sources() + toolExecutions()

AI Service 返回 Result<T> 而非裸 T 时，可获取 Token 用量、RAG 来源、工具执行记录等元数据。