ternlight 是一个只需 5–7 MB 就能在浏览器和 Node.js 中运行的端侧语义搜索模型，它把引擎、模型和分词器打包进一个 WebAssembly 文件，完全靠 CPU 完成向量嵌入，无需调用任何 API。它的核心指标是Spearman 秩相关系数 0.844和SciFact NDCG@10 达 0.465——这两个数字到底怎么算出来的、又说明了什么？本文带你完整解读 ternlight 的评测方法论。

🤔 先搞懂：ternlight 是做什么的？

一句话：把一段文本变成一个 384 维的语义向量（embedding），再用余弦相似度找"意思相近"的文本。它的技术栈相当激进：

• 三值权重（ternary weights）：每个权重只能是-1、0、+1，矩阵乘法变成加减法
• 单文件交付：模型 + BERT 分词器 + Rust 推理引擎，全部塞进一个.wasm
• 零依赖运行：不需要 GPU、不需要 ML 框架、不需要联网

项目分为两个档位（详见 README.md）：

那么问题来了：压缩了 20 倍以上的模型，质量还剩多少？官方用两个指标来回答——Spearman 和 NDCG@10。

📐 Spearman：学生模型的"排序能力"像不像老师

ternlight 的模型是从all-MiniLM-L6-v2（教师模型）蒸馏而来的学生模型。Spearman 评测回答的问题是：

给定一堆句子，学生模型给句子对打的"相似度分数"，排序上是否与教师模型一致？

具体流程（实现见 spearman.js）：

1. 取100 条留出（held-out）MS MARCO 查询，先用教师模型算好每句的嵌入向量，存为语料文件 spearman_smoke_1k.json
2. 候选模型用 WASM 引擎重新嵌入同样的句子
3. 用固定随机种子（seed=42）确定性抽取 1000 个句子对
4. 分别计算两侧的余弦相似度，再算两组分数之间的Spearman 秩相关系数

这个指标的关键特性：

• 1.0 = 完美：学生与教师对每一对句子的相似程度排序完全一致
• 对尺度和偏移不敏感：只看排序，不看绝对分数
• 完全可复现：固定种子意味着任何人重跑都会得到一模一样的数字（精确到 4 位小数）

⚠️ 注意：Spearman 衡量的是蒸馏保真度（学生像不像老师），而不是"模型对人类的判断有多准"——后者属于 STS-Benchmark 那一类评测，是另一套数字。

🔍 NDCG@10：能不能真正"搜到"对的文档

Spearman 高 ≠ 检索一定好用。一个模型可以在相似度打分上表现优秀，但实际做"查询 → 找文档"的排序时翻车。所以官方引入了下游检索任务来检验真正的产品能力。

NDCG@10（Normalized Discounted Cumulative Gain）是信息检索领域的标准指标，通俗地说：

对每个查询，模型排在前 10 名的文档里，真正相关的文档是否排在越靠前的位置？分数越高越好，1.0 表示完美排序。

计算方式（见 evaluation.py）：

• 在 BEIR 的SciFact任务上测试：约5,183 篇文档语料 ×300 条测试查询
• 用余弦相似度给所有文档打分，取 Top-10
• 按位置越靠后折减越大（log2(排名+2)分母），计算 DCG，再除以理想排序的 IDCG
• 所有查询取微平均

官方把 NDCG@10 称为"承载性数字"（load-bearing number）——因为对"语义搜索库"这个产品定位来说，能不能搜到，才是用户真正关心的问题。

📊 真实结果：压缩 20 倍，质量掉了多少？

完整评测报告见 eval/quality/RESULTS.md，核心数字如下：

从这张"质量换尺寸"的散点图可以读出三个关键结论：

1. fp32 → int8 → int4 几乎无损：Spearman 从 0.883 缓降到 0.835，保留了约 95% 的排序信号
2. 悬崖在 4 bit 以下：再压到三值嵌入，Spearman 骤降 0.13——所以emb_int4成为默认发布档位
3. 一句话总结：从 fp32 教师模型到发布版，体积压缩 20 倍，只损失 0.165 的 Spearman

原始数据（含字节数、参数量、检查点路径）都记录在 eval/results/quality.json，保证数字可追溯、可复现。

🧪 评测方法论的四个设计原则

ternlight 的完整评测框架定义在 eval-methodology.md，覆盖模型质量、量化差距、性能、体积、兼容性、横向对比六个维度。几个值得学习的方法论细节：

• 发布差距，而不只是头条数字："Spearman 0.844" 单独看没意义，必须对照教师模型（1.0）和 fp32 学生模型（0.883）才有上下文
• 版本锚定一切：每次发布生成带版本号的results/v<X.Y.Z>.json，报告由 run-eval.sh 脚本统一再生成，杜绝手工改表
• 区分引擎与模型：引擎 bug 和模型弱点都会拉低指标，所以 parity 测试（Rust 数学是否与 Python 一致到 ~1e-7）和绝对质量测试分开报告（见 eval/ 目录结构）
• 所有数字确定性可复现：固定 seed、固定语料、固定 commit，重跑即复现

🎯 结论：ternlight 的质量到底怎么样？

答案是"相当能打，且边界清晰"：

• ✅ 对 5–7 MB 的端侧嵌入模型而言，0.844 Spearman + 0.465 NDCG@10 意味着搜索即输入、FAQ 匹配、意图路由这类短文本场景完全够用
• ✅ 评测体系本身值得参考：双指标互补（保真度 + 下游任务）、全链路可复现、主动公布"差距"
• ⚠️ 它不是前沿模型——128 token 输入上限、仅支持英文，绝对质量低于text-embedding-3-large这类 API 模型
• 💡选择建议：当体积、延迟、离线能力和隐私比最后几个质量点更重要时，ternlight 是最优解之一；反之请选云端嵌入 API

深入阅读：项目总览 · 模型内部结构 · 推理引擎 · 模型注册信息