为什么 Recall@5 不够用第03篇开了一个先例：用 30 道检索题测向量路径，Recall@5 = 0.958。后来每篇涉及检索实验的文章，都用类似的方式汇报结果。Recall@5 是个合理的起点指标，但它有三个盲区：盲区一：精度。Recall@5 问的是"正确答案有没有出现在前5个结果里"，但代码检索的目标经常是"精确定位到那一个函数"。出现在第5位和出现在第1位，用 Recall@5 得分一样，但实际价值差很多——第1位意味着直接命中，第5位意味着还要手动翻找。盲区二：任务类型。第08篇确立了三路检索架构，不同路径对应不同任务：向量路径做语义探索，图路径做结构遍历，符号路径做精确匹配。一套 Recall@5 数据集评的是哪条路径？三条混在一起评，还是分开评？混评会掩盖某条路径的具体短板。盲区三：影响面分析。代码库知识库的核心价值之一是"改这个函数会影响哪些地方"。这类任务的正确答案是一个集合（所有上游调用方），评测时不能只看"有没有返回相关结果"，还要看"有没有漏掉重要的调用方"。这是召回率问题，但不是 Recall@5。四维评测指标针对代码库知识库的特点，提出四个专用指标：指标一：符号定位准确率（Symbol Location Accuracy）定义：对一组"找这个功能在哪实现"的查询，正确答案（目标函数）出现在第一位的比例。为什么用 Top-1 而不是 Top-5：代码库检索的"成功"是找到那个具体的函数。出现在第3位说明还需要人工筛选。Top-1 准确率衡量的是直接命中能力，这对实际工程使用体验影响最大。评测数据集构建：查询示例： Q1: "如何向 LightRAG 插入新文档" A1: lightrag/lightrag.py::ainsert (函数，行1428) Q2: "LightRAG 支持哪些查询模式" A2: lightrag/base.py::QueryParam (类，行83) Q3: "文档分块策略在哪里决定的" A3: lightrag/parser/routing.py::resolve_chunk_options Q4: "删除一个文档会触发哪些清理操作" A4: lightrag/lightrag.py::adelete_by_doc_id对应本系列实验数据：第03篇的向量检索 Recall@5 = 0.958，转换为 Top-1 准确率后通常在 0.75～0.85 之间——前5位里有答案，但排在第一的比例更低。指标二：语义搜索召回率（Semantic Search Recall）定义：对一组查询，正确答案出现在前 K 个结果里的比例。K 通常取 5 或 10。和 Recall@5 的区别：评测对象不是全量检索，而是专门针对"术语不对齐"场景——用户说"文件解析"，代码里叫"document ingestion pipeline"；用户说"缓存机制"，代码里叫"KV storage with TTL"。这类查询最能体现向量路径的价值：BM25 在术语不对齐时会失败，向量 embedding 可以跨越词汇鸿沟。评测数据集构建要点：查询必须刻意使用与代码不同的术语，否则 BM25 就能答对，测不出向量路径的差异。好的测试用例（术语不对齐）： Q: "文档去重逻辑" → A: compute_mdhash_id (operate.py) Q: "LLM 请求速率控制" → A: priority_limit_async_func_call (utils.py) Q: "知识图谱节点合并" → A: _merge_nodes_then_upsert (operate.py) 弱的测试用例（术语直接对齐，BM25 就能做到）： Q: "priority limit async func" → A: priority_limit_async_func_call指标三：影响面分析完整率（Impact Analysis Completeness）定义：对一个目标函数，要求返回"所有直接调用方"，评测实际返回结果和真实调用方集合的交集比例。这是最接近实际工程价值的指标：改一个函数之前，知识库能不能告诉我所有会受影响的地方。公式：Completeness = |returned callers ∩ actual callers| / |actual callers|对 LightRAG 的实测数据（第09篇）：QueryParam的真实调用方有 19 个，search_code("QueryParam")返回了全部 19 个。这一组的 Completeness = 1.0。但并非所有函数都这么理想。BaseVectorStorage.upsert的 fan_in = 268，如果工具有返回数量上限（比如 limit=50），就会漏掉 218 个调用方，Completeness 急剧下降。这不是召回算
为什么 Recall@5 不够用第03篇开了一个先例：用 30 道检索题测向量路径，Recall@5 = 0.958。后来每篇涉及检索实验的文章，都用类似的方式汇报结果。Recall@5 是个合理的起点指标，但它有三个盲区：盲区一：精度。Recall@5 问的是"正确答案有没有出现在前5个结果里"，但代码检索的目标经常是"精确定位到那一个函数"。出现在第5位和出现在第1位，用 Recall@5 得分一样，但实际价值差很多——第1位意味着直接命中，第5位意味着还要手动翻找。盲区二：任务类型。第08篇确立了三路检索架构，不同路径对应不同任务：向量路径做语义探索，图路径做结构遍历，符号路径做精确匹配。一套 Recall@5 数据集评的是哪条路径？三条混在一起评，还是分开评？混评会掩盖某条路径的具体短板。盲区三：影响面分析。代码库知识库的核心价值之一是"改这个函数会影响哪些地方"。这类任务的正确答案是一个集合（所有上游调用方），评测时不能只看"有没有返回相关结果"，还要看"有没有漏掉重要的调用方"。这是召回率问题，但不是 Recall@5。四维评测指标针对代码库知识库的特点，提出四个专用指标：指标一：符号定位准确率（Symbol Location Accuracy）定义：对一组"找这个功能在哪实现"的查询，正确答案（目标函数）出现在第一位的比例。为什么用 Top-1 而不是 Top-5：代码库检索的"成功"是找到那个具体的函数。出现在第3位说明还需要人工筛选。Top-1 准确率衡量的是直接命中能力，这对实际工程使用体验影响最大。评测数据集构建：查询示例： Q1: "如何向 LightRAG 插入新文档" A1: lightrag/lightrag.py::ainsert (函数，行1428) Q2: "LightRAG 支持哪些查询模式" A2: lightrag/base.py::QueryParam (类，行83) Q3: "文档分块策略在哪里决定的" A3: lightrag/parser/routing.py::resolve_chunk_options Q4: "删除一个文档会触发哪些清理操作" A4: lightrag/lightrag.py::adelete_by_doc_id对应本系列实验数据：第03篇的向量检索 Recall@5 = 0.958，转换为 Top-1 准确率后通常在 0.75～0.85 之间——前5位里有答案，但排在第一的比例更低。指标二：语义搜索召回率（Semantic Search Recall）定义：对一组查询，正确答案出现在前 K 个结果里的比例。K 通常取 5 或 10。和 Recall@5 的区别：评测对象不是全量检索，而是专门针对"术语不对齐"场景——用户说"文件解析"，代码里叫"document ingestion pipeline"；用户说"缓存机制"，代码里叫"KV storage with TTL"。这类查询最能体现向量路径的价值：BM25 在术语不对齐时会失败，向量 embedding 可以跨越词汇鸿沟。评测数据集构建要点：查询必须刻意使用与代码不同的术语，否则 BM25 就能答对，测不出向量路径的差异。好的测试用例（术语不对齐）： Q: "文档去重逻辑" → A: compute_mdhash_id (operate.py) Q: "LLM 请求速率控制" → A: priority_limit_async_func_call (utils.py) Q: "知识图谱节点合并" → A: _merge_nodes_then_upsert (operate.py) 弱的测试用例（术语直接对齐，BM25 就能做到）： Q: "priority limit async func" → A: priority_limit_async_func_call指标三：影响面分析完整率（Impact Analysis Completeness）定义：对一个目标函数，要求返回"所有直接调用方"，评测实际返回结果和真实调用方集合的交集比例。这是最接近实际工程价值的指标：改一个函数之前，知识库能不能告诉我所有会受影响的地方。公式：Completeness = |returned callers ∩ actual callers| / |actual callers|对 LightRAG 的实测数据（第09篇）：QueryParam的真实调用方有 19 个，search_code("QueryParam")返回了全部 19 个。这一组的 Completeness = 1.0。但并非所有函数都这么理想。BaseVectorStorage.upsert的 fan_in = 268，如果工具有返回数量上限（比如 limit=50），就会漏掉 218 个调用方，Completeness 急剧下降。这不是召回算
