Superlinked数值嵌入指南：MIN/MAX与SIMILAR两种模式的实战区别

Superlinked数值嵌入指南：MIN/MAX与SIMILAR两种模式的实战区别

【免费下载链接】sieOpen-source inference server and production cluster for all the models your agent needs.项目地址: https://gitcode.com/GitHub_Trending/su/sie

在 Superlinked 向量检索框架中，数值嵌入（Number Embedding）让价格、评分、身高、负债额这类数字也能参与语义相似度排序。本文带你快速搞懂NumberSpace的两大阵营：MIN/MAX 模式（偏好最小/最大）与SIMILAR 模式（偏好最接近查询值），用一张对比表讲清两者的实战区别，帮你 30 秒做出正确选择。


为什么数值需要"嵌入"？

传统数据库里，数字只能用来过滤（WHERE price < 100）或排序，无法和文本、图片一起参与混合相似度打分。

Superlinked 的做法是：把min_value~max_value区间映射到一段圆弧上（每段区间对应一个角度），数值越"好"，其向量在空间中离理想方向越近。这样"身高更高、债务更低"就能和"文本更相关"一起加权排序了。

核心实现位于 number_embedding.py，它通过sin/cos把归一化后的数值变成 3 维向量。

MIN / MAX 模式：偏好"最大"或"最小"

这两种模式不需要在查询时给出具体数值，排序完全由存储值本身决定：

• 📈MAXIMUM（maximum）：偏好更大的数值。适合"身高越高越好""评分越高越好"。
• 📉MINIMUM（minimum）：偏好更小的数值。适合"价格越低越好""延迟越小越好"。

两个隐藏细节值得注意：

1. 越界惩罚（negative_filter）：MAX 模式下低于min_value的值、MIN 模式下高于max_value的值，会被打上惩罚向量，在排序中被压低。
2. 缺省值不扣分：源数据缺失时，MIN 模式默认等价于"最小值"、MAX 模式默认等价于"最大值"——即缺失值同样被视为"好值"。

官方示例把"身高（越大越好）+ 欠款（越小越好，且欠款呈幂律分布）"放在一个索引里，代码见 number_embedding_minmax.ipynb：

height_space = sl.NumberSpace( number=person.height, min_value=100, max_value=200, mode=sl.Mode.MAXIMUM) debt_space = sl.NumberSpace( number=person.outstanding_debt_amount, min_value=0, max_value=1e6, mode=sl.Mode.MINIMUM, scale=sl.LogarithmicScale())

对数刻度（LogarithmicScale）：处理"头重脚轻"的数据

像欠款、销售额这种幂律分布数据（少数人极端高、大多数人很低），用线性刻度会让低端区间几乎挤在一起、失去区分度。加上scale=sl.LogarithmicScale()（默认底数 10）后，低端数值被拉开，区分能力显著提升。

SIMILAR 模式：偏好"最接近"

如果你想要的是"接近 178cm 的人"，而不是"越高越好"，就用SIMILAR 模式：

height_space = sl.NumberSpace( number=person.height, min_value=100, max_value=220, mode=sl.Mode.SIMILAR) query = sl.Query(person_index).find(person).similar(height_space, 178)


SIMILAR 模式的关键规则：

• ⚠️必须配合.similar查询子句，否则查询会直接报错——这是最常见的踩坑点。
• 数值到圆弧的映射规则与 MIN/MAX 相同，但相似度是相对查询值计算的：175cm 与 180cm 查询 178cm，180cm 更近、排名靠前（分数差会非常小）。
• 区间两端越界都受惩罚（低于 min 或高于 max 均被压低）。
• 允许字段为空（_allow_empty_fields为 True），空值不参与惩罚。

完整可运行示例见 number_embedding_similar.ipynb。

一张表看懂三种模式的区别

如何选择：3 步决策清单

1. 业务目标固定（"永远要最便宜/最高分"）→ 用 MIN 或 MAX 模式。
2. 业务目标随用户查询变化（"用户说想要 178cm 左右"）→ 用 SIMILAR 模式，并在每次查询里带上.similar子句。
3. 数据严重偏斜（少数极端值）→ 无论哪种模式，考虑scale=sl.LogarithmicScale()拉开低端区分度。

查询结果会以表格形式返回，可参考基本构建模块文档中的截图效果 basicbb_query1.png。

关键文件与参考资料

• 空间定义：number_space.py
• 嵌入算法（圆弧映射 + 对数变换）：number_embedding.py
• Mode / Scale 枚举：number_embedding_config.py
• 官方 API 参考：number_space.mdx
• 空间体系总览：space 概览

小结

🎯MIN/MAX 模式回答"哪个最极值"，SIMILAR 模式回答"哪个最接近我"。两者共用同一套圆弧嵌入，区别只在于打分参照物是"区间端点"还是"查询值"。记住 SIMILAR 模式缺少.similar子句会报错、幂律数据记得开对数刻度，这两个坑就基本避开了。

【免费下载链接】sieOpen-source inference server and production cluster for all the models your agent needs.项目地址: https://gitcode.com/GitHub_Trending/su/sie