语义相似度依赖外部模型把文本变成向量；similar 的 semantic 模块不下载、不运行模型，只负责接收固定维度向量，做点积 / 余弦相似度和精确 Top-K。它适合小规模语义检索、基准验证和候选重排。

应用场景

• 向量相似度打分：embedding_cosine() 计算两个同维向量的余弦。
• 小规模向量检索：EmbeddingIndex 精确 Top-K。
• 混合检索第二段：BM25 / ANN 召回候选后，用精确余弦重排。
• Python 侧 cross_encoder_rerank()：用批量回调做交叉编码器重排，不绑定推理框架。

性能指标

耗时是本地 libsimilar_c.so + Python ctypes 冒烟值。EmbeddingIndex 是线性扫描，查询时间随文档数和维度线性增长。

效果指标

• 余弦相似度：范围通常为 [-1, 1]，常用 0～1；用于相同量纲的向量比较。
• 精确 Top-K：结果是精确的，不受近似索引召回率影响。
• ANN 场景：先用 HNSW / IVF / DiskANN 召回候选，再测量 Recall@K；候选不足时再回退到更多检索路径。
• 交叉编码器：通常精度更高但更慢，只对少量候选重排，不作为全库扫描器。

推荐配置与阈值

• 所有向量必须同维；创建索引时固定 dim。
• 全库文档小于几万到几十万、且延迟预算允许时，可直接精确扫描。
• 大规模集合：ANN 召回 100～1000 个候选，再用本模块精确打分或交叉编码器重排。
• 余弦阈值需要按业务标注集标定，不宜直接照搬其他语料。

边界与误区

• 本模块不提供 ANN 索引，超大向量库应使用专业向量引擎。
• 它不负责文本到向量的推理；向量质量决定语义效果。
• 有状态句柄必须调用 close()，避免释放时机不确定。

一句话记住：向量质量来自模型，similar 只做同维精确打分和重排；大规模召回交给 ANN。