Java接入向量数据库：实现文档检索与语义搜索实战

做Java后端这么多年，大部分时间都在跟MySQL、Redis、Elasticsearch打交道。直到上半年接了一个文档检索的需求，才发现传统的ES方案在某些场景下，比如语义搜索、相似问题匹配，真的是使不上劲。项目把标题定为“Java 接入向量数据库：实现文档检索与语义搜索”，正好把这段时间踩坑、选型、落地的过程沉淀下来，希望对同样在Java技术栈里折腾向量检索的同学有点帮助。

这个项目解决的问题很明确：在Java服务里，把非结构化的文档数据（Word、PDF、Markdown、数据库文本字段等）转换成向量，写入向量数据库，然后基于向量相似度实现语义级别的搜索。跟传统的关键词匹配不一样，语义搜索能理解“苹果售后电话”和“iPhone客服热线是多少”其实是同一个意思。整理下来，核心链路包括文档解析、文本切分、Embedding向量化、向量入库、相似度检索，最后是Java代码接入和性能调优。这篇博文适合两类人：一类是Java后端想给自己的系统加搜索或推荐能力，另一类是面试前想搞明白向量数据库实战细节的候选人。整个项目从需求分析到上线跑通，用了大概两周时间，代码量不大，但坑确实不少。

1. 项目背景与整体思路拆解

1.1 为什么传统方案搞不定这个需求

先说需求本身：系统里积累了几千篇产品文档和客服问答记录，用户搜“怎么退款”，希望把跟退款流程、退款时效相关的文档排在最前面。用ES或者MySQL的LIKE查询，只能做字面匹配，搜“怎么退款”可能查不到“申请退货后资金什么时候到账”这种文档——因为关键词完全不重叠，但是语义上是高度相关的。

当时我对比了几种方案：

方案	匹配方式	能理解语义吗	适合场景
MySQL LIKE /全文索引	字符匹配	否	精确查询、结构化过滤
Elasticsearch BM25	词频+逆文档频率	有限（同义词扩展）	关键词搜索、日志检索
向量数据库 + Embedding	向量距离	是	语义搜索、相似推荐、问答匹配

ES的BM25模型本质上是统计词频，它能处理“退款”这个词，但理解不了“钱没到账”和“退款慢”之间的关系。想要做到语义级别，必须把文本映射到高维向量空间，让语义相近的文本在空间里距离更近。这就得引入Embedding模型和向量数据库。

1.2 项目整体的技术选型与链路设计

整个系统从上到下拆成四层：

1. 文档接入层：负责读取各种格式的文档，解析成纯文本。我这边主要用了Apache Tika来处理PDF、Word、HTML，简单场景直接读文本文件也行。
2. 文本切分层：把长文档切成合适的块（Chunk）。这一步非常关键，直接决定检索效果。
3. 向量化层：调用Embedding模型把文本块变成向量。我用的是本地部署的BGE系列模型，也可以用云厂商的Embedding API。
4. 存储检索层：向量数据库负责存储向量和原始文本，提供相似度检索接口。Java服务通过官方SDK对接。

最终的检索链路是：用户输入query → query向量化 → 向量数据库ANN搜索 → 返回TopK文档块 → （可选）Rerank重排 → 拼接结果返回。

这个设计看起来不复杂，但每一步都有不少学问。我建议拿到需求先不要急着写代码，把文档格式摸清楚，统计一下文本量级，估算向量维度，再选数据库，否则后面返工的成本很高。

1.3 标题背后隐藏的三个核心技术点

标题里写了三个关键词：Java接入、文档检索、语义搜索。对应三个核心技术点：

• Java接入：需要选对SDK，搞懂连接池、超时、重试、异步写入这些客户端层面的问题。很多向量数据库是Python生态优先，Java客户端要么功能不全，要么文档稀烂，这是最大的坑。
• 文档检索：从“搜关键词”升级到“搜含义”，但也要处理中文分词、文档去重、长文档切分、切片后的上下文丢失等问题。
• 语义搜索：核心是Embedding模型的质量和索引算法的选择。模型选不好，向量算得再快结果也是错的。

这三个点环环相扣，缺一个环节，整体效果都会大打折扣。

2. 向量数据库选型与Java SDK评估

2.1 主流向量数据库横向对比

选型阶段我调研了四款常见的向量数据库：Milvus、Qdrant、Chroma、pgvector。每一款都有自己的定位，适合的场景差异很大。

Milvus是目前最成熟的分布式向量数据库，功能全，支持混合查询（向量+标量过滤）、Collection分区、数据持久化、水平扩容。缺点是部署重，依赖Etcd、MinIO、Pulsar这些组件，小项目用起来杀鸡用牛刀。Java SDK是官方的milvus-sdk-java，整体维护得还不错，接口覆盖了大部分功能。

Qdrant用Rust写的，单机性能很好，部署简单，一个二进制文件搞定。提供Java客户端（官方叫qdrant-java-client），支持grpc和rest两种协议，索引参数可调。如果你不想搞复杂的分布式，Qdrant是首选。

Chroma是轻量级方案，Python生态非常顺滑，适合做原型验证。Java客户端虽然存在，但功能覆盖不全，某些高级特性（如过滤、分段）用起来比较蹩脚，生产环境我暂时不会选它。

pgvector是PostgreSQL插件，可以让你在原有业务库里直接加向量字段，不需要额外维护一套存储。优点是运维简单、事务能力强、可以跟业务数据做SQL级联查；缺点是向量检索性能比专业向量库差一些，索引构建和查询速度在数据量大了之后会下滑。

我当时的选择是Milvus，主要原因：一是数据量在百万级，需要分布式扩展能力；二是项目要求支持过滤标签（比如按文档类型过滤），Milvus的标量过滤配合向量检索做得比较成熟；三是官方Java SDK比较稳定。如果你的数据量在几万条以内，pgvector或者Qdrant单机版完全够了，别盲目上重武器。

2.2 Java SDK的选型要点与踩坑记录

选定了Milvus之后，我看了一下Java SDK的版本情况。Milvus官方提供两个Java库：一个是旧的fabric8客户端（不推荐，已不活跃），另一个是新的milvus-sdk-java，在GitHub上持续维护，支持Milvus 2.x的全部核心接口。Maven坐标是：

<dependency> <groupId>io.milvus</groupId> <artifactId>milvus-sdk-java</artifactId> <version>2.4.0</version> </dependency>

需要重点提一下，新老SDK的API风格完全不一样。老的SDK用的是XxxParam格式，一个新的SDK更贴近RESTful风格，引入了一个MilvusServiceClient接口。如果你网上搜到老教程，那代码基本不能用。我建议直接看官方GitHub仓库的examples目录，不要看二手博客。

另一个容易踩的坑是Java版本。Milvus SDK基于Java 11编译，如果你项目还在Java 8，要么升级到11+，要么考虑用HTTP调REST API绕过SDK。我见过不少团队因为这个问题卡住，最后在自己的服务里包了一层OkHttp去调/api/search接口，也能用，但协议细节要自己处理，不省心。

此外，SDK默认的connectTimeout和keepAlive时间都偏短，高并发场景下容易出现连接复用失效、Connection reset。我后来把连接池配置调大，并且开启gRPC的keepalive ping，问题基本消失。下面是关键配置片段：

MilvusClient client = new MilvusServiceClient( ConnectParam.newBuilder() .withHost("localhost") .withPort(19530) .withKeepAliveTime(10, TimeUnit.SECONDS) .withKeepAliveTimeout(3, TimeUnit.SECONDS) .withKeepAliveWithoutCalls(true) .build() );

2.3 索引类型的选择：HNSW还是IVF_FLAT

向量检索的索引直接决定了查询速度和准确率。Milvus里常用的索引包括FLAT、IVF_FLAT、IVF_PQ、HNSW。我做了一个简单对比：

• FLAT：暴力全量计算，精确但慢，适合百万级以下且对速度不敏感的场景。
• IVF_FLAT：倒排分组，先聚类再搜索，速度快但召回略降。适合十亿级以上的大库，参数调起来麻烦。
• IVF_PQ：乘积量化压缩向量，内存占用低，但会损失精度，适合超大规模且内存捉襟见肘的场景。
• HNSW：基于图的近似最近邻算法，召回率高，查询延迟低，是中小规模（百万到千万级）的最佳折中。

我选HNSW，具体参数：M=16，efConstruction=200，efSearch=64。M越大图连接越密，召回率高但内存占用也高；efConstruction是建索引时探索的候选数，影响索引质量，太大建索引慢；efSearch是查询时的探索宽度，越大越慢但召回越好。下面是建索引和查询的Java代码：

JsonObject indexParams = new JsonObject(); indexParams.addProperty("M", "16"); indexParams.addProperty("efConstruction", "200"); indexParams.addProperty("metric_type", "COSINE"); indexParams.addProperty("index_type", "HNSW"); milvusClient.createIndex( CreateIndexParam.newBuilder() .withCollectionName("document_chunks") .withFieldName("embedding") .withIndexType(IndexType.HNSW) .withMetricType(MetricType.COSINE) .withExtraParam(indexParams.toString()) .build() );

实际测试下来，500万向量数据、2核4G的机器上单查询延迟稳定在10毫秒以内，效果还是很满意的。这里我特别强调一下，MetricType建议用COSINE余弦距离，对文本向量效果比对欧氏距离更好，因为余弦相似度跟向量的绝对长度无关，更适合Embedding向量的特性。

3. 文档处理与向量化核心链路

3.1 文档解析：从PDF/Word到干净文本

向量数据库存的不是原始文件，而是切分后的文本块。首先要做的就是把各种格式的文档解析成纯文本。这一步看着简单，实际很烦。

PDF解析我试了两个库：PDFBox和Apache Tika。PDFBox纯Java生态，简单PDF好用；但只要PDF里有表格、多栏排版或者扫描图片，解析出来就是一堆乱序文本。Tika内部把PDFBox和OCR（Tesseract）都包了，解析效果更好，但依赖较多，启动时稍微慢一点。我的建议是：能用Tika直接上Tika，省心。

Word文档相对好处理，Apache POI或者Tika都行。需要注意的是一些加密文档和带宏的文档，解析前要处理异常。我的代码里统一用一个DocumentParser入口：

@Component public class DocumentParser { private final Tika tika = new Tika(); public String parse(byte[] content, String filename) throws IOException { try { Metadata metadata = new Metadata(); metadata.set(TikaMetadataKeys.RESOURCE_NAME_KEY, filename); return tika.parseToString(new ByteArrayInputStream(content), metadata); } catch (TikaException e) { throw new IOException("Document parsing failed: " + filename, e); } } }

还要做一下清洗：去掉多余空行、HTML标签、无意义的目录页码、图片说明等。脏文本进Embedding模型，向量质量只会更差，别嫌预处理麻烦。

3.2 文本切分策略：固定长度 vs 语义切分

切分是检索效果的分水岭。块太长，语义过于宽泛，向量无法精确表达某个局部主题，检索召回一堆“差不多”的文档；块太短，上下文信息不完整，向量又缺乏足够的语义线索。经验值是：中文场景下，每个块300到500个字符比较合适，同时让相邻块有50到100字符的重叠，避免一句话被截断，语义断裂。

我有两个方案可以做切分：

方案一：固定长度切分。简单粗暴，按字数切分，加重叠。适合结构不严格的文本，很多开源项目（比如LangChain的RecursiveCharacterTextSplitter）就是基于这个思路。

方案二：语义切分。按段落、标题、列表边界切分，最大程度保留语义完整性。我参考了LangChain的分隔符优先级思路：先按标题切，再按段落切，最后按句子切。例如：

public List<String> splitText(String text) { List<String> chunks = new ArrayList<>(); // 先按章节标题切 String[] sections = text.split("(?m)^(#+\\s|第[一二三四五六七八九十]+章|\\d+\\.\\s)"); for (String section : sections) { // 再按段落切 String[] paragraphs = section.split("\\n\\s*\\n"); StringBuilder current = new StringBuilder(); for (String para : paragraphs) { if (current.length() + para.length() > 400 && current.length() > 200) { chunks.add(current.toString()); current.setLength(0); } current.append(para).append("\n"); } if (current.length() > 0) { chunks.add(current.toString()); } } return chunks; }

实际效果对比，方案二在知识问答场景下召回准确率明显更高，尤其是技术文档这种标题层级丰富的文本。当然如果你的文档是一整段散文式的，方案一也够用了。切分完还有一个细节：每块要保留文档ID、标题路径、页码这些元数据，后面检索结果要能定位回原文。

3.3 Embedding模型的选择与向量化性能优化

文本向量化的质量直接决定语义搜索的上限。模型层面，我对比了三条路：

1. 用云厂商的Embedding API：效果好，不用管部署，但是有网络开销和费用，数据要出内网。
2. 用本地开源的Embedding模型：推荐BGE系列（如bge-m3、bge-small-zh-v1.5），中文效果好，支持768或1024维，单机部署即可。
3. 用通用多模态模型：适合图文混合场景，但Java生态里调用麻烦。

我最终选了本地部署BGE模型，向量维度1024。为什么不用768？BGE官方对比实验里，1024维在中文任务上效果更好，而且Milvus处理1024维的向量完全没压力。

Java端调用Embedding模型，最简单的方式是把模型封装成一个HTTP服务（也可以用Python写一个FastAPI接口），Java用RestTemplate或WebClient调用。向量化是个纯计算密集的操作，建议批量处理，一次传一批文本，比逐条调用效率高好几倍。我用的是批量接口，每批32条，吞吐量大概是每秒40次请求，单条请求融合了多文本，整体性能很可观。

public List<List<Float>> embedBatch(List<String> texts) { Map<String, Object> requestBody = new HashMap<>(); requestBody.put("texts", texts); ResponseEntity<EmbeddingResponse> response = restTemplate.postForEntity( embeddingServiceUrl, requestBody, EmbeddingResponse.class); return response.getBody().getEmbeddings(); }

还有一点要注意：embedding接口返回的向量，在Java里通常是double[]或者float[]类型，但Milvus SDK要求List ，转换的时候别在循环里做太多拆箱装箱，否则GC压力很大。我是把原始模型输出换成float[]数组存到内存，插入时再转成List ，性能好一些。

4. Java接入向量数据库核心代码实现

4.1 建Collection、定义Schema与写入数据

先看建Collection这一步。Milvus是基于Collection组织的，类似关系数据库的表。设计Schema时要考虑好主键、向量字段和标量字段。我在项目里定义一个collection叫document_chunks，字段包括：

• id：主键，用自增Long
• doc_id：文档ID，标量字段，用于过滤
• chunk_text：原始文本内容，标量字段
• embedding：1024维向量字段

Java创建Collection的代码如下：

public void createCollection() { FieldType idField = FieldType.newBuilder() .setName("id") .setDataType(DataType.Int64) .setPrimaryKey(true) .setAutoID(true) .build(); FieldType docIdField = FieldType.newBuilder() .setName("doc_id") .setDataType(DataType.VarChar) .setMaxLength(128) .build(); FieldType textField = FieldType.newBuilder() .setName("chunk_text") .setDataType(DataType.VarChar) .setMaxLength(4096) .build(); FieldType embeddingField = FieldType.newBuilder() .setName("embedding") .setDataType(DataType.FloatVector) .setDimension(1024) .build(); CreateCollectionParam createParam = CreateCollectionParam.newBuilder() .withCollectionName("document_chunks") .withDescription("document semantic search chunks") .withFieldTypes(Arrays.asList(idField, docIdField, textField, embeddingField)) .build(); milvusClient.createCollection(createParam); }

插入数据时，按批次构建List<InsertParam.Field>，每批500条左右。一次性插入太多数据容易导致内存暴涨，太少则RPC开销占比过高。这里直接给一个批量插入的实现：

public void batchInsert(List<DocumentChunk> chunks) { List<InsertParam.Field> fields = new ArrayList<>(); List<Long> ids = new ArrayList<>(); List<String> docIds = new ArrayList<>(); List<String> texts = new ArrayList<>(); List<List<Float>> vectors = new ArrayList<>(); for (DocumentChunk chunk : chunks) { ids.add(chunk.getId()); docIds.add(chunk.getDocId()); texts.add(chunk.getText()); vectors.add(chunk.getEmbedding()); } fields.add(new InsertParam.Field("id", ids)); fields.add(new InsertParam.Field("doc_id", docIds)); fields.add(new InsertParam.Field("chunk_text", texts)); fields.add(new InsertParam.Field("embedding", vectors)); InsertParam insertParam = InsertParam.newBuilder() .withCollectionName("document_chunks") .withFields(fields) .build(); milvusClient.insert(insertParam); }

这里提醒一下，不同的SDK版本insert接口的字段名可能略有差异，以自己引入的版本javadoc为准。

4.2 查询向量化与ANN搜索实现

搜索的入口是把用户的query也转成向量，然后调Milvus的search接口。这一步的细节很多，尤其是query向量的归一化、TopK的选择和输出字段的过滤。

query向量生成复用之前的embedding服务，拿到List 后直接传入SearchParam。这里我踩过一个坑：BGE模型官方建议，query在做embedding时先加一个指令前缀（比如“为这个句子生成表示以用于检索相关文章：”），不加前缀的检索效果会差一截。这个细节在很多Java博客里没人提。

搜索参数设置如下：

public List<SearchResult> search(String query, String docIdFilter, int topK) { List<Float> queryVector = embeddingClient.embed(query); SearchParam searchParam = SearchParam.newBuilder() .withCollectionName("document_chunks") .withVectorFieldName("embedding") .withVectors(Collections.singletonList(queryVector)) .withTopK(topK) .withMetricType(MetricType.COSINE) .withParams("{\"ef\": 64}") .build(); if (docIdFilter != null && !docIdFilter.isEmpty()) { searchParam.withExpr("doc_id == \"" + docIdFilter + "\""); } SearchResult searchResult = milvusClient.search(searchParam); return parseSearchResults(searchResult); }

搜索完成之后，Milvus会返回每条记录的ID、distance分数以及你自己要求返回的字段。要拿chunk_text，必须在SearchParam里设置OutputFields，否则只能拿到ID，还得二次查库，非常浪费性能。例如：

searchParam.withOutputFields(Arrays.asList("doc_id", "chunk_text"));

4.3 从文档到语义搜索的最小可运行流程

把上述模块串联起来，一个最小可运行的服务流程大概是：

1. 接收文档上传请求，解析文本。
2. 切分文本为chunks，逐条做embedding。
3. 构造字段列表，批量写入Milvus。
4. 接收用户query，embedding后查Milvus。
5. 把命中的chunk_text返回给前端，附带相似度分数。

我项目里用Spring Boot把这几个步骤做成了两个接口：POST /api/doc/upload和GET /api/search。核心逻辑加起来两百行左右，关键代码不复杂，难的是让embedding模型和Milvus形成稳定的数据链路。如果只跑通demo，这套代码一天就能写完；要做到生产可用，要注意的地方太多了，后面单独开一节讲。

5. 文档检索效果优化与混合检索实战

5.1 为什么纯向量检索依然会翻车

向量检索不是银弹。我实测了三百条测试query，纯向量召回在文档检索场景的F1大约在80%左右，剩下的20%问题主要出在：

1. 专有名词召回差：比如“FTP”“熔断器”“CPU飙升”这种词汇，语义上可能跟“连接不上”、“网关异常”相近，但向量模型有时候抓不到精确指代关系。
2. 结果排序不稳定：query包含多个条件时，向量模型容易把某个强关联片段排太前，忽略了整体匹配度。
3. 历史版本矛盾和相似文档堆叠：一个cluster里全是讲同一主题的文档，TopK容易被一篇长文档的多个chunk屠榜。

解决方案是在向量检索之外，叠加一层关键词检索或者BM25召回，做混合检索（Hybrid Search）。向量负责语义召回，BM25负责精确词匹配，两边结果融合，能显著提升准确率。

5.2 用RRF算法融合向量和关键词结果

主流混合检索的融合算法有RRF（Reciprocal Rank Fusion）和加权分数融合。RRF的核心逻辑是把两条结果列表的排名倒数相加，排名越高贡献越大，对分数尺度不敏感，不需要额外调权重。公式不复杂：

score(document) = Σ 1 / (k + rank(document))

k是平滑系数，一般取60。我自己实现了一个简化版RRF：

public Map<String, Double> rrfFusion(List<SearchResult> vectorResults, List<SearchResult> keywordResults) { Map<String, Double> scores = new HashMap<>(); int k = 60; for (int i = 0; i < vectorResults.size(); i++) { String docId = vectorResults.get(i).getDocId(); scores.merge(docId, 1.0 / (k + i + 1), Double::sum); } for (int i = 0; i < keywordResults.size(); i++) { String docId = keywordResults.get(i).getDocId(); scores.merge(docId, 1.0 / (k + i + 1), Double::sum); } return scores.entrySet().stream() .sorted(Map.Entry.<String, Double>comparingByValue().reversed()) .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue, (e1, e2) -> e1, LinkedHashMap::new)); }

融合之后你会发现，纯粹的语义相似doc和关键词完全命中的doc排到了前面，整体效果比单一向量检索稳很多。如果还想更精细，可以在向量召回之后加一个rerank模型（比如cross-encoder），但这需要额外的模型推理服务，而且Java侧调用成本偏高，数据量大的时候先不做。

5.3 标量过滤与元数据管理：让检索更精准

实际业务里很少只做全文语义搜索，通常还要附带各种过滤条件，比如“只看技术文档”“只看客服问答”“只看某个时间段的文档”。向量数据库里这类过滤建议用标量字段配合表达式完成，而不是把条件拼进文本再去embedding——文本变了向量就变了，这相当于把过滤逻辑塞进语义空间，效果很难控制。

Milvus支持直接在SearchParam里加expr表达式：

.withExpr("doc_type == \"faq\" and create_time > 1735689600")

把这个过滤条件下推到存储层，数据库会先做标量过滤，再进入向量索引搜索，性能损失可控。这里要特别提一个注意点：过滤字段一定要建索引，Milvus对标量字段默认不建索引，如果你在千万级大盘上做未索引字段的过滤，查询会慢到怀疑人生。

另一个元数据的实践是，在chunk_text之外存储完整的父子文档映射关系。比如每一条chunk包含chunk_id和parent_id，检索命中的是chunk_id，但返回给用户时按parent_id做一次分组聚合，把多个chunk合并成一篇完整文档再展示。这样用户体验更友好，不需要看到一堆片段。

6. 常见问题与排查技巧实录

6.1 连接问题：gRPC连接被重置、空闲超时

Milvus Java SDK默认走gRPC，长连接模式下容易出现空闲一段时间的Connection reset或者“UNAVAILABLE: Network closed for unknown reason”。这个问题本质上是服务端和客户端keepalive配置不对齐。排查路径：先看Milvus服务端是否开了keepalive，再看客户端是否禁用keepaliveWithoutCalls。Java端解决方法是：

.withKeepAliveWithoutCalls(true) .withKeepAliveTime(10, TimeUnit.SECONDS) .withKeepAliveTimeout(3, TimeUnit.SECONDS)

如果还在用grpc的单连接，高并发下也容易触发GOAWAY或too many pings，SDK上线前最好先压测，不要等线上炸。

6.2 数据量上来后内存过高

插入的向量全部加载到内存，会吃掉大量堆内存。Milvus插入接口一次性传几万条向量，客户端Java进程堆内存会瞬间飙升。我遇到过一次OOM，排查结果是批量插入时构造了一个超大的ArrayList，一次性把几十万条向量全部放内存。解决办法：控制批次大小，单批次建议512条，插入后释放引用，用-Xmx限制堆内存，并且开启GC日志观察频繁Full GC。

向量数据库本身对内存的需求也不低。HNSW索引会额外占用一部分内存，建议服务端内存至少是向量数据体积的2到3倍。如果你是2G内存的小机器跑500万条1024维向量，基本必挂。

6.3 中文检索效果差，问题出在切分还是embedding

中文检索效果差，第一反应先别怀疑模型，先检查切分。我遇到过最典型的翻车情况：一个文档里包含“这是一个测试文档。测试内容如下：”这种短句稀碎，切分后产生大量无意义chunk，这些chunk的向量几乎一样，检索时严重干扰排序。解决办法是在切分时过滤掉长度小于50字符的chunk，或者用简单规则把连续短句合并。

如果切分没问题，再检查embedding模型是否适合中文。部分英文模型处理中文很差，建议使用bge-m3或text2vec-large-chinese这类中文模型。做一次简单的自测：拿10条相似的query两两算余弦相似度，如果相似度普遍低于0.6，基本可以断定模型没选对。

6.4 Java类型转换与精度问题

Embedding接口返回的float数组，转到Milvus的List 时，可能会遇到精度损失。大部分开源模型输出的float是32位浮点，Java的float恰好也是32位，理论上无损耗。但如果你用double接数据再强转float，可能出现精度变化。我的建议是整个链路统一用float，别用double。

另一个问题是同一批向量里维数不一致。embedding服务偶尔会返回dim小于1024的向量（模型处理空文本时可能出现），插入时Milvus会直接报“vector dimension mismatch”，排查起来很隐蔽。我在embedding调用后加了一个校验：

if (vector.size() != 1024) { throw new IllegalStateException("Embedding dimension mismatch: " + vector.size()); }

6.5 常用检索参数速查表

参数	推荐值	说明
chunk_size	300-500字符	中文场景经验值，越大越泛，越小越碎
chunk_overlap	50-100字符	防止句子被截断
HNSW M	16	越大精度越高，内存占用越大
efConstruction	200	建索引质量，太大会变慢
efSearch	64	查询探索量，小则快，大则准
TopK	10-20	语义搜索建议先召回粗集再rerank
batch_size	512条	插入批次，过大内存爆，过慢

7. 从Demo到生产：一点实操心得

最后分享两个比较关键的实操体会。

第一，向量数据库不是放进去就完事的，索引和数据质量决定上限。我有一次把文档清洗、切分、embedding都做完了，检索效果还是不理想。后来发现是切分时把表格拆散了，导致每个chunk的语义支离破碎。从那以后，我给自己定了一条规矩：每次做检索效果评估，至少要人工抽查二十条失败case，分类记录是切分问题、embedding问题还是排序问题，再针对性优化。盲调参数效率极低。

第二，Java服务接入向量数据库，本质上是在分布式系统和机器学习模型之间搭一座桥，调试时要把数据流、线程池、连接池、内存占用放在一起看。有一个经验是给embedding调用单独建一个线程池，设置合理的超时和失败降级——一旦embedding服务抖动，不能拖垮核心查询链路。我在项目里给embedding服务配了熔断器，超时300毫秒直接降级返回空结果，保证搜索接口的主流程可用。

项目做到上线运行，整体的效果是：用户搜索“微信支付失败怎么解决”，能精确命中“微信支付错误码查不到账单”这类语义近似的文档；搜索“申请售后”，能召回“退款流程说明”和“退货地址怎么填”等关联文档。对比之前的ES关键词搜索，问答准确率提升了大概30%。

如果你也想在Java项目里做文档检索和语义搜索，我建议先从最小链路起步，别一上来就铺分布式，先用Qdrant单机或pgvector跑通，再根据自己的数据量决定要不要上Milvus。这个方向的技术栈还在快速演进，但核心的“切分-向量化-索引-混合检索”链路短期内不会变，把基本功打扎实了，后面换任何数据库都只是SDK的问题。