Langchain4J-Ai

LangChain4j 从入门到实战：完整技术手册

1. LangChain4j 核心概念与快速入门

1.1 LangChain4j 简介

1.1.1 框架定位与目标

LangChain4j 是一个专为 Java 生态系统设计的开源库，其核心目标是极大地简化将大语言模型（LLM）的强大功能集成到 Java 应用程序中的过程 。在人工智能浪潮席卷全球的背景下，尽管 Python 和 JavaScript 社区涌现出大量成熟的 LLM 开发框架，但 Java 领域却相对缺乏一个功能全面、易于使用的解决方案。LangChain4j 的诞生正是为了填补这一空白，它致力于为 Java 开发者提供一个统一、高效且富有表现力的工具集，使他们能够像使用其他主流 Java 框架一样，轻松地构建、部署和管理由 LLM 驱动的智能应用 。该框架的开发始于 2023 年初，正值 ChatGPT 引发的技术变革热潮，其设计理念融合了 LangChain、Haystack、LlamaIndex 等业界知名框架的精华，并在此基础上进行了创新，以适应 Java 语言的特性和企业级应用的需求 。LangChain4j 不仅仅是一个简单的 API 封装，它更是一个综合性的开发平台，旨在降低 LLM 技术的使用门槛，让开发者能够专注于业务逻辑的实现，而非底层技术细节的纠缠。

1.1.2 核心特性：统一API与综合工具箱

LangChain4j 的两大核心支柱是其提供的统一 API 和全面的工具箱，这两者共同构成了其强大而灵活的开发能力 。首先，统一 API 的设计旨在解决 LLM 提供商（如 OpenAI、Google Vertex AI）和向量嵌入存储（如 Pinecone、Milvus）各自使用专有 API 所带来的碎片化问题 。通过 LangChain4j，开发者可以学习一套标准的 API，并在不同的 LLM 和向量存储之间轻松切换，而无需重写大量业务代码。这种抽象层类似于 Java 持久化领域的 Hibernate 框架，极大地提升了代码的可移植性和可维护性 。其次，LangChain4j 提供了一个内容丰富的综合工具箱，该工具箱凝聚了社区在构建 LLM 应用过程中总结出的常见模式、抽象和技术 。这个工具箱的范围非常广泛，从底层的提示词模板（Prompt Templating）、聊天记忆管理（Chat Memory Management）和输出解析（Output Parsing），到高级模式如 AI 代理（Agents）和检索增强生成（RAG），都提供了开箱即用的实现 。这种分层设计使得无论是构建一个简单的问答机器人，还是开发一个包含数据摄取、检索和生成的复杂 RAG 管道，开发者都能在 LangChain4j 中找到合适的工具和组件，从而显著加快开发进程 。

1.1.3 支持的LLM与向量存储

LangChain4j 的一个显著优势在于其广泛的集成能力，它支持超过 15 个主流的大语言模型（LLM）提供商和超过 15 种向量嵌入存储方案 。这种广泛的支持为 Java 开发者提供了极大的灵活性和选择空间，可以根据具体的应用场景、成本预算和性能要求，自由地选择最合适的底层技术。在 LLM 方面，LangChain4j 不仅支持业界领先的 OpenAI 系列模型（如 GPT-4），还兼容 Google 的 Vertex AI（包括 Gemini 和 PaLM 2）、Anthropic 的 Claude、Amazon Bedrock、Mistral AI 以及众多开源模型如 Ollama、LocalAI 和 Hugging Face 等 。这种多样性确保了开发者可以利用最前沿的模型能力。在向量存储方面，LangChain4j 同样提供了丰富的选项，包括云端的 Pinecone、Milvus，以及可以本地部署的 Chroma、Weaviate 等 。此外，它还支持将向量存储在内存中（InMemoryEmbeddingStore），这对于快速原型设计和测试环境非常有用。这种对多种 LLM 和向量存储的无缝集成，使得 LangChain4j 成为一个真正与供应商无关的框架，开发者可以轻松地在不同服务之间进行迁移和比较，而无需对上层应用逻辑进行大规模修改 。

1.2 项目集成与依赖配置

1.2.1 Maven依赖引入

在 Java 项目中集成 LangChain4j 非常直接，主要通过 Maven 或 Gradle 等构建工具来管理依赖。为了确保依赖版本的统一和兼容性，官方推荐使用 Bill of Materials (BOM) 的方式进行管理 。首先，需要在项目的 pom.xml 文件的 <dependencyManagement> 部分引入 langchain4j-bom。这个 BOM 文件定义了所有 LangChain4j 模块及其兼容的版本，从而避免了手动管理每个依赖版本可能引发的冲突问题。具体的配置如下所示，其中 ${langchain4j.version} 应替换为当前最新的稳定版本，例如 1.0.1 。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-bom</artifactId>
            <version>${langchain4j.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

在引入了 BOM 之后，就可以在 <dependencies> 部分按需添加具体的 LangChain4j 模块。例如，如果项目需要使用 OpenAI 的模型，就需要引入 langchain4j-open-ai 依赖。同样，如果需要使用 Reactor 进行响应式编程，可以引入 langchain4j-reactor 。这种模块化的设计使得依赖管理更加清晰和轻量，开发者只需引入项目实际需要的功能模块，避免了引入不必要的库。

<dependencies>
    <!-- 引入核心的 LangChain4j 库 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j</artifactId>
    </dependency>
    
    <!-- 引入 OpenAI 的集成模块 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-open-ai</artifactId>
    </dependency>
    
    <!-- 引入 Reactor 支持，用于流式调用 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-reactor</artifactId>
    </dependency>
    
    <!-- 其他依赖，如 Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

1.2.2 Spring Boot项目初始化

LangChain4j 与 Spring Boot 框架的集成非常紧密，官方提供了专门的 Spring Boot Starter 来简化配置和开发流程 。在一个典型的 Spring Boot 项目中，初始化过程非常顺畅。首先，确保 pom.xml 中已经包含了 Spring Boot 的父依赖和 spring-boot-starter-web 依赖，这是构建 Web 应用的基础。接着，通过引入 langchain4j-spring-boot-starter（或相关模块的 starter），Spring Boot 的自动配置机制会自动检测并配置好 LangChain4j 所需的核心组件，例如 ChatLanguageModel 的 Bean 实例 。开发者只需在 application.properties 或 application.yml 文件中提供必要的配置信息，如 LLM 提供商的 API Key、Base URL 和模型名称等，即可完成集成。例如，要配置一个 OpenAI 的聊天模型，可以在配置文件中添加 langchain4j.open-ai.chat-model.api-key=your-api-key 和 langchain4j.open-ai.chat-model.model-name=gpt-4 等属性。这种约定优于配置的方式极大地降低了入门门槛，使得开发者可以快速启动并运行一个集成了 LLM 功能的 Spring Boot 应用，而无需编写繁琐的 Java 配置代码。

1.2.3 基础API调用示例

LangChain4j 提供了简洁直观的基础 API，使得与 LLM 的交互变得异常简单。其核心接口之一是 ChatLanguageModel，它定义了接收一个或多个 ChatMessage 并返回一个 AiMessage 的标准方法 。对于简单的用例，可以直接使用 generate 方法，传入一个字符串作为用户消息，并直接获取模型返回的字符串内容。以下是一个最基本的调用示例，展示了如何使用 OpenAiChatModel 与 OpenAI 的模型进行交互 ：

import dev.langchain4j.model.openai.OpenAiChatModel;

public class SimpleChatExample {
    public static void main(String[] args) {
        // 创建一个 OpenAiChatModel 实例，使用 "demo" 作为 API Key
        // 注意：在生产环境中，应使用真实的 API Key
        OpenAiChatModel model = OpenAiChatModel.withApiKey("demo");
        
        // 用户输入
        String userMessage = "你好，LangChain4j!";
        
        // 调用 generate 方法生成响应
        String response = model.generate(userMessage);
        
        // 打印 AI 的回复
        System.out.println("AI: " + response);
    }
}

这个例子虽然简单，但它清晰地展示了 LangChain4j 的核心交互模式。对于更复杂的场景，OpenAiChatModel 提供了构建器（Builder）模式，允许开发者进行更精细化的配置，例如设置 baseUrl（用于连接本地或代理服务器）、maxTokens（限制生成内容的最大长度）、temperature（控制生成内容的随机性）、timeout（设置请求超时时间）以及 maxRetries（设置失败重试次数）等 。这种灵活的配置方式使得开发者能够根据不同的业务需求和模型特性，对 LLM 的行为进行精确控制。

import dev.langchain4j.model.openai.OpenAiChatModel;
import java.time.Duration;

public class AdvancedChatExample {
    public static void main(String[] args) {
        // 使用构建器模式创建一个高度定制化的 OpenAiChatModel 实例
        OpenAiChatModel customizedModel = OpenAiChatModel.builder()
                .baseUrl("http://your-local-llm-server.com/v1/") // 连接到本地 LLM 服务器
                .apiKey("your-actual-api-key") // 设置真实的 API Key
                .modelName("gpt-4") // 指定使用的模型
                .maxTokens(1000) // 限制最大生成 token 数
                .temperature(0.7) // 设置温度，值越低越确定
                .timeout(Duration.ofSeconds(30)) // 设置 30 秒超时
                .maxRetries(3) // 设置最多重试 3 次
                .build();
        
        String response = customizedModel.generate("请用 Java 写一个快速排序算法。");
        System.out.println("AI: " + response);
    }
}

2. Tools工具：扩展LLM的外部能力

2.1 Tools工具原理与作用

2.1.1 功能概述：Function Calling

LangChain4j 中的 Tools 工具，其核心概念对应于大语言模型领域的“Function Calling”（功能调用）或“Tool Use”能力。这项技术的本质是让 LLM 不仅仅是一个被动的文本生成器，而是能够主动地与外部世界进行交互的智能代理。当 LLM 在处理用户请求时，如果它判断需要执行某个外部操作（例如查询数据库、调用 API、执行计算等）来获取信息或完成一个动作，它可以生成一个结构化的调用指令，指定要调用的工具名称以及所需的参数。LangChain4j 框架会拦截这个指令，并负责执行相应的 Java 方法，然后将执行结果返回给 LLM。LLM 接收到结果后，会将其整合到最终的回答中，呈现给用户。这个过程极大地扩展了 LLM 的能力边界，使其能够访问实时信息、操作外部系统，从而解决那些仅依靠其内部知识无法完成的任务。例如，一个 LLM 本身不知道今天的天气，但通过一个天气查询工具，它就能为用户提供准确的天气预报。这种机制将 LLM 的自然语言理解能力与 Java 生态系统的强大功能无缝结合，为构建复杂的、具有实际业务价值的智能应用提供了坚实的基础。

2.1.2 核心注解：@Tool与@P

在 LangChain4j 中，定义一个可供 LLM 调用的工具方法非常简洁，主要通过两个核心注解来完成：@Tool 和 @P。@Tool 注解用于标记一个 Java 方法，使其成为一个可被 LLM 识别和调用的工具。这个注解通常需要一个字符串参数，用于描述该工具的功能。这个描述至关重要，因为它会作为提示信息的一部分发送给 LLM，帮助 LLM 理解这个工具的作用、适用场景以及如何正确使用它。一个清晰、准确的描述能够显著提高 LLM 调用工具的准确性和成功率。@P 注解（Parameter 的缩写）则用于标记工具方法的参数。与 @Tool 类似，@P 注解也需要一个字符串参数，用于描述该参数的含义。这个描述同样会传递给 LLM，指导它在生成调用指令时如何为该参数提供正确的值。例如，如果一个参数是用户的手机号码，那么 @P("考生手机号") 这样的描述就能让 LLM 明白它需要从一个包含手机号的上下文中提取出这个值。通过这两个注解，开发者可以将任何现有的 Java 方法（包括服务层、数据访问层的方法）无缝地暴露给 LLM，使其成为 LLM 能力的一部分，而无需编写复杂的适配代码。

2.2 实战案例：构建预约管理工具

2.2.1 业务场景分析

为了更好地理解 LangChain4j 中 Tools 工具的实际应用，我们以一个“高考志愿填报咨询预约系统”为例。在这个场景中，用户（考生或家长）可以通过一个聊天机器人界面与系统进行交互，完成预约咨询服务的操作。用户可能会说：“我想预约一个明天的咨询，我叫张三，手机号是 13800138000。” 传统的 LLM 只能理解这句话的意图，但无法真正地将这个预约信息存储到数据库中。通过 LangChain4j 的 Tools 工具，我们可以创建一个 ReservationTool，它包含 addReservation 和 findReservation 等方法。当 LLM 解析出用户的预约意图后，它会自动生成一个调用 addReservation 方法的指令，并将从用户话语中提取出的姓名、手机号等信息作为参数传入。LangChain4j 框架会执行这个方法，将数据持久化到数据库，并返回一个成功或失败的结果给 LLM。最终，LLM 会向用户确认：“好的，张三，您的预约已成功提交，我们会在明天与您联系。” 这个案例完美地展示了如何利用 Tools 工具将 LLM 的自然语言交互能力与后端业务逻辑（数据持久化）相结合，构建一个完整的、具有实际功能的智能应用。

2.2.2 准备工作：数据库与实体类

在实现 ReservationTool 之前，需要完成一些基础的准备工作，包括数据库环境的搭建、实体类的创建以及数据访问层（Mapper）和业务逻辑层（Service）的开发。首先，需要设计一个数据库表来存储预约信息，例如 reservations 表，其字段可以包括 id（主键）、name（考生姓名）、gender（性别）、phone（手机号）、communication_time（预约沟通时间）、province（所在省份）和 estimated_score（预估分数）。接着，需要创建一个对应的 Java 实体类 Reservation，使用 JPA 注解（如 @Entity, @Id）或 Lombok 注解（如 @Data）来简化代码。然后，需要开发一个数据访问层接口（例如 ReservationMapper），它继承自 MyBatis 的 BaseMapper 或类似的持久化框架接口，用于执行基本的数据库 CRUD 操作。最后，需要创建一个服务层类 ReservationService，在该类中注入 ReservationMapper，并实现具体的业务逻辑，如 insert(Reservation reservation) 和 findByPhone(String phone) 方法。这些准备工作是构建 ReservationTool 的基础，确保了工具方法在被调用时能够与后端数据库进行有效的交互。

2.2.3 工具类ReservationTool的实现

在完成数据库和实体类的准备工作后，就可以开始实现核心的 ReservationTool 类了。这个类需要使用 @Component 注解将其标记为一个 Spring Bean，以便能够被 Spring 容器管理和注入到其他组件中。在类内部，通过 @Autowired 注解注入之前创建的 ReservationService，用于执行具体的业务逻辑。ReservationTool 的核心是定义一个或多个带有 @Tool 注解的方法，这些方法将作为 LLM 可调用的工具。例如，addReservation 方法用于处理添加预约的请求，而 findReservation 方法则用于根据手机号查询已有的预约记录。每个工具方法都应该有清晰的职责，并且其参数和返回值应该设计得易于 LLM 理解和处理。通过这种方式，ReservationTool 成为了一个桥梁，连接了 LLM 的自然语言世界和后端系统的结构化数据世界。

import com.nitheima.consultant.pojo.Reservation;
import com.nitheima.consultant.service.ReservationService;
import dev.langchain4j.agent.tool.P;
import dev.langchain4j.agent.tool.Tool;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import java.time.LocalDateTime;

@Component
public class ReservationTool {

    // 注入预约服务，用于处理业务逻辑
    @Autowired
    private ReservationService reservationService;

    // 定义一个工具方法，用于添加新的预约
    @Tool("预约志愿填报服务")
    public void addReservation(
            @P("考生姓名") String name,
            @P("考生性别") String gender,
            @P("考生手机号") String phone,
            @P("预约沟通时间，格式为：yyyy-MM-dd'T'HH:mm") String communicationTime,
            @P("考生所在省份") String province,
            @P("考生预估分数") Integer estimatedScore
    ) {
        // 将接收到的参数封装成一个 Reservation 对象
        Reservation reservation = new Reservation(
                null, // ID 通常由数据库自动生成
                name,
                gender,
                phone,
                LocalDateTime.parse(communicationTime), // 将字符串解析为 LocalDateTime
                province,
                estimatedScore
        );
        // 调用服务层方法，将预约信息保存到数据库
        reservationService.insert(reservation);
    }

    // 定义另一个工具方法，用于根据手机号查询预约
    @Tool("根据考生手机号查询预约单")
    public Reservation findReservation(@P("考生手机号") String phone) {
        // 调用服务层方法，从数据库中查询预约信息
        return reservationService.findByPhone(phone);
    }
}

2.2.4 工具方法的定义与参数描述

在 ReservationTool 类中，工具方法的定义和参数描述是至关重要的环节，它直接决定了 LLM 能否正确、高效地使用这些工具。@Tool 注解的描述应该简洁明了地概括工具的功能，例如 @Tool("预约志愿填报服务") 清晰地告诉 LLM，这个方法的作用是处理预约请求。同样，@Tool("根据考生手机号查询预约单") 也明确地指出了 findReservation 方法的用途。对于方法参数，@P 注解的描述则起到了指导 LLM 进行信息提取和格式化的作用。例如，@P("预约沟通时间，格式为：yyyy-MM-dd'T'HH:mm") 不仅说明了参数的含义，还明确指出了期望的日期时间格式，这有助于 LLM 从用户的自然语言输入（如“明天下午三点”）中解析出符合要求的结构化数据。这种详细的参数描述是实现可靠工具调用的关键，它减少了歧义，提高了 LLM 生成正确调用指令的概率，从而保证了整个交互流程的顺畅和准确。

2.3 在AI服务中配置与使用Tools

2.3.1 @AiService注解配置

要在 LangChain4j 的 AI 服务（AI Service）中使用定义好的 Tools，关键步骤是在定义 AI 服务接口时使用 @AiService 注解进行配置。@AiService 是 LangChain4j 提供的一个高级抽象，它允许开发者通过定义一个普通的 Java 接口来声明一个由 LLM 驱动的服务。这个接口中的方法代表了可以与 LLM 进行交互的不同功能。@AiService 注解本身包含多个属性，用于精细地配置 AI 服务的行为。其中，tools 属性是一个核心配置项，它接受一个 Class<?> 类型的数组，用于指定该 AI 服务可以访问和使用的工具类。例如，如果我们的 AI 服务需要处理预约相关的业务，就需要在 @AiService 注解中将 ReservationTool.class 添加到 tools 数组中。这样，当 LLM 在处理与该 AI 服务相关的请求时，它就会知道可以调用 ReservationTool 中定义的方法来完成任务。这种声明式的配置方式非常直观和灵活，使得将工具集成到 AI 服务中变得非常简单。

2.3.2 将工具Bean注入AI服务

在 Spring Boot 环境中，LangChain4j 能够很好地与 Spring 的依赖注入（DI）容器集成。当使用 @AiService 注解定义一个 AI 服务接口时，LangChain4j 会自动为其生成一个代理实现类，并将其注册为 Spring 容器中的一个 Bean。这个代理实现类负责处理与 LLM 的通信、工具调用以及结果整合等复杂逻辑。在 tools 属性中指定的工具类（如 ReservationTool），由于它们本身也使用了 @Component 等 Spring 注解，因此它们也是 Spring 容器中的 Bean。LangChain4j 的 AI 服务代理在运行时，会自动从 Spring 容器中查找并注入这些工具 Bean 的实例。这意味着开发者无需手动进行 Bean 的装配，整个依赖注入过程是完全自动化的。这种设计充分利用了 Spring 框架的强大功能，使得代码更加简洁、解耦，并且易于测试和维护。开发者只需关注于定义好工具类和 AI 服务接口，剩下的集成工作都由框架在幕后完成。

2.3.3 调用流程与效果演示

当用户通过前端界面与集成了 ReservationTool 的 AI 服务进行交互时，整个调用流程如下：首先，用户的自然语言输入（例如：“帮我查一下手机号 13800138000 的预约”）被发送到后端，并由 AI 服务接口的某个方法（例如 chat(String message)）接收。接着，LangChain4j 的代理实现会将这个输入，连同系统提示（System Prompt）和可用的工具列表（包括 ReservationTool 的描述）一起发送给 LLM。LLM 分析输入后，识别出用户的意图是查询预约，并判断需要调用 findReservation 工具。然后，LLM 生成一个结构化的 JSON 调用指令，指定工具名称为 findReservation，参数 phone 的值为 13800138000。LangChain4j 框架接收到这个指令后，会找到 ReservationTool Bean 并调用其 findReservation 方法，传入相应的参数。该方法执行数据库查询，并返回一个 Reservation 对象。LangChain4j 将这个对象序列化后返回给 LLM。最后，LLM 根据返回的预约信息，生成一段友好的自然语言回复（例如：“您好，已为您查到预约信息。考生张三的预约时间是明天下午 3 点。”），并将其返回给用户。这个流畅的交互过程展示了 Tools 工具如何无缝地将 LLM 的语言能力与后端业务逻辑连接起来，实现了从自然语言理解到数据操作再到结果反馈的完整闭环。

3. RAG知识库：检索增强生成

3.1 RAG技术原理

3.1.1 核心思想：结合外部知识

检索增强生成（Retrieval-Augmented Generation, RAG）是一种旨在提升大型语言模型（LLM）性能的技术框架，其核心思想在于将LLM的生成能力与外部知识源的检索能力相结合。传统的LLM虽然能够生成流畅且连贯的文本，但其知识完全来源于训练数据，这导致其知识库存在时效性限制，无法回答训练截止日期之后发生的事件或特定领域的专业知识。RAG通过引入一个可动态更新的外部知识库，有效地解决了这一问题。当用户提出问题时，RAG系统首先会从外部知识库中检索出与问题最相关的文本片段，然后将这些片段作为上下文信息，连同用户的问题一起，输入到LLM中。LLM在接收到这些增强的上下文后，能够生成更准确、更具时效性且更符合特定领域要求的回答。这种方法不仅提升了回答的质量，还增加了LLM应用的可解释性，因为我们可以追溯生成答案所依据的具体知识来源。

3.1.2 工作流程：存储与检索

RAG的工作流程主要可以分为两个核心阶段：存储（Indexing）和检索（Retrieval）。在存储阶段，系统需要处理外部知识源，例如文档、网页或数据库。这个过程通常包括以下几个步骤：首先，使用文档加载器（Document Loader）将原始文本数据加载到系统中；其次，通过文档分割器（Document Splitter）将长文本切分成更小的、语义完整的文本块（Chunks），以便于后续的向量化和检索；然后，利用向量模型（Embedding Model）将每个文本块转换成高维向量，这些向量能够捕捉文本的语义信息；最后，将这些向量及其对应的原始文本块存储到向量数据库（Vector Store）中，从而构建起一个可检索的知识索引。在检索阶段，当用户提交查询时，系统会使用相同的向量模型将用户的查询问题也转换成一个向量。然后，在向量数据库中执行相似性搜索，找出与查询向量最相似（即语义上最相关）的文本块向量。这些被检索出的文本块随后会被用作上下文，与原始问题一同提交给LLM，以生成最终的回答。整个流程实现了从海量外部知识中动态提取相关信息，并辅助LLM进行精准生成的目标。

3.2 RAG快速入门：构建本地知识库

3.2.1 引入langchain4j-easy-rag依赖

为了快速在Java项目中实现RAG功能，LangChain4j提供了一个名为langchain4j-easy-rag的便捷依赖包。这个依赖包旨在简化RAG的初始化和配置过程，它内部集成了内存版的向量数据库和默认的向量模型，使得开发者无需进行复杂的配置即可快速搭建一个基础的RAG应用。根据提供的资料，该依赖的Maven坐标为dev.langchain4j:langchain4j-easy-rag:1.0.1-beta6。通过引入这个依赖，开发者可以省去手动配置和集成向量数据库（如Pinecone, Milvus等）和向量模型（如OpenAI的text-embedding-ada-002）的繁琐步骤。这对于快速原型验证、学习RAG基本原理或在小型项目中应用RAG技术非常有帮助。langchain4j-easy-rag封装了文档加载、文本分割、向量化和存储等一系列核心操作，提供了一个高层次的API，让开发者能够专注于业务逻辑的实现，而不是底层基础设施的搭建。

代码示例：引入langchain4j-easy-rag依赖

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-easy-rag</artifactId>
    <version>1.0.1-beta6</version>
</dependency>

该依赖包含了内存向量数据库和默认向量模型，极大地简化了RAG应用的搭建过程。

3.2.2 加载知识文档：ClassPathDocumentLoader

在构建RAG知识库的第一步是加载外部的知识文档。LangChain4j为此提供了ClassPathDocumentLoader工具类，它能够方便地从项目的类路径（classpath）中加载指定目录下的所有文档。根据教程中的示例，开发者需要将知识文档（例如一个名为《西北大学.pdf》的文件）放置在项目的resources/content目录下。然后，通过调用ClassPathDocumentLoader.loadDocuments("content")方法，系统会自动扫描该目录，读取其中的文件内容，并为每个文件创建一个Document对象。Document对象是LangChain4j中用于封装文档内容及其元数据（如文件名、路径等）的核心数据结构。这个过程将非结构化的文件数据转换成了程序可以处理的结构化对象，为后续的文本分割和向量化奠定了基础。ClassPathDocumentLoader的使用极大地简化了文档加载的流程，使得开发者可以轻松地将本地文件系统集成到RAG应用中。

代码示例：使用ClassPathDocumentLoader加载文档

import dev.langchain4j.data.document.Document;
import dev.langchain4j.data.document.loader.ClassPathDocumentLoader;
import java.util.List;

// 在Spring配置类中定义一个Bean
@Bean
public EmbeddingStore store() {
    // 1. 从类路径的"content"目录加载所有文档
    List<Document> documents = ClassPathDocumentLoader.loadDocuments("content");
    // ... 后续步骤
    return null;
}

此代码段展示了如何加载resources/content目录下的所有文档，并将它们作为Document对象列表返回。

3.2.3 构建向量存储：InMemoryEmbeddingStore

在文档被加载和分割之后，需要一个地方来存储这些文本块及其对应的向量，这就是向量数据库的作用。在langchain4j-easy-rag的快速入门示例中，为了简化配置，使用了InMemoryEmbeddingStore。正如其名，InMemoryEmbeddingStore是一个基于内存的向量数据库实现。它将所有的向量数据存储在应用程序的内存中，因此具有极高的读写性能。开发者只需通过new InMemoryEmbeddingStore()即可创建一个实例。这种方式非常适合于开发、测试环境或数据量较小的应用场景，因为它无需任何外部数据库服务的支持，配置简单，启动迅速。然而，需要注意的是，由于数据完全存储在内存中，一旦应用程序重启，所有已存储的向量数据都会丢失。对于生产环境或需要持久化存储的场景，应该考虑使用如Redis, Pinecone, Milvus等支持持久化的外部向量数据库。

代码示例：创建InMemoryEmbeddingStore实例

import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore;
import dev.langchain4j.store.embedding.EmbeddingStore;

@Bean
public EmbeddingStore store() {
    // 1. 加载文档 (略)
    List<Document> documents = ClassPathDocumentLoader.loadDocuments("content");
    
    // 2. 构建内存向量数据库操作对象
    InMemoryEmbeddingStore store = new InMemoryEmbeddingStore();
    
    // ... 后续步骤
    return store;
}

这段代码创建了一个InMemoryEmbeddingStore的实例，用于在内存中存储和管理向量数据。

3.2.4 文档处理与向量化存储

在加载了文档并创建了向量存储之后，接下来的关键步骤是将文档进行处理（分割）并转换为向量，最后存储到向量数据库中。LangChain4j提供了一个高度封装的工具类EmbeddingStoreIngestor来简化这一复杂流程。这个类内部集成了文本分割器、向量模型和存储逻辑，开发者只需通过其构建器（builder）模式进行简单配置即可。具体来说，需要将之前创建的EmbeddingStore实例传递给EmbeddingStoreIngestor.builder().embeddingStore(store)，以指定向量的存储位置。构建完成后，调用ingestor.ingest(documents)方法，并传入需要处理的Document对象列表。在ingest方法的内部，EmbeddingStoreIngestor会自动完成以下操作：首先，使用其内置的文本分割器（如按段落或句子分割）将每个Document分割成多个TextSegment；然后，使用其内置的向量模型将每个TextSegment转换成一个向量；最后，将这个向量及其对应的TextSegment一同存储到指定的EmbeddingStore中。这个过程完全自动化，极大地降低了RAG实现的门槛。

代码示例：使用EmbeddingStoreIngestor进行文档处理和存储

import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.data.document.Document;
import dev.langchain4j.data.document.loader.ClassPathDocumentLoader;
import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore;
import dev.langchain4j.rag.content.retriever.ContentRetriever;

@Bean
public EmbeddingStore store() {
    // 1. 加载文档
    List<Document> documents = ClassPathDocumentLoader.loadDocuments("content");
    
    // 2. 构建内存向量数据库
    InMemoryEmbeddingStore store = new InMemoryEmbeddingStore();
    
    // 3. 构建EmbeddingStoreIngestor，用于文档分割、向量化及存储
    EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
            .embeddingStore(store) // 指定向量存储位置
            .build();
    
    // 4. 执行ingest操作，完成所有流程
    ingestor.ingest(documents);
    
    return store;
}

此代码片段完整地展示了从加载文档到将其处理并存储到内存向量数据库的全过程，是RAG存储阶段的核心实现。

3.3 核心API：实现知识检索

3.3.1 构建ContentRetriever对象

在RAG的检索阶段，核心任务是构建一个ContentRetriever对象，它负责根据用户的查询从向量数据库中检索出最相关的知识片段。根据教程的目录结构，这部分内容位于3.7.2.2 检索章节下，具体分为3.7.2.2.1 构建ContentRetriever对象和3.7.2.2.2 配置ContentRetriever对象。虽然具体的代码示例在当前提供的资料中不完整，但基于LangChain4j的通用模式和EmbeddingStoreIngestor的使用方式，我们可以推断其构建过程。通常，ContentRetriever的实现类会与EmbeddingStore紧密关联。例如，可能会存在一个EmbeddingStoreContentRetriever类，其构建器需要传入一个EmbeddingStore实例。这个ContentRetriever对象将封装向量相似性搜索的逻辑，包括将用户查询向量化、在EmbeddingStore中执行搜索、并根据相似度得分筛选和返回最相关的TextSegment列表。这个对象是连接用户查询和知识库的桥梁，是实现RAG检索功能的关键组件。

3.3.2 配置检索参数：maxResults与minScore

在构建ContentRetriever对象时，通常需要配置一些关键参数来控制检索行为，其中最重要的两个参数是maxResults和minScore。maxResults参数用于限制每次检索返回的最相关文本片段的数量。设置一个合理的maxResults值（例如，3到5个）可以避免向LLM提供过多无关或冗余的信息，从而防止上下文窗口被浪费，并提高LLM生成答案的准确性和效率。minScore（或称为相似度阈值）参数则用于过滤掉相似度得分过低的文本片段。相似度得分通常是一个介于0和1之间的浮点数，得分越高表示文本片段与查询的语义相关性越强。通过设置一个minScore阈值（例如，0.7），可以确保只有那些真正相关的、高质量的知识片段才会被送入LLM，从而避免引入噪声信息，干扰LLM的判断。这两个参数的配置需要根据具体的应用场景和数据特点进行调整，以达到最佳的检索效果。在LangChain4j中，这些参数通常可以通过ContentRetriever的构建器进行设置。

3.3.3 在AI服务中集成ContentRetriever

构建并配置好ContentRetriever对象后，最后一步是将其集成到AI服务（AI Service）中。在LangChain4j中，AI服务通常是通过AiServices工具类创建的动态代理对象。开发者需要定义一个接口，并在接口方法上使用@SystemMessage、@UserMessage等注解来描述LLM的行为。为了启用RAG功能，需要在这个AI服务的构建过程中，将之前创建的ContentRetriever实例注入进去。例如，通过AiServices.builder(ConsultantService.class).contentRetriever(contentRetriever).build()这样的方式进行配置。一旦集成完成，当用户调用AI服务的方法并传入问题时，AiServices框架会自动执行以下流程：首先，将用户问题传递给ContentRetriever进行检索；然后，将检索到的知识片段和原始问题组合成一个增强的提示（Prompt）；最后，将这个增强的提示发送给LLM，并返回LLM生成的答案。这种集成方式将RAG的检索逻辑无缝地融入到了AI服务的调用流程中，对开发者来说是完全透明的，极大地简化了RAG应用的开发。

3.4 收尾工作与测试

3.4.1 完整配置示例

一个完整的RAG配置通常涉及多个Spring Bean的协同工作，包括嵌入模型、向量存储、内容检索器等。以下是一个在Spring Boot配置类中定义这些Bean的示例：

import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.openai.OpenAiEmbeddingModel;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore;
import dev.langchain4j.rag.content.retriever.ContentRetriever;
import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class RagConfig {

    @Bean
    public EmbeddingModel embeddingModel() {
        // 配置OpenAI的嵌入模型
        return OpenAiEmbeddingModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("text-embedding-ada-002")
                .build();
    }

    @Bean
    public EmbeddingStore<TextSegment> embeddingStore() {
        // 创建内存向量存储
        return new InMemoryEmbeddingStore<>();
    }

    @Bean
    public ContentRetriever contentRetriever(EmbeddingModel embeddingModel, EmbeddingStore<TextSegment> embeddingStore) {
        // 构建并配置内容检索器
        return EmbeddingStoreContentRetriever.builder()
                .embeddingStore(embeddingStore)
                .embeddingModel(embeddingModel)
                .maxResults(3)
                .minScore(0.75)
                .build();
    }

    // 在应用启动时，可以调用一个方法来加载和向量化文档
    // @Bean
    // public CommandLineRunner loadData(EmbeddingModel embeddingModel, EmbeddingStore<TextSegment> embeddingStore) {
    //     return args -> {
    //         // 加载、分割、嵌入并存储文档
    //         // ...
    //     };
    // }
}

这个配置类清晰地定义了RAG所需的核心组件，并将它们注入到Spring容器中，供@AiService使用。

3.4.2 测试RAG效果

测试是验证RAG系统是否按预期工作的关键步骤。可以通过编写单元测试或简单地通过Controller接口进行手动测试。

1. 准备测试数据：确保你的知识文档（如knowledge.txt）中包含一些可以被提问的内容。例如，文档中有一段关于“LangChain4j支持哪些LLM”的描述。
2. 启动应用：运行Spring Boot应用。
3. 发送测试请求：通过Postman、curl或前端页面，向你的聊天接口发送一个与知识库内容相关的问题，例如：“LangChain4j支持哪些大语言模型？”
4. 观察结果：检查返回的回答。一个成功的RAG系统应该能够准确地从知识库中找到相关信息，并生成一个基于这些信息的、详细的回答。如果回答不准确或无法回答，则需要检查前面的配置步骤，特别是文档加载、分割、嵌入模型和检索参数的设置。

此外，为了避免每次启动应用都重新加载和向量化文档（这在开发阶段尤其耗时），可以将向量化后的数据持久化。例如，如果使用Redis作为向量存储，就可以实现数据的持久化。在收尾工作部分，文章目录中也提到了“避免每次启动程序都做向量化的操作”，这通常通过将处理好的向量数据存储在持久化的向量数据库（如Redis, Pinecone, Milvus等）中来实现 。

4. 高级特性与最佳实践

4.1 流式调用（Streaming）

4.1.1 使用StreamingChatLanguageModel

在构建交互式 AI 应用时，用户体验至关重要。传统的 API 调用方式是阻塞式的，即用户发送请求后需要等待 LLM 生成完整的回答才能看到结果，这在生成长文本时会造成明显的延迟。为了解决这个问题，LangChain4j 提供了对流式调用（Streaming） 的支持，其核心是 StreamingChatLanguageModel 接口。与 ChatLanguageModel 不同，StreamingChatLanguageModel 不会一次性返回完整的 AiMessage，而是通过一个回调机制，将 LLM 生成的内容以增量（token by token）的方式实时地推送给客户端。这种非阻塞的交互模式极大地提升了应用的响应速度和用户体验，用户可以像与真人对话一样，实时地看到 AI 正在“思考”和“打字”的过程。LangChain4j 为所有主流的 LLM 提供商都提供了对应的 StreamingChatLanguageModel 实现，例如 OpenAiStreamingChatModel，其配置方式与 OpenAiChatModel 类似，同样可以通过 Spring Boot 的自动配置或手动构建器模式来创建。

4.1.2 实现流式响应

要在 Spring Boot 应用中实现流式响应，通常需要将 StreamingChatLanguageModel 与响应式编程库（如 Reactor）结合使用。LangChain4j 为此提供了专门的集成模块 langchain4j-reactor。通过该模块，开发者可以轻松地将 LLM 的流式输出转换为一个 Flux<String> 或 Flux<ChatResponse> 对象。Flux 是 Reactor 中的一个核心类型，代表一个异步的、可能无限的数据序列。当客户端订阅这个 Flux 时，每当 LLM 生成一个新的 token，它就会被推送到客户端，从而实现真正的实时响应。在 Controller 层，可以直接返回 Flux<String>，Spring WebFlux 会自动处理底层的 Server-Sent Events (SSE) 或 HTTP/2 流，将数据分块发送给前端。这种方式不仅提升了用户体验，还能有效降低服务器的内存占用，因为它不需要在内存中存储完整的响应内容。

4.2 消息注解与会话记忆

4.2.1 @SystemMessage与@UserMessage

在定义 AI 服务接口时，LangChain4j 提供了一系列注解来简化提示词（Prompt）的构建，其中 @SystemMessage 和 @UserMessage 是最常用的两个。@SystemMessage 注解用于定义系统级别的指令，它通常用于设定 AI 的角色、行为准则、回答风格或提供必要的背景知识。例如，可以设置 @SystemMessage("你是一个专业的法律顾问，请用严谨、客观的语言回答用户的问题。")。这个系统消息会在每次调用时作为对话的初始上下文发送给 LLM，从而引导其生成符合预期的回答。@UserMessage 注解则用于标记方法参数，表明该参数是用户的输入。LangChain4j 会自动将方法参数的值作为用户消息发送给 LLM。通过组合使用这两个注解，开发者可以以声明式的方式构建结构化的提示词，而无需在代码中手动拼接字符串，使得代码更加清晰和易于维护。

4.2.2 配置ChatMemory

为了让 AI 应用能够进行有意义的多轮对话，必须实现会话记忆（Chat Memory） 。会话记忆负责存储和管理与特定用户的对话历史，并在每次新的交互时，将相关的历史信息提供给 LLM，使其能够理解上下文。LangChain4j 提供了 ChatMemory 接口及多种实现，如 MessageWindowChatMemory 和 TokenWindowChatMemory。MessageWindowChatMemory 会保留最近 N 条消息，而 TokenWindowChatMemory 则会保留最近 N 个 token 的对话内容。在 Spring Boot 应用中，可以通过配置类创建一个 ChatMemory Bean，并将其注入到 AI 服务中。例如，可以创建一个 MessageWindowChatMemory.withMaxMessages(10) 的实例，这意味着 AI 将能记住最近的 10 轮对话。这种机制是实现连贯、有逻辑的多轮对话的基础。

4.2.3 实现多轮对话

结合 @AiService 注解和 ChatMemory，实现多轮对话变得非常简单。首先，在定义 AI 服务接口时，需要为每个对话会话提供一个唯一的标识符（memoryId），这通常通过 @MemoryId 注解来标记一个方法参数。这个 memoryId 可以是一个用户 ID、会话 ID 或任何能够唯一标识一次对话的字符串。当调用 AI 服务的方法时，LangChain4j 会根据这个 memoryId 从 ChatMemory 中加载对应的对话历史，并将其与当前的用户消息一起发送给 LLM。LLM 在生成回答后，新的对话内容（用户消息和 AI 回复）又会被保存回 ChatMemory 中，与 memoryId 关联。这样，下一次使用相同的 memoryId 调用时，LLM 就能看到完整的对话历史，从而实现上下文感知的多轮对话。

4.3 AI服务（AI Service）模式

4.3.1 @AiService注解详解

@AiService 是 LangChain4j 提供的最高级别的抽象，它彻底改变了与 LLM 交互的方式。通过在一个普通的 Java 接口上添加 @AiService 注解，开发者可以声明一个由 AI 驱动的服务。LangChain4j 会在运行时通过动态代理技术，自动生成该接口的实现类。这个实现类封装了所有与 LLM 交互的底层细节，包括调用模型、处理响应、管理会话记忆、执行工具调用以及检索知识库等。开发者只需在接口方法上使用 @SystemMessage、@UserMessage 等注解来定义交互逻辑，而无需编写任何实现代码。这种模式极大地简化了复杂 AI 应用的开发，使得代码更加简洁、可读性更强，并且易于测试和维护。

4.3.2 显式装配（EXPLICIT）模式

在使用 @AiService 时，可以通过 wiringMode 属性来指定依赖的装配模式。AiServiceWiringMode.EXPLICIT 是其中一种模式，意为显式装配。在这种模式下，AI 服务所需的所有组件，如 chatModel、streamingChatModel、chatMemoryProvider、contentRetriever 和 tools，都必须在 @AiService 注解中通过字符串形式明确指定其对应的 Spring Bean 名称。这种方式虽然需要手动配置，但它提供了最大的灵活性和控制力，使得开发者可以精确地控制 AI 服务所使用的每一个组件。例如，tools = "reservationTool" 明确指定了要使用的工具 Bean。这种显式声明的方式也使得依赖关系一目了然，便于理解和调试。

4.3.3 整合Tools、RAG与记忆

@AiService 的强大之处在于它能够无缝地整合 LangChain4j 的所有核心功能。通过在一个注解中同时配置 tools、contentRetriever 和 chatMemoryProvider，开发者可以构建一个功能极其强大的 AI 代理。例如，一个配置了这三个属性的 AI 服务，将具备以下能力：

1. 会话记忆：能够记住与用户的对话历史，实现多轮对话。
2. 知识库检索（RAG） ：能够根据用户问题，从外部知识库中检索相关信息，生成基于事实的回答。
3. 工具调用（Tools） ：能够根据用户需求，调用外部工具执行具体操作，如查询数据库、调用 API 等。

这种整合能力使得开发者可以像搭积木一样，将不同的功能模块组合在一起，构建出能够处理复杂任务的智能应用。例如，一个智能客服机器人，它可以记住用户的偏好（记忆），回答关于产品的问题（RAG），并帮助用户查询订单状态（Tools）。所有这些复杂的功能，都通过一个简洁的 @AiService 接口定义来完成，这正是 LangChain4j 框架设计哲学的体现。