夜雨聆风学习资料网

ARTICLE · 1387336

做 RAG 一定要上 Milvus?我把源码扒了一遍

做 RAG 一定要上 Milvus?我把源码扒了一遍

一句话:换向量库确实只改一个 Bean,但「同一个接口」不等于「同一个行为」。 我把社区模块的源码扒了一遍,6 处差异,每一处都会让结果悄悄变掉,而且不报错。


① 先说结论

先说清楚我自己的项目:它的向量库不是 Lucene。

是 InMemoryEmbeddingStore + 一个 JSON 文件。

类名 LuceneVectorConfig、目录名 lucene-rag-index/、连仓库名都叫 lucene-rag —— 全是历史包袱。 早期方案换掉了,名字没跟着改。

那我怎么知道换 Lucene 会出事?

我把社区模块的源码扒了。dev.langchain4j:langchain4j-community-lucene,版本 1.9.0-beta16(跟本项目的 BGE 嵌入模块同一条 beta 线)。

扒完我数了一遍:6 处真实差异,其中 3 处会静默改变结果。

#
差异
后果
1
score 刻度不同minScore(0.7)
 在 Lucene 上形同虚设
2
过滤器静默丢弃
源码里就一行 log.debug,你的过滤条件根本没生效
3
删除直接抛异常removeAll()
 抛 UnsupportedFeatureException
4
返回的向量恒为 null
取 match.embedding() 的代码直接 NPE
5
中文分词不支持StandardAnalyzer
 把中文切成一字一 token
6
旧库不可迁移store.json
 迁不过去,必须重新入库

「换 Bean 只改一行」这话本身没错。错的是把它当成「换了就一样」。


② 一个反直觉的结论

Lucene 听起来是「全文检索之王」,中文分词却是它最弱的一环 —— 而中文 RAG 恰好正中这一枪。

我一开始的判断是:Lucene 有 BM25、有倒排、有成熟的分词器,中文肯定比纯向量检索强(毕竟中文分词是国产搜索引擎的看家本事)。

错了。

社区模块的全文检索用的是:

new QueryParser(contentFieldName, new StandardAnalyzer())

StandardAnalyzer 是 Lucene 的默认分词器,不支持中文分词 —— CJK 字符会被一字一 token 切开。

📌 「LangChain4j 是 Java 生态的大模型框架」→ 被切成Lang、Chain4j、是、Ja、va、生、态、的、大、模、型、框、架

BM25 那一路的全文召回质量,在中文上明显偏弱。

而我的项目是 bge-small-zh + 中文文档 ——恰好是 StandardAnalyzer 最吃亏的场景。

所以结论有点反直觉:

想做「全文 + 向量」混合检索,Lucene 是对的选型 —— 但前提是你的文档不是中文。中文场景下,它在最有价值的那个能力上,恰好是最弱的。

顺带一提,Lucene 的 QueryParser 对用户问句里的特殊字符(:"()会抛 ParseException,那一路检索会被直接降级丢弃。


③ 跑一遍看看

⚠️ 先声明一件事,这篇的诚信底线:我的项目没有真的接 Lucene。pom.xml 里没有这个依赖, 下面每条差异都是对社区模块 1.9.0-beta16 源码的核实,我标了源码位置。 凡是我没实跑过的,我不写「我实测」。

3.1 最要命的一条:score 刻度

同一个 EmbeddingSearchRequest,两个实现给出的 score 完全不是一回事:

为什么 InMemory 的 score 一定在 [0,1]? 因为它的实现是这么算的:

// RelevanceScore —— 上游源码
publicstatic RelevanceScore fromCosineSimilarity(double cosineSimilarity){
returnnew RelevanceScore((cosineSimilarity + 1) / 2);
}

余弦相似度天然在 [-1, 1],**映射到 [0, 1]**。 所以 minScore(0.7) 在 InMemory 上真的就是「70% 相关」—— 可解释。

Lucene 那边返回的是原始 BM25 + KNN 混合分,没有上界(常见 5~30)。minScore(0.7) 对这个刻度来说,低到等于不存在。

这是「切换无感」最容易翻车的地方 —— 参数没动,代码没动,结果悄悄变了。 还不报错。

3.2 一个必须澄清的坑:minScore 根本传不了 10.0

我在自己的文档里写过一句「在 Lucene 上设 minScore(10.0) = 几乎全被过滤」。

这句话是错的。 扒源码才发现,EmbeddingSearchRequest 的构造器里就有这么一行:

this.minScore = ensureBetween(getOrDefault(minScore, 0.0), 0.0, 1.0, "minScore");

minScore 被硬校验在 [0, 1]。传 10.0 直接抛 IllegalArgumentException —— 根本走不到「过滤」那一步。

所以准确的说法是:

在 Lucene 上,你没法靠调高 minScore 来救。这个旋钮只能在 [0,1] 里拧, 而 Lucene 的分根本不在这个区间里。换句话说,这个阈值参数在某些向量库上压根不够用。

(顺便:maxResults 的默认值也是 3,源码 getOrDefault(maxResults, 3)。你的配置值跟框架默认值撞车的时候,你根本不知道自己在用哪个。)

3.3 过滤器:静默丢弃,不报错

InMemory
Lucene 社区模块
过滤器
✅ 真的执行filter.test(metadata)
❌ 静默丢弃

Lucene 那边的源码就一行:

log.debug("Ignoring request filter");

log.debug。

也就是说:你的过滤条件被扔掉了,程序继续跑,结果里全是不该出现的文档。不抛异常、不打 warn、不影响返回码。 默认日志级别下你连那行 debug 都看不到。

📌 这 6 条里我最警惕的就是这条,因为它连「结果变了」都不算 ——你以为自己设了一个约束,其实没设。查这种问题最快的办法:把日志级别调到 debug,看有没有 "Ignoring" 这行。

3.4 删除:直接抛异常

InMemory
Lucene 社区模块
removeAll()
✅ 三种重载全支持
❌ 未覆盖 → 抛 UnsupportedFeatureException

这条反而是最友好的失败 —— 它会炸,炸得明明白白。 「文档过期了要删掉重录」这种需求一上 Lucene 就直接编译期/运行期报错。

对比第 3.3 条:一个会炸,一个不炸。我宁愿它炸。

3.5 返回的向量:Lucene 那边恒为 null

EmbeddingMatch 有 4 个字段:

publicclassEmbeddingMatch<Embedded> {
privatefinal Double score;
privatefinal String embeddingId;
privatefinal Embedding embedding;   // ← Lucene 里恒为 null
privatefinal Embedded embedded;
}
InMemory
Lucene 社区模块
match.embedding()
✅ 返回原向量
❌ 恒为 null

为什么? Lucene 的 KnnFloatVectorField不存原向量 —— 它只建索引。

如果你的代码里有「拿命中片段的向量再算一次距离」这种逻辑,换过去之后会 NPE,而且只在检索命中时才 NPE —— 空库时不炸,有数据才炸,非常难查。

3.6 中文分词:StandardAnalyzer 一字一 token

上面 §② 已经讲透了,这里补个具体的:

LuceneContentRetriever 的全文检索:
new QueryParser(contentFieldName, new StandardAnalyzer())

StandardAnalyzer 是 Lucene 默认的英文分词器,遇到 CJK 字符走的是StandardTokenizer 的 CJK 分支(按单个汉字切)。

文本
英文分词器的切法
LangChain4j 是 Java 生态的大模型框架LangChain4j是Java生态的大模型框架

「生态」被切成「生」「态」—— BM25 的词频统计就废了。

3.7 依赖与持久化

项
InMemory
Lucene 社区模块
外部依赖
零
(LangChain4j 自带)
约 9MB
(lucene-core/queryparser/facet/queries/sandbox 9.12.3 + jtokkit 1.1.0)
持久化
JSON 单文件(serializeToFile)
Lucene Directory 索引目录
数据迁移
—
❌ 旧 store.json 不可迁移,必须重新入库

换 Bean 的代码确实很短:

// demo / 万级以内:零外部依赖
@Bean
public EmbeddingStore<TextSegment> embeddingStore(){
returnnew InMemoryEmbeddingStore<>();
}

// 想上全文 + 向量混合检索
@Bean
public EmbeddingStore<TextSegment> embeddingStore(){
return LuceneEmbeddingStore.builder()
            .directory(Path.of("./lucene-index"))
            .embeddingModel(embeddingModel)
            .build();
}

接口是同一个 EmbeddingStore<TextSegment>,所以「只改一个 Bean」是成立的。但「无缝替换」不成立 —— 上面 6 条,每一条都会让你重新想一遍。

3.8 那到底该选哪个

场景
选谁
为什么
demo / 万级以内 / 单实例
InMemoryEmbeddingStore
零依赖、零运维、接口全实现(过滤器、删除都能用)
想要全文 + 向量混合检索,且文档不是中文
Lucene
 社区模块
这是它真正的差异化价值
中文文档
 + 要混合检索
⚠️ Lucene 要慎用
StandardAnalyzer
 不支持中文分词;要么换分词器(那就得自己写 retriever),要么走别的路
十万级以上 / 多实例 / 要高可用Milvus / Qdrant / pgvector
这才是「上向量库」真正该上的场景
已有 ES 集群ES 8+
 的向量能力
别再单独引一个 Lucene

一句话总结选型:InMemory 够用的时候别换;中文场景下 Lucene 的混合检索优势发挥不出来; 真正需要向量库的场景是十万级以上,那时候 Milvus 才是答案 —— 而不是 Lucene。


④ 踩过的坑(怎么定位的)

这一节列的都是换库时才会遇到的坑。前三个是我扒源码扒出来的, 后两个是我自己项目里踩的。

坑 1:过滤器静默丢弃 —— 最阴的一个

现象:你的代码里有 filter(按 source 过滤、只要某个业务域的文档), 换到 Lucene 之后,返回结果里混进了不该出现的文档。 不报错、不打日志、返回 200。

根因(社区模块源码):

log.debug("Ignoring request filter");

一行 debug 日志,然后把你的过滤条件扔了。

怎么定位的:这是最需要「主动怀疑」的一类问题 ——因为没有任何异常指向它。 我的办法是:**把日志级别调到 debug,grep "Ignoring"**:

logging:
level:
dev.langchain4j.store.embedding.lucene:DEBUG

一行日志,直接现形。

怎么修的:别指望换库能带过去。 要么在换库之前, 先 grep 一遍自己代码里所有 filter 的使用点,逐个确认在新库下还有效; 要么就接受「这个过滤在新库上没有」,自己写一层。

有个直觉我到现在还留着:跨实现切换时,最危险的不是「报错」,是「不报错」。报错你知道。静默降级,你只会怀疑人生。 所以换库之后第一件事:拿同一批数据、同一组参数,跑一次对比。

坑 2:minScore 形同虚设 —— 参数不变,结果悄悄变

现象:InMemory 上 minScore=0.7 能滤掉一批低分片段; 换成 Lucene 之后,低分片段全放行了,答案里开始出现不相干的段落。

根因:score 刻度不同(§3.1)。InMemory 是 (cos+1)/2 ∈ [0,1],Lucene 是 5~30 的原始分。

怎么定位的:别看参数,看返回值。 我把两边命中的 score 都打出来对比:

// 临时加一行,看真实刻度
matches.forEach(m -> log.info("score={} text={}",
        String.format("%.4f", m.score()), m.embedded().text().substring(0, 20)));

InMemory 打出来是 0.9234 这种,Lucene 打出来是 18.7721 这种 —— 一眼就知道不是一套刻度。

怎么修的:换库时,所有跟阈值有关的参数全部重新校准。别照抄旧值,也别指望调大 —— 那个旋钮被锁在 [0,1] 里(§3.2)。

坑 3:removeAll 抛 UnsupportedFeatureException

现象:「文档过期了要删掉重录」这个需求,一换库就炸。

根因:社区模块没实现这个方法。

怎么定位的:接口方法一眼能看出来 —— javap 一下 LuceneEmbeddingStore, 看它覆写了 EmbeddingStore 的哪些方法,没覆写的那些就是会抛的。

怎么修的:这反而是好事 —— 抛异常比静默丢弃强多了。 唯一要做的是在切换清单里把它列出来,别等上线才发现。

坑 4:命中片段的向量取不到 → NPE

现象:检索命中之后抛 NullPointerException,但空库时一切正常。

根因:match.embedding() 在 Lucene 下恒为 null(§3.5)。 我的代码里有一处「拿命中向量和查询向量再算一次距离做二次排序」。

怎么定位的:NPE 的堆栈直接指到那一行。难的是复现 —— 必须「有数据 + 命中」才会触发。

怎么修的:

  • 要么这段逻辑就不该存在(二次排序用 score 就够了)
  • 要么就别依赖 embedding() 非空,改成 Optional 或显式判空并说明为什么是 null

坑 5:我自己项目里的坑 —— 类名和配置都在骗人

现象:想「把向量库换成 Lucene」,打开代码找 LuceneVectorConfig, 发现里面建的是 InMemoryEmbeddingStore。

更坑的是application.yml 里写着:

vector:
store-type:inmemory-json# ← 没有任何代码读它
index-dir:./lucene-rag-index

store-type 是纯装饰性配置。 没有任何 @Value 读它。 目录名 lucene-rag-index 也只是历史包袱,里面躺的是一个 JSON 文件。

怎么定位的:grep -rn "store-type" src/main/java —— 零命中。

怎么修的:改配置没用,得改 Bean。然后把误导性的名字改掉。

这一条我单独拎出来说,因为它跟选型没关系,但杀伤力一样大:你的配置项、类名、目录名,会让下一个人(或者半年后的你)做出错误判断。名字里带着错误信息,比没名字更贵。


⑤ 什么场景别用它

别这么干
为什么
「看别人都上 Milvus,我也上」
Milvus 是为了千万级的。你万级以内,InMemory 零依赖零运维,比 Milvus 少三个 Docker 容器
「InMemory 不够专业」
它是 LangChain4j 官方接口的标准实现,接口全实现(过滤器、删除都支持)。专业不专业看你的数据量
「Lucene 是全文检索之王,中文肯定强」StandardAnalyzer
 不支持中文分词,一字一 token。中文场景这是它的短板不是长板
「换 Bean 就等于换了个库」
同一个接口,6 处行为差异(本文全部)。换之前先做对比测试
「先把 store-type 改成 lucene 试试」
那个配置没人读。改它什么都不会发生
「先用着,等数据涨到百万再换」
迁移成本要提前算。Lucene 那条尤其狠:旧 store.json 不可迁移,必须重新入库 —— 十万条重新入库的 embedding 成本,算过再决定
「中文 RAG 上 Lucene 混合检索」
要中文分词就得换分词器(IK / jieba),那就得自己写 retriever —— 那就不是「换个 Bean」了

最后一条最值得展开:

如果你真的需要中文的「全文 + 向量」混合检索,Lucene 社区模块的默认配置只是个起点。中文分词、retriever、两路结果怎么融合,都得你自己接。 你得自己接一个中文分词器,自己写 retriever,自己控制两路结果怎么融合。 做到这一步,性质就变了 —— 换个 Bean 变成了换一套检索层。

这时候真正该问的是:我要的是混合检索,还是「能撑住千万级」?这是两个问题,别混在一起答。

企业级怎么换

我这套是 MVP 的选择。到了企业级,换法没这么轻:

现在
换成
要动什么
JSON + InMemory
pgvector
加一张表、改一个 Bean,复用现有 PostgreSQL
JSON + InMemory
Milvus
多一个集群、改 Bean、写数据迁移脚本
全文 + 向量混合
ES 8+
已有 ES 集群就别单独引 Lucene

选的时候,关键不是「谁更强」,是「你手上已经有什么」。

已经有 PostgreSQL,就别为一个向量库再上 Milvus;已经有 ES,就别单独引一套 Lucene。 多引一个中间件就多一份运维成本,而这份成本通常没被算进选型表里。

Java 团队其实大部分不用做选择题

上面那三条是我自己走过的。换成 Java 后端的视角来看,大多数项目根本不用挑 —— 你手上已经有的东西,直接就决定了答案:

你手上已经有什么
直接用它
理由
PostgreSQL
pgvector
装个插件就行,不加新服务;向量跟业务表同库,联表过滤天然一致
Elasticsearch 集群
ES 8+
 的向量能力
混合召回本来就是 ES 的强项,别再单独引一套 Lucene
Redis
Redis Stack
内存里的,微秒级响应 —— 适合做热数据缓存,不是全量存储
MongoDB
Atlas Vector Search
文档和向量同库,不用另外同步
MySQL
MySQL 9.0+ 原生 VECTOR
生态还在完善,中小场景够用
什么都没有
先 pgvector
,撑不住了再说
千万级以内 pgvector 够用了

Java 这条线还有两个坑:

  • 别在核心链路上用 JNI 封装的向量库。Java 调 FAISS 这类方案,JNI 一崩整个 JVM 跟着崩,这个风险不值当 —— 离线批量算向量可以,在线检索不行。
  • 客户端 SDK 的版本必须跟服务端严格对齐。Java SDK 的小版本一多,服务端升了、SDK 没跟上,协议就不兼容,报出来的错还特别难懂。

还有一条不算坑,但很影响开发速度:优先选 Spring AI / LangChain4j 原生支持的方案。 原生支持意味着你少写一大圈封装代码 —— 说白了,就是少在「怎么把向量库包装成 LangChain4j 认的样子」上花时间。

而这一层恰恰是最容易出错的地方 —— 本文开头那 6 条差异,全都发生在包装层底下。

这也是我为什么从 InMemory 起步 —— 它未必最好,但最不需要运维。等运维成本小于性能收益了,再换。


接下来的: 第 4 篇《一行配置切换 6 款大模型》—— 换 LLM 和换向量库是两回事:换 LLM 改三个字段,换向量库要重新想 6 件事。

本文完整梳理对应技术的原理逻辑、落地方案与使用边界,可直接用于项目实践与技术学习参考。


回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料