Java 大模型应用项目实战：硅谷小智医疗助手

4、封装对话对象

package com.donglin.java.ai.langchain4j.bean;

import lombok.Data;

@Data
public class ChatForm {
    private Long memoryId; // 对话 id
    private String message; // 用户问题
}

5、添加 Controller 方法

package com.donglin.java.ai.langchain4j.controller;

import com.donglin.java.ai.langchain4j.assistant.XiaozhiAgent;
import com.donglin.java.ai.langchain4j.bean.ChatForm;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "硅谷小智")
@RestController
@RequestMapping("/xiaozhi")
public class XiaozhiController {
    @Autowired
    private XiaozhiAgent xiaozhiAgent;

    @Operation(summary = "对话")
    @PostMapping("/chat")
    public String chat(@RequestBody ChatForm chatForm) {
        return xiaozhiAgent.chat(chatForm.getMemoryId(), chatForm.getMessage());
    }
}

6、待优化

• 信息查询：提示词中还应该提供医院信息（如位置信息，营业时间等）、科室信息（都有哪些科室）、医生信息（都有哪些医生）
• 业务实现：预约、取消预约、查询是否预约等
• 技术选型：信息查询可以使用 RAG 检索增强生成，业务实现需要通过 Function Calling 函数调用

二、Function Calling 函数调用

Function Calling 函数调用 也叫 Tools 工具。

1、入门案例

例如，大语言模型本身并不擅长数学运算。如果应用场景中偶尔会涉及到数学计算，我们可以为他提供一个'数学工具'。当我们提出问题时，大语言模型会判断是否使用某个工具。

1.1、创建工具类

用 @Tool 注解的方法：既可以是静态的，也可以是非静态的；可以具有任何可见性（公有、私有等）。

package com.donglin.java.ai.langchain4j.tools;

import dev.langchain4j.agent.tool.Tool;
import org.springframework.stereotype.Component;

@Component
public class CalculatorTools {
    @Tool
    double sum(double a, double b) {
        System.out.println("调用加法运算");
        return a + b;
    }

    @Tool
    double squareRoot(double x) {
        System.out.println("调用平方根运算");
        return Math.sqrt(x);
    }
}

1.2、配置工具类

在 SeparateChatAssistant 中添加 tools 属性配置

@AiService(
    wiringMode = EXPLICIT,
    chatModel = "qwenChatModel",
    chatMemoryProvider = "chatMemoryProvider",
    tools = "calculatorTools" // 配置 tools
)

1.3、测试工具类

package com.donglin.java.ai.langchain4j;

import com.donglin.java.ai.langchain4j.assistant.SeparateChatAssistant;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
public class ToolsTest {
    @Autowired
    private SeparateChatAssistant separateChatAssistant;

    @Test
    public void testCalculatorTools() {
        String answer = separateChatAssistant.chat(1, "1+2 等于几，475695037565 的平方根是多少？");
        // 答案：3，689706.4865
        System.out.println(answer);
    }
}

测试后可以查看持久化存储中 SYSTEM、USER、AI 以及 Tools 的消息，分析 tools 的调用流程。

2、@Tool 注解的可选字段

@Tool 注解有两个可选字段：

• name（工具名称）：工具的名称。如果未提供该字段，方法名会作为工具的名称。
• value（工具描述）：工具的描述信息。

通常最好提供清晰且有意义的名称和描述，这样大语言模型就能获得更多信息，以决定是否调用给定的工具以及如何调用。

3、@P 注解

方法参数可以选择使用 @P 注解进行标注。 @P 注解有两个字段：

• value：参数的描述信息，这是必填字段。
• required：表示该参数是否为必需项，默认值为 true，此为可选字段。

4、@ToolMemoryId

如果你的 AIService 方法中有一个参数使用 @MemoryId 注解，那么你也可以使用 @ToolMemoryId 注解 @Tool 方法中的一个参数。提供给 AIService 方法的值将自动传递给 @Tool 方法。

package com.donglin.java.ai.langchain4j.tools;

public class CalculatorTools {
    @Tool(name = "加法", value = "返回两个参数相加之和")
    double sum(@ToolMemoryId int memoryId, @P(value = "加数 1", required = true) double a, @P(value = "加数 2", required = true) double b) {
        System.out.println("调用加法运算 " + memoryId);
        return a + b;
    }

    @Tool(name = "平方根", value = "返回给定参数的平方根")
    double squareRoot(@ToolMemoryId int memoryId, double x) {
        System.out.println("调用平方根运算 " + memoryId);
        return Math.sqrt(x);
    }
}

5、解析

结合例子解释一下「@MemoryId ↔ @ToolMemoryId」的关系。

1. 有什么问题要解决？ 一个 AI 助手通常会有多个用户、每个用户可能有多个会话。你需要一种机制来区分这条对话属于谁、属于哪个会话，这样才能做到记忆隔离，不会'串线'。这就是 @MemoryId 的作用：它就是'记忆编号 / 会话 ID'。

2. @MemoryId 在 AIService 层

   @AiService
   public interface Assistant {
       // memoryId = 谁在聊天（哪个用户/哪个会话）
       String chat(@MemoryId int memoryId, @UserMessage String userMessage);
   }
   

   调用时你会写：assistant.chat(1, "帮我算一下 3 + 5")。这里 memoryId=1 的聊天属于「用户 1 / 会话 1」。

3. 当 AI 调用工具（@Tool） AI 在对话中可能会调用你提供的工具（例如 CalculatorTools）。问题是：工具方法也要知道是谁在调用，不然不同用户的数据就混了。这里用到 @ToolMemoryId。

   public class CalculatorTools {
       @Tool(name = "加法")
       double sum(@ToolMemoryId int memoryId, @P("加数 1") double a, @P("加数 2") double b) {
           System.out.println("调用加法，memoryId=" + memoryId);
           return a + b;
       }
   }
   

4. 运行链路

   1. 用户 A 发消息 → assistant.chat(1, "帮我算 3 + 5")，这里 @MemoryId = 1。
   2. LLM 决定调用工具 → CalculatorTools.sum(...)。
   3. 框架自动把 @MemoryId 的值 (1) 传给工具方法的 @ToolMemoryId 参数。 最终调用就变成：sum(1, 3, 5);。

5. 总结一句话

   • @MemoryId：告诉 AIService 这一条消息属于谁/哪个会话。
   • @ToolMemoryId：工具方法里拿到同样的 ID，保证工具调用和对话上下文一一对应，不串用户。

三、项目实战 - 优化硅谷小智

1、预约业务的实现

这部分我们实现硅谷小智的查询挂号、预约挂号、取消挂号的功能。

1.1、创建 MySQL 数据库表

CREATE DATABASE `guiguxiaozhi`;
USE `guiguxiaozhi`;
CREATE TABLE `appointment` (
  `id` BIGINT NOT NULL AUTO_INCREMENT,
  `username` VARCHAR(50) NOT NULL,
  `id_card` VARCHAR(18) NOT NULL,
  `department` VARCHAR(50) NOT NULL,
  `date` VARCHAR(10) NOT NULL,
  `time` VARCHAR(10) NOT NULL,
  `doctor_name` VARCHAR(50) DEFAULT NULL,
  PRIMARY KEY (`id`)
);

1.2、引入依赖

<!-- Mysql Connector -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.3.0</version>
</dependency>
<!-- mybatis-plus 持久层 -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>${mybatis-plus.version}</version>
</dependency>

1.3、配置数据库连接

application.properties

# 基本数据源配置
spring.datasource.url=jdbc:mysql://localhost:3306/guiguxiaozhi?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&useSSL=false
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
# 开启 SQL 日志打印
mybatis-plus.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl

1.4、创建实体类

package com.donglin.java.ai.langchain4j.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
public class Appointment {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String username;
    private String idCard;
    private String department;
    private String date;
    private String time;
    private String doctorName;
}

1.5、Mapper

接口

package com.donglin.java.ai.langchain4j.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.donglin.java.ai.langchain4j.entity.Appointment;
import org.apache.ibatis.annotations.Mapper;

@Mapper
public interface AppointmentMapper extends BaseMapper<Appointment> {}

XML：在 resources 下创建 mapper 目录，创建 AppointmentMapper.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.donglin.java.ai.langchain4j.mapper.AppointmentMapper"></mapper>

1.6、Service

接口

package com.donglin.java.ai.langchain4j.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.donglin.java.ai.langchain4j.entity.Appointment;

public interface AppointmentService extends IService<Appointment> {
    Appointment getOne(Appointment appointment);
}

实现类

package com.donglin.java.ai.langchain4j.service.impl;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.donglin.java.ai.langchain4j.entity.Appointment;
import com.donglin.java.ai.langchain4j.mapper.AppointmentMapper;
import com.donglin.java.ai.langchain4j.service.AppointmentService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class AppointmentServiceImpl extends ServiceImpl<AppointmentMapper, Appointment> implements AppointmentService {
    @Autowired
    private AppointmentMapper baseMapper;

    /**
     * 查询挂号是否存在
     * @param appointment
     * @return
     */
    @Override
    public Appointment getOne(Appointment appointment) {
        LambdaQueryWrapper<Appointment> queryWrapper = new LambdaQueryWrapper<>();
        queryWrapper.eq(Appointment::getUsername, appointment.getUsername());
        queryWrapper.eq(Appointment::getIdCard, appointment.getIdCard());
        queryWrapper.eq(Appointment::getDepartment, appointment.getDepartment());
        queryWrapper.eq(Appointment::getDate, appointment.getDate());
        queryWrapper.eq(Appointment::getTime, appointment.getTime());
        Appointment appointmentDB = baseMapper.selectOne(queryWrapper);
        return appointmentDB;
    }
}

1.7、创建测试用例

package com.donglin.java.ai.langchain4j;

import com.donglin.java.ai.langchain4j.entity.Appointment;
import com.donglin.java.ai.langchain4j.service.AppointmentService;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
class AppointmentServiceTest {
    @Autowired
    private AppointmentService appointmentService;

    @Test
    void testGetOne() {
        Appointment appointment = new Appointment();
        appointment.setUsername("张三");
        appointment.setIdCard("123456789012345678");
        appointment.setDepartment("内科");
        appointment.setDate("2025-04-14");
        appointment.setTime("上午");
        Appointment appointmentDB = appointmentService.getOne(appointment);
        System.out.println(appointmentDB);
    }

    @Test
    void testSave() {
        Appointment appointment = new Appointment();
        appointment.setUsername("张三");
        appointment.setIdCard("123456789012345678");
        appointment.setDepartment("内科");
        appointment.setDate("2025-04-14");
        appointment.setTime("上午");
        appointment.setDoctorName("张医生");
        appointmentService.save(appointment);
    }

    @Test
    void testRemoveById() {
        appointmentService.removeById(1L);
    }
}

2、Tools

2.1、创建 Tools

package com.donglin.java.ai.langchain4j.tools;

import com.donglin.java.ai.langchain4j.entity.Appointment;
import com.donglin.java.ai.langchain4j.service.AppointmentService;
import dev.langchain4j.agent.tool.P;
import dev.langchain4j.agent.tool.Tool;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

@Component
public class AppointmentTools {
    @Autowired
    private AppointmentService appointmentService;

    @Tool(name = "预约挂号", value = "根据参数，先执行工具方法 queryDepartment 查询是否可预约，并直接给用户回答是否可预约，并让用户确认所有预约信息，用户确认后再进行预约。")
    public String bookAppointment(Appointment appointment) {
        // 查找数据库中是否包含对应的预约记录
        Appointment appointmentDB = appointmentService.getOne(appointment);
        if (appointmentDB == null) {
            appointment.setId(null); // 防止大模型幻觉设置了 id
            if (appointmentService.save(appointment)) {
                return "预约成功，并返回预约详情";
            } else {
                return "预约失败";
            }
        }
        return "您在相同的科室和时间已有预约";
    }

    @Tool(name = "取消预约挂号", value = "根据参数，查询预约是否存在，如果存在则删除预约记录并返回取消预约成功，否则返回取消预约失败")
    public String cancelAppointment(Appointment appointment) {
        Appointment appointmentDB = appointmentService.getOne(appointment);
        if (appointmentDB != null) {
            // 删除预约记录
            if (appointmentService.removeById(appointmentDB.getId())) {
                return "取消预约成功";
            } else {
                return "取消预约失败";
            }
        }
        // 取消失败
        return "您没有预约记录，请核对预约科室和时间";
    }

    @Tool(name = "查询是否有号源", value = "根据科室名称，日期，时间和医生查询是否有号源，并返回给用户")
    public boolean queryDepartment(@P(value = "科室名称") String name, @P(value = "日期") String date, @P(value = "时间，可选值：上午、下午") String time, @P(value = "医生名称", required = false) String doctorName) {
        System.out.println("查询是否有号源");
        System.out.println("科室名称：" + name);
        System.out.println("日期：" + date);
        System.out.println("时间：" + time);
        System.out.println("医生名称：" + doctorName);
        // TODO 维护医生的排班信息：如果没有指定医生名字，则根据其他条件查询是否有可以预约的医生（有返回 true，否则返回 false）；如果指定了医生名字，则判断医生是否有排班（没有排版返回 false）；如果有排班，则判断医生排班时间段是否已约满（约满返回 false，有空闲时间返回 true）
        return true;
    }
}

2.2、配置 Tools

在 XiaozhiAgent 中添加 tools 配置

@AiService(
    wiringMode = EXPLICIT,
    chatModel = "qwenChatModel",
    chatMemoryProvider = "chatMemoryProviderXiaozhi",
    tools = "appointmentTools" // tools 配置
)

2.3、测试

在 Controller 中测试

step1: {"memoryId": 1, "message": "我想预约明天上午的神经内科"}
step2: {"memoryId": 1, "message": "张三丰，130821200909093777, 李主任"}
step3: {"memoryId": 1, "message": "我想预约明天上午的神经内科 张三丰，130821200909093777, 李主任"}
step4: {"memoryId": 1, "message": "对不起，明天临时有事，请帮我取消预约"}

四、检索增强生成 RAG

1、如何让大模型回答专业领域的知识

LLM 的知识仅限于它所训练的数据。如果你想让 LLM 了解特定领域的知识或专有数据，你可以：

• 使用 RAG
• 使用你的数据微调 LLM
• 结合 RAG 和微调

1.1、微调大模型

在现有大模型的基础上，使用小规模的特定任务数据进行再次训练，调整模型参数，让模型更精确地处理特定领域或任务的数据。更新需重新训练，计算资源和时间成本高。

• 优点：一次会话只需一次模型调用，速度快，在特定任务上性能更高，准确性也更高。
• 缺点：知识更新不及时，模型训成本高、训练周期长。
• 应用场景：适合知识库稳定、对生成内容准确性和风格要求高的场景，如对上下文理解和语言生成质量要求高的文学创作、专业文档生成等。

1.2、RAG

Retrieval-Augmented Generation 检索增强生成 将原始问题以及提示词信息发送给大语言模型之前，先通过外部知识库检索相关信息，然后将检索结果和原始问题一起发送给大模型，大模型依据外部知识库再结合自身的训练数据，组织自然语言回答问题。通过这种方式，大语言模型可以获取到特定领域的相关信息，并能够利用这些信息进行回复。

• 优点：数据存储在外部知识库，可以实时更新，不依赖对模型自身的训练，成本更低。
• 缺点：需要两次查询：先查询知识库，然后再查询大模型，性能不如微调大模型。
• 应用场景：适用于知识库规模大且频繁更新的场景，如企业客服、实时新闻查询、法律和医疗领域的最新知识问答等。

1.3、RAG 常用方法

• 全文（关键词）搜索。这种方法通过将问题和提示词中的关键词与知识库文档数据库进行匹配来搜索文档。根据这些关键词在每个文档中的出现频率和相关性对搜索结果进行排序。
• 向量搜索，也被称为'语义搜索'。文本通过嵌入模型被转换为数字向量。然后，它根据查询向量与文档向量之间的余弦相似度或其他相似性/距离度量来查找和排序文档，从而捕捉更深层次的语义含义。
• 混合搜索。结合多种搜索方法（例如，全文搜索 + 向量搜索）通常可以提高搜索的效果。

2、向量搜索 vector search

2.1、向量 Vectors

可以将向量理解为从空间中的一个点到另一个点的移动。很多时候，我们处理的向量是从原点 (0, 0) 开始的，比如 b。这样我们可以省略向量起点部分，直接说 b 是向量 (100, -50)。

如何将向量的概念扩展到非数值实体上呢（例如文本）？

2.2、维度 Dimensions

如我们所见，每个数值向量都有 x 和 y 坐标（或者在多维系统中是 x、y、z，…）。x、y、z…是这个向量空间的轴，称为维度。对于我们想要表示为向量的一些非数值实体，我们首先需要决定这些维度，并为每个实体在每个维度上分配一个值。

因此，我们的汽车 Car 向量将是 (4, yes, yes, 5)，或者用数值表示为 (4, 1, 1, 5)（将 yes 设为 1，no 设为 0）。 向量的每个维度代表数据的不同特性，维度越多对事务的描述越精确，我们可以使用'是否有翅膀'、'是否使用柴油'、'最高速度'、'平均重量'、'价格'等等更多的维度信息。

2.3、相似度 Similarity

如果用户搜索'轿车 Car'，你希望能够返回所有与'汽车 automobile'和'车辆 vehicle'等信息相关的结果。向量搜索就是实现这个目标的一种方法。

如何确定哪些是最相似的？ 每个向量都有一个长度和方向。例如，在这个图中，p 和 a 指向相同的方向，但长度不同。p 和 b 正好指向相反的方向，但有相同的长度。然后还有 c，长度比 p 短一点，方向不完全相同，但很接近。

那么，哪一个最接近 p 呢？ 如果'相似'仅仅意味着指向相似的方向，那么 a 是最接近 p 的。接下来是 c。b 是最不相似的，因为它正好指向与 p 相反的方向。如果'相似'仅仅意味着相似的长度，那么 b 是最接近 p 的（因为它有相同的长度），接下来是 c，然后是 a。 由于向量通常用于描述语义意义，仅仅看长度通常无法满足需求。大多数相似度测量要么仅依赖于方向，要么同时考虑方向和大小。

2.4、相似度测量 Measures of similarity

相似度测量即相似度计算。四种常见的向量相似度计算方法。

• 欧几里得距离 Euclidean distance
• 曼哈顿距离 Manhattan distance
• 点积 Dot product
• 余弦相似度 Cosine similarity

3、RAG 的过程

RAG 过程分为 2 个不同的阶段：索引和检索。

3.1、索引阶段

在索引阶段，对知识库文档进行预处理，可实现检索阶段的高效搜索。

• 以下是索引阶段的简化图：加载知识库文档 ==> 将文档中的文本分段 ==> 利用向量大模型将分段后的文本转换成向量 ==> 将向量存入向量数据库

为什么要进行文本分段？ 大语言模型（LLM）的上下文窗口有限，所以整个知识库可能无法全部容纳其中。

• 你在提问中提供的信息越多，大语言模型处理并做出回应所需的时间就越长。
• 你在提问中提供的信息越多，花费也就越多。
• 提问中的无关信息可能会干扰大语言模型，增加产生幻觉（生成错误信息）的几率。 我们可以通过将知识库分割成更小、更易于理解的片段来解决这些问题。

3.2、检索阶段

• 以下是检索阶段的简化图：通过向量模型将用户查询转换成向量 ==> 在向量数据库中根据用户查询进行相似度匹配 ==> 将用户查询和向量数据库中匹配到的相关内容一起交给 LLM 处理

4、文档加载器 Document Loader

4.1、常见文档加载器

• 来自 langchain4j 模块的文件系统文档加载器（FileSystemDocumentLoader）
• 来自 langchain4j 模块的类路径文档加载器（ClassPathDocumentLoader）
• 来自 langchain4j 模块的网址文档加载器（UrlDocumentLoader）
• 来自 langchain4j-document-loader-amazon-s3 模块的亚马逊 S3 文档加载器（AmazonS3DocumentLoader）
• 来自 langchain4j-document-loader-azure-storage-blob 模块的 Azure Blob 存储文档加载器（AzureBlobStorageDocumentLoader）
• 来自 langchain4j-document-loader-github 模块的 GitHub 文档加载器（GitHubDocumentLoader）
• 来自 langchain4j-document-loader-google-cloud-storage 模块的谷歌云存储文档加载器（GoogleCloudStorageDocumentLoader）
• 来自 langchain4j-document-loader-selenium 模块的 Selenium 文档加载器（SeleniumDocumentLoader）
• 来自 langchain4j-document-loader-tencent-cos 模块的腾讯云对象存储文档加载器（TencentCosDocumentLoader）

4.2、测试文档加载

package com.donglin.java.ai.langchain4j;

import dev.langchain4j.data.document.Document;
import dev.langchain4j.data.document.loader.FileSystemDocumentLoader;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
public class RAGTest {
    @Test
    public void testReadDocument() {
        // 使用 FileSystemDocumentLoader 读取指定目录下的知识库文档
        // 并使用默认的文档解析器 TextDocumentParser 对文档进行解析
        Document document = FileSystemDocumentLoader.loadDocument("E:/knowledge/测试.txt");
        System.out.println(document.text());
    }
}

其他加载文档的方式

// 加载单个文档
Document document = FileSystemDocumentLoader.loadDocument("E:/knowledge/file.txt", new TextDocumentParser());
// 从一个目录中加载所有文档
List<Document> documents = FileSystemDocumentLoader.loadDocuments("E:/knowledge", new TextDocumentParser());
// 从一个目录中加载所有的.txt 文档
PathMatcher pathMatcher = FileSystems.getDefault().getPathMatcher("glob:*.txt");
List<Document> documents = FileSystemDocumentLoader.loadDocuments("E:/knowledge", pathMatcher, new TextDocumentParser());
// 从一个目录及其子目录中加载所有文档
List<Document> documents = FileSystemDocumentLoader.loadDocumentsRecursively("E:/knowledge", new TextDocumentParser());

5、文档解析器 Document Parser

5.1、常见文档解析器

文档可以是各种格式的文件，比如 PDF、DOC、TXT 等等。为了解析这些不同格式的文件，有一个'文档解析器'（DocumentParser）接口，并且我们的库中包含了该接口的几种实现方式：

• 来自 langchain4j 模块的文本文档解析器（TextDocumentParser），它能够解析纯文本格式的文件（例如 TXT、HTML、MD 等）。
• 来自 langchain4j-document-parser-apache-pdfbox 模块的 Apache PDFBox 文档解析器（ApachePdfBoxDocumentParser），它可以解析 PDF 文件。
• 来自 langchain4j-document-parser-apache-poi 模块的 Apache POI 文档解析器（ApachePoiDocumentParser），它能够解析微软办公软件的文件格式（例如 DOC、DOCX、PPT、PPTX、XLS、XLSX 等）。
• 来自 langchain4j-document-parser-apache-tika 模块的 Apache Tika 文档解析器（ApacheTikaDocumentParser），它可以自动检测并解析几乎所有现有的文件格式。

假设如果我们想解析 PDF 文档，那么原有的 TextDocumentParser 就无法工作了，我们需要引入 langchain4j-document-parser-apache-pdfbox。

5.2、添加依赖

<!-- 解析 pdf 文档 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-document-parser-apache-pdfbox</artifactId>
    <version>1.0.0-beta3</version>
</dependency>

5.3、解析 pdf 文档

/**
 * 解析 PDF
 */
@Test
public void testParsePDF() {
    Document document = FileSystemDocumentLoader.loadDocument("E:/knowledge/医院信息.pdf", new ApachePdfBoxDocumentParser());
    System.out.println(document);
}

6、文档分割器 Document Splitter

6.1、常见文档分割器

LangChain4j 有一个'文档分割器'（DocumentSplitter）接口，并且提供了几种开箱即用的实现方式：

• 按段落文档分割器（DocumentByParagraphSplitter）
• 按行文档分割器（DocumentByLineSplitter）
• 按句子文档分割器（DocumentBySentenceSplitter）
• 按单词文档分割器（DocumentByWordSplitter）
• 按字符文档分割器（DocumentByCharacterSplitter）
• 按正则表达式文档分割器（DocumentByRegexSplitter）
• 递归分割：DocumentSplitters.recursive (...)

默认情况下每个文本片段最多不能超过 300 个 token。

6.2、测试向量转换和向量存储

Embedding (Vector) Stores 常见的意思是'嵌入（向量）存储'。在机器学习和自然语言处理领域，Embedding 指的是将数据（如文本、图像等）转换为低维稠密向量表示的过程，这些向量能够保留数据的关键特征。而 Stores 表示存储，即用于存储这些嵌入向量的系统或工具。它们可以高效地存储和检索向量数据，支持向量相似性搜索，在文本检索、推荐系统、图像识别等任务中发挥着重要作用。

Langchain4j 支持的向量存储： https://docs.langchain4j.dev/integrations/embedding-stores/

添加依赖：

<!-- 简单的 rag 实现 -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-easy-rag</artifactId>
</dependency>

测试：

/**
 * 加载文档并存入向量数据库
 */
@Test
public void testReadDocumentAndStore() {
    // 使用 FileSystemDocumentLoader 读取指定目录下的知识库文档
    // 并使用默认的文档解析器对文档进行解析 (TextDocumentParser)
    Document document = FileSystemDocumentLoader.loadDocument("E:/knowledge/人工智能.md");
    // 为了简单起见，我们暂时使用基于内存的向量存储
    InMemoryEmbeddingStore<TextSegment> embeddingStore = new InMemoryEmbeddingStore<>();
    // ingest
    // 1、分割文档：默认使用递归分割器，将文档分割为多个文本片段，每个片段包含不超过 300 个 token，并且有 30 个 token 的重叠部分保证连贯性
    // DocumentByParagraphSplitter(DocumentByLineSplitter(DocumentBySentenceSplitter(DocumentByWordSplitter)))
    // 2、文本向量化：使用一个 LangChain4j 内置的轻量化向量模型对每个文本片段进行向量化
    // 3、将原始文本和向量存储到向量数据库中 (InMemoryEmbeddingStore)
    EmbeddingStoreIngestor.ingest(document, embeddingStore);
    // 查看向量数据库内容
    System.out.println(embeddingStore);
}

6.3、测试文档分割

/**
 * 文档分割
 */
@Test
public void testDocumentSplitter() {
    // 使用 FileSystemDocumentLoader 读取指定目录下的知识库文档
    // 并使用默认的文档解析器对文档进行解析 (TextDocumentParser)
    Document document = FileSystemDocumentLoader.loadDocument("E:/knowledge/人工智能.md");
    // 为了简单起见，我们暂时使用基于内存的向量存储
    InMemoryEmbeddingStore<TextSegment> embeddingStore = new InMemoryEmbeddingStore<>();
    // 自定义文档分割器
    // 按段落分割文档：每个片段包含不超过 300 个 token，并且有 30 个 token 的重叠部分保证连贯性
    // 注意：当段落长度总和小于设定的最大长度时，就不会有重叠的必要。
    DocumentByParagraphSplitter documentSplitter = new DocumentByParagraphSplitter(300, 30, // token 分词器：按 token 计算
            new HuggingFaceTokenizer());
    // 按字符计算
    // DocumentByParagraphSplitter documentSplitter = new DocumentByParagraphSplitter(300, 30);
    EmbeddingStoreIngestor.builder().embeddingStore(embeddingStore).documentSplitter(documentSplitter).build().ingest(document);
}

6.4、token 和 token 计算

LangChain4j：

@Test
public void testTokenCount() {
    String text = "这是一个示例文本，用于测试 token 长度的计算。";
    UserMessage userMessage = UserMessage.userMessage(text);
    // 计算 token 长度
    // QwenTokenizer tokenizer = new QwenTokenizer(System.getenv("DASH_SCOPE_API_KEY"), "qwen-max");
    HuggingFaceTokenizer tokenizer = new HuggingFaceTokenizer();
    int count = tokenizer.estimateTokenCountInMessage(userMessage);
    System.out.println("token 长度：" + count);
}

6.5、工作方式

1. 实例化一个'文档分割器'（DocumentSplitter），指定所需的'文本片段'（TextSegment）大小，并且可以选择指定 characters 或 token 的重叠部分。
2. '文档分割器'（DocumentSplitter）将给定的文档（Document）分割成更小的单元，这些单元的性质因分割器而异。例如，'按段落分割文档器'（DocumentByParagraphSplitter）将文档分割成段落（由两个或更多连续的换行符定义），而'按句子分割文档器'（DocumentBySentenceSplitter）使用 OpenNLP 库的句子检测器将文档分割成句子，依此类推。
3. 然后，'文档分割器'（DocumentSplitter）将这些较小的单元（段落、句子、单词等）组合成'文本片段'（TextSegment），尝试在单个'文本片段'（TextSegment）中包含尽可能多的单元，同时不超过第一步中设置的限制。如果某些单元仍然太大，无法放入一个'文本片段'（TextSegment）中，它会调用一个子分割器。这是另一个'文档分割器'（DocumentSplitter），能够将不适合的单元分割成更细粒度的单元。会向每个文本片段添加一个唯一的元数据条目'index'。第一个'文本片段'（TextSegment）将包含 index=0，第二个是 index=1，依此类推。

期望的文本片段最大大小

1. 模型上下文窗口：如果你使用的大语言模型（LLM）有特定的上下文窗口限制，这个值不能超过模型能够处理的最大 token 数。例如，某些模型可能最大只能处理 2048 个 token，那么设置的文本片段大小就需要远小于这个值，为后续的处理（如添加指令、其他输入等）留出空间。通常，在这种情况下，你可以设置为 1000 - 1500 左右，具体根据实际情况调整。
2. 数据特点：如果你的文档内容较为复杂，每个段落包含的信息较多，那么可以适当提高这个值，比如设置为 500 - 800 个 token，以便在一个文本片段中包含相对完整的信息块。相反，如果文档段落较短且信息相对独立，设置为 200 - 400 个 token 可能就足够了。
3. 检索需求：如果希望在检索时能够更精确地匹配到相关信息，较小的文本片段可能更合适，这样可以提高信息的粒度。例如设置为 200 - 300 个 token。但如果更注重获取完整的上下文信息，较大的文本片段（如 500 - 600 个 token）可能更有助于理解相关内容。

重叠部分大小

1. 上下文连贯性：重叠部分的主要作用是提供上下文连贯性，避免因分割导致信息缺失。如果文档内容之间的逻辑联系紧密，建议设置较大的重叠部分，如 50 - 100 个 token，以确保相邻文本片段之间的过渡自然，模型在处理时能够更好地理解上下文。
2. 数据冗余：然而，设置过大的重叠部分会增加数据的冗余度，可能导致处理时间增加和资源浪费。因此，需要在上下文连贯性和数据冗余之间进行平衡。一般来说，20 - 50 个 token 的重叠是比较常见的取值范围。
3. 模型处理能力：如果使用的模型对输入的敏感性较高，较小的重叠部分（如 20 - 30 个 token）可能就足够了，因为过多的重叠可能会引入不必要的干扰信息。但如果模型对上下文依赖较大，适当增加重叠部分（如 40 - 60 个 token）可能会提高模型的性能。

例如，在处理一般性的文本资料，且使用的模型上下文窗口较大（如 4096 个 token）时，设置文本片段最大大小为 600 - 800 个 token，重叠部分为 30 - 50 个 token 可能是一个不错的选择。但最终的设置还需要通过实验和实际效果评估来确定，以找到最适合具体应用场景的参数值。

五、项目实战 - 在硅谷小智中实现 RAG

1、创建@Bean 对象

在 xiaozhiAgentConfig 中添加 ContentRetriever

@Bean
ContentRetriever contentRetrieverXiaozhi() {
    // 使用 FileSystemDocumentLoader 读取指定目录下的知识库文档
    // 并使用默认的文档解析器对文档进行解析
    Document document1 = FileSystemDocumentLoader.loadDocument("E:/knowledge/医院信息.md");
    Document document2 = FileSystemDocumentLoader.loadDocument("E:/knowledge/科室信息.md");
    Document document3 = FileSystemDocumentLoader.loadDocument("E:/knowledge/神经内科.md");
    List<Document> documents = Arrays.asList(document1, document2, document3);
    // 使用内存向量存储
    InMemoryEmbeddingStore<TextSegment> embeddingStore = new InMemoryEmbeddingStore<>();
    // 使用默认的文档分割器
    EmbeddingStoreIngestor.ingest(documents, embeddingStore);
    // 从嵌入存储（EmbeddingStore）里检索和查询内容相关的信息
    return EmbeddingStoreContentRetriever.from(embeddingStore);
}

2、添加配置

在 XiaozhiAgent 中添加 contentRetriever 配置

@AiService(
    wiringMode = EXPLICIT,
    chatModel = "qwenChatModel",
    chatMemoryProvider = "chatMemoryProviderXiaozhi",
    tools = "appointmentTools",
    contentRetriever = "contentRetrieverXiaozhi" // 配置向量存储
)

3、修改工具的 value 提示

@Tool(name = "预约挂号", value = "根据参数，先执行工具方法 queryDepartment 查询是否可预约，并直接给用户回答是否可预约，并让用户确认所有预约信息，用户确认后再进行预约。如果用户没有提供具体的医生姓名，请从向量存储中找到一位医生。")

4、测试 RAG

在 Controller 中测试

step1: {"memoryId": 1, "message": "我头疼应该如何处理？"}
step2: {"memoryId": 1, "message": "张三丰，130821200909093777, 明天上午神经内科，要最好的医生"}
step3: {"memoryId": 1, "message": "如何到医院的神经内科"}

六、向量模型和向量存储

1、向量大模型

1.1、介绍

通用文本向量模型： 使用通用文本向量 text-embedding-v3，维度 1024，维度越多，对事务的描述越精准，信息检索的精度越高。

1.2、模型配置

使用 text-embedding-v3 依然需要添加 langchain4j-community-dashscope 依赖，我们之前已经添加过了。 配置向量模型

# 集成阿里通义千问 - 通用文本向量-v3
langchain4j.community.dashscope.embedding-model.api-key=${DASH_SCOPE_API_KEY}
langchain4j.community.dashscope.embedding-model.model-name=text-embedding-v3

1.3、文本向量化

package com.donglin.java.ai.langchain4j;

import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.output.Response;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
public class EmbeddingTest {
    @Autowired
    private EmbeddingModel embeddingModel;

    @Test
    public void testEmbeddingModel() {
        Response<Embedding> embed = embeddingModel.embed("你好");
        System.out.println("向量维度：" + embed.content().vector().length);
        System.out.println("向量输出：" + embed.toString());
    }
}

2、向量存储

2.1、Pinecone 简介

之前我们使用的是 InMemoryEmbeddingStore 作为向量存储，但是不建议在生产中使用基于内存的向量存储。因此这里我们使用 Pinecone 作为向量数据库。 官方网站：The vector database to build knowledgeable AI | Pinecone 访问官方网站、注册、登录、获取 apiKey 且配置在环境变量中。默认有 2GB 的免费存储空间。

2.2、Pinecone 的使用

得分的含义 在向量检索场景中，当我们把查询文本转换为向量后，会在嵌入存储（EmbeddingStore）里查找与之最相似的向量（这些向量对应着文档片段等内容）。为了衡量查询向量和存储向量之间的相似程度，会使用某种相似度计算方法（例如余弦相似度等）来得出一个数值，这个数值就是得分。得分越高，表明查询向量和存储向量越相似，对应的文档片段与查询文本的相关性也就越高。

得分的作用

• 筛选结果：通过设置 minScore 阈值，能够过滤掉那些与查询文本相关性较低的结果。在代码里，minScore(0.8) 意味着只有得分大于等于 0.8 的结果才会被返回，低于这个阈值的结果会被舍弃。这样可以确保返回的结果是与查询文本高度相关的，提升检索结果的质量。
• 控制召回率和准确率：调整 minScore 的值可以在召回率和准确率之间进行权衡。如果把阈值设置得较低，那么更多的结果会被返回，召回率会提高，但可能会包含一些相关性不太强的结果，导致准确率下降；反之，如果把阈值设置得较高，返回的结果数量会减少，准确率会提高，但可能会遗漏一些相关的结果，使得召回率降低。在实际应用中，需要根据具体的业务需求来合理设置 minScore 的值。

示例说明 假设我们有一个关于水果的文档集合，嵌入存储中存储了这些文档片段的向量。当我们使用'苹果的营养价值'作为查询文本时，向量检索会计算查询向量与存储向量的相似度得分。如果 minScore 设置为 0.8，那么只有那些与'苹果的营养价值'相关性非常高的文档片段才会被返回，而一些只简单提及苹果但没有详细讨论其营养价值的文档片段可能由于得分低于 0.8 而不会被返回。

2.3、集成 Pinecone

参考文档：Pinecone | LangChain4j 添加依赖：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-pinecone</artifactId>
</dependency>

2.4、配置向量存储对象

package com.donglin.java.ai.langchain4j.config;

import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.pinecone.PineconeEmbeddingStore;
import dev.langchain4j.store.embedding.pinecone.PineconeServerlessIndexConfig;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class EmbeddingStoreConfig {
    @Autowired
    private EmbeddingModel embeddingModel;

    @Bean
    public EmbeddingStore<TextSegment> embeddingStore() {
        // 创建向量存储
        EmbeddingStore<TextSegment> embeddingStore = PineconeEmbeddingStore.builder()
                .apiKey(System.getenv("PINECONE_API_KEY"))
                .index("xiaozhi-index") // 如果指定的索引不存在，将创建一个新的索引
                .nameSpace("xiaozhi-namespace") // 如果指定的名称空间不存在，将创建一个新的名称空间
                .createIndex(PineconeServerlessIndexConfig.builder()
                        .cloud("AWS") // 指定索引部署在 AWS 云服务上
                        .region("us-east-1") // 指定索引所在的 AWS 区域为 us-east-1
                        .dimension(embeddingModel.dimension()) // 指定索引的向量维度，该维度与 embeddedModel 生成的向量维度相同
                        .build())
                .build();
        return embeddingStore;
    }
}

2.5、测试向量存储

在 EmbeddingTest 测试类中添加

@Autowired
private EmbeddingStore embeddingStore;

/**
 * 将文本转换成向量，然后存储到 pinecone 中
 *
 * 参考：
 * https://docs.langchain4j.dev/tutorials/embedding-stores
 */
@Test
public void testPineconeEmbeded() {
    // 将文本转换成向量
    TextSegment segment1 = TextSegment.from("我喜欢羽毛球");
    Embedding embedding1 = embeddingModel.embed(segment1).content();
    // 存入向量数据库
    embeddingStore.add(embedding1, segment1);
    TextSegment segment2 = TextSegment.from("今天天气很好");
    Embedding embedding2 = embeddingModel.embed(segment2).content();
    embeddingStore.add(embedding2, segment2);
}

3、相似度匹配

接收请求获取问题，将问题转换为向量，在 Pinecone 向量数据库中进行相似度搜索，找到最相似的文本片段，并将其文本内容返回给客户端。

/**
 * Pinecone-相似度匹配
 */
@Test
public void embeddingSearch() {
    // 提问，并将问题转成向量数据
    Embedding queryEmbedding = embeddingModel.embed("你最喜欢的运动是什么？").content();
    // 创建搜索请求对象
    EmbeddingSearchRequest searchRequest = EmbeddingSearchRequest.builder()
            .queryEmbedding(queryEmbedding)
            .maxResults(1) // 匹配最相似的一条记录
            //.minScore(0.8)
            .build();
    // 根据搜索请求 searchRequest 在向量存储中进行相似度搜索
    EmbeddingSearchResult<TextSegment> searchResult = embeddingStore.search(searchRequest);
    // searchResult.matches()：获取搜索结果中的匹配项列表。
    // .get(0)：从匹配项列表中获取第一个匹配项
    EmbeddingMatch<TextSegment> embeddingMatch = searchResult.matches().get(0);
    // 获取匹配项的相似度得分
    System.out.println(embeddingMatch.score()); // 0.8144288515898701
    // 返回文本结果
    System.out.println(embeddingMatch.embedded().text());
}

七、项目实战 - 在硅谷小智中整合向量数据库

1、上传知识库到 Pinecone

在 EmbeddingTest 类中添加

@Test
public void testUploadKnowledgeLibrary() {
    // 使用 FileSystemDocumentLoader 读取指定目录下的知识库文档
    // 并使用默认的文档解析器对文档进行解析
    Document document1 = FileSystemDocumentLoader.loadDocument("E:/knowledge/医院信息.md");
    Document document2 = FileSystemDocumentLoader.loadDocument("E:/knowledge/科室信息.md");
    Document document3 = FileSystemDocumentLoader.loadDocument("E:/knowledge/神经内科.md");
    List<Document> documents = Arrays.asList(document1, document2, document3);
    // 文本向量化并存入向量数据库：将每个片段进行向量化，得到一个嵌入向量
    EmbeddingStoreIngestor.builder()
            .embeddingStore(embeddingStore)
            .embeddingModel(embeddingModel)
            .build()
            .ingest(documents);
}

2、修改 XiaozhiAgentConfig

添加基于 Pinecone 的向量数据库配置

@Autowired
private EmbeddingStore embeddingStore;
@Autowired
private EmbeddingModel embeddingModel;

@Bean
ContentRetriever contentRetrieverXiaozhiPincone() {
    // 创建一个 EmbeddingStoreContentRetriever 对象，用于从嵌入存储中检索内容
    return EmbeddingStoreContentRetriever.builder()
            // 设置用于生成嵌入向量的嵌入模型
            .embeddingModel(embeddingModel)
            // 指定要使用的嵌入存储
            .embeddingStore(embeddingStore)
            // 设置最大检索结果数量，这里表示最多返回 1 条匹配结果
            .maxResults(1)
            // 设置最小得分阈值，只有得分大于等于 0.8 的结果才会被返回
            .minScore(0.8)
            // 构建最终的 EmbeddingStoreContentRetriever 实例
            .build();
}

3、修改 XiaozhiAgent

修改 contentRetriever 的配置为 contentRetrieverXiaozhiPincone

@AiService(
    wiringMode = EXPLICIT,
    chatModel = "qwenChatModel",
    chatMemoryProvider = "chatMemoryProviderXiaozhi",
    tools = "appointmentTools",
    contentRetriever = "contentRetrieverXiaozhiPincone"
)

八、项目实战 - 改造流式输出

大模型的流式输出是指大模型在生成文本或其他类型的数据时，不是等到整个生成过程完成后再一次性返回所有内容，而是生成一部分就立即发送一部分给用户或下游系统，以逐步、逐块的方式返回结果。这样，用户就不需要等待整个文本生成完成再看到结果。通过这种方式可以改善用户体验，因为用户不需要等待太长时间，几乎可以立即开始阅读响应。

1、添加依赖

<!-- 流式输出 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-reactor</artifactId>
</dependency>

2、配置流式输出模型

在 application.properties 中配置流式输出大模型

# 集成阿里通义千问 - 流式输出
langchain4j.community.dashscope.streaming-chat-model.api-key=${DASH_SCOPE_API_KEY}
langchain4j.community.dashscope.streaming-chat-model.model-name=qwen-plus

3、编码

修改 XiaozhiAgent 中 chatModel 改为 streamingChatModel = 'qwenStreamingChatModel'

chat 方法的返回值为 Flux<String>

@AiService(
    wiringMode = EXPLICIT,
    streamingChatModel = "qwenStreamingChatModel",
    chatMemoryProvider = "chatMemoryProviderXiaozhi",
    tools = "appointmentTools",
    contentRetriever = "contentRetrieverXiaozhiPincone"
)
public interface XiaozhiAgent {
    @SystemMessage(fromResource = "zhaozhi-prompt-template.txt")
    Flux<String> chat(@MemoryId Long memoryId, @UserMessage String userMessage);
}

修改 XiaozhiController 中 chat 方法的返回值为 Flux<String>，并添加 produces 属性

@Operation(summary = "对话")
@PostMapping(value = "/chat", produces = "text/stream;charset=utf-8")
public Flux<String> chat(@RequestBody ChatForm chatForm) {
    return xiaozhiAgent.chat(chatForm.getMemoryId(), chatForm.getMessage());
}

3、测试

九、项目实战 - 运行前端工程

1、安装 Node.js

Node.js 是一个基于 JavaScript 引擎的服务器端环境，前端项目在开发环境下要基于 Node.js 来运行。 安装：node-v18.17.1-x64.msi

2、配置 npm 镜像

打开命令行，配置依赖的下载使用阿里镜像

npm config set registry https://registry.npmmirror.com

3、运行前端项目

进入项目目录，执行下面的命令启动项目：

cd xiaozhi-ui
npm i
npm run dev

改成自己的端口号

4、输出内容支持 markdown 语法

1. 通过 npm 安装 marked 包：

npm install marked

2. 引入 marked：

import { marked } from 'marked'

3. 将输出内容转为 HTML：

// Markdown 转 HTML 函数
const markdownToHtml = (content) => {
    if (!content) return '';
    // 配置 marked 选项
    marked.setOptions({
        breaks: true, // 启用换行符转换为 <br>
        gfm: true, // 启用 GitHub 风格的 Markdown
        sanitize: false // 允许 HTML 标签
    });
    try {
        return marked.parse(content);
    } catch (error) {
        console.error('Markdown 解析错误:', error);
        return content;
    }
}

4. 修改模板中的 v-html 渲染内容：

在模板中的消息显示部分，使用 v-html 来渲染经过 Markdown 转换的 HTML 内容：

<span v-if="message.isUser" v-html="message.content"></span>
<span v-else v-html="markdownToHtml(message.content)"></span>

5. 效果展示