深入 flexsearch4cj 核心:上下文索引(Context Index)评分算法原理剖析
深入 flexsearch4cj 核心:上下文索引(Context Index)评分算法原理剖析
flexsearch4cj 是一个快速、零依赖的全文搜索库,它的核心竞争力来自一项被称为**上下文索引(Context Index)**的评分算法。与传统搜索库"查询时才算分"的思路不同,flexsearch4cj 在数据写入阶段就把每个词的位置提前换算成相关性分数并归档存储,查询时只需"查桶取号",无需实时计算,这就是它又快又准的秘密。
一、为什么要用"上下文索引"评分
传统倒排索引记录的是"哪个词出现在哪些文档里",至于"出现在什么位置、相关性有多强",往往要等用户查询时再逐条计算。数据量一大,这个实时打分环节就成了性能瓶颈。
flexsearch4cj 的做法是把打分前置到索引构建阶段:
- 每个词按它在文本中的位置算出一个"分数桶";
- 文档 ID 直接挂进对应的分数桶;
- 查询时按桶号顺序取结果,天然就是"按相关性排序"的顺序。
下面是 flexsearch4cj 的整体结构示意,核心逻辑集中在 core 层:
从源码看,整个 Index 对象其实只有两个"主桶"就撑起了全部能力,定义在 index.cj 中:
var map: Boxdata // 主索引:词 -> 分数桶 -> 文档ID列表
var ctx: Boxdata // 上下文索引:词 -> 邻近词 -> 分数桶 -> 文档ID列表
- map(主索引):回答"这个词出现在哪些文档里",且按分数分层;
- ctx(上下文索引):回答"哪个词和这个词经常相邻出现",这是多词查询精排的关键。
Boxdata 是项目自研的轻量容器,一个类型即可表达"字典、数组、字符串"三种形态(见 boxdata.cj),正是它让"多层嵌套的分数桶"能用极小的内存开销表达出来。
二、get_score:把"位置"换算成"分数"
上下文索引的地基是一个名为 get_score 的打分函数(index.cj),它解决一个朴素问题:同一个词,出现在文档开头还是结尾,相关性应该不一样。
它的核心逻辑只有三条规则:
| 条件 | 结果 |
|---|---|
| 词在第 0 位(i <= 0) | 直接记 0 分(基准桶) |
| 分辨率 resolution <= 1 | 不区分位置,统一 0 分 |
| 文档词数 + 词长 <= resolution | 分数 = 词的真实位置 |
| 文档较长(超过 resolution) | 分数按比例压缩到 1 ~ resolution-1 区间 |
可以把它理解成"等比例刻度尺":短文档用原始位置精确定位;长文档则把位置线性压缩进固定的刻度范围(默认 resolution = 9,即只有 0~8 共 9 个分数桶)。
这正是它内存友好的原因:无论文档多长,一个词最多只占用固定个数的分数桶,而不是为每个位置建一条记录。
三、写入流程:分词、打分、顺手建好"词邻居表"
当调用 index.add(id, content) 写入一条数据时(index.cj),内部依次发生四件事:
- 分词:用
encode函数把文本切成词数组(支持拉丁、CJK、西里尔、阿拉伯等语系,见 charset_latin_default.cj 等文件); - 主索引打分:每个词经
get_score算出分数,文档 ID 被挂入map的对应分数桶; - 上下文打分:若启用上下文(
tokenize = "strict"且contextDepth > 0),则向后扫描contextDepth + 1个邻近词,为每一对"当前词 → 邻近词"单独计算一个上下文分数; - 写入 ctx:词对按字典序排序(
contextBidirectional = true时双向可查),存入ctx[词][邻近词][上下文分数]的三级结构。
这里有个精巧的细节:上下文分数的基准分(resolution + 0 还是 resolution + 1)取决于文档总长与分辨率的比值(index.cj)——文档越长、上下文跨度被压缩得越厉害,词与词的"共现"就越不可信,因此系统会自动给短文档的上下文关系更高一档的信任度。
这套"词间关联"的结构可以类比为下图的绑定关系——中心节点(Annotation)声明与多个目标节点的关联,而 ctx 正是以"当前词"为中心、把"邻近词"作为目标节点组织起来:
同时,写入端用 dupes_inner 做了去重:同一个邻近词在同一次写入中只登记一次,避免长文档里高频词把上下文桶撑爆。
四、查询流程:单桶直达 + 交集精排
理解了写入,查询逻辑(index.cj)就很好懂了,分两种情况:
情况一:单关键词,或无上下文场景
- 查询词直接命中
map[词],得到按分数桶排列的 ID 列表; - 分数桶从小到大遍历 = 相关性从高到低,取满
limit条即提前终止(index.cj)。
情况二:多关键词,且启用了上下文(depthls = true)
这是上下文索引最出彩的地方(index.cj):
- 把查询词的第一个词当作"锚点",后续词依次作为"上下文候选";
- 每个后续词不是去
map里查,而是查ctx[锚点][该词]——即"与锚点相邻出现过的文档"才进入候选; - 各轮候选集逐层做交集,最终由 intersect.cj 的
Intersect.intersect完成多轮集合求交。
举个例子:搜索"全文 搜索 库"时,只有同时满足"包含全文"、"全文附近出现过搜索"、"搜索附近出现过库"的文档才能留在最终结果里。这在效果上接近"短语相邻匹配",但不需要维护真正的短语索引,存储成本极低。
另一个性能技巧:多词查询前,系统会先把查询词按长度从长到短排序(index.cj)——长词更"稀有",先处理小集合,交集计算能尽早收窄候选,甚至提前返回空结果。
五、关键配置项一览
上下文索引的行为由三个选项控制,定义在 index_options.cj:
| 配置项 | 默认值 | 作用 |
|---|---|---|
contextDepth |
1 | 向后扫描的邻近词数量,越大上下文越强,索引也越大 |
contextResolution |
1 | 上下文分数的桶数,越大上下文区分度越高 |
contextBidirectional |
true | 词对是否按字典序归一化后双向可查 |
项目还提供了开箱即用的 Preset 预设(index_options.cj),其中与上下文评分关系最直接的有:
| 预设 | 特点 |
|---|---|
MEMORY |
resolution=3、minlength=4,索引体积最小 |
SCORE |
resolution=20、contextDepth=3、contextResolution=9,评分精度最高,适合对排序质量敏感的全文检索 |
PERFORMANCE |
contextDepth=2,兼顾速度与上下文质量 |
选型建议:小数据量追求内存 → MEMORY;大文本、多词查询、讲究排序质量 → SCORE;拿不准就用 DEFAULT 起步。
六、小结:三点看懂上下文索引
- 打分前置:位置分数在写入时就算好并存入分数桶,查询免计算;
- 词对建图:ctx 结构把"谁和谁相邻"提前归档,多词查询靠交集快速收窄候选;
- 参数可调:
contextDepth、contextResolution、contextBidirectional三个旋钮,配合Preset即可在不同内存、速度、精度之间自由权衡。
如果你想动手验证这些机制,推荐阅读 doc/feature_api.md 中的接口文档,并结合 index.cj 中的 add / search 两个方法断点调试——跟着一个词从"分词 → 打分 → 入桶 → 查询命中"走一遍,上下文索引的原理就彻底通了。

