一、项目简介

该系统以 Lucene 为核心检索引擎，整合智谱 AI 语义检索与 RAG 总结能力，采用 Lucene + SpringBoot + Swing 技术栈适配多格式文档，基于 C/S 架构实现文档的高效检索、在线预览与便捷下载。

核心概念解释

1、开源的、高性能的全文检索引擎库 Lucene ：

核心工作流程

Lucene 的核心流程分为 索引构建 和 检索查询 两部分。

核心特点

1. 全文检索能力不同于数据库的精确匹配，Lucene 支持模糊匹配、关键词权重、短语检索、范围检索等复杂文本查询，能快速从海量文本中找出相关内容。
2. 基于倒排索引。
3. 轻量级与可扩展它不是一个完整的搜索引擎应用，而是一个工具库，开发者可以通过 API 自定义扩展功能。
4. 支持多语言配合不同的分词器（如 IK Analyzer、HanLP 等中文分词器），可以适配中文、英文等多语言文本的检索需求。

2、开源文档内容提取工具库 Apache Tika ：

核心工作流程

1. 文件检测：Tika 先识别输入文件的格式（比如判断是 PDF 还是 Word）。
2. 解析文件：根据文件格式调用对应的解析器，读取文件内容。
3. 内容提取：将文件中的二进制数据转为纯文本，同时提取元数据。
4. 输出结果：返回纯文本内容和结构化的元数据，供后续处理（比如送入 Lucene 建立索引）。

核心特点

1. 多格式支持几乎能解析市面上所有常见的文件类型，包括：
   • 文本类：TXT、Markdown、XML、JSON
   • 办公类：Word、Excel、PPT、PDF
   • 多媒体类：图片（提取元数据如分辨率、拍摄时间）、音频 / 视频（提取编码、时长等信息）
   • 压缩包类：ZIP、RAR（支持解压并解析内部文件）
2. 统一的 API 接口不管是哪种格式的文件，Tika 都提供一套标准化的 API，开发者无需针对不同文件编写不同的解析逻辑，调用简单。
3. 轻量级且可扩展基于 Java 开发，依赖少，同时支持自定义解析器，可适配特殊格式的文件。
4. 元数据提取除了文件正文，还能提取文件的元数据信息，比如文档作者、创建时间、文件大小、标题等

3、RAG 搜索（检索增强生成）：

你可以把RAG 搜索理解为给大语言模型加一个 “外挂知识库”，用于解决大模型存在知识滞后、易出幻觉、答案难追溯等问题。它的解决思路主要是分成两步：1）先检索：用户提问后，先从外部知识库（比如文档、数据库）里找出和问题最相关的资料；2）再生成：把这些资料和问题一起交给大模型，让它基于这些真实资料来回答，而不是只靠自己的 “记忆” 瞎编。

4、JSON：
一种通用的文本数据格式可以类比于 Java 里的Map/对象。

核心作用：专门用来在不同系统 / 不同语言之间传递数据。
JSON 序列化 → Java 对象转成 JSON 字符串
把 Java 中的实体类对象 / Map 集合，变成 JSON 格式的字符串 的过程，就叫序列化。
JSON 反序列化 → JSON 字符串转成 Java 对象
把 JSON 格式的字符串，变成 Java 中的实体类对象 / Map 集合 的过程，就叫反序列化。

5、Java原生HttpURLConnection 和 OkHttp3：

都是 Java 语言中用来发送HTTP 网络请求的工具。

系统架构图

主要功能流程图

二、系统功能简介

功能	概述
1.服务端初始化功能	服务端启动时自动创建 docs 文档目录与 lucene_index 索引目录，递归扫描支持格式的文档，通过 Lucene 构建全文索引并同步生成 AI 向量缓存，确保检索数据与文档目录实时一致。
2.多格式文档解析功能	基于 Apache Tika 组件，适配 TXT、CSV、Log、MD、PDF、Word、Excel、PPT 等主流格式，精准提取文本内容用于索引与向量构建，解决多格式文档兼容性问题。
3.双模式检索功能	支持纯 Lucene 关键词精准检索与智谱 AI 语义检索：关键词检索通过多字段匹配返回精准结果，AI 语义检索结合文本转向量与相似度匹配，支持模糊语义查询，可勾选生成 RAG 智能总结。
4. 文件下载功能	客户端选中文件后可自定义保存路径或使用默认路径，下载前检测同名文件并弹出覆盖提示，采用 BufferedOutputStream 优化写入效率，适配 Windows 操作逻辑。
5. 服务器状态监测功能	客户端通过定时心跳检测服务端健康状态，以红绿灯UI组件直观展示（绿色在线 / 红色离线），支持服务器地址配置与持久化存储。
6.操作日志记录功能	服务端自动记录客户端 IP、操作类型（检索 / 下载 / 系统操作 / 异常）、操作详情，日志按日期拆分存储，采用 UTF-8 编码。

功能结构图：

本系统采用 C/S（客户端 / 服务端）架构，分为客户端和服务端两个核心部分，各部分功能模块相互协作完成全文检索与文件管理流程。系统功能结构如图所示：

三、技术栈

1. 核心框架与工具

类别	技术选型
后端框架	SpringBoot 3.2.0（Web 核心）
检索引擎	Apache Lucene 8.11.2（关键词检索、索引管理）
文档解析	Apache Tika 2.9.1（多格式文档内容提取）
AI 能力	智谱 AI（glm-4 模型：文本总结；embedding-2 模型：文本转向量）
数据传输与解析	FastJSON 2.0.32（JSON 序列化 / 反序列化）
网络通信	Java 原生 HttpURLConnection、OkHttp3（AI 接口调用）
工具类	Commons-IO（IO 操作）、Commons-Math3（向量相似度计算）
前端交互（客户端）	Swing（桌面可视化界面）
构建工具	Maven（依赖管理、打包）
JDK 版本	JDK 21

2. 辅助技术

• 日志记录：自定义 LogUtils（核心是用 SLF4J + Logback 组合实现的）；
• 缓存：VectorCacheService（内存向量缓存）；
• 数据校验：文件格式校验（DocumentParseUtil）、服务器地址格式校验；
• 编码：UTF-8（全局统一编码，避免中文乱码）。

3. 采用的大模型

model 参数取值	模型名称	使用场景
embedding-2	智谱嵌入模型 2 代	文本转向量
glm-4	智谱大模型 4 代	生成 AI 总结、RAG 回答、关键词优化

四、系统实现细节

1、包的结构

2、类的功能

1）SearchServerApplication：服务端入口，启动SpringBoot并触发索引初始化。

2）DesktopSearchEngine：客户端入口，Swing界面渲染、用户交互（搜索/下载/配置）、服务器状态监测。

3）ZhipuConfig：存储智谱AI的密钥、接口地址、模型名称等静态配置。

4）FileConstant：定义文档存储路径、Lucene索引字段、支持的文件后缀（TXT/Office/PDF）。

5）SearchController：暴露检索接口，接收客户端请求，分发到 LuceneSearchService处理。

6）FileController：暴露文件下载接口，根据文件名从文档目录读取文件并返回给客户端。

7）HealthController：服务器健康检查接口，供客户端心跳监测。

8）SearchResultDTO：封装检索结果的结构化数据（文件名+内容摘要）。

9）VectorEntity：存储文档的向量数据（含文件名、路径、内容、向量数组）

10）FileManageService：服务启动时初始化文档目录、索引目录，调用LuceneSearchService构建索引。

11）LuceneSearchService：核心业务服务：索引构建、纯Lucene 检索、AI 混合检索、关键词优化、RAG生成。

12）VectorCacheService：内存向量缓存管理：批量添加向量、清空缓存、余弦相似度计算与相似向量搜索。

13）AiUtils：调用智谱AI接口：关键词优化、RAG总结生成、文本转向量。

14）DocumentParseUtil：解析文档内容（基于Tika）、校验文件是否为支持格式。

15）HttpUtil：客户端HTTP工具：调用服务端检索 / 下载接口、关键词高亮处理。

16）LogUtils记录系统日志（操作类型、IP、详情）、获取客户端真实IP。

17）LuceneUtil：Lucene工具：索引创建、关键词检索、内容摘要生成。

18）ResultVo：统一接口返回格式（code：200 成功 / 500 失败；msg：提示信息；data：业务数据）。

3、类之间的关系（UML图）

4、客户端与服务器的设计

服务器

服务器就是经典的控制台界面，docs作为数据库，可随时上传或删除文件资源：

特别的是，服务器配有日志功能，可以很好地对客户端的行为进行监控，同时还可以跟踪客户端IP，也是一种网络安全的体现（日志功能按日期进行划分，以补充的形式进行迭代）：

服务器端的核心作用--索引初始化与管理：

索引初始化是服务端启动后的核心任务，需完成文档目录创建、索引目录创建、文档扫描、索引构建及 AI 向量缓存生成等一系列操作。通过 SpringBoot 的 CommandLineRunner 接口，确保项目启动后统一触发初始化逻辑；使用 Lucene 的 IndexWriter 以 CREATE 模式创建全新索引，避免历史索引残留导致的重复检索问题；递归扫描 docs 目录下所有文件，通过 DocumentParseUtil 校验文件格式，仅对支持的多格式文档进行文本解析与索引构建，代码展示如下：

服务端启动流程：

启动SearchServerApplication → 触发FileManageService初始化 → 创建文档 / 索引目录 → 调用LuceneSearchService扫描文档 → 基于LuceneUtil构建索引 + 基于AiUtils生成向量 → 向量存入VectorCacheService。

客户端

客户端采用 Java Swing 构建桌面应用。主界面采用BorderLayout分层布局：北部为搜索交互面板，中部为左右分栏面板，南部为AI总结展示区。核心难点在于：组件交互的逻辑绑定：搜索框回车触发检索、文件列表选中联动内容预览、AI 检索勾选后启用总结功能。

核心组件：

JFrame：项目主窗口，所有组件的根容器；
JTextField：关键词输入框，接收用户输入；
JButton：搜索 / 生成总结按钮，触发业务逻辑；
JCheckBox：AI 检索 / 生成总结开关，控制功能逻辑；
JTextArea + JScrollPane：检索结果展示区，展示文本内容；

辅助组件：

JOptionPane：弹窗提示；
JPanel：面板组件，用来分组存放按钮、复选框，让界面更整洁；
Font/Color：设置字体、颜色，美化界面；

客户端的核心功能主要是两个 -- 检索和下载

1、检索

先说检索，检索的话是该系统最为突出的特色了，因为实现了AI语义检索与RAG总结的接入：

AI 接入是本项目的核心增强亮点，通过整合智谱AI大模型的文本转向量、关键词优化与RAG总结能力，实现模糊语义匹配 + 检索结果智能提炼，大幅提升检索灵活性与实用性。核心需求包括：关键词语义优化、文本向量生成与相似度匹配、检索结果RAG总结，同时确保AI接口调用稳定、向量计算高效。

关键的实现逻辑：

配置层：通过 ZhipuConfig 存储 AI 接口密钥、地址与模型参数，统一管理配置；

工具层：AiUtils 封装AI接口调用逻辑，实现文本转向量、关键词优化、RAG 总结三大核心能力；

服务层：LuceneSearchService 整合纯 Lucene 检索与 AI 语义检索，VectorCacheService 管理内存向量缓存，提升匹配效率；

交互层：客户端支持AI 语义检索、RAG 总结勾选触发，服务端根据参数动态路由处理逻辑。

配置层（ZhipuConfig.java）

图4.7 工具层（AiUtils.java）

图4.8 服务层（VectorCacheService.java）

图4.9 交互层（LuceneSearchService.java）

客户端检索流程：

用户输入关键词 → 选择检索模式（纯 Lucene/AI） → DesktopSearchEngine通过HttpUtil调用SearchController → 服务端SearchController分发到LuceneSearchService → 检索结果封装为SearchResultDTO → 通过ResultVo返回客户端 → 客户端高亮显示结果并支持预览 / 下载。

2、下载

下载功能的实现主要是参考了浏览器的下载功能，主要是实现目标路径选择与默认路径记忆以及同名文件冲突处理。通过 JFileChooser 实现目录选择，使用 File 类检测文件是否存在，通过 JOptionPane 弹出覆盖确认对话框，确保用户操作体验一致。同时采用 BufferedOutputStream 提升文件写入效率，避免下载过程中文件占用导致的异常。

代码太长，我这里给出调用逻辑：

客户端按钮点击→触发DesktopSearchEngine的下载逻辑（状态校验、路径选择、同名检测）→调用HttpUtil.downloadFile发送HTTP请求→服务端FileController接收请求并返回文件流→客户端HttpUtil将流写入本地文件→提示下载结果。

实现服务器与客户端交互的核心 -- HttpUtil 工具类

HttpUtil 是客户端与服务端交互的核心媒介，统一封装 HTTP GET 请求逻辑，聚焦关键词搜索与文件下载两大核心场景，通过统一编码处理、超时控制、异常捕获，确保数据传输稳定可靠，是客户端与服务端数据交互的唯一通道。

五、课程设计总结及展望

总结

1、产生的问题：

问题 1：进行关键词检索的时候PDF不能被高亮显示

产生原因：高亮逻辑是精准字符匹配：客户端拿到解析后的文本，用 String.indexOf(keyword) 找关键词的位置，找到后对这个位置的字符标色。PDF文件的本质不是文本文件，是图文排版文件。Tika解析时，会把这些文本块拼接成一个字符串，拼接的过程中就会插入大量的空格、换行符、制表符，导致关键词被隔断，所以高亮不到位。

解决方法：增强文本清洗规则，彻底清洗PDF解析后的所有垃圾字符，核心是利用正则表达式。

问题 2：一开始打包的服务器.jar搜不到文件

产生的原因：我以为的逻辑是.jar在桌面、docs在桌面所以new File("docs") 就该找到桌面的docs文件夹；但其实在Windows系统下双击.jar后，程序找的docs文件夹是C:\Users\用户名\docs，而不是桌面的C:\Users\用户名\Desktop\docs，程序找不到docs文件夹，所以搜不到文件、下载提示不存在。

解决方法：可以设置 jar 包所在目录为当前目录：写一个 .bat 批处理脚本，强制把 Java 的工作目录，切换到 .jar 包所在的目录：

@echo off

cd /d %~dp0

java -jar lucene-search-serve.jar

pause

问题 3：接入AI存在巨大挑战

产生的原因：一开始我使用的是DeepSeek的API，但由于DeepSeek的服务器部署在境外，导致国内环境下调用存在网络访问限制，需要额外配置代理或本地部署，难度大。

解决方法：改用国内部署服务器的智谱AI API，无需额外配置网络环境，接入流程更简洁方便。

额外：就算后面改用成智谱AI，但我依然觉得对AI的接入、使用存在一定障碍，此次AI的接入花了我四个多小时，从一开始问大模型解决方法到一步一步调试发现不可行再去网上查询资料，其实是很耗费时间的一个事情，走了许多弯路。其实这也提供给我了许多思考：在自身理论基础不成熟的时候，对AI的利用其实是很难的，换句话说，你本身的能力的不足，会导致你看不懂AI提供的解决方法。我一开始想要接入deepseek，只是有这个想法，但是其实我对AI接入项目这个事情是一窍不通的，所以我给大模型的提示词就是“我的项目是一个以Lucene为基础的多格式文档全文搜索引擎，我想接入DeepSeek以实现语义搜索和RAG 搜索”，那大模型也是第一时间就告诉我了需要创建API、调用接口、在Maven项目中配置依赖。可是尝试了半天都不行，在网上找了许多教程，才终于明白一切工作都准备好了为什么没有接入成功，倘若我一开始就对这些大模型服务器部署、大模型接入有一定了解程度的话就不会像一只无头苍蝇一样没有任何想法只能一味依赖AI。所以这次项目做下来最大的感触确实是加强自身实力，当然不是说利用AI不好，AI是项目完成的重要辅助，通过这次AI相伴的项目完成，让我对学习到的理论知识有一个系统的学习理解，知识点不再是单一的、散乱的了，而是让我看到了项目创作的多样性。

2、亮点：

功能 1：文件下载同名覆盖提示

亮点与特色：完全模拟 Windows 系统文件操作逻辑，检测到同名文件时弹出警告对话框，让用户选择是否覆盖，提升用户操作体验；支持默认保存路径设置与记忆，减少用户重复操作。

功能 2：关键词高亮预览

亮点与特色：使用正则表达式不区分大小写匹配关键词，通过 HTML 标签设置黄色背景高亮，直观展示关键词在文档中的位置；自动截取关键词前后上下文生成摘要，避免全文展示导致的信息冗余。

功能 3：AI大模型的调用

流程：Java代码 → HTTP请求工具（HttpURLConnection/OkHttp3）→ 发送POST请求到智谱AI接口 → AI服务器处理 → 返回JSON结果 → HTTP工具接收结果 → 代码解析JSON

展望

1、多关键词的检索：该项目能支持多个关键词组合检索，提升检索灵活性。

2、优先级排序：实现的前提是以多关键词检索为基础，比如匹配到的关键词越多，那优先级越高，越靠上，便利用户查询，提高检索效率。

3、客户端有历史检索记录：在客户端添加历史检索记录存储功能，支持记录查询关键词、检索时间，用户可快速重新检索，提升操作便捷性，这也更符合现代检索器的一些基本功能。

4、权限的开放：可以添加用户登录模块，支持不同用户角色，比如管理员、普通用户，管理员可管理文档的上传与删除，普通用户仅可检索与下载。

六、课程设计感想

本次课程设计让我深刻体会到 C/S 架构的协作模式，客户端与服务端的通信需要考虑编码、超时、异常处理等多个细节，任何一个环节疏忽都会导致功能异常。还有就是Java用来做项目的便捷性。Java是面向对象编程的，将不同的实现放在不同的类很容易去管理，因为这个项目有迭代很多版，但其实每次不论要增加或去掉某一功能，只要增加或删除某一类就好了，这个感触是平常做题感受不到的。还有就是本次项目有切切实实地巩固了我的专业知识，基本上把本学期所学的所有知识点都利用上了，也是一种知识点的串联。后续我希望进一步学习Elasticsearch分布式搜索技术，将单节点系统升级为分布式架构，提升大规模文档检索的性能与扩展性；同时学习Vue.js开发Web客户端，提升界面的交互性和美观度。