企业官网建设流程全解析

简介：一份基于Java+Vue的向量数据库语义检索与相似文档查重系统的详细项目实例，面向具备Spring Boot、Vue基础，从事自然语言处理、知识管理或内容安全的软件工程师与架构师。内容覆盖文档上传、文本向量化、Milvus近似检索、查重分析与可视化完整流程，展开需求分析、系统架构、数据库建模、API规范、前后端实现与部署运维，含完整程序代码、数据库设计和GUI设计。压缩包仅1个docx文档，大小81KB，已有153人学习浏览。docx按项目背景、挑战与解决方案、模型架构、模块描述及代码示例等目录组织，重点讲解BERT语义向量生成、向量批量入库、相似度计算与查重核心逻辑，并涉及多格式解析、智能分段、自适应阈值、高亮比对报告等设计。适合学术论文查重、企业知识产权保护、网络内容监控、政务档案管理等场景，可作为智能检索与查重平台开发的实用参考。

1. 基于 java+vue 的向量检索查重系统，先别急着写代码

基于 java+vue 的向量数据库语义检索与相似文档查重系统，第一眼看上去像是把 Python 生态里才顺手的方案硬搬进 Java。实际做课设、毕业设计或企业内部文档去重工具，这个组合比纯 Python 更现实：Spring Boot 处理文档上传、权限和 MySQL 元数据，Vue 负责检索交互，真正跟向量相关的部分只需一个 embedding 生成脚本加一个向量库服务。这套系统解决"文档太多、关键词搜不准、查重靠肉眼"三个具体问题。适合需要交付完整系统的毕业生、想搭知识库或做合同审计工具的 Java 工程师；它不要求你掌握训练模型，核心是理解 embedding、向量比对和阈值设计。

2. 向量语义检索与查重原理：从关键词命中到向量距离，为什么能抓到近似文本

在动手写 Spring Boot 之前，先想清楚一个前提：关键词检索和语义检索的差距到底在哪里。ES 或 MySQL 的 LIKE 查询依赖倒排索引，能匹配"苹果发布新手机"和"苹果发布新手机"这种完全相同或同字面的文本，但遇到"iPhone 出新款了"就断了。倒排索引对同义词、语序调整和概括性改写几乎没有应对能力。向量数据库解决的正是这个问题：把文本编码成稠密向量，用几何距离衡量语义关系。

这套系统的名字里同时有"语义检索"和"相似文档查重"，两者共用一套向量库，但行为目标不同。检索是给定一句 query，返回与之最相关的文档片段；查重是给定一批文档，找出互相重复的内容。下面把这两个目标分开讲，顺便把向量库选型讲清楚。

2.1 语义检索为什么比关键词检索强：embedding 与余弦相似度的关系

先说 embedding 的本质。一段文本经过模型编码后，输出一个固定长度的浮点数数组，例如 bge-small-zh-v1.5 输出 512 维向量，m3e-base 输出 768 维。在这个高维空间里，语义接近的文本向量距离近，语义无关的向量距离远。衡量距离最常用的是余弦相似度，即 (A·B) / (|A| × |B|)。两个向量方向一致时值接近 1；如果嵌入模型在输出前做了归一化，余弦相似度等价于点积，Qdrant 返回的 score 可以直接当作相似度读取。

对 Java 工程师来说，这里有个容易误解的分工：向量计算并不在 Java 里做。常见做法是起一个独立的 Python 服务，用 sentence-transformers 加载中文模型，对外暴露一个 HTTP 接口，Java 把待编码文本传过去拿回浮点数组。Java 端真正负责的是把向量交给 Qdrant，并由 Qdrant 完成相似度搜索。这样拆开的好处是模型切换、版本升级都只在 Python 侧发生，Java 和向量库之间只需要对齐维度。

embedding 服务的超时时间要留足。CPU 环境下一条 200 字的中文文本编码大约需要 100 到 300 毫秒，批量编码时一次传 32 条是最稳妥的。编码完的向量建议统一归一化，这样后续 Qdrant 里无论配 Cosine 还是 Dot 距离，分数口径都是一致的。

为了说明语义距离的效果，举一个实际例子。在倒排索引里，"甲方逾期付款应当承担违约责任"和"买方拖欠货款需要赔偿"没有匹配；但两个句子的向量相似度可以到 0.85 以上，这对查重来说已经是高危信号。如果只靠关键词查重，这类改写过的重复条款几乎都会漏掉。

2.2 相似文档查重的本质：向量距离、阈值与去重分组

检索和查重的差异在工程上很明显：检索返回 topN，交给用户自己判断；查重要给出"是否重复"的判定结果，并且把疑似重复的文档聚合到一个组里。既然是判定，就必须有阈值。阈值定太高漏报，定太低误报，而系统一旦大量误报，用户会直接失去信任，所以查重模块的阈值设计比检索模块的 topN 设计敏感得多。

没有做过向量检索的团队，第一版常会用"把整篇文档编码成一个向量，然后两两算相似度"的做法。这个方案在小规模数据上能用，但有一个明显的缺陷：文档变长后，局部重复会被大量不重复内容稀释。比如一份 5000 字的合同，只有其中一段 800 字的条款和其他文档重复，整篇编码后相似度可能只有 0.7 不到，完全触发不了阈值。

正确做法是先把文档切成 chunk。我一般用固定窗口切割，文本长度按 160 到 240 字比较稳，窗口重叠 20 到 40 字。切片粒度有讲究：太小了碎片噪声大，太大了局部重复容易被稀释。切片后每个 chunk 单独编码入库，payload 里记录文档 ID 和序号。查重时让一个 chunk 的向量去向量库检索，如果命中的点属于另一篇文档且分数超过阈值，就记录一条候选重复对。所有候选对收集完之后，按文档 ID 做分组，自然就得到查重报告。

阈值没有通用答案。以 bge-small-zh 为例，在业务文档上从 0.82 起步比较稳；m3e 系列的分数普遍偏高，要用 0.85 或 0.86 起步；同名章节、模板填空这类高度模板化的文本，阈值甚至可以到 0.9。换一次 embedding 模型，阈值必须重新标定，这一点后面第 5 章会展开讲。

2.3 向量数据库选型：Qdrant、Milvus、Chroma 在 Java 生态里的取舍

向量检索可以不做成独立服务，直接在 Java 内存里维护一个 List<float[]> 也能完成 demo 级检索。但数据超过几万条之后，暴力遍历开始卡顿，而且文档还要支持按业务字段过滤，这时候就该引入真正的向量数据库。国内从业者常用的向量库主要是 Qdrant、Milvus、Chroma 三个，下面把对 Java 栈的适配情况放在一张表里。

选型结论很直接：课设、毕设和中小企业的知识库场景，优先 Qdrant；数据量到千万级、需要分布式扩容时再考虑 Milvus。Chroma 的好处是起步最快，但它的 Java 生态最弱，对 Spring Boot 项目不是首选。另一种常见做法是继续用 ES 的 dense_vector 字段，如果团队 ES 已经跑得很熟且数据量不大，也能落地；但在 HNSW 索引参数调节、payload 过滤、批量 upsert 的便利性上，它和专门向量库的体验差距明显。

还有一点需要提前意识到：向量数据库只负责存和查，文档的元数据、上传文件本身、查重分组结果仍然放在 MySQL。两边的关联方式就是 payload 里的 docId，这个设计在后面建表时会体现出来。先把概念理清，再进入具体实现。

3. Spring Boot + Vue 落地最小系统：Word 入库、向量检索与查重接口一条线跑通

在动手前先定技术栈版本，避免后面环境对不上：后端用 JDK 17 + Spring Boot 3.x，前端用 Vue 3 + Vite，数据库用 MySQL 8，向量库用 Qdrant。JDK 8 环境下 Spring Boot 2.7 也可以跑，但 Qdrant 官方 Java 客户端要求的最低版本是 Java 11，所以 JDK 17 是最省心的选择。前端不装额外重型组件库，用 Element Plus 就够。

3.1 环境准备与工程骨架：MySQL 建三张表、Qdrant 容器和 Maven 依赖

先启动 Qdrant。REST 端口 6333 用于调试和 Python 脚本接入，gRPC 端口 6334 供 Java 客户端使用，两个端口都要映射出来。

docker run -d --name qdrant \ -p 6333:6333 -p 6334:6334 \ -v qdrant_storage:/qdrant/storage \ qdrant/qdrant

-v把向量数据落到命名卷里，容器重启不丢数据。启动后用curl http://localhost:6333/collections确认返回空数组，说明服务正常。

MySQL 侧建三张核心表。doc 表存文件元数据，chunk 表存切片文本和向量库 pointId 的关联，duplicate_pair 表存查重命中的候选对。

CREATE TABLE doc ( id BIGINT PRIMARY KEY AUTO_INCREMENT, title VARCHAR(255) NOT NULL, file_path VARCHAR(500), chunk_count INT DEFAULT 0, create_time DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE chunk ( id BIGINT PRIMARY KEY AUTO_INCREMENT, doc_id BIGINT NOT NULL, seq INT NOT NULL, content TEXT NOT NULL, vector_id VARCHAR(64) NOT NULL, KEY idx_doc_id (doc_id) ); CREATE TABLE duplicate_pair ( id BIGINT PRIMARY KEY AUTO_INCREMENT, doc_a_id BIGINT NOT NULL, doc_b_id BIGINT NOT NULL, max_score DOUBLE NOT NULL, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, KEY idx_pair (doc_a_id, doc_b_id) );

doc_id 和 vector_id 是关键关联字段：vector_id 存 Qdrant 的 point id，写的是 docId-chunkSeq 这种业务可见字符串，排查问题时可以直接去 Qdrant 里定位。chunk 表把原文落了一份在 MySQL，检索结果回显时不用每次反向查 Qdrant payload，向量库意外丢失时也能作为重建依据。

后端 Maven 依赖主要有两块：POI 用来解析 Word 文档，Qdrant 客户端用来操作向量库。

<dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.5</version> </dependency> <dependency> <groupId>io.qdrant</groupId> <artifactId>client</artifactId> <version>1.12.0</version> </dependency>

POI 5.x 对应 JDK 8 以上，没问题。Qdrant 客户端版本换过几次命名空间，1.x 统一使用io.qdrant.client，网上搜到旧项目里com.qdrant.client的 import 是旧版社区包，直接升级依赖并把 import 改过来。

3.2 文档解析与文本切片：POI 读 Word，切片后交给 Python 服务做 embedding

前端上传的 Word 落到本地临时目录后，后端先用 POI 解析正文。注意 doc 和 docx 是两种格式：docx 用 XWPF 解析，老式 .doc 要用 HWPF，混用会直接解析失败或读出乱码。

List<String> extractParagraphs(File file, boolean isDocx) throws Exception { List<String> texts = new ArrayList<>(); if (isDocx) { try (XWPFDocument doc = new XWPFDocument(new FileInputStream(file))) { for (XWPFParagraph p : doc.getParagraphs()) { String t = p.getText().trim(); if (!t.isEmpty()) texts.add(t); } for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { String t = cell.getText().trim(); if (!t.isEmpty()) texts.add(t); } } } } } return texts; }

doc.getParagraphs()拿不到表格里的内容，所以要单独遍历表格。如果后续要兼容 PDF，可以用 pdfbox 转文本后走同样的切片流程，这样即便本地没有对应文档解析器也能兜底。

切片是查重精度的第一个隐藏参数。固定窗口容易实现，我习惯按 200 字切、重叠 20 字。

public static List<String> splitChunks(String text, int size, int overlap) { List<String> chunks = new ArrayList<>(); int start = 0; while (start < text.length()) { int end = Math.min(start + size, text.length()); chunks.add(text.substring(start, end)); if (end == text.length()) break; start = end - overlap; } return chunks; }

size设 200，overlap设 20。重叠的意义是防止重复内容恰好落在两个窗口的交界处被切开；20 字对中文来说能覆盖大部分句子边界。如果文档类型偏短文本，比如工单和公告，size 缩小到 64、重叠设为 8 到 16 会更好。

切好的文本需要转成向量。这里采用独立的 Python embedding 服务，避免在 JVM 里跑深度学习推理的复杂度。

from fastapi import FastAPI, Request from sentence_transformers import SentenceTransformer app = FastAPI() model = SentenceTransformer("BAAI/bge-small-zh-v1.5") @app.post("/embed") async def embed(req: Request): body = await req.json() texts = body["texts"] vectors = model.encode(texts, normalize_embeddings=True).tolist() return {"vectors": vectors}

Java 侧调用这个接口时，把一批 chunk 文本打包成 JSON POST 过去，一次最多传 32 条。normalize_embeddings=True让输出向量长度归一为 1，后续 Qdrant 用 Cosine 距离时，score 才是稳定的余弦相似度。遇到接口超时，先查 Python 进程的模型加载路径和内存占用，大多数慢请求都是冷启动或模型没进内存造成的。

3.3 写入与检索：Java 客户端操作 Qdrant 的 collection、upsert 和 search

接着实现对 Qdrant 的写读。第一步创建 collection，关键参数是维度和距离度量。

QdrantClient client = new QdrantClient( QdrantGrpcClient.newBuilder("localhost", 6334, false).build()); client.createCollectionAsync("doc_chunks_bge512", VectorParams.newBuilder() .setSize(512) .setDistance(Distance.Cosine) .build()).get();

collection 名我固定带模型标识bge512，这样从 bge-small-zh 换到 m3e-base 时，直接新开一个doc_chunks_m3e768，新旧数据不会互相污染。setSize(512)必须与 embedding 模型输出维度一致，bge-small-zh-v1.5 是 512 维，m3e-base 是 768 维，一旦建错只能删了重建。

写入点数据时，除了向量，还把 docId、chunkSeq、原文内容都塞进 payload。

List<PointStruct> points = new ArrayList<>(); for (int i = 0; i < vectors.size(); i++) { long pointId = docId * 100000 + i; // docId 为 MySQL 主键 points.add(PointStruct.newBuilder() .setId(PointId.newBuilder().setNum(pointId).build()) .setVectors(Vectors.newBuilder().setVector(vectors.get(i))) .putPayload("docId", new Value().setStringValue(String.valueOf(docId))) .putPayload("chunkSeq", new Value().setIntegerValue(i)) .putPayload("content", new Value().setStringValue(chunks.get(i))) .build()); } client.upsertAsync("doc_chunks_bge512", points, new UpsertPoints(true)).get();

UpsertPoints(true)表示等待写入完成再返回，保证后续检索能查到。pointId 用docId * 100000 + chunkSeq生成，前提是 docId 不超过 99999；数据量再大建议改成 UUID，并在 payload 里保留 docId 和 chunkSeq 字段。pointId 在排查问题时可以直接看出向量属于哪个文档第几段。

检索接口的代码量反而不大。

List<ScoredPoint> hits = client.searchAsync("doc_chunks_bge512", SearchPoints.newBuilder() .setVector(queryVector) .setLimit(10) .setWithPayload(true) .build()).get();

setLimit(10)控制返回候选数。检索接口返回 10 个点是合理的；查重场景要放宽到 20 到 30，因为候选少了会把轻度重复漏掉。setWithPayload(true)让结果把 content 一起带回来，前端直接展示命中片段，不需要再回 MySQL 查一遍。要注意getScore()的分数范围和模型、距离度量强相关，建议在检索接口里对分数做一次展示层归一化，否则用户看到 0.8 会误以为是 80 分。

3.4 相似文档查重：用检索接口反向扫描，按阈值生成重复分组

查重和检索共用同一个向量库，但代码目标不同。对一份文档的每个 chunk，拿它的向量去全库检索，命中别的文档且分数超过阈值就记一对候选。

double threshold = 0.82; Map<String, Set<String>> pairMap = new HashMap<>(); for (Chunk chunk : chunks) { List<ScoredPoint> hits = searchChunk(chunk.getVector(), 30); for (ScoredPoint hit : hits) { String hitDocId = hit.getPayload().get("docId").getStringValue(); if (hitDocId.equals(docId)) continue; if (hit.getScore() >= threshold) { pairMap.computeIfAbsent(docId, k -> new HashSet<>()).add(hitDocId); } } }

这段逻辑里最容易被忽略的是hitDocId.equals(docId)这一行。同一文档的相邻 chunk 在重叠窗口下会被自己命中，如果不跳过自身，查重结果会大量出现"自己和自己重复"的假阳性。候选对收集完成后，按文档 ID 做连通分组，一个组就是一份疑似重复的文档集合，输出时带上每组最大命中分数作为排序依据。

查重是离线任务，建议用 Spring 的@Async跑，不要在文件上传请求里同步做。任务进度写入一张 task 表，前端轮询状态。工程上最常见的问题是索引任务做一半挂了：doc 表有了记录，chunk 表空着，再跑一遍又重复入库。我的做法是让任务天然可重跑：先插入 doc 记录，解析切片后写入 MySQL，调 embedding 服务，再写 Qdrant，最后更新 doc.chunk_count。任一步失败，doc 都是中间状态，定时任务把 chunk_count 为 0 且创建时间超过 10 分钟的记录重新拉起来执行。

3.5 Vue 检索页与查重报告：axios 联动、结果表格和状态轮询

前端最小可用的页面只有两个：上传页和检索页。上传页负责把 Word 文件交给/api/upload，后端返回 taskId；检索页提供一个输入框和结果表格。

<template> <el-input v-model="query" placeholder="输入一句话检索文档内容" clearable @keyup.enter="search" /> <el-table :data="results" stripe> <el-table-column prop="docId" label="文档编号" width="100" /> <el-table-column prop="content" label="命中片段" show-overflow-tooltip /> <el-table-column prop="score" label="相似度" width="110" /> </el-table> </template> <script setup> import { ref } from 'vue' import axios from 'axios' const query = ref('') const results = ref([]) async function search() { if (!query.value.trim()) return const { data } = await axios.get('/api/search', { params: { q: query.value } }) results.value = data } </script>

Vue 3 的<script setup>下，异步响应式数据直接用ref就行，不需要this。axios 的params会把对象拼成 query string，后端用@RequestParam("q")接收。这里要处理好请求竞态：用户快速输入两次，第一次响应晚到会覆盖第二次的结果。简单做法是每次请求前记录一个自增序号，响应回来时只接受最新序号的数据。查重报告页面用同样的表格组件展示，加上一个"导出 CSV"按钮即可，后端生成 CSV 后用window.open触发下载。

4. 避坑与排查：这套系统最容易翻车的 5 个位置，从环境到阈值都有后悔药

一个看似简单的业务逻辑，做到生产环境经常被环境问题磨掉半天时间。下面这几条是从解析到阈值的踩坑记录，每条都是真实现象，附上原因和解决方式。这套系统的"后悔药"不多，但都很具体。

4.1 Word 解析乱码与表格内容缺失

现象：docx 文件用 Office 打开正常，导入系统后段落变成乱码，或者整个表格内容在库里完全没有记录。

原因：docx 和 doc 是两种完全不同的打包格式，POI 里 XWPF 处理 docx，HWPF 处理 doc。只写一个 XWPF 解析器，遇到 .doc 文件要么抛异常要么读出乱码；表格内容又不属于XWPFParagraph，需要单独走getTables()遍历。

解决：上传后根据文件扩展名判断解析器，doc 和 docx 拆成两个方法。清洗文本时把\r\n、多个连续空格和特殊空白字符统一替换成单个空格，避免切片后出现孤立换行符导致的空 chunk。还要检查 MySQL 连接 URL 是否带上characterEncoding=utf8，否则入库后中文变乱码，乱码再一路带进向量库，检索结果全是"看似匹配实则乱码"。

4.2 别在 JVM 里直接跑 embedding 模型

现象：用 DJL 加 ONNX 在 Java 侧加载 bge 模型，启动耗时 30 秒以上，CPU 推理一条文本也要几百毫秒，并发一高整个检索接口直接卡死。

原因：Java 的深度学习推理栈在中文文本 embedding 这一侧的生态远没有 Python 的 sentence-transformers 顺手。模型文件转换、词表加载、版本匹配，每一步都可能因为依赖版本对不上而翻车，调试成本极高。

解决：把 embedding 做成独立 FastAPI 服务，Java 只做 HTTP 调用。服务用 uvicorn 启动，CPU 核数够就开 2 到 4 个 worker，不够就单进程，避免模型重复加载撑爆内存。这样替换模型只在 Python 侧进行，Java 代码完全不用动。如果团队不允许引入 Python，次优方案是用 ONNX Runtime 的 Java API 跑一个转好的 bge-onnx 模型，但你要有心理准备去处理 tokenizer 和 token 长度对齐的问题。

4.3 collection 建完就报错：维度与距离度量必须一次写对

现象：createCollectionAsync传了 512 维，upsert 时报 dimension mismatch；或者搜索结果分数忽高忽低，像是随机的。

原因：Qdrant 的 collection 创建后 schema 不可变，维度写错只能删了重建。距离度量选了 Dot，但 embedding 没有归一化，分数完全不能作为相似度参考。

解决：建 collection 前，先用 Python 打印模型输出向量的长度和范数，确认维度后再写代码。度量统一用 Cosine，同时 Python 侧编码时设置normalize_embeddings=True。我给 collection 起的名字里带上维度标识，比如doc_chunks_bge512，换模型时不会把旧 collection 里的脏数据带到新流程。

4.4 查重结果全是相似或全不相似：阈值和 embedding 模型绑定

现象：同一批文档，用 m3e-base 跑出来的相似度普遍比 bge 高 0.03 到 0.05，阈值沿用网上经验值 0.85，结果全是疑似重复；换回 bge 又漏报。

原因：不同 embedding 模型的分数尺度完全不同，甚至同一模型的 checkpoint 更新也会改变分布。查重阈值没有通用的"良好实践值"，必须基于当前模型和当前数据分布重新标定。

解决：准备 20 对已知重复的文档和 20 对已知不重复的文档，跑一遍得到分数分布，在两组分布重叠区间的中点附近取阈值。初始值可以从 bge 的 0.82 开始，然后看误报率再微调。这个校准工作最好沉淀成一个带标注的小脚本，以后换模型或换语料都能复用。

4.5 上传超时、跨域报错与索引中间状态

现象：前端 axios 报跨域错；上传一个 20MB 的 Word 文件，请求在 Nginx 处 504 超时；任务跑到一半 Python 服务挂掉，MySQL 里的 doc 表和 Qdrant 里的向量数据对不上。

原因：Vite devServer 端口（5173）请求 Spring Boot（8080）跨域，需要在后端配 CORS 或前端配 Vite proxy。大文件同步处理本来就慢，加上转发层默认超时时间短，前端等不到结果。embedding 服务崩溃后，doc 元数据已入库，但向量库缺失，重复跑会生成重复数据。

解决：跨域配置只选一处生效，不要同时配 CORS 和中间件转发。上传接口只做落盘和返回 taskId，索引流程全部异步，前端用轮询查询状态。索引任务设计成幂等：docId 已存在就跳过入库，向量写入前先按 pointId 检查是否已存在。这些细节看着琐碎，但实际运行起来，它们决定了这个系统是用来演示还是能稳定跑下去。

5. 把系统从"能跑"推到"能用"：Embedding 模型选择、切片策略与 Vue 交互细节

系统能跑通之后，下一步是让检索结果可信、查重误报可控、页面用得顺手。这一章包含三个调优方向和一个前端细节，每一项都可以单独验证效果。

5.1 换一个 embedding 模型，召回效果立竿见影

模型选择对中文语义效果的影响最大，甚至超过后续调参。三个常用模型的对比：

模型不是越大越好。CPU 推理场景下，bge-small 的单条编码耗时大约是 m3e 的一半，而且它的 512 维在单机 Qdrant 里占用内存更小。选择失误会让召回表现差很多，换来换去也让人烦躁。如果固定使用 bge-small-zh-v1.5，建议在 Python 服务的依赖文件里锁死模型名称和版本。重新下载模型时，不同 checkpoint 的 embedding 分布有细微差别，可能导致先前校准的阈值失灵。维度一定对齐：m3e-base 换回 bge 时，collection 记得用新名字。

5.2 相似度阈值的校准方法：不靠感觉，靠小样本分布

前面已经多次提到阈值和模型强绑定，这里说具体怎么标定。从现有文档库里挑 20 对"明显重复"和 20 对"明显不重复"的内容，每一对都计算向量相似度，打印两组分数范围。若重复组最低分是 0.87，不重复组最高分是 0.79，那阈值取 0.83 到 0.85 之间都有余量。若两组有交集，优先靠近重复组的高分侧，减少误报，宁漏勿错——查重系统误报太多比漏报更难解释。

模板化文档要特别注意阈值差异。合同、官方文书这类文本模板高度统一，正常不重复的两段内容也可能有 0.9 以上的基础相似度，此时阈值要往上提到 0.93 之类。这个经验没法直接迁移，最现实的路径是每接入一个领域语料，就重复一遍小样本校准。

5.3 切片窗口与 payload：两个决定查重精度的隐藏参数

切片长度和重叠窗口直接决定局部重复是否会被稀释。业务文档用 200 字、重叠 20 字起步；如果文档平均每段短，可以把窗口收窄到 64 字。切片后，对入库的 payload 字段做一次最终确认：

查重执行时还有一个细节：重叠窗口造成的相邻 chunk 互相命中，除了跳过同 docId，还可以进一步用 chunkSeq 相邻判断过滤。比如 A 文档第 3 段命中 A 文档第 4 段，在查重场景里不是跨文档重复，直接过滤。这条过滤规则放在检索接口之外，避免影响正常语义检索的结果。

5.4 Vue 交互细节：检索竞态、任务轮询和路由懒加载

前端做深了会发现流程比后端更容易出问题。检索接口的响应时间不稳定，用户连续输入会触发上一次响应覆盖新结果，解决办法是维护一个请求序号，只接受最新响应。上传大文件时页面长时间没有反馈，我用状态轮询做任务进度：/api/upload返回 taskId，前端每隔 2 秒请求/api/task/{taskId}，状态从 PROCESSING 变 DONE 后自动跳转检索页。查重报告导出用 CSV，后端生成临时文件，前端window.open下载，不要在浏览器里拼表格。

另一个容易忽略的地方是路由设计。检索页和查重报告页用vue-router的懒加载导入，component: () => import('...')，这样首屏不会一次性加载 Element Plus 的完整组件树。从检索结果页跳转到该文档的查重报告时，把 docId 作为路由参数传给报告页，后端按 docId 查 duplicate_pair 表即可，前端不需要维护全局状态。

6. 查重复核的进阶技巧：向量召回 + 精排，别再做全库两两比对

系统上线前，你可能会想：全库两两查重能不能做？数据量在 1 万篇文档以内，把每个 chunk 都和其他 chunk 比较一次是 O(n²)，单机勉强能跑；数据量一到 5 万篇，全库比对的时间就不可接受了。更重要的是，两两比对的粒度太粗：两篇文档同一处改写，其他部分完全不相关，整体相似度会被拉低到阈值以下。我在做完一个合同库之后，换成了"向量召回 + 精排复核"两阶段方案。

第一阶段用 Qdrant 做召回。每个 chunk 的向量去检索 topN，放宽到 30 个候选，这时候记录的是可能相关的文档对。第二阶段对候选对做精排，精排指标不依赖 embedding，而是计算两段文本的重叠程度。常用公式是finalScore = 0.7 * vectorScore + 0.3 * overlapRatio，其中 overlapRatio 用两个文本的 4-gram 集合重叠比例。交集多说明这批候选确实是逐字或近乎逐字的重复，而不是语义擦边的相似。

double finalScore(double vectorScore, String textA, String textB) { double overlap = overlapRatio(textA, textB); return 0.7 * vectorScore + 0.3 * overlap; }

权重系数是可调的，不是数学公式。如果你想验证这个方案是否有效，找 10 组已知重复的文档跑一遍，把第二阶段是否能把每组都筛出来作为通过标准。我自己的教训是：第一次只靠单一阈值做查重，为了减少误报把阈值调高，结果漏掉了一份改写了措辞的合同；改成两阶段之后，召回阶段保持宽松，精排阶段收紧，每个阶段只调节一个变量，问题清晰了很多。这个"分段调参、分段验证"的思路，同样适用于检索与查重的其他参数。希望帮到你。

本文还有配套的精品资源，点击获取