Soulmate索引原理解析:前缀如何批量写入Redis Sorted Set的完整教程

原创2026-10-14 21:24:151,873 阅读
文章标签:后端

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 步:

  1. 归一化:转小写、剔除非单词符号(保留中日韩字符,见 normalize)
  2. 丢停用词:默认停用词为 vs / at / the(见 config.rb),可通过配置文件覆盖
  3. 逐词切片:每个词从 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 负责反向"收拢":

  1. 把搜索词拆分、归一化,丢弃短词和停用词,排序
  2. zinterstore:对命中的所有 soulmate-index:{type}:{词} 一次求交集,同分排序保留——item 必须"每个词都包含"才入围,天然去重
  3. zrevrange:按分值倒序取 Top N
  4. hmget:用 id 从数据 HASH 批量取回原始 JSON
  5. 交集结果写入 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"做自动补全的完整骨架。

登录后查看全文
soulmate