1.2 发展历程与开源生态

2020 年前后，纯生成模型的幻觉问题把工程界逼到墙角

在体系的时间轴上，LEANN 不是凭空出现的，它是「检索增强」这一路线在边缘侧的落地形态。理解它的来历，能帮你在选型时少走弯路。

我们回顾一段真实的技术拐弯。早期向量库（如 FAISS 的开源）证明了十亿级向量也能毫秒检索，但那只是「找回相似片段」，不会「组织答案」。随后检索增强生成兴起，大家发现把外部知识喂给大模型能显著压低幻觉；可大模型本身太重，跑不到边缘端。LEANN 的出现，是把「重活」拆开：检索留在库里，生成压缩成一个小网络。

开源生态里，LEANN 的定位介于「纯向量数据库」和「重型 RAG 框架」之间。它不替你管整个知识中台，而是专注提供一个能嵌入设备的最小运行时。下面这段代码模拟了一次「版本能力对照」，帮你判断该用哪一代能力。

CAP = {
    'v1': {'index': 'flat', 'rerank': False, 'edge': True},
    'v2': {'index': 'hnsw', 'rerank': True,  'edge': True},
    'v3': {'index': 'hnsw', 'rerank': True,  'edge': True, 'hybrid': True},
}

def pick_version(need_hybrid, on_edge):
    for ver, cap in CAP.items():
        if need_hybrid and not cap.get('hybrid'):
            continue
        if on_edge and not cap['edge']:
            continue
        return ver
    return 'none'

print('边缘端需混合检索 ->', pick_version(True, True))
print('仅边缘基础检索 ->', pick_version(False, True))
​

这段逻辑本身简单，但它体现了生态演进的取舍：v1 只能平面检索、无重排，适合纯 demo；v2 引入图索引和重排头，才真正能在边缘端干活；v3 补上混合检索，应对「关键词 + 语义」并存的查询。

不少团队卡在从 v1 迁到 v2，根因是重排头引入了新的训练环节。我们给出迁移时的检查清单函数。

def migration_checklist(old_cfg, new_cfg):
    problems = []
    if old_cfg.get('rerank') is False and new_cfg.get('rerank') is True:
        problems.append('需准备重排头训练数据（查询-相关/不相关对）')
    if old_cfg.get('index') == 'flat' and new_cfg.get('index') == 'hnsw':
        problems.append('需调 m 与 ef 参数，平面检索无此概念')
    return problems or ['可平滑迁移']

print(migration_checklist({'rerank': False, 'index': 'flat'},
                          {'rerank': True, 'index': 'hnsw'}))
​

案例：从 v1 平面检索迁到 v2 重排

• 背景：某客服知识库用 v1 平面检索，十万人规模还能扛，但答案常把过时条款排前面。
• 操作：按上面的检查清单，先补重排训练对（从历史会话里挖「用户采纳/未采纳」），再切 hnsw 索引。
• 结果：首条采纳率从 58% 升到 79%，但上线前多花了约两周标注。
• 解读：v2 的收益来自重排头，成本也来自重排头；生态演进不是白捡的。
• 变式：若标注人力不足，可先用规则弱标注（如点击即相关），再迭代。

我们再多看一层：开源项目的生命力不只在代码，而在治理。LEANN 采用「维护者加领域提交者」两层结构，前者管架构一致性，后者来自各行业的真实用例。这种分工让一家医疗设备公司和一家电商都能把自家需求反哺回来，而不必等核心团队排期。

下面给出一段贡献热力统计，帮维护者判断生态是否健康，它比 star 数更能说明问题。

def ecosystem_health(issues, prs, contributors):
    # 健康信号：贡献者是否多元、PR 是否有人审
    multi = len({c for c in contributors}) >= 5
    reviewed = sum(1 for p in prs if p.get('reviewed')) / max(1, len(prs))
    return {'贡献者多元': multi, 'PR 评审率': round(reviewed, 2)}

print(ecosystem_health([1], [{'reviewed': True}], ['a','b','c','d','e']))
​

回到主线，生态成熟度的判断，和我们在第一章讲的「能力边界」是同一件事：能吸引外部用例，说明边界被真实需求反复验证过。

开源生态里还有一个常被低估的角色：文档与示例。我们在多个项目里观察到，同一个框架，文档齐备的仓库采纳率高出一个数量级。原因很现实：边缘端开发者时间碎、试错贵，能照着跑通的示例比架构图更有说服力。LEANN 把可复现示例列为与代码同等地位的贡献类型，这正是本册坚持每节给带注释的能跑片段的原因，示例本身就是生态的黏合剂。

再谈版本支持的寿命。边缘设备换代周期比云端慢得多，一颗芯片可能要撑五年。选这类框架要看它是否承诺对旧运行时的长期兼容，而不是只在最新硬件上跑分。生态成熟度的一个硬指标，是老设备上的可用版本是否仍有人维护。我们在第一章讲能力边界，这里补一个时间维度的边界：今天的合适，要能撑到设备退役才算数。

版本能力的递进也提醒我们，不要在同一版里同时追三件事，那会让你既测不准也修不完。

本节可考核点：能讲出 LEANN 相对纯向量库和重型 RAG 框架的差异，并说清 v1 到 v2 迁移的真实成本在哪。