尧图网站建设 
LEANN 归一化嵌入支持自动距离度量检测与 Cosine/MIPS 正确选择实战指南【免费下载链接】LEANN[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.项目地址: https://gitcode.com/GitHub_Trending/le/LEANNLEANN 在构建索引时会自动识别 OpenAI、Voyage AI、Cohere 等厂商的归一化嵌入模型L2 范数为 1 的单位向量并自动为其选择最优的distance_metriccosine无需手动干预。本文以 docs/normalized_embeddings.md 为骨架结合leann-core与leann-backend-hnsw的源码实现深入讲解归一化嵌入的原理、自动检测的判定逻辑、支持的模型清单、完整的构建与搜索用法以及错误度量导致 HNSW 提前终止等问题的底层原因帮助你为自己的 RAG 应用选对距离度量。什么是归一化嵌入Normalized Embeddings归一化嵌入是指L2 范数恰好等于 1的向量即单位向量。这类向量经过 L2 归一化向量除以自身范数后任意两个向量之间的余弦相似度Cosine Similarity就等于它们的内积点积因此它们天然是为余弦相似度优化而非为最大内积搜索MIPSMaximum Inner Product Search设计。在 LEANN 中归一化嵌入的识别结果直接决定索引使用的距离度量进而影响整个检索链路的质量。这一点在 api.py 的LeannBuilder.__init__L469-L536中有着完整的实现。自动检测机制三步帮你做对度量选择当你用归一化嵌入模型创建LeannBuilder实例时LEANN 会自动完成三件事见 api.py未指定度量时自动设置distance_metriccosine检测到归一化模型且用户没有显式传入distance_metric时代码会直接写入backend_kwargs[distance_metric] cosine并发出UserWarning告知用户已自动切换手动指定了其他度量时给出警告若用户显式传入非 cosine 度量如mipsLEANN 不会静默覆盖而是发出警告提示该组合可能导致次优的检索结果以正确度量获得最优检索性能构建端与查询端都会依据cosine对向量做 L2 归一化使 HNSW 图的度量与向量空间严格匹配。检测逻辑的源码实现细节从源码看检测分为精确匹配与模式匹配两级api.py精确匹配维护一个(embedding_mode, model_name)元组集合normalized_embeddings_models包含 OpenAI、Voyage、Cohere 的全部已知归一化模型匹配时先将 mode 与 model 转小写再做全等或子串包含判断模式匹配兜底未命中精确集合时按厂商规则推断OpenAImode 或 model 名含openai且模型名含text-embedding、ada、3-small、3-large之一Voyagemode 或 model 名含voyage即视为归一化Voyage 全系模型均归一化Coheremode 或 model 名含cohere且模型名含embed。这意味着即使你使用的具体 OpenAI/Cohere 版本号不在精确清单中例如未来的text-embedding-4-*只要命名符合上述模式同样会被正确识别。支持的归一化嵌入模型清单根据 docs/normalized_embeddings.md 及 api.py 中的精确集合以下模型会被自动识别为归一化嵌入厂商模型名说明OpenAItext-embedding-ada-002全系 OpenAI 文本嵌入模型均归一化OpenAItext-embedding-3-small归一化OpenAItext-embedding-3-large归一化Voyage AIvoyage-2归一化Voyage AIvoyage-3归一化Voyage AIvoyage-large-2归一化Voyage AIvoyage-multilingual-2归一化Voyage AIvoyage-code-2归一化Cohereembed-english-v3.0归一化Cohereembed-multilingual-v3.0归一化Cohereembed-english-light-v3.0归一化Cohereembed-multilingual-light-v3.0归一化注意模式匹配规则尤其是 Voyage 全系、OpenAItext-embedding系列会覆盖精确清单之外的同系列新版本因此上表是确认清单而非封闭清单。示例用法自动检测与手动覆盖以下代码继承自 docs/normalized_embeddings.md 的示例并补充了源码层面的行为说明。方式一自动检测推荐from leann.api import LeannBuilder # 自动检测 - 将使用 cosine 距离 builder LeannBuilder( backend_namehnsw, embedding_modeltext-embedding-3-small, embedding_modeopenai ) # Warning: Detected normalized embeddings model text-embedding-3-small... # Automatically setting distance_metriccosine当未传入distance_metric时api.py 会将distance_metric写入backend_kwargs并随索引一起持久化到index.meta.json的backend_kwargs字段中。之后无论是构建端HNSWBuilder还是查询端HNSWSearcher、BaseSearcher都会从该字段读取度量保证索引构建与在线检索使用同一套度量约定参见 searcher_base.py 中搜索时从 meta 读取distance_metric、缺省回退mips的逻辑。方式二手动覆盖不推荐builder LeannBuilder( backend_namehnsw, embedding_modeltext-embedding-3-small, embedding_modeopenai, distance_metricmips # 将显示警告 ) # Warning: Using mips distance metric with normalized embeddings...此时检测到is_normalizedTrue且用户指定了非 cosine 度量api.py 会保留用户的设置并发出UserWarning。度量本身仍然生效但代价是检索质量下降——具体原因见下文为什么这很重要一节。支持的度量取值与底层映射在 HNSW 后端中度量字符串会被映射为 Faiss 的度量枚举hnsw_backend.pydistance_metric取值Faiss 枚举说明mipsfaiss.METRIC_INNER_PRODUCT最大内积搜索非归一化模型的默认最优度量l2faiss.METRIC_L2欧氏距离平方cosinefaiss.METRIC_INNER_PRODUCT余弦相似度向量归一化后内积即余弦值得注意的是cosine在 Faiss 层实际映射为METRIC_INNER_PRODUCT——因为归一化后的单位向量内积等价于余弦相似度无需 Faiss 内部再做归一化。真正完成归一化的是 LEANN 自己的normalize_l2()函数hnsw_backend.pydef normalize_l2(data: np.ndarray) - np.ndarray: norms np.linalg.norm(data, axis1, keepdimsTrue) norms[norms 0] 1 # 避免除零 return data / norms该函数对零向量做了除零保护。它的调用发生在两端构建端HNSWBuilder.build()在distance_metric cosine时对全部入库向量执行normalize_l2(data)hnsw_backend.py查询端HNSWSearcher.search()对查询向量同样执行normalize_l2(query)hnsw_backend.py。只有两端都归一化内积度量才能严格等价于余弦相似度。非归一化嵌入继续使用 MIPS像facebook/contriever以及其他未经归一化的 sentence-transformers 模型LEANN不会把它们判定为归一化模型因此默认仍使用mips度量——这对它们才是最优的docs/normalized_embeddings.md。从源码看这类模型在精确集合与模式匹配两级检测中均不命中api.pybackend_kwargs中不会出现distance_metric各后端因此回退到各自默认值HNSW 为mips见 hnsw_backend.py。这印证了 LEANN 的设计原则度量与向量空间必须匹配。归一化模型用 cosine非归一化模型用 MIPS各取所长。为什么这很重要错误度量的三大危害原文档明确指出对归一化嵌入使用错误度量会导致三类问题而源码给出了更精确的机理HNSW 提前终止导致检索质量下降归一化向量全部落在单位球面上所有内积分数都挤压在很窄的区间内。HNSW 搜索默认启用相对距离检查check_relative_distance当候选分数区间过窄时会被误判为已收敛而过早终止搜索错过真正的高质量邻居。源码中的针对性处理非常直观hnsw_backend.py# 对 OpenAI embeddings cosine 距离禁用相对距离检查 # 防止所有分数都处于狭窄区间时提前终止 if self.distance_metric cosine and any( openai_model in embedding_model for openai_model in [text-embedding, openai] ): params.check_relative_distance False else: params.check_relative_distance True可以看到LEANN 对OpenAI 归一化嵌入 cosine这一典型组合显式关闭了相对距离检查从机制上规避提前终止问题反之若使用 MIPS 度量则无法触发这一保护正是文档所述poor search quality的根源。结果排序不正确MIPS 搜索的是内积最大而语义相关性更接近余弦相似度。向量模长与方向信息混杂在内积中会使排序偏离真实的语义距离。性能次优度量与向量空间不匹配时图结构、剪枝pruning与距离重算逻辑都基于错误的几何假设整体检索效果与正确度量相比有明显差距。此外重算模式下的距离计算也在嵌入服务端遵循同样的度量约定l2用平方欧氏距离其他含 cosine 与 mips用负点积hnsw_embedding_server.py保证重算得分与索引度量一致。实践要点小结使用 OpenAI / Voyage / Cohere 等归一化嵌入模型构建LeannBuilder时无需手动指定distance_metricLEANN 会自动设置cosine若坚持手动覆盖为非 cosine 度量请接受UserWarning并知晓检索质量风险自定义 embedding 流程时若你的模型输出已经是单位向量可参考 api.py 的检测清单自行确认若输出未归一化则保持默认 MIPS 即可度量选择会影响构建与查询两端归一化、Faiss 度量枚举、相对距离检查、重算距离任何一环不一致都会破坏检索一致性。更多相关细节可继续阅读 docs/normalized_embeddings.md 原文以及索引构建入口 api.py、HNSW 后端实现 hnsw_backend.py 与检索基类 searcher_base.py。【免费下载链接】LEANN[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.项目地址: https://gitcode.com/GitHub_Trending/le/LEANN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LEANN 归一化嵌入支持：自动距离度量检测与 Cosine/MIPS 正确选择实战指南
LEANN 归一化嵌入支持自动距离度量检测与 Cosine/MIPS 正确选择实战指南【免费下载链接】LEANN[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.项目地址: https://gitcode.com/GitHub_Trending/le/LEANNLEANN 在构建索引时会自动识别 OpenAI、Voyage AI、Cohere 等厂商的归一化嵌入模型L2 范数为 1 的单位向量并自动为其选择最优的distance_metriccosine无需手动干预。本文以 docs/normalized_embeddings.md 为骨架结合leann-core与leann-backend-hnsw的源码实现深入讲解归一化嵌入的原理、自动检测的判定逻辑、支持的模型清单、完整的构建与搜索用法以及错误度量导致 HNSW 提前终止等问题的底层原因帮助你为自己的 RAG 应用选对距离度量。什么是归一化嵌入Normalized Embeddings归一化嵌入是指L2 范数恰好等于 1的向量即单位向量。这类向量经过 L2 归一化向量除以自身范数后任意两个向量之间的余弦相似度Cosine Similarity就等于它们的内积点积因此它们天然是为余弦相似度优化而非为最大内积搜索MIPSMaximum Inner Product Search设计。在 LEANN 中归一化嵌入的识别结果直接决定索引使用的距离度量进而影响整个检索链路的质量。这一点在 api.py 的LeannBuilder.__init__L469-L536中有着完整的实现。自动检测机制三步帮你做对度量选择当你用归一化嵌入模型创建LeannBuilder实例时LEANN 会自动完成三件事见 api.py未指定度量时自动设置distance_metriccosine检测到归一化模型且用户没有显式传入distance_metric时代码会直接写入backend_kwargs[distance_metric] cosine并发出UserWarning告知用户已自动切换手动指定了其他度量时给出警告若用户显式传入非 cosine 度量如mipsLEANN 不会静默覆盖而是发出警告提示该组合可能导致次优的检索结果以正确度量获得最优检索性能构建端与查询端都会依据cosine对向量做 L2 归一化使 HNSW 图的度量与向量空间严格匹配。检测逻辑的源码实现细节从源码看检测分为精确匹配与模式匹配两级api.py精确匹配维护一个(embedding_mode, model_name)元组集合normalized_embeddings_models包含 OpenAI、Voyage、Cohere 的全部已知归一化模型匹配时先将 mode 与 model 转小写再做全等或子串包含判断模式匹配兜底未命中精确集合时按厂商规则推断OpenAImode 或 model 名含openai且模型名含text-embedding、ada、3-small、3-large之一Voyagemode 或 model 名含voyage即视为归一化Voyage 全系模型均归一化Coheremode 或 model 名含cohere且模型名含embed。这意味着即使你使用的具体 OpenAI/Cohere 版本号不在精确清单中例如未来的text-embedding-4-*只要命名符合上述模式同样会被正确识别。支持的归一化嵌入模型清单根据 docs/normalized_embeddings.md 及 api.py 中的精确集合以下模型会被自动识别为归一化嵌入厂商模型名说明OpenAItext-embedding-ada-002全系 OpenAI 文本嵌入模型均归一化OpenAItext-embedding-3-small归一化OpenAItext-embedding-3-large归一化Voyage AIvoyage-2归一化Voyage AIvoyage-3归一化Voyage AIvoyage-large-2归一化Voyage AIvoyage-multilingual-2归一化Voyage AIvoyage-code-2归一化Cohereembed-english-v3.0归一化Cohereembed-multilingual-v3.0归一化Cohereembed-english-light-v3.0归一化Cohereembed-multilingual-light-v3.0归一化注意模式匹配规则尤其是 Voyage 全系、OpenAItext-embedding系列会覆盖精确清单之外的同系列新版本因此上表是确认清单而非封闭清单。示例用法自动检测与手动覆盖以下代码继承自 docs/normalized_embeddings.md 的示例并补充了源码层面的行为说明。方式一自动检测推荐from leann.api import LeannBuilder # 自动检测 - 将使用 cosine 距离 builder LeannBuilder( backend_namehnsw, embedding_modeltext-embedding-3-small, embedding_modeopenai ) # Warning: Detected normalized embeddings model text-embedding-3-small... # Automatically setting distance_metriccosine当未传入distance_metric时api.py 会将distance_metric写入backend_kwargs并随索引一起持久化到index.meta.json的backend_kwargs字段中。之后无论是构建端HNSWBuilder还是查询端HNSWSearcher、BaseSearcher都会从该字段读取度量保证索引构建与在线检索使用同一套度量约定参见 searcher_base.py 中搜索时从 meta 读取distance_metric、缺省回退mips的逻辑。方式二手动覆盖不推荐builder LeannBuilder( backend_namehnsw, embedding_modeltext-embedding-3-small, embedding_modeopenai, distance_metricmips # 将显示警告 ) # Warning: Using mips distance metric with normalized embeddings...此时检测到is_normalizedTrue且用户指定了非 cosine 度量api.py 会保留用户的设置并发出UserWarning。度量本身仍然生效但代价是检索质量下降——具体原因见下文为什么这很重要一节。支持的度量取值与底层映射在 HNSW 后端中度量字符串会被映射为 Faiss 的度量枚举hnsw_backend.pydistance_metric取值Faiss 枚举说明mipsfaiss.METRIC_INNER_PRODUCT最大内积搜索非归一化模型的默认最优度量l2faiss.METRIC_L2欧氏距离平方cosinefaiss.METRIC_INNER_PRODUCT余弦相似度向量归一化后内积即余弦值得注意的是cosine在 Faiss 层实际映射为METRIC_INNER_PRODUCT——因为归一化后的单位向量内积等价于余弦相似度无需 Faiss 内部再做归一化。真正完成归一化的是 LEANN 自己的normalize_l2()函数hnsw_backend.pydef normalize_l2(data: np.ndarray) - np.ndarray: norms np.linalg.norm(data, axis1, keepdimsTrue) norms[norms 0] 1 # 避免除零 return data / norms该函数对零向量做了除零保护。它的调用发生在两端构建端HNSWBuilder.build()在distance_metric cosine时对全部入库向量执行normalize_l2(data)hnsw_backend.py查询端HNSWSearcher.search()对查询向量同样执行normalize_l2(query)hnsw_backend.py。只有两端都归一化内积度量才能严格等价于余弦相似度。非归一化嵌入继续使用 MIPS像facebook/contriever以及其他未经归一化的 sentence-transformers 模型LEANN不会把它们判定为归一化模型因此默认仍使用mips度量——这对它们才是最优的docs/normalized_embeddings.md。从源码看这类模型在精确集合与模式匹配两级检测中均不命中api.pybackend_kwargs中不会出现distance_metric各后端因此回退到各自默认值HNSW 为mips见 hnsw_backend.py。这印证了 LEANN 的设计原则度量与向量空间必须匹配。归一化模型用 cosine非归一化模型用 MIPS各取所长。为什么这很重要错误度量的三大危害原文档明确指出对归一化嵌入使用错误度量会导致三类问题而源码给出了更精确的机理HNSW 提前终止导致检索质量下降归一化向量全部落在单位球面上所有内积分数都挤压在很窄的区间内。HNSW 搜索默认启用相对距离检查check_relative_distance当候选分数区间过窄时会被误判为已收敛而过早终止搜索错过真正的高质量邻居。源码中的针对性处理非常直观hnsw_backend.py# 对 OpenAI embeddings cosine 距离禁用相对距离检查 # 防止所有分数都处于狭窄区间时提前终止 if self.distance_metric cosine and any( openai_model in embedding_model for openai_model in [text-embedding, openai] ): params.check_relative_distance False else: params.check_relative_distance True可以看到LEANN 对OpenAI 归一化嵌入 cosine这一典型组合显式关闭了相对距离检查从机制上规避提前终止问题反之若使用 MIPS 度量则无法触发这一保护正是文档所述poor search quality的根源。结果排序不正确MIPS 搜索的是内积最大而语义相关性更接近余弦相似度。向量模长与方向信息混杂在内积中会使排序偏离真实的语义距离。性能次优度量与向量空间不匹配时图结构、剪枝pruning与距离重算逻辑都基于错误的几何假设整体检索效果与正确度量相比有明显差距。此外重算模式下的距离计算也在嵌入服务端遵循同样的度量约定l2用平方欧氏距离其他含 cosine 与 mips用负点积hnsw_embedding_server.py保证重算得分与索引度量一致。实践要点小结使用 OpenAI / Voyage / Cohere 等归一化嵌入模型构建LeannBuilder时无需手动指定distance_metricLEANN 会自动设置cosine若坚持手动覆盖为非 cosine 度量请接受UserWarning并知晓检索质量风险自定义 embedding 流程时若你的模型输出已经是单位向量可参考 api.py 的检测清单自行确认若输出未归一化则保持默认 MIPS 即可度量选择会影响构建与查询两端归一化、Faiss 度量枚举、相对距离检查、重算距离任何一环不一致都会破坏检索一致性。更多相关细节可继续阅读 docs/normalized_embeddings.md 原文以及索引构建入口 api.py、HNSW 后端实现 hnsw_backend.py 与检索基类 searcher_base.py。【免费下载链接】LEANN[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.项目地址: https://gitcode.com/GitHub_Trending/le/LEANN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考