Java实现Word与PDF全文检索：Elasticsearch 7.x文档解析、IK分词与高亮查询实战

1. 从一份合同翻找说起：为什么Word和PDF的全文检索值得单独做

前阵子帮一个做企业文档管理的朋友处理一个需求，他们内部有几千份Word合同和PDF技术方案，平时找一份文件只能靠文件名，可文件名往往起得极其随意，比如“最终版”“修改版2”“扫描件001”。真正想找“里面提到违约金比例的那份合同”，只能一份份点开用眼睛扫，效率低到让人崩溃。这个场景其实非常普遍——只要一个团队积累的文档超过几百份，文件名检索就彻底失效了，必须深入到文件内部的文字内容去搜。

这就是全文内容检索要解决的问题：把Word、PDF这类二进制文档里的文字“抽”出来，存进一个专门做搜索的引擎里，之后用户输入任意关键词，系统就能定位到具体是哪份文件、甚至哪一页、哪一段命中了。Elasticsearch 7.x 就是干这件事的成熟选择，它自带分词、倒排索引、高亮、打分排序，省去了自己写检索算法的巨大工作量。而Java作为企业后端的主力语言，用Java去对接Elasticsearch做文档检索，是很多中后台系统的标准技术栈。

这篇文章适合谁看？如果你手上有Java基础、大致听说过Elasticsearch但没真正落地过文档检索，或者你已经能往ES里塞结构化数据、但一碰到Word和PDF就卡在“怎么把内容弄进去”这一步，那这篇内容就是为你准备的。我会把整个链路拆开讲：文档怎么解析、内容怎么清洗、索引怎么设计、查询怎么写、高亮怎么返回，以及我在实际项目里踩过的那些坑。全程围绕Elasticsearch 7.x的Java API展开，不绕弯子。

需要先说明一点：全文检索的效果，七成取决于“内容抽取”这一步干得干不干净，剩下三成才是ES的查询调优。很多人一上来就研究ES的查询语法，结果发现搜出来的东西驴唇不对马嘴，根子其实在解析环节。所以下面的内容，我会把解析部分讲得比查询部分更细。

2. 文档解析这一关：Word和PDF的内容抽取到底难在哪

2.1 为什么不能直接把文件丢给Elasticsearch

刚接触这个需求的人常有一个直觉：Elasticsearch不是能存文档吗，那我把Word文件直接传进去不就行了？这个想法会撞墙。Elasticsearch存储和索引的基本单位是JSON文档，它的字段类型是文本、数值、日期这些，它根本不认识.docx和.pdf的二进制格式。你如果硬把二进制字节塞进一个字段，ES只会把它当成一堆乱码字符，分词器面对乱码什么也切不出来，检索自然无从谈起。

所以正确的链路是：先用解析库把Word/PDF里的纯文本抽出来，变成普通字符串，再把这个字符串作为字段值写进ES。ES负责的是“对已经变成文本的内容做索引和检索”，而“把二进制变成文本”这件事，必须由Java侧的解析库来完成。理解了这个分工，后面的技术选型就顺理成章了。

2.2 Word解析：Apache POI的两套API别用混

Java里解析Word最主流的库是Apache POI。这里有个新手极易踩的坑：POI针对Word有两套完全不同的API，对应两种文件格式。

• HWPFDocument：处理老的.doc格式（Word 97-2003），基于OLE2复合文档结构。
• XWPFDocument：处理新的.docx格式（Word 2007+），基于OOXML的ZIP包结构。

这两个类不通用。你拿XWPFDocument去打开一个.doc文件，会直接抛异常；反过来也一样。实际项目里两种格式都可能存在，所以稳妥的做法是先判断文件扩展名或魔数，再决定用哪个解析器。我一般会封装一个统一的入口方法，内部做分发，对外只暴露“给我一个文件，还我一段文本”。

用XWPFDocument抽取段落文本的核心逻辑很直接：遍历getParagraphs()拿到每个段落，调getText()。但这里有个细节——表格里的文字不在段落列表里。很多合同、报价单的关键信息恰恰在表格中，如果你只抽段落，表格内容会全部丢失。正确做法是同时遍历getTables()，对每个表格再遍历行和单元格，把单元格里的段落文本也拼进来。这个坑我在第一个项目里就踩了，导致用户搜合同金额怎么都搜不到，排查半天才发现金额在表格里。

2.3 PDF解析：为什么我最终选了PDFBox而不是别的

PDF的解析比Word更麻烦，因为PDF本质上是一种“排版描述语言”，它记录的是“在坐标(x,y)画这几个字”，而不是“这里有一段话”。所以从PDF里还原出有意义的文本流，本身就是个有损的过程。

Java里常见的PDF文本抽取库有PDFBox和iText。iText功能强但许可证对商业使用有约束，需要仔细评估；PDFBox是Apache基金会的开源项目，许可证宽松，抽取纯文本够用，所以企业项目里我用PDFBox居多。核心类是PDDocument和PDFTextStripper：

try (PDDocument document = PDDocument.load(new File(filePath))) { PDFTextStripper stripper = new PDFTextStripper(); stripper.setSortByPosition(true); // 关键：按坐标排序 String text = stripper.getText(document); }

setSortByPosition(true)这行非常关键。PDF里的文字对象在文件中的存储顺序，和它在页面上视觉呈现的顺序经常不一致。如果不按坐标排序，抽出来的文本可能是错乱的，一句话被拆得七零八落，检索时自然匹配不上。开启这个选项后，PDFBox会按文字在页面上的实际位置（从上到下、从左到右）重新排列，抽出来的文本可读性会好很多。

2.4 扫描件PDF：一个必须提前和需求方说清楚的边界

有一类PDF是扫描件——本质上是图片，里面根本没有文字对象，只有一张张扫描图像。这种文件用PDFBox抽出来是空字符串，因为确实没有文字可抽。要处理它必须上OCR（光学字符识别），比如Tesseract配合图像预处理。但OCR是另一个技术栈，识别率受扫描质量影响很大，而且速度慢。

我的经验是：在项目启动阶段就要和需求方确认文档库里有没有扫描件、占比多少。如果有且占比不小，要么单独做OCR流程，要么明确告知这部分文件不支持全文检索。最怕的是闷头做完，上线后用户拿一份扫描件搜不到，回头质疑系统有bug。提前把边界讲清楚，比事后解释省事得多。

3. 把文本变成可检索的索引：字段映射与中文分词的取舍

3.1 索引Mapping设计：哪些字段该建、该用什么类型

内容抽出来之后，下一步是设计索引的Mapping。一个实用的文档检索索引，我通常会放这几类字段：

这里有个高频考点：fileName为什么要同时建text和keyword？因为这两种查询需求都存在。用户可能想“模糊搜文件名里带‘合同’的”，这需要text分词；也可能想“精确找名叫‘2024年度采购合同.docx’的那份”，这需要keyword精确匹配。ES的fields多字段特性正好满足，一个字段值同时以两种方式索引，查询时按需选用。

content字段是重点，它承载全文检索。这里要注意一个默认值陷阱：ES的text字段默认对单个字段的索引内容有长度限制，虽然一般文档不会超，但如果你把整本书的内容塞进一个字段，可能触发max相关的问题。对于超长文档，可以考虑按段落或按页拆成多个子文档，或者用nested结构，不过这会增加复杂度，普通企业文档场景一般不需要。

3.2 中文分词：默认分词器为什么不能用

这是中文全文检索里最容易被忽视、后果又最严重的一环。Elasticsearch默认的standard分词器是按字符切分的，对英文没问题，对中文就是灾难——它会把“采购合同管理”切成“采”“购”“合”“同”“管”“理”一个个单字。这样索引之后，你搜“合同”能匹配到，但搜“采购合同”这种词组时，因为索引里根本没有“采购合同”这个词条，匹配效果会大打折扣，而且单字索引会让索引体积暴涨、查询变慢。

正确做法是安装中文分词插件。业界最常用的是IK分词器（elasticsearch-analysis-ik），它提供两种模式：

• ik_smart：粗粒度，切出的词少而整，适合大多数检索场景。
• ik_max_word：细粒度，会把一个词的所有可能组合都切出来，召回率高但索引更大。

我的实践是：建索引时用ik_max_word（尽量多切，保证召回），查询时用ik_smart（按用户意图切，保证精度）。这种“索引细、查询粗”的搭配是IK的经典用法，能兼顾召回和准确。Mapping里这样写：

"content": { "type": "text", "analyzer": "ik_max_word", "search_analyzer": "ik_smart" }

注意：IK分词器是第三方插件，需要单独下载对应ES版本的安装包，解压到ES的plugins目录后重启节点。版本号必须和ES主版本严格对应，7.x的插件装到7.x的ES上，否则节点起不来。

3.3 自定义词典：让专业术语不被切碎

IK自带的主词典是通用词库，遇到行业术语经常切错。比如“履约保证金”可能被切成“履约”“保证金”，如果用户习惯整体搜“履约保证金”，就可能匹配不上。解决办法是配置自定义词典：在IK的配置目录下建一个custom.dic文件，每行写一个词，然后在IKAnalyzer.cfg.xml里引用它，重启后生效。

自定义词典的维护是个持续活儿。我的建议是：上线初期先跑一批真实查询日志，看哪些词被切错了，再逐步往词典里加。不要一开始就想穷举所有术语，那样既累又容易漏。

4. Java客户端对接：从单条入库到批量索引的完整实现

4.1 客户端选型：RestHighLevelClient还是新版的Java API Client

Elasticsearch 7.x时代，Java侧官方主推的客户端是RestHighLevelClient，它基于HTTP REST协议，通过RestClient做底层通信。7.x后期官方推出了新的Elasticsearch Java API Client，但7.x版本上RestHighLevelClient依然是文档最全、社区案例最多的选择，所以本文以它为主。

引入依赖（Maven）：

<dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>7.17.0</version> </dependency>

版本号要和你的ES服务端版本保持一致，7.x内部小版本尽量对齐，避免协议不兼容。初始化客户端：

RestHighLevelClient client = new RestHighLevelClient( RestClient.builder(new HttpHost("es-host", 9200, "http")) );

生产环境建议配置多个节点地址，客户端会自动做负载均衡和故障转移。用完记得client.close()释放连接。

4.2 单条文档入库：IndexRequest的正确姿势

把一份解析好的文档写进ES，用IndexRequest：

IndexRequest request = new IndexRequest("doc_index"); request.id(docId); // 用文档唯一ID，避免重复入库 Map<String, Object> doc = new HashMap<>(); doc.put("fileName", fileName); doc.put("content", content); doc.put("fileType", fileType); doc.put("createTime", new Date()); request.source(doc, XContentType.JSON); IndexResponse response = client.index(request, RequestOptions.DEFAULT);

这里有个设计决策值得说：用文档自身的唯一标识（比如文件路径的哈希或数据库主键）作为ES文档id。这样做的好处是重复入库时ES会覆盖而不是新增，天然幂等。如果让ES自动生成id，同一份文件解析两次就会产生两条重复记录，检索结果里出现重复项，体验很差。

4.3 批量入库：BulkRequest才是生产环境的答案

单条入库适合调试，生产环境几千上万份文档，必须用BulkRequest批量提交。批量的大小有讲究：太小则网络往返次数多，太大则单次请求体过大容易超时。我的经验值是每批500到1000条，或者累计请求体控制在5到10MB左右，哪个先到就提交。

BulkRequest bulkRequest = new BulkRequest(); for (Document doc : docList) { IndexRequest req = new IndexRequest("doc_index").id(doc.getId()); req.source(buildMap(doc), XContentType.JSON); bulkRequest.add(req); if (bulkRequest.numberOfActions() >= 500) { client.bulk(bulkRequest, RequestOptions.DEFAULT); bulkRequest = new BulkRequest(); } } if (bulkRequest.numberOfActions() > 0) { client.bulk(bulkRequest, RequestOptions.DEFAULT); }

批量提交后一定要检查响应里的失败项。BulkResponse.hasFailures()为true时，要遍历BulkItemResponse找出哪些文档失败了、失败原因是什么。我见过有人批量写完不看响应，结果部分文档因为字段类型不匹配被静默拒绝，检索时才发现少了一批文件。

4.4 解析与入库的解耦：别让一个坏文件拖垮整批

实际文档库里总有那么几份“问题文件”——损坏的PDF、加密的Word、格式异常的docx。如果解析逻辑和入库逻辑写在一个循环里，一份文件解析抛异常，整个批次就中断了。正确做法是把解析和入库解耦：解析阶段对每份文件单独try-catch，解析失败的记录到日志和一张“失败清单”表里，成功的才进入入库队列。这样一份坏文件不会影响其他几百份正常文件。

更进一步，解析本身是CPU密集型操作，入库是IO密集型操作，两者可以用不同的线程池并行。解析线程池负责把文件变成文本，入库线程池负责批量写ES，中间用阻塞队列衔接。这个架构在文档量大的时候能显著提升吞吐。

5. 查询与高亮：让用户一眼看到命中的那句话

5.1 多字段查询：文件名和正文一起搜

用户输入一个关键词，通常希望文件名和正文都参与匹配。用MultiMatchQuery可以一次搜多个字段：

MultiMatchQueryBuilder mmq = QueryBuilders.multiMatchQuery(keyword, "fileName", "content") .type(MultiMatchQueryBuilder.Type.BEST_FIELDS) .field("fileName", 2.0f); // 文件名权重更高

BEST_FIELDS策略会取各字段中得分最高的作为最终得分，适合字段之间内容差异大的场景。给fileName加2倍权重，是因为文件名命中往往比正文命中更相关——用户搜“采购合同”，文件名就叫这个的，大概率比正文里顺带提一句的更符合意图。

5.2 高亮：把命中的词用标签包起来

高亮是全文检索体验的关键。用户不想在一大段文字里自己找关键词，而是希望系统直接把命中的片段标出来。ES的高亮功能通过HighlightBuilder实现：

HighlightBuilder highlightBuilder = new HighlightBuilder(); highlightBuilder.field("content"); highlightBuilder.preTags("<em class='hl'>"); highlightBuilder.postTags("</em>"); highlightBuilder.fragmentSize(150); // 每个片段150字符 highlightBuilder.numberOfFragments(3); // 最多返回3个片段

fragmentSize控制返回的片段长度，太小则上下文不足，太大则前端展示不下。150字符左右是我常用的值，能覆盖一句话的上下文。numberOfFragments控制返回几个片段，一般3个足够，多了前端也展示不过来。

拿到高亮结果后，前端把<em>标签渲染成高亮样式即可。注意高亮片段里的HTML标签要做转义处理，防止文档内容里本身含有尖括号导致XSS问题。

5.3 分页与排序：别用from+size做深分页

普通分页用from和size没问题：

SearchSourceBuilder sourceBuilder = new SearchSourceBuilder(); sourceBuilder.from(pageNum * pageSize); sourceBuilder.size(pageSize);

但要注意，from + size的深分页（比如翻到第1000页）性能很差，因为ES需要在每个分片上取出from+size条再协调节点合并排序。如果确实有深分页需求，应该用search_after配合排序字段来做游标式翻页。普通企业文档检索，用户翻到几十页就顶天了，from+size够用，但心里要有这根弦。

排序方面，默认按相关性得分_score降序。如果用户想按时间排，可以加一个createTime的排序字段。注意一旦指定了自定义排序，_score就不再是默认排序依据，如果还想保留相关性排序，要把_score显式加进排序列表。

6. 那些文档里不写、但上线后一定会遇到的问题

6.1 大文件解析的内存溢出

一份几百页的PDF，用PDFBox一次性load进内存再抽取，很容易把JVM堆撑爆，尤其是并发解析多份大文件时。解决办法有两个方向：一是限制单次解析的文件大小，超过阈值（比如50MB）的走单独的低并发通道；二是用PDFBox的流式读取，边读边抽，不把整个文档对象常驻内存。Word的XWPFDocument同理，超大docx也要小心。

6.2 编码问题导致的乱码

有些老Word文档或PDF内部编码不规范，抽出来的中文是乱码。这种情况往往不是解析库的锅，而是文档本身的字符编码就有问题。处理办法是在抽取后做一次编码检测和修正，或者对明显乱码的内容打标记、跳过入库。指望100%还原所有文档的编码是不现实的，接受一定比例的失败率，把失败清单暴露给运维，比追求完美更实际。

6.3 索引膨胀与段合并

文档内容多、分词细，索引体积会涨得很快。ES底层是Lucene，每次写入会产生新的段（segment），段太多会影响查询性能。ES会自动做段合并，但在大批量导入期间，可以临时调大index.refresh_interval（比如从默认1秒改成30秒），减少刷新次数，提升导入速度。导入完成后再改回来。这个参数调整在批量导入场景下效果很明显。

6.4 增量更新：文件改了怎么办

文档库不是一成不变的，文件会被修改、新增、删除。全量重建索引代价太大，必须做增量。我的做法是：用文件的最后修改时间或内容哈希作为版本标识，定时扫描文档目录，只处理有变化的文件。内容哈希变了才重新解析入库，没变的跳过。删除的文件则根据路径去ES里删对应id的文档。这套机制配合定时任务，能做到准实时同步。

6.5 检索结果的相关性调优

上线后经常收到“搜出来的不是我想要的”这类反馈。相关性调优是个细活，常见手段包括：调整字段权重（boost）、用function_score结合时间衰减（新文档得分略高）、对完全匹配的短语用match_phrase提升精度。我的建议是先把基础检索跑通，收集一批真实的“搜不准”案例，再针对性调，不要一上来就堆一堆复杂的打分函数，那样反而难以维护。

7. 我在实际项目里沉淀下来的几条经验

做这类文档检索系统，技术选型其实不复杂，难的是把工程细节处理干净。我最大的体会是：解析环节的健壮性决定了整个系统的可用性。ES再强，喂进去的是垃圾文本，搜出来的也是垃圾。所以我在解析层投入的精力，往往比查询层还多——异常捕获、失败重试、失败清单、格式兼容，这些“脏活”才是项目能不能稳定跑起来的关键。

另一个体会是关于中文分词。很多人第一次做中文检索，搜出来的结果莫名其妙，排查半天才发现是分词器没配对。记住那个口诀：索引用细粒度、查询用粗粒度，专业术语进自定义词典。这三条做到，中文检索的准确率能上一个台阶。

最后说个容易被忽略的点：给检索结果加一个“为什么这条会命中”的反馈。比如高亮片段、命中字段提示。用户看到命中的上下文，才会信任这个系统。如果只返回一个文件名列表，用户点进去发现关键词在很不起眼的地方，会觉得系统“乱搜”。把命中依据透明化，体验会好很多。

这套方案我已经在几个内部文档系统里落地过，从几千份到几万份文档的规模都跑得动。核心链路就是：解析抽文本、清洗去噪、IK分词建索引、多字段查询加高亮。把这条链路走通，剩下的就是根据具体业务做调优了。如果你正准备做类似的东西，建议先用几十份真实文档跑通全流程，再考虑规模和性能的事，别一上来就设计过度复杂的架构。