Soulmate索引原理解析:前缀如何批量写入Redis Sorted Set的完整教程
Soulmate索引原理解析:前缀如何批量写入Redis Sorted Set的完整教程
Soulmate 是一个用 Ruby 编写的轻量级自动补全(Autocomplete)搜索工具,它用 Redis Sorted Set 作为前缀索引:你还没输完,它就能按已输入的部分词毫秒级返回 Top N 建议。本教程完整拆解它的索引原理——一条记录的词如何被切成十几个前缀,又如何通过 pipelined 批量写入 Redis,最后再讲如何用 3 条命令在本地跑起来。
一、先认识数据:一个 item 就是一行 JSON
在 Soulmate 眼里,任何你想提供补全的对象(场馆、艺人、赛事)都是一个 item:
{"id":1,"term":"Dodger Stadium","score":84,
"data":{"url":"/dodger-stadium-tickets/","subtitle":"Los Angeles, CA"}}
四个字段各司其职:
| 字段 | 作用 |
|---|---|
id |
唯一标识符(同类型内唯一) |
term |
要补全的词,可通过 aliases 附带别名 |
score |
自定义权重,最终结果按它排序(同分按字典序) |
data |
任意元数据,命中时原样返回给前端 |
项目自带一份小型示例数据集 test/samples/venues.json(7 条真实场馆记录,含 aliases 和一条中文数据)。
与传统关键词搜索最大的不同:Soulmate 不等你把词输完,而是直接匹配你已经输入的"前缀"。
二、Redis 键布局:索引只占 3 种 key
Soulmate 的全部索引都放在 Redis 里,base.rb 定义了三种 key 模板:
| Key | Redis 类型 | 作用 |
|---|---|---|
soulmate-index:{type} |
SET | 前缀"总集",记录该类型下所有已存在的前缀,全量重建时用于批量清理 |
soulmate-index:{type}:{prefix} |
Sorted Set | 索引核心:每个前缀一个集合,存放"包含该前缀词"的 item id,以 score 为排序分值 |
soulmate-data:{type} |
HASH | 存每个 item 的原始 JSON(key 为 id);索引里只存 id,省内存 |
比如加载一条 term 为 "Dodger Stadium" 的 venue 后,Redis 里大致长这样:
soulmate-index:venue (SET) → { do, dod, dodg, dodge, dodger, st, sta, ... }
soulmate-index:venue:stad (ZSET) → 28(90) 3(92) 1(84) 30(80) 29(75)
soulmate-index:venue:dodger (ZSET) → 1(84)
soulmate-data:venue (HASH) → 1 → {"id":1,"term":"Dodger Stadium",...}
括号里是
member(id) → 分值(score)。
三、前缀是怎么生成的:3 步切片
前缀生成逻辑在 helpers.rb 的 prefixes_for_phrase,只有 3 步:
- 归一化:转小写、剔除非单词符号(保留中日韩字符,见 normalize)
- 丢停用词:默认停用词为
vs/at/the(见 config.rb),可通过配置文件覆盖 - 逐词切片:每个词从 2 个字符开始一直切到完整词长,所有词合并去重
以 "Dodger Stadium" 为例(min_complete 默认 2):
dodger → do, dod, dodg, dodge, dodger (5 个)
stadium → st, sta, stad, stadi, stadiu, stadium (6 个)
共 11 个前缀,每个前缀对应一个 Sorted Set。test_soulmate.rb 里有同款的断言用例,包括中文"测试中文 test"的混合切片。
💡 为什么从 2 个字符切起?单词前缀冲突太多没意义,查询侧会直接丢弃短于 min_complete 的搜索词,索引侧也同步从该长度切起,避免产生无用的 key。
四、核心:一条 pipelined 批量写入几十个 key
重头戏来了——写入流程。loader.rb 的 add 方法核心就这几行:
Soulmate.redis.pipelined do
Soulmate.redis.hset(database, item["id"], MultiJson.encode(item))
prefixes_for_phrase(phrase).each do |p|
Soulmate.redis.sadd(base, p) # 总集记前缀
Soulmate.redis.zadd("#{base}:#{p}", item["score"], item["id"]) # 前缀索引
end
end
算一笔账:一条 item 要执行 1 次 HSET + N 次 SADD + N 次 ZADD,N 是前缀数量(10~30 很常见)。如果逐条发送,就是几十次网络往返;而 pipelined 把这几十条命令一次性打包发给 Redis,网络 RTT 从 N 次压缩到 1 次——这就是"批量写入"的含义。
两个容易忽略的细节:
- aliases 一并入索引:item 的
term和所有aliases会拼成一个 phrase 统一切片(loader.rb)。所以示例数据里 "Sun Life Stadium" 输入 "Land Shark" 也能命中它 - 同 id 先删后写:
add会先调用 remove 清掉旧记录的原始数据和全部前缀索引,保证更新幂等;全量加载时load会传:skip_duplicate_check => true跳过这步检查
五、查询侧:zinterstore 交集 + Top N + 10 分钟缓存
写入侧把前缀"打散"进一堆 Sorted Set,matcher.rb 负责反向"收拢":
- 把搜索词拆分、归一化,丢弃短词和停用词,排序
zinterstore:对命中的所有soulmate-index:{type}:{词}一次求交集,同分排序保留——item 必须"每个词都包含"才入围,天然去重zrevrange:按分值倒序取 Top Nhmget:用 id 从数据 HASH 批量取回原始 JSON- 交集结果写入
soulmate-cache:{type}:*并设置 10 分钟过期,相同搜索词直接命中缓存
所以搜索 stad 会返回 "Angel Stadium(90) → Citi Field(92,via 别名 Shea Stadium) → Dodger Stadium(84) → ...",分数高的排前面。
六、动手:3 条命令搭出你的前缀索引
先安装 gem(soulmate.gemspec 依赖 redis / sinatra / multi_json):
gem install soulmate
用示例数据全量加载(CLI 入口在 bin/soulmate):
soulmate load venue --redis=redis://localhost:6379/0 < test/samples/venues.json
命令行直接查询验证:
soulmate query venue stad
或者启动 HTTP 服务(bin/soulmate-web,服务实现在 server.rb),然后访问:
http://localhost:5678/search?types[]=venue&limit=3&term=stad
/search 支持多类型查询(types[]=event&types[]=venue),加 callback 参数可输出 JSONP;--stop-words 参数可以指定自定义停用词文件。
七、上手前的 5 个细节清单
- score 是唯一的排序杠杆:Soulmate 不做全文相关性计算,
score就是排名分,需要你自己在业务侧算好 load是全量重建:load 先 pipelined 批量删除旧前缀集合与总集,再逐条重建;重建窗口内可能短暂返回空集,靠缓存过期自愈(源码里有注释说明)- 索引大小 ≈ 词数 × 平均词长:把
min_complete调大能显著缩小索引 - 中文开箱即用:归一化保留 CJK 字符,中文前缀同样会被切片入索引
- 项目状态:Soulmate 已不再活跃维护,作者推荐后继项目 Soulheart;作为"Redis + Sorted Set"实现自动补全的教科书案例,其原理依然值得完整研读
一句话总结 Soulmate 的索引套路:写入打散前缀,查询取交集,索引只存 id,pipelined 加速。把这四句吃透,你就掌握了"前缀 + Sorted Set"做自动补全的完整骨架。